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:
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 Creating Panes with Your Own Drawing and Input.
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 Pixmaps and Metafiles.
These are used for drawing to a printer. Printing is described in Printing from the CAPI—the Hardcopy API.
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 Pixmaps and Metafiles.
Graphics ports instances are created or temporarily redirected by any of these interfaces:
make-instance with output-pane or any subclass (including editor-pane, pinboard-layout and graph-pane).
create-pixmap-port and with-pixmap-graphics-port.
with-internal-metafile and with-external-metafile.
with-print-job and simple-print-port.
For the details, see the manual pages for the various CAPI and GRAPHICS-PORTS classes listed above.
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.
(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:
The operations can then be drawn by one call, and on Cocoa and Windows can also be put in on the clipboard so that another process can access it.
The file is in a format that other applications can also use.
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.
(example-edit-file "capi/graphics/metafile")
(example-edit-file "capi/graphics/metafile-rotation")
CAPI User Guide and Reference Manual (Macintosh version) - 25 Feb 2015