A pixmap can be thought of as an "off-screen window," that is, a medium that can be used for graphical output, but that is not visible on any display device. Pixmaps are provided to allow a programmer to generate a piece of output associated with some display device that can then be rapidly drawn on a real display device. For example, an electrical CAD system might generate a pixmap that corresponds to a complex, frequently-used part in a VLSI schematic, and then use copy-from-pixmap to draw the part as needed.
The exact representation of a pixmap is explicitly unspecified. There is no interaction between the pixmap operations and output recording; that is, displaying a pixmap on a medium is a pure drawing operation that affects only the display, not the output history. Some mediums may not support pixmaps; in this case, an error will be signaled.
allocate-pixmap [Generic Function]
Arguments: medium width height
Summary: Allocates and returns a pixmap object that can be used on any medium that shares the same characteristics as medium . (What constitutes "shared characteristics" varies from host to host.) medium can be a sheet, a medium, or a stream.
The resulting pixmap will be width units wide, height units high, and as deep as is necessary to store the information for the medium. The exact representation of pixmaps is explicitly unspecified. The returned value is the pixmap.
deallocate-pixmap [Generic Function]
Summary: Deallocates the pixmap pixmap .
pixmap-width [Generic Function]
pixmap-height [Generic Function]
pixmap-depth [Generic Function]
Summary: These functions return, respectively, the programmer-specified width, height, and depth of the pixmap pixmap .
copy-to-pixmap [Generic Function]
Arguments: medium medium-x medium-y width height
&optional
pixmap (pixmap-x
0
) (pixmap-y
0
)
Summary: Copies the pixels from the medium medium starting at the position specified by ( medium-x , medium-y ) into the pixmap pixmap at the position specified by ( pixmap-x , pixmap-y ). A rectangle whose width and height is specified by width and height is copied. medium-x and medium-y are specified in user coordinates. (If medium is a medium or a stream, then medium-x and medium-y are transformed by the user transformation.)
If pixmap is not supplied, a new pixmap will be allocated. Otherwise, pixmap must be an object returned by allocate-pixmap that has the appropriate characteristics for medium .
The returned value is the pixmap.
copy-from-pixmap [Generic Function]
Arguments: pixmap pixmap-x pixmap-y width height medium window-x window-y
Summary: Copies the pixels from the pixmap pixmap starting at the position specified by ( pixmap-x , pixmap-y ) into the medium medium at the position ( medium-x , medium-y ). A rectangle whose width and height is specified by width and height is copied. medium-x and medium-y are specified in user coordinates. (If medium is a medium or a stream, then medium-x and medium-y are transformed by the user transformation.)
pixmap must be an object returned by allocate-pixmap that has the appropriate characteristics for medium .
The returned value is the pixmap. This is intended to specialize on both the pixmap and medium arguments.
Arguments: medium from-x from-y width height to-x to-y
Summary: Copies the pixels from the medium medium starting at the position specified by ( from-x , from-y ) to the position ( to-x , to-y ) on the same medium. A rectangle whose width and height is specified by width and height is copied. from-x , from-y , to-x , and to-y are specified in user coordinates. (If medium is a medium or a stream, then medium-x and medium-y are transformed by the user transformation.)
with-output-to-pixmap [Macro]
Arguments: (medium-var medium
&key
width height)
&body
body
Summary: Binds medium-var to a "pixmap medium" (that is, a medium that does output to a pixmap with the characteristics appropriate to the medium medium ) and then evaluates body in that context. All the output done to the medium designated by medium-var inside of body is drawn on the pixmap stream. The pixmap medium supports the medium output protocol, including all of the graphics functions.
width and height are integers that give the dimensions of the pixmap. If they are omitted, the pixmap will be large enough to contain all the output done by body .
medium-var must be a symbol; it is not evaluated. The returned value is a pixmap that can be drawn onto medium using copy-from-pixmap .