gfx.h

Includes:
<XPLMPanelGraphics.h>
<stdbool.h>
<stdint.h>

Introduction

Canvas-like API for X-Plane 12.4.4+ XPLMPanelGraphics drawing.

GFX abstracts away XPLMPanelGraphics' vertices, and instead provides you with a stateful canvas-like API to draw lines, arcs, Bézier curves, TTF- and bitmap-font text.


Groups

Shared state management

Group members:

gfx_bake_shared
gfx_fini_shared
gfx_init_shared

 

Transformations

When using the path API, all co-ordinates are specified in _user space_. Drawing commands submitted to X-Plane's Panel Graphics API are in _device space_: for avionics, this means the x and y axes originate at the bottom left of the device screen, and increase up and right; for windows, the x and y axes originate at the bottom left of the desktop space, and increase up and right.

When a new frame starts (by calling `gfx_new_frame()`), user space and device space are the same. However, it can be useful to _transform_ user space, so co-ordinates are easier to work with. For example, when drawing a map, it is easier to rotate the the axes by the current aircraft's heading, than doing the rotation maths for each point drawn on the map.

The transformation API is how the user space to device space relation is modified.

The current transform state can be saved and restored, much like the OpenGL transorm stack.

Group members:

gfx_reset
gfx_restore
gfx_rotate
gfx_save
gfx_scale
gfx_translate

 

Vector Drawing

Vector drawing using GFX is done using paths. You first construct one or multiple paths using the various functions of the path API; then call `gfx_stroke()`, `gfx_clip()`, or `gfx_fill()` to paint the path onto the context.

A path can contain multiple _sub paths_: every time `gfx_move_to()` is called, a new sub-path is created. When calling `gfx_stroke()`, distinct sub-paths are drawn disconnected.

Calls to `gfx_set_color()`, `gfx_set_line_width()`, take effect when `gfx_stroke() or `gfx_fill()` is called.

Group members:

gfx_arc
gfx_arc_negative
gfx_clip
gfx_clip_preserve
gfx_clip_reset
gfx_close_path
gfx_curve_to
gfx_fill
gfx_fill_preserve
gfx_line_cap_t
gfx_line_to
gfx_move_to
gfx_rectangle
gfx_set_color
gfx_set_line_cap
gfx_set_line_width
gfx_stroke
gfx_stroke_fast
gfx_stroke_preserve
gfx_tex

 

Context & Frame Handling

Group members:

gfx_begin_frame
gfx_destroy
gfx_end_frame
gfx_new

 

Color utilities.

Group members:

gfx_color_mult
gfx_load_tex
gfx_load_tex_atlas
gfx_rgb
gfx_rgba
gfx_rgbaf
gfx_rgbf

 

Resource Loading

Group members:

gfx_bitmap_font_desc_t
gfx_load_bitmap_font
gfx_text_align_t

 

Text Drawing

Group members:

gfx_set_bitmap_font
gfx_set_font_face
gfx_set_font_size

Functions

gfx_arc
gfx_arc_negative
gfx_bake_shared
gfx_begin_frame
gfx_clip
gfx_clip_preserve
gfx_clip_reset
gfx_close_path
gfx_color_mult
gfx_curve_to
gfx_destroy
gfx_end_frame
gfx_fill
gfx_fill_preserve
gfx_fini_shared
gfx_init_shared
gfx_line_to
gfx_load_bitmap_font
gfx_load_tex
gfx_load_tex_atlas
gfx_move_to
gfx_new
gfx_rectangle
gfx_reset
gfx_restore
gfx_rgb
gfx_rgba
gfx_rgbaf
gfx_rgbf
gfx_rotate
gfx_save
gfx_scale
gfx_set_bitmap_font
gfx_set_color
gfx_set_font_face
gfx_set_font_size
gfx_set_line_cap
gfx_set_line_width
gfx_stroke
gfx_stroke_fast
gfx_stroke_preserve
gfx_tex
gfx_translate

gfx_arc

void gfx_arc( 
    gfx_ctx_t *ctx, 
    float x, 
    float y, 
    float radius, 
    float angle_start, 
    float angle_end );
Parameters
ctx

Pointer to the context.

x

x co-ordinate of the arc center.

y

y co-ordinate of the arc center.

angle_start

Angle at which the arc begins.

angle_end

Angle at which the arc begins.

Discussion

Adds an circular arc of the given `radius` to the current path.

The arc is centered at `(x, y)` at the centre, begins at `angle_start`, and progresses in the direction of increasing angles to `angle_end`.

Angles are in radians; the point at 0 radians lies on the x-axis, and angles increase counter-clockwise.

After this call, the path's current point is the point on the arc at `angle_end`.

gfx_arc_negative

void gfx_arc_negative( 
    gfx_ctx_t *ctx, 
    float x, 
    float y, 
    float radius, 
    float angle_start, 
    float angle_end );
Parameters
ctx

Pointer to the context.

x

x co-ordinate of the arc center.

y

y co-ordinate of the arc center.

angle_start

Angle at which the arc begins.

angle_end

Angle at which the arc begins.

Discussion

Adds an circular arc of the given `radius` to the current path.

The arc is centered at `(x, y)` at the centre, begins at `angle_start`, and progresses in the direction of decreasing angles to `angle_end`.

gfx_bake_shared

void gfx_bake_shared();
Discussion

Bakes any texture atlases needed by GFX objects. Call once all your GFX contexts are done with initialisation, and you do not need to create any more resources.

gfx_begin_frame

void gfx_begin_frame(
    gfx_ctx_t *ctx);
Parameters
ctx

Pointer to the context.

Discussion

Starts a new rendering frame.

gfx_clip

void gfx_clip(
    gfx_ctx_t *ctx);
Parameters
ctx

Pointer to the context.

Discussion

Uses a context's current path as a convex polygon to create a clipping area, and discard the path.

Any drawing submitted after `gfx_clip()` and before `gfx_clip_reset()` is only shown when it lies within the polygon's area.

gfx_clip_preserve

void gfx_clip_preserve(
    gfx_ctx_t *ctx);
Parameters
ctx

Pointer to the context.

Discussion

Uses a context's current path as a convex polygon to create a clipping area, and keep the path.

Any drawing submitted after `gfx_clip()` and before `gfx_clip_reset()` is only shown when it lies within the polygon's area.

gfx_clip_reset

void gfx_clip_reset(
    gfx_ctx_t *ctx);
Parameters
ctx

Pointer to the context.

Discussion

Discard a context's current clipping area.

gfx_close_path

void gfx_close_path(
    gfx_ctx_t *ctx);
Parameters
ctx

Pointer to the context.

Discussion

Closes the current sub-path, by adding a point in the same location as the sub-path's first point.

gfx_color_mult

uint32_t gfx_color_mult(
    uint32_t c,
    float m);
Discussion

Multiplies each component of a colour by a scalar.

gfx_curve_to

void gfx_curve_to(
    gfx_ctx_t *ctx,
    float x1,
    float y1,
    float x2,
    float y2,
    float x3,
    float y3);
Parameters
ctx

Pointer to the context.

x1

x co-ordinate of the first control point.

y1

y co-ordinate of the first control point.

x2

x co-ordinate of the second control point.

y2

y co-ordinate of the second control point.

x3

x co-ordinate of the curve's end point.

y3

y co-ordinate of the curve's end point.

Discussion

Adds a cubic bezier curve to the current path.

The curve joins the current point to `(x3, y3)`, with `(x1, y1)` and `(x2, y2)` as control points. If there is no current point, the curve begins at `(x1, y1)`.

gfx_destroy

void gfx_destroy(
    gfx_ctx_t *ctx);
Parameters
ctx

A pointer to the context to destroy.

Discussion

Destroys a GFX context.

gfx_end_frame

void gfx_end_frame(
    gfx_ctx_t *ctx);
Parameters
ctx

Pointer to the context.

Discussion

Ends the rendering frame.

No work is done, but this allows the context to check that the rendering calls were well-formed, and that context save & restores are well balanced.

gfx_fill

void gfx_fill(
    gfx_ctx_t *ctx);
Parameters
ctx

Pointer to the context.

Discussion

Fills a context's current path as a convex polygon, and discards the path.

gfx_fill_preserve

void gfx_fill_preserve(
    gfx_ctx_t *ctx);
Parameters
ctx

Pointer to the context.

Discussion

Fills a context's current path as a convex polygon, and keep the path.

gfx_fini_shared

void gfx_fini_shared();
Discussion

Frees any memory used by GFX shared resources. Call once at plugin teardown.

gfx_init_shared

void gfx_init_shared();
Discussion

Initialises shared resources used by the GFX layer. Call once at plugin start.

gfx_line_to

void gfx_line_to(
    gfx_ctx_t *ctx,
    float x,
    float y);
Parameters
ctx

Pointer to the context.

x

x co-ordinate of the new point.

y

x co-ordinate of the new point.

Discussion

Adds a line to the current path, from the current position to the new co-ordinates.

If there is no current position, calling `gfx_line_to()` is equivalent to calling `gfx_move_to()`.

After this call, the current point will be `(x, y)`.

gfx_load_bitmap_font

int32_t gfx_load_bitmap_font(
    const char *path,
    const gfx_bitmap_font_desc_t *desc);
Parameters
path

the absolute path to the PNG file.

desc

the loader description for the font.

Return Value

the font index, used when drawing text.

Discussion

Loads a bitmap font from an atlas file.

The atlas is assumed to contain 16 columns by 4 rows.

gfx_load_tex

int32_t gfx_load_tex(
    const char *path);
Parameters
path

the absolute path to the PNG file.

Return Value

a valid texture index, or -1 if texture load failed.

Discussion

Loads one texture from a PNG file, and adds it to a shared atlas.

gfx_load_tex_atlas

int32_t gfx_load_tex_atlas(
    const char *path,
    int col,
    int row,
    int *w,
    int *h);
Parameters
path

the absolute path to the PNG file.

col

the number of columns in the atlas.

row

the number of rows in the atlas.

w

a pointer to an integer, will be filled with the width of each atlas tile.

h

a pointer to an integer, will be filled with the height of each atlas tile.

Return Value

the texture index of the first atlas tile, or -1 if texture load failed.

Discussion

Loads one texture atlas from a PNG file.

gfx_move_to

void gfx_move_to(
    gfx_ctx_t *ctx,
    float x,
    float y);
Parameters
ctx

Pointer to the context.

x

x co-ordinate of the new point.

y

x co-ordinate of the new point.

Discussion

Begin a new sub-path in a context. If the current path already has point, there will be a gap between the last point and the new co-ordinates.

After this call, the current point will be `(x, y)`.

gfx_new

gfx_ctx_t *gfx_new();
Return Value

A pointer to the new context.

Discussion

Creates a new GFX context.

Contexts keep track of the transform stack, draw colour, line width, and active bitmap and TTF fonts.

gfx_rectangle

void gfx_rectangle(
    gfx_ctx_t *ctx,
    float x,
    float y,
    float w,
    float h);
Parameters
ctx

Pointer to the context.

x

x co-ordinate of the lower left corner of the rectangle.

y

y co-ordinate of the lower left corner of the rectangle.

w

Width of the rectangle.

Discussion

Adds a rectangle to the current path.

This is a convenience function, which is exactly equivalent to calling:

gfx_move_to(ctx, x, y); gfx_line_to(ctx, x, y + h); gfx_line_to(ctx, x + w, y + h); gfx_line_to(ctx, x + w, y); gfx_close_path(ctx);

gfx_reset

void gfx_reset(
    gfx_ctx_t *ctx);
Parameters
ctx

Pointer to the context.

Discussion

Resets the user-space transform to the default (coincident with device space).

gfx_restore

void gfx_restore(
    gfx_ctx_t *ctx);
Parameters
ctx

Pointer to the context.

Discussion

Pops the user-space transform from the stack, and make it current.

gfx_rgb

uint32_t gfx_rgb(
    uint8_t r,
    uint8_t g,
    uint8_t b);
Discussion

Creates a color object from red, green, and blue 8-bit components (0-255).

gfx_rgba

uint32_t gfx_rgba(
    uint8_t r,
    uint8_t g,
    uint8_t b,
    uint8_t a);
Discussion

Creates a color object from red, green, blue, and alpha 8-bit components (0-255).

gfx_rgbaf

uint32_t gfx_rgbaf(
    float r,
    float g,
    float b,
    float a);
Discussion

Creates a color object from red, green, blue, and alpha floating point components (0.0 - 1.0).

gfx_rgbf

uint32_t gfx_rgbf(
    float r,
    float g,
    float b);
Discussion

Creates a color object from red, green, and blue floating point components (0.0 - 1.0).

gfx_rotate

void gfx_rotate(
    gfx_ctx_t *ctx,
    float angle);
Parameters
ctx

Pointer to the context.

angle

Rotation along the z axis, in radians.

Discussion

Rotate the user-space axes by a given angles.

gfx_save

void gfx_save(
    gfx_ctx_t *ctx);
Parameters
ctx

Pointer to the context.

Discussion

Saves the current user-space transform, and pushes it on the transform stack.

gfx_scale

void gfx_scale(
    gfx_ctx_t *ctx,
    float sx,
    float sy);
Parameters
ctx

Pointer to the context.

sx

x-axis scaling factor.

sy

y-axis scaling factor.

Discussion

Scales the user-space x- and y-axes by given factors.

gfx_set_bitmap_font

void gfx_set_bitmap_font(
    gfx_ctx_t *ctx,
    int32_t font_id);
Parameters
ctx

Pointer to the context.

font_id

A valid bitmap font ID.

Discussion

Sets the font used for bitmap text drawing.

gfx_set_color

void gfx_set_color(
    gfx_ctx_t *ctx,
    uint32_t color);
Parameters
ctx

Pointer to the context.

color

The color in which lines, polygons and text should be drawn.

Discussion

Sets the color used to draw in a context.

gfx_set_font_face

void gfx_set_font_face(
    gfx_ctx_t *ctx,
    int32_t font_id);
Parameters
ctx

Pointer to the context.

font_id

A valid TTF font ID.

Discussion

Sets the TTF font face used for TTF text drawing.

gfx_set_font_size

void gfx_set_font_size(
    gfx_ctx_t *ctx,
    float size);
Parameters
ctx

Pointer to the context.

size

Character size.

Discussion

Sets the character size used for TTF text drawing.

gfx_set_line_cap

void gfx_set_line_cap(
    gfx_ctx_t *ctx,
    gfx_line_cap_t cap);
Parameters
ctx

Pointer to the context.

cap

The cap with which lines should be drawn.

Discussion

Sets the caps with which lines should be drawn in a context.

gfx_set_line_width

void gfx_set_line_width(
    gfx_ctx_t *ctx,
    float width);
Parameters
ctx

Pointer to the context.

width

The width at which lines should be drawn.

Discussion

Sets the width at which lines should be drawn in a context.

gfx_stroke

void gfx_stroke(
    gfx_ctx_t *ctx);
Parameters
ctx

Pointer to the context.

Discussion

Draws a context's current path as a line, then discards the path.

gfx_stroke_fast

void gfx_stroke_fast(
    gfx_ctx_t *ctx);
Parameters
ctx

Pointer to the context.

Discussion

Draws a context's current path as a line, then discards the path.

Unlike `gfx_stroke(gfx_ctx_t *)`, this does check whether the path is closed or not, and just submits the vertices as-is to `XPLMLinesWithWidth()`.

gfx_stroke_preserve

void gfx_stroke_preserve(
    gfx_ctx_t *ctx);
Parameters
ctx

Pointer to the context.

Discussion

Draws a context's current path as a line, and keep the path.

gfx_tex

void gfx_tex(
    gfx_ctx_t *ctx,
    int32_t tex,
    float x,
    float y);
Parameters
ctx

Pointer to the context.

tex

Texture applied to the rectangle.

x

x co-ordinate of the lower left corner of the rectangle.

y

y co-ordinate of the lower left corner of the rectangle.

Discussion

Draws a rectangle at a given point, with a given texture applied to it.

gfx_translate

void gfx_translate(
    gfx_ctx_t *ctx,
    float x,
    float y);
Parameters
ctx

Pointer to the context.

x

Translation along the x axis.

y

Translation along the y axis.

Discussion

Moves the user-space origin by a given `(x, y)` vector.

Typedefs

gfx_bitmap_font_desc_t
gfx_ctx_t
gfx_line_cap_t
gfx_text_align_t

gfx_bitmap_font_desc_t

typedef struct { 
    /** The ASCII code for the first character represented in the font atlas. 
        */
    char first_char; 
    /** The number of characters contained in the font atlas. */
    int32_t char_count; 
    /** Whether the dot character is drawn at full width, or half width. 
        */
    bool short_dot; 
} gfx_bitmap_font_desc_t;
Discussion

Parameters used when loading a bitmap font file.

gfx_ctx_t

typedef struct gfx_ctx_t gfx_ctx_t;
Discussion

Context object, used to store the current drawing state for one window or avionics device.

gfx_line_cap_t

typedef enum gfx_line_cap_t { 
    /** Lines start and stop exactly at their end points, in a straight line. 
        */
    GFX_LINE_CAP_BUTT = 0, 
    /** Lines have round endings, centered on the end points. 
        */
    GFX_LINE_CAP_ROUND = 1, 
    /** Lines have square endings, centered on the end points. 
        */
    GFX_LINE_CAP_SQUARE = 2, 
} gfx_line_cap_t;
Discussion

Specifies how end points of lines are drawn.

gfx_text_align_t

typedef enum { 
    /** The text's left boundary is aligned with the drawing position. 
        */
    GFX_ALIGN_LEFT, 
    /** Text is centered on the drawing position. */
    GFX_ALIGN_CENTER, 
    /** The text's right boundary is aligned with the drawing position. 
        */
    GFX_ALIGN_RIGHT, 
} gfx_text_align_t;
Discussion

A text alignment

 

Last Updated: Thursday, September 17, 2026