XLua2 API Ref XPLMPanelGraphics Latest - 4.4.0-d4

Panel Graphics Texture Atlas

These routines manage texture atlases for drawing images on the panel. A texture atlas packs multiple source images into a single GPU texture for efficient rendering. The typical workflow is:

  • Create an atlas with XPLMCreateTextureAtlas.
  • Add images from files or raw pixel data. Each image (or cell of an image set) receives a zero-based index.
  • Call XPLMTextureAtlasBake to upload the atlas to the GPU.
  • Draw images using the DrawAt, DrawIn, DrawStretched, DrawScaled, or DrawMesh routines.
  • Destroy the atlas with XPLMDestroyTextureAtlas when it is no longer needed.

All images are stored as RGBA, 4 bytes per pixel.

XPLMTextureAtlasRef

typedef

An opaque handle to a texture atlas. Create one with XPLMCreateTextureAtlas and destroy it with XPLMDestroyTextureAtlas.

local my_textureAtlasRef = nil  -- XPLMTextureAtlasRef

Used by:

XPLMTextureVertex_t

struct

A vertex for textured mesh drawing. Combines a position in panel coordinates with normalized texture coordinates within the image.

Texture coordinates are always relative to the image you are drawing, never to the atlas sheet it happens to be packed into. This is true for both XPLMTextureAtlasDrawMesh and XPLMTextureSourceDrawMesh, so the same vertex array means the same thing to either one.

local My_TextureVertex_t = {
    x  = 0.0,     -- float
    y  = 0.0,     -- float
    s  = 0.0,     -- float
    t  = 0.0,     -- float
}

XPLMCreateTextureAtlas

function

This function creates a new, empty texture atlas. After creating the atlas, add images with the XPLMTextureAtlasAddImage or XPLMTextureAtlasAddImageFile family of functions, then call XPLMTextureAtlasBake before drawing.

Returns an opaque atlas handle.

-- returns XPLMTextureAtlasRef -> assign to local/var
local my_textureAtlasRef = XPLMCreateTextureAtlas(
)

XPLMDestroyTextureAtlas

function

This function destroys a texture atlas and frees all associated GPU and CPU resources.

XPLMDestroyTextureAtlas(
    inTextureAtlas     -- XPLMTextureAtlasRef
)

See associated types:

XPLMTextureAtlasAddImageFile

function

This function loads a PNG image file and adds it to the atlas as a single image. Call this before XPLMTextureAtlasBake.

  • inImageFilePath: the file system path to a PNG file.

Returns the zero-based image index assigned to this image.

-- returns int -> assign to local/var
local my_result = XPLMTextureAtlasAddImageFile(
    inTextureAtlas,     -- XPLMTextureAtlasRef
    inImageFilePath     -- string
)

See associated types:

XPLMTextureAtlasAddImageFileSet

function

This function loads a PNG image file and subdivides it into a grid of cells, adding each cell to the atlas as a separate image. This is useful for sprite sheets and image strip assets. Call this before XPLMTextureAtlasBake.

  • inImageFilePath: the file system path to a PNG file.
  • inCellsX: the number of columns to divide the image into.
  • inCellsY: the number of rows to divide the image into.

Returns the zero-based image index of the first cell (top-left). Subsequent cells are numbered in row-major order: index + y * inCellsX + x.

-- returns int -> assign to local/var
local my_result = XPLMTextureAtlasAddImageFileSet(
    inTextureAtlas,     -- XPLMTextureAtlasRef
    inImageFilePath,    -- string
    inCellsX,           -- int
    inCellsY            -- int
)

See associated types:

XPLMTextureAtlasAddImage

function

This function adds a single image from raw pixel data to the atlas. The pixel data must be RGBA format, 4 bytes per pixel, with rows ordered from top to bottom. Call this before XPLMTextureAtlasBake.

  • inImage: pointer to the raw RGBA pixel data.
  • inWidth: the image width in pixels.
  • inHeight: the image height in pixels.

Returns the zero-based image index assigned to this image.

-- returns int -> assign to local/var
local my_result = XPLMTextureAtlasAddImage(
    inTextureAtlas,    -- XPLMTextureAtlasRef
    inImage,           -- unsigned char
    inWidth,           -- int
    inHeight           -- int
)

See associated types:

XPLMTextureAtlasBake

function

This function packs all previously added images into a GPU texture. You must call this after adding all images and before any draw calls. Once baked, you cannot add more images to the atlas.

XPLMTextureAtlasBake(
    inTextureAtlas     -- XPLMTextureAtlasRef
)

See associated types:

XPLMTextureAtlasGetImageWidth

function

This function returns the width in pixels of a single image (or cell) in the atlas.

Returns the image width in pixels.

-- returns int -> assign to local/var
local my_result = XPLMTextureAtlasGetImageWidth(
    inTextureAtlas,    -- XPLMTextureAtlasRef
    inImageIndex       -- int
)

See associated types:

XPLMTextureAtlasGetImageHeight

function

This function returns the height in pixels of a single image (or cell) in the atlas.

Returns the image height in pixels.

-- returns int -> assign to local/var
local my_result = XPLMTextureAtlasGetImageHeight(
    inTextureAtlas,    -- XPLMTextureAtlasRef
    inImageIndex       -- int
)

See associated types:

XPLMTextureAtlasDrawAt

function

This function draws an atlas image at its native resolution. The image is positioned with its top-left corner at (inX, inY) and extends rightward and downward by its native pixel dimensions.

  • inTintColor: a color that is multiplied with the texture. Use XPLMMakeColor(1, 1, 1, 1) for no tinting.
  • inX: the left edge of the image, in panel coordinates.
  • inY: the top edge of the image, in panel coordinates.
XPLMTextureAtlasDrawAt(
    inTextureAtlas,    -- XPLMTextureAtlasRef
    inImageIndex,      -- int
    inTintColor,       -- see uint32_t / XPLMMakeColor
    inX,               -- float
    inY                -- float
)

See associated types:

XPLMTextureAtlasDrawIn

function

This function draws an atlas image scaled to fill a rectangular region. The image is stretched or compressed to exactly match the specified bounds.

  • inTintColor: a color that is multiplied with the texture.
  • inLeft, inTop, inRight, inBottom: the bounding rectangle in panel coordinates.
XPLMTextureAtlasDrawIn(
    inTextureAtlas,    -- XPLMTextureAtlasRef
    inImageIndex,      -- int
    inTintColor,       -- see uint32_t / XPLMMakeColor
    inLeft,            -- float
    inTop,             -- float
    inRight,           -- float
    inBottom           -- float
)

See associated types:

XPLMTextureAtlasDrawStretched

function

This function draws an atlas image using 9-slice scaling into a rectangular region. The image is divided into a 3x3 grid (each slice being one third of the original width and height). The four corner slices are drawn at their native size, the four edge slices are stretched along one axis, and the center slice is stretched in both directions. This preserves corners and borders when scaling UI elements like buttons or panels.

  • inTintColor: a color that is multiplied with the texture.
  • inLeft, inTop, inRight, inBottom: the bounding rectangle in panel coordinates.
XPLMTextureAtlasDrawStretched(
    inTextureAtlas,    -- XPLMTextureAtlasRef
    inImageIndex,      -- int
    inTintColor,       -- see uint32_t / XPLMMakeColor
    inLeft,            -- float
    inTop,             -- float
    inRight,           -- float
    inBottom           -- float
)

See associated types:

XPLMTextureAtlasDrawScaled

function

This function draws an atlas image with arbitrary scaling, rotation, and positioning. The image is placed so that the atlas-space pivot point (inXAtlas, inYAtlas) aligns with the panel-space position (inXPanel, inYPanel), then scaled and rotated around that point.

  • inTintColor: a color that is multiplied with the texture.
  • inXPanel, inYPanel: the destination point in panel coordinates.
  • inXAtlas, inYAtlas: the pivot point within the image, in pixels from the image's bottom-left corner.
  • inXScale, inYScale: horizontal and vertical scale factors. 1.0 draws at native resolution.
  • inRotateCW: clockwise rotation in degrees around the pivot point.
XPLMTextureAtlasDrawScaled(
    inTextureAtlas,    -- XPLMTextureAtlasRef
    inImageIndex,      -- int
    inTintColor,       -- see uint32_t / XPLMMakeColor
    inXPanel,          -- float
    inYPanel,          -- float
    inXAtlas,          -- float
    inYAtlas,          -- float
    inXScale,          -- float
    inYScale,          -- float
    inRotateCW         -- float
)

See associated types:

XPLMTextureAtlasDrawMesh

function

This function draws an atlas image onto an arbitrary triangle-strip mesh. Each vertex specifies both a panel-space position and a normalized texture coordinate within the image (0.0 to 1.0). This gives you full control over how the image is mapped onto geometry.

Texture coordinates are relative to the image, not to the atlas sheet; the mapping onto wherever the image was packed is applied for you, exactly as it is for the other atlas drawing routines. One consequence is that the same vertex array can be drawn with any inImageIndex - you do not have to rebuild the mesh to switch images.

Coordinates outside 0.0 to 1.0 are not clamped, and will sample whatever neighboring image shares the atlas sheet. Keep them in range.

  • inTintColor: a color that is multiplied with the texture.
  • vertices: an array of XPLMTextureVertex_t vertices defining the triangle strip.
  • count: the number of vertices. Must be at least 3.
XPLMTextureAtlasDrawMesh(
    inTextureAtlas,    -- XPLMTextureAtlasRef
    inImageIndex,      -- int
    inTintColor,       -- see uint32_t / XPLMMakeColor
    vertices,          -- see XPLMTextureVertex_t
    count              -- ArraySize
)

See associated types: