All Manuals > CAPI User Guide and Reference Manual > 13 Drawing - Graphics Ports

13.1 Introduction

Graphics Ports allow you to write source-compatible applications which draw text, lines, shapes and images, for different host window systems. Graphics Ports are the destinations for the drawing primitives. They are implemented with a generic host-independent part and a small host-specific part.

All Graphics Ports symbols are exported from the graphics-ports package, nicknamed gp.

Graphics Ports implement a set of drawing functions and a mechanism for specifying the graphics state to be used in each drawing function call. There are four categories of graphics ports:

On-screen ports
These correspond to visible windows. They are instances of output-pane or a subclass, and are integral part of the CAPI panes system. The functionality of output-pane (other than drawing) is discussed in 12 Creating Panes with Your Own Drawing and Input. All drawing to an output-pane must be done inside its display-callback.
Pixmap ports
These are solely for off-screen drawing. Once the drawing is completed they can be copied to another port (typically an on-screen port, with copy-area), or converted to an image. For the details see 13.1.2 Pixmaps and Metafiles.
Printer ports
These are used for drawing to a printer. Printing is described in 16 Printing from the CAPIā€”the Hardcopy API.
Metafile ports
These are used for recording drawing operations so that the drawing can be realized later or exported to a file that can read by other applications. For the details see 13.1.2 Pixmaps and Metafiles.

13.1.1 Creating instances

Graphics ports instances are created or temporarily redirected by any of these interfaces:

On-screen ports
make-instance with output-pane or any subclass (including editor-pane, pinboard-layout and graph-pane).
Pixmap ports
Metafile ports
Printer ports

For the details, see the manual pages for the various CAPI and GRAPHICS-PORTS classes listed above.

13.1.2 Pixmaps and Metafiles

Pixmaps are graphics ports for doing off-screen drawing. You create a pixmap with with-pixmap-graphics-port or create-pixmap-port, and draw on it using the drawing functions. You draw the contents of the pixmap on another port (any kind of port) by copying it (using copy-area), or create an image from it using make-image-from-port. The drawing into and the using of a pixmap can be interleaved (but not in parallel), and each time you use the pixmap you get the result of all the drawing operations on it until this point. If the pixmap is created by with-pixmap-graphics-port it is destroyed on exiting the scope of with-pixmap-graphics-port, otherwise you will need to destroy the pixmap when you finish with it (using destroy-pixmap-port).

Pixmaps are used for efficiency. In general copy-area would be much faster than doing the drawing operations again for any significant number of drawing operations. It is especially useful for drawing inside the display-callback of an output-pane, which is called whenever part of the output pane needs redrawing, and needs to be fast to look good.

Pixmaps are also useful way of creating your own images for exporting with externalize-and-write-image.

Examples of using pixmaps:

(example-edit-file "capi/graphics/compositing-mode-simple")
(example-edit-file "capi/graphics/compositing-mode")
(example-edit-file "capi/graphics/image-scaling")
(example-edit-file "capi/graphics/images-with-alpha")
(example-edit-file "capi/graphics/pixmap-port")
(example-edit-file "capi/graphics/plot-offline")

Metafiles are graphics ports that record drawing operations to them. They are used for two purposes:

You can group operations by drawing to a metafile inside with-internal-metafile which returns a metafile object, and later drawing the metafile by using draw-metafile. You can also convert it directly to an image by draw-metafile-to-image. Once you have finished with it you need to free the metafile by free-metafile.

It is possible to perform the same task by drawing the operations to a pixmap and then drawing the pixmap, as described above. However, a metafile gives much better results when it is transformed, because it does the drawing with the transformation, while with a pixmap the transformation transforms the pixels. Metafiles also give better results when the drawing is not completely opaque.

The result of with-internal-metafile can also be put on the clipboard for other processes, by using set-clipboard with a :plist (list :metafile metafile). LispWorks can also read a metafile from the clipboard by passing :metafile as the format to clipboard.

You can export the drawing to a file by drawing to a metafile inside using with-external-metafile, which creates the file when it exits.

On Microsoft Windows it creates a Windows enhanced metafile (there are several possible formats). On Cocoa and GTK+ it creates a PDF file.

Compared to exporting images (using with-pixmap-graphics-port, make-image-from-port, and externalize-and-write-image), the exported metafiles (PDF or Windows metafile) behave much better in transformation and combination with other drawings. They are also simpler to use.

LispWorks itself can read the file that was created by with-external-metafile using the functions that read images (load-image, read-external-image).

Metafile functionality is not available on version of GTK+ before 2.8, and on Motif. The function can-use-metafile-p can be used to check whether the GUI system associated with a screen supports metafile functionality.

Examples of metafiles:

(example-edit-file "capi/graphics/metafile")
(example-edit-file "capi/graphics/metafile-rotation")

CAPI User Guide and Reference Manual (Macintosh version) - 01 Dec 2021 19:31:22