Panel Graphics Retained Drawing

These routines let you record a sequence of panel graphics drawing commands and replay them efficiently on subsequent frames. This is useful for static or infrequently changing parts of a display: record once, then replay each frame without reissuing individual draw calls.

WARNING: A retained drawing captures references to the texture atlases and fonts used during recording. If you destroy a texture atlas or font that was used in a retained drawing, you must also destroy that retained drawing - replaying it will reference invalid resources.

XPLMRetainedDrawing_t

typedef

An opaque handle to a recorded sequence of drawing commands. Create one by bracketing draw calls between XPLMBeginRetainedDrawing and XPLMEndRetainedDrawing. Destroy it with XPLMDestroyRetainedDrawing when it is no longer needed.

typedef void * XPLMRetainedDrawing_t;

XPLMBeginRetainedDrawing

function

This function begins recording drawing commands. All panel graphics calls made after this function and before XPLMEndRetainedDrawing are captured into a retained drawing instead of being rendered immediately.

NOTE: Do not nest retained drawing sessions.

XPLM_API void       XPLMBeginRetainedDrawing(void);

XPLMEndRetainedDrawing

function

This function ends recording and returns a handle to the captured drawing commands. Subsequent panel graphics calls are once again rendered immediately.

Returns an opaque handle to the retained drawing.

XPLM_API XPLMRetainedDrawing_tXPLMEndRetainedDrawing(void);

XPLMDrawRetained

function

This function replays a previously recorded sequence of drawing commands. You can call this multiple times per frame and across multiple frames to efficiently re-draw the same content.

XPLM_API void       XPLMDrawRetained(
                         XPLMRetainedDrawing_t drawing
                    );

XPLMDestroyRetainedDrawing

function

This function destroys a retained drawing and frees its resources.

XPLM_API void       XPLMDestroyRetainedDrawing(
                         XPLMRetainedDrawing_t drawing
                    );