7.1 Area and Plane Operations

clear-area clears an area or an entire window to the background. Since pixmaps do not have backgrounds, they cannot be filled by using the functions described in the following paragraphs. Instead, you should use draw-rectangle, which sets the pixmap to a known value. See Drawing Rectangles, for information on draw-rectangle.

Function: clear-area window &key (:x 0) (:y 0) :width :height :exposures-p

window

A window.

:x

:y

Upper-left corner of the area to be cleared. These coordinates are relative to the window origin. Type is int16.

:width

The width of the area to clear or nil to clear to the remaining width of the window. Type is card16 or null.

:height

The height of the area to clear or nil to clear to the remaining height of the window. Type is card16 or null.

:exposures-p

Specifies if :exposure events should be generated for the affected areas. Type boolean.

Draws a rectangular area in the specified window with the background pixel or pixmap of the window. The :x and :y coordinates are relative to the window origin, and specify the upper-left corner of the rectangular area that is to be cleared. A nil or zero value for :height or :width clears the remaining area (height - y or width - x). If the window has a defined background tile, the rectangle is tiled by using a plane-mask of all ones and a function of :copy. If the window has background :none, the contents of the window are not changed. In either case, if :exposures-p is non-nil, then one or more :exposure events are generated for regions of the rectangle that are either visible or are being retained in a backing store.

To clear the entire area in a specified window, use (clear-area window).

Function: copy-area source gcontext source-x source-y width height destination destination-x destination-y

source

Source drawable.

gcontext

The graphics context to use during the copy operation.

source-x

source-y

The x and y coordinates of the upper-left corner of the area in the source drawable. These coordinates are relative to the source drawable origin. Type is int16.

width

height

The width and height of the area being copied. These apply to both the source and destination areas. Type is card16.

destination

The destination drawable.

destination-x

destination-y

The x and y coordinates of the upper left corner of the area in the destination drawable. These coordinates are relative to the destination drawable origin. Type is int16.

Copies the specified rectangular area from the source drawable to the specified rectangular area of the destination drawable, combining them as specified in the supplied graphics context (gcontext). The x and y coordinates are relative to their respective drawable origin, with each pair specifying the upper left corner of the area.

If either regions of the source area are obscured and have not been retained in backing store, or regions outside the boundaries of the source drawable are specified, those regions are not copied. Instead, the following occurs on all corresponding destination regions that are either visible or are retained in backing store:

• If the destination rectangle is a window with a background other than :none, these corresponding regions of the destination are tiled, using plane-mask of all ones and function of boole-1 (copy source), with that background.
• If the exposures attribute of the graphics context is :on, then :graphics-exposure events for all corresponding destination regions are generated (regardless of tiling or whether the destination is a window or a pixmap).
• If exposures is :on but no regions are exposed, a :no-exposure event is generated. Note that by default, exposures is :on for new graphics contexts. See Graphics Contexts, for further information.

Function: copy-plane source gcontext plane source-x source-y width height destination destination-x destination-y

source

The source drawable.

gcontext

The graphics context to use during the copy operation.

plane

Specifies the bit-plane of the source drawable. Exactly one bit must be set. Type is pixel.

source-x

source-y

The x and y coordinates of the upper-left corner of the area in the source drawable. These coordinates are relative to the source drawable origin. Type is int16.

width

height

The width and height of the area being copied. These apply to both the source and destination areas. Type is card16.

destination

The destination drawable.

destination-x

destination-y

The x and y coordinates of the upper-left corner of the destination area in the destination drawable. These coordinates are relative to the destination drawable origin. Type is int16.

Uses a single bit plane of the specified rectangular area of the source drawable along with the specified graphics context (gcontext) to modify the specified rectangle area of the destination drawable. The drawables specified by the source and destination arguments must have the same root but need not have the same depth.

Effectively, this operation forms a pixmap of the same depth as destination and with a size specified by the source area. It then uses the foreground and background from the graphics context (foreground where the bit-plane in source contains a one bit, background where the bit-plane in source contains a zero bit), and the equivalent of a copy-area operation is performed with all the same exposure semantics. This can also be thought of as using the specified region of the source bit-plane as a stipple with a fillstyle of :opaque-stippled for filling a rectangular area of the destination.