Panel_graphics Transform/Scissors/Masks

These routines modify the drawing state for subsequent panel graphics calls. The transformation matrix controls the position, rotation, and scale of all drawing. The scissor rectangle clips drawing to a rectangular region. The stencil mask clips drawing to an arbitrary shape.

Each state type has a push/pop stack. Always push before modifying state and pop to restore the previous state when you are done.

XPLMTransformPush

function

This function saves the current transformation matrix onto the transform stack. Call XPLMTransformPop to restore it. Calls must be balanced.

XPLM_API void       XPLMTransformPush(void);

XPLMTransformPop

function

This function restores the transformation matrix from the top of the transform stack, undoing all translate, rotate, and scale operations since the matching XPLMTransformPush.

XPLM_API void       XPLMTransformPop(void);

XPLMTransformTranslate

function

This function translates (offsets) all subsequent drawing by the specified amounts. The translation is applied on top of the current transformation matrix.

dx: horizontal offset in pixels, positive to the right.
dy: vertical offset in pixels, positive upward.

XPLM_API void       XPLMTransformTranslate(
                         float                dx,
                         float                dy
                    );

XPLMTransformRotate

function

This function rotates all subsequent drawing around a center point. The rotation is applied on top of the current transformation matrix.

centerX, centerY: the center of rotation in panel coordinates.
angle: the rotation angle in degrees, positive counterclockwise.

XPLM_API void       XPLMTransformRotate(
                         float                centerX,
                         float                centerY,
                         float                angle
                    );

XPLMTransformScale

function

This function scales all subsequent drawing relative to the origin of the current coordinate system. The scale is applied on top of the current transformation matrix.

scaleX: horizontal scale factor. 1.0 is no change, 2.0 doubles width.
scaleY: vertical scale factor. 1.0 is no change, 2.0 doubles height.

XPLM_API void       XPLMTransformScale(
                         float                scaleX,
                         float                scaleY
                    );

XPLMScissorPush

function

This function saves the current scissor rectangle onto the scissor stack. Call XPLMScissorPop to restore it. Calls must be balanced.

XPLM_API void       XPLMScissorPush(void);

XPLMScissorPop

function

This function restores the scissor rectangle from the top of the scissor stack, undoing any set or shrink operations since the matching XPLMScissorPush.

XPLM_API void       XPLMScissorPop(void);

XPLMScissorSet

function

This function sets an absolute scissor rectangle. Only pixels within this rectangle are drawn; everything outside is clipped.

top, left, bottom, right: the scissor bounds in panel coordinates.

XPLM_API void       XPLMScissorSet(
                         int                  top,
                         int                  left,
                         int                  bottom,
                         int                  right
                    );

XPLMScissorShrink

function

This function insets (shrinks) the current scissor rectangle by the specified amounts on each side. The result is the intersection of the current scissor rectangle and the new inset rectangle, so the drawable area can only get smaller. This is useful for nested clipping.

top: inset from the top edge, in pixels.
left: inset from the left edge, in pixels.
bottom: inset from the bottom edge, in pixels.
right: inset from the right edge, in pixels.

XPLM_API void       XPLMScissorShrink(
                         int                  top,
                         int                  left,
                         int                  bottom,
                         int                  right
                    );

XPLMBeginSetupStencilMask

function

This function begins stencil mask setup. While in setup mode, drawing commands write to the stencil buffer instead of to the screen. Draw the shapes that define your mask region, then call XPLMEndSetupStencilMask to finish.

bits: the stencil bit pattern to write into the stencil buffer where geometry is drawn.
mask: a bitmask selecting which stencil bits are written.

XPLM_API void       XPLMBeginSetupStencilMask(
                         unsigned int         bits,
                         unsigned int         mask
                    );

XPLMEndSetupStencilMask

function

This function ends stencil mask setup. After this call, drawing commands once again render to the screen. Call XPLMUseStencilMask to activate the mask for subsequent drawing, or XPLMClearStencilMask to discard it.

XPLM_API void       XPLMEndSetupStencilMask(void);

XPLMUseStencilMask

function

This function activates stencil testing. Subsequent drawing is clipped to the region defined during stencil setup: only pixels where the stencil buffer matches the specified bit pattern are drawn.

bits: the reference bit pattern to test against.
mask: a bitmask selecting which stencil bits participate in the test.

XPLM_API void       XPLMUseStencilMask(
                         unsigned int         bits,
                         unsigned int         mask
                    );

XPLMClearStencilMask

function

This function clears the stencil buffer and disables stencil testing. Subsequent drawing is no longer clipped by the stencil mask.

XPLM_API void       XPLMClearStencilMask(void);