Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/DREssedAlarm184/LWXGL/llms.txt

Use this file to discover all available pages before exploring further.

LWXGL supports loading type-1 (palette-indexed) TGA images with an 8-bit color depth and a 16-entry BGR palette. These can be rendered onto image canvases, optionally replacing the global LWXGL palette so the image is displayed with its own colors.

​
TGA file format requirements

LWXGL validates the TGA header on load. The file must meet all of the following criteria:
FieldRequired value
Image type (byte 2)1 — color-mapped (palette-indexed)
Color map type (byte 1)1 — color map present
Color map length (bytes 5–6, little-endian)16 entries
Color map entry size (byte 7)24 bits (BGR)
Pixel depth (byte 16)8 bits
Image descriptor (byte 17)0 (bottom-up) or 32 (top-down)
Width / Height (bytes 12–15)Little-endian 16-bit each
The palette is read as 16 × 3-byte BGR triples (48 bytes total) immediately after the image ID field.
LWXGL validates the TGA header on load and returns an error code if the format doesn’t match. Use a graphics editor that supports indexed 8-bit TGA export with exactly 16 colors, such as GIMP (export as “raw color map TGA” with 256-color mode reduced to 16 entries).

​
Quick path — GCreateTGAImage

int GCreateTGAImage(int id, int x, int y, const char* path, int change_palette);
The simplest way to display a TGA file: loads the image from path, creates an image canvas element at (x, y) sized to match the image dimensions, draws the image into it, and flushes it to screen — all in one call. change_palette = 1 replaces the LWXGL 16-color palette with the palette embedded in the TGA file. Return values:
CodeMeaning
0Success
1File could not be opened
2Header validation failed (unsupported format)
int r = GCreateTGAImage(20, 100, 100, "assets/sprite.tga", 0);
if (r != 0) {
    fprintf(stderr, "TGA load failed: %d\n", r);
}

​
Two-step path — allocate then draw

int  GAllocateTGA(const char* name, const char* path, int change_palette);
void GDrawIndexedTGA(int id, int x, int y, const char* name);
void GDeleteTGA(const char* name);
For images that need to be redrawn every frame (such as animated sprites), the two-step path avoids reloading from disk repeatedly. GAllocateTGA reads the file into a named in-memory store. GDrawIndexedTGA then blits the pixels from that store into any image canvas at any position. The name parameter is a user-chosen string key used to retrieve the allocation later. 
// Load once at startup:
int r = GAllocateTGA("player", "assets/player.tga", 0);
if (r != 0) { /* handle error */ }

// Draw into canvas id=10 each frame:
GClearImage(10, 0);
GDrawIndexedTGA(10, px, py, "player");
GUpdateImage(10);

// Free when the image is no longer needed:
GDeleteTGA("player");
GDrawIndexedTGA clips pixels that fall outside the canvas bounds, so you can safely draw a sprite partially off-screen. GDeleteTGA frees the pixel and palette buffers associated with the name. Calling it with a name that was never allocated is a no-op.

​
Palette import

When change_palette = 1 is set (either via GAllocateTGA or GCreateTGAImage), calling GDrawIndexedTGA iterates over all 16 palette entries from the TGA file and calls GPaletteModify for each one. The BGR values in the TGA palette are converted to RGB before being applied. After the last entry (index 15), GPaletteModify is called with redraw = 1, which triggers GRedrawAllImages to refresh every canvas so the new colors take effect immediately.
If change_palette = 1 is used with multiple TGA images that have different embedded palettes, drawing one image will overwrite the palette established by the previous one. To avoid unexpected color shifts, either use a single shared palette across all TGA assets, or only enable palette import for the image that defines the authoritative palette for your scene.

Build docs developers (and LLMs) love

Get started for freeTalk to us