It is quite often that you want to transiently add some drawing on top of the permanent drawing of an output-pane. Most typically, you want to allow the user to select an area by dragging the mouse while pressing a button, and you want to include some transient graphics to indicate what they are going to select. This could simply be a rectangle, but you may want something more complex.
Ideally, the display-callback of the pane would be fast enough to handle this, in which case you simply need to make the display-callback draw the transient graphics. For example, in the case of a pinboard-layout, it can be done by adding a transient pinboard-object above the other objects. This is demonstrated by the "outliner" example:
Note that in this case the outliner's drawing is simple, but it could draw much more complex graphics if required.
However, that solution does not work well if the display-callback is not fast enough for these situations. The Cached Display functionality is intended to be used in this case. There are two ways to use the Cached Display interface:
(if (drawing-by-cached-display-p pane)
(output-pane-draw-from-cached-display pane x y width height)
(real-display-callback pane x y width height))
In both cases you finish using the cached display by calling output-pane-free-cached-display. The function output-pane-cached-display-user-info can be used to hold temporary data during the operation.
CAPI User Guide and Reference Manual (Unix version) - 25 Feb 2015