source files: [xc]cmr.[ch]
(SEND <cmr> :CLEAR-OVERLAY-BITPLANES)
This message clears the overlay bitplanes available via the :WHICH-BITPLANES :OVERLAY-BITPLANES option to the :DRAW command, in the area of the screen corresponding to the camera viewport.
This message is intended primarily for use in conjunction with the :WHICH-BITPLANES :DRAW option, to implement fast rubberbanding and such over complex images which cannot be redrawn quickly.
Since overlay planes and the operations on them vary wildly from machine to machine, the effect of this call is undefined on overlay planes outside the viewport, and on other overlay and underlay planes not effected by the above :DRAW option.
In general, the driver can be expected to do whatever is fastest, and when speed doesn't decide the issue, to clear the fewest bits consistent with the above.
On many machines, clearing the overlay planes is an expensive operation -- it may involve reading, masking and rewriting three megabytes of RAM! -- so you should normally try to do it at most once per frame.
This call returns NIL if the driver/hardware doesn't have good overlay support (for example, if it implements :WHICH-PLANES :OVERLAY-PLANES by simply doing destructive 2-D draws into the main image buffer, and ignores :CLEAR-OVERLAY-BITPLANES calls completely) else returns an unspecified non-NIL value.