Panel Graphics Fonts

These routines create fonts from TrueType font files and draw text onto the panel. You create a font handle, add one or more TTF faces to it, then use the handle to measure and draw strings. Font handles must be destroyed when no longer needed.

XPLMCharSet_t

enum

This enumeration specifies the character set for a font created with XPLMCreateFont. The character set determines which glyphs are rasterized and available for drawing.

Name	Value	Description
xplm_CharSetDigits	0	Digits 0-9 and common numeric punctuation only.
xplm_CharSetASCII	1	The printable ASCII character range (codes 32-126).
xplm_CharSetUnicode	2	Full Unicode support; glyphs are rasterized on demand.

XPLMJustification_t

enum

This enumeration specifies horizontal text justification for the font drawing routines. The x and y position you pass to a drawing function is the baseline of the text at the anchor point determined by justification: left-aligned text anchors at the left edge, centered text at the midpoint, and right-aligned text at the right edge.

Name	Value	Description
xplm_JustLeft	0	Left-justified; x is the left edge of the string.
xplm_JustCenter	1	Center-justified; x is the horizontal center of the string.
xplm_JustRight	2	Right-justified; x is the right edge of the string.

XPLMFontMetrics_t

struct

XPLMFontMetrics_t receives font measurement data from XPLMFontGetMetrics. The structure may be expanded in future SDKs - always set structSize to the size of your structure in bytes.

typedef struct {
     int                       structSize;
     float                     lineHeight;
     float                     lineAscent;
     float                     lineDescent;
} XPLMFontMetrics_t;

XPLMFontHandle

typedef

An opaque handle to a font created by XPLMCreateFont. Pass this handle to the font measurement and drawing routines. Destroy the handle with XPLMDestroyFont when you are done with it.

typedef void* XPLMFontHandle;

XPLMCreateFont

function

This function creates a new font handle. The character set determines which glyphs are available for rendering. After creating the font, add one or more TrueType faces with XPLMFontAddFace before drawing.

Returns an opaque font handle.

XPLM_API XPLMFontHandleXPLMCreateFont(
                         XPLMCharSet_t        charset
                    );

XPLMDestroyFont

function

This function destroys a font handle and frees all associated resources.

XPLM_API void       XPLMDestroyFont(
                         XPLMFontHandle       font
                    );

XPLMFontAddFace

function

This function adds a TrueType font face to an existing font handle. You may add multiple faces to a single font to provide fallback glyphs; if a glyph is not found in the first face, subsequent faces are searched in the order they were added.

ttf_path: a file system path to a .ttf or .otf font file.

XPLM_API void       XPLMFontAddFace(
                         XPLMFontHandle       font,
                         char const*          ttf_path
                    );

XPLMFontGetMetrics

function

This function returns line metrics for a font at a given size. The metrics describe the vertical dimensions of a line of text and are useful for computing text layout.

fontSize: the font size in pixels.
outMetrics: receives the computed metrics. You must set outMetrics->structSize before calling.

XPLM_API void       XPLMFontGetMetrics(
                         XPLMFontHandle       font,
                         float                fontSize,
                         XPLMFontMetrics_t*   outMetrics
                    );

XPLMFontMeasureString

function

This function returns the width in pixels that a string would occupy if drawn at the given font size. The string is not drawn.

Returns the horizontal advance width, in pixels.

XPLM_API float      XPLMFontMeasureString(
                         XPLMFontHandle       font,
                         float                fontSize,
                         char const*          string
                    );

XPLMFontGetLineCount

function

This function calculates how many lines a string would occupy if word-wrapped to the specified width at the given font size.

Returns the number of lines.

XPLM_API int        XPLMFontGetLineCount(
                         XPLMFontHandle       font,
                         float                fontSize,
                         char const*          string,
                         float                width
                    );

XPLMFontFitForward

function

This function returns the number of characters from the beginning of a string that fit within the specified width at the given font size. Characters are measured left to right.

Returns a character count.

XPLM_API int        XPLMFontFitForward(
                         XPLMFontHandle       font,
                         float                fontSize,
                         char const*          string,
                         float                width
                    );

XPLMFontFitReverse

function

This function returns the number of characters from the end of a string that fit within the specified width at the given font size. Characters are measured right to left. This is useful for right-aligning a truncated string.

Returns a character count.

XPLM_API int        XPLMFontFitReverse(
                         XPLMFontHandle       font,
                         float                fontSize,
                         char const*          string,
                         float                width
                    );

XPLMFontDrawString

function

This function draws a null-terminated string at the specified position with the given font, size, color, and justification. The x and y coordinates specify the baseline position at the justification anchor point.

fontSize: the font size in pixels.
x, y: the anchor position of the baseline, in panel coordinates.

XPLM_API void       XPLMFontDrawString(
                         XPLMFontHandle       font,
                         uint32_t             color,
                         float                fontSize,
                         float                x,
                         float                y,
                         char const*          string,
                         XPLMJustification_t  justification
                    );

XPLMFontDrawStringFixedSpacing

function

This function draws a null-terminated string using fixed character spacing instead of the font's natural proportional spacing. Each character occupies exactly fixedSpacing pixels horizontally, regardless of the glyph's actual width. This is useful for numeric readouts where digits must not shift as values change.

fontSize: the font size in pixels.
x, y: the anchor position of the baseline, in panel coordinates.
fixedSpacing: the horizontal advance per character, in pixels.

XPLM_API void       XPLMFontDrawStringFixedSpacing(
                         XPLMFontHandle       font,
                         uint32_t             color,
                         float                fontSize,
                         float                x,
                         float                y,
                         char const*          string,
                         int                  fixedSpacing,
                         XPLMJustification_t  justification
                    );

XPLMFontDrawStringWordWrapped

function

This function draws a null-terminated string with automatic word wrapping. Text is broken at word boundaries to fit within the specified wrap width. Lines are stacked downward from the initial y position, spaced by the font's line height.

fontSize: the font size in pixels.
x, y: the anchor position of the first line's baseline, in panel coordinates.
wrapWidth: the maximum line width in pixels before wrapping.

XPLM_API void       XPLMFontDrawStringWordWrapped(
                         XPLMFontHandle       font,
                         uint32_t             color,
                         float                fontSize,
                         float                x,
                         float                y,
                         char const*          string,
                         int                  wrapWidth,
                         XPLMJustification_t  justification
                    );

XPLMFontDrawStringRotated

function

This function draws a null-terminated string rotated by the specified angle around the anchor point. The anchor point is determined by x, y, and the justification, just as in XPLMFontDrawString.

fontSize: the font size in pixels.
x, y: the anchor position of the baseline, in panel coordinates.
angle: the rotation angle in degrees, positive counterclockwise.

XPLM_API void       XPLMFontDrawStringRotated(
                         XPLMFontHandle       font,
                         uint32_t             color,
                         float                fontSize,
                         float                x,
                         float                y,
                         char const*          string,
                         float                angle,
                         XPLMJustification_t  justification
                    );