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’s TGA API loads type-1 (palette-indexed, 8bpp) TGA files into memory and renders them onto image canvas elements. Because TGA assets store raw palette indices as pixel values — exactly the same representation LWXGL uses internally — blitting them onto an image canvas is a direct memory copy with no color conversion. TGA files can optionally replace the global 16-color palette with the palette embedded in the file at draw time.
GAllocateTGA
int GAllocateTGA(const char* name, const char* path, int change_palette);
path into an in-memory store keyed by name. If a TGA with the same name already exists, it is freed before the new one is loaded.
Parameters
| Parameter | Type | Description |
|---|
name | const char* | Unique string key for this TGA asset — used with GDrawIndexedTGA and GDeleteTGA |
path | const char* | Filesystem path to the TGA file |
change_palette | int | If non-zero, the TGA’s embedded palette will be applied to the global LWXGL palette each time this asset is drawn via GDrawIndexedTGA |
Returns
| Value | Meaning |
|---|
0 | Success |
1 | File could not be opened |
2 | File header does not match the expected format |
| Header byte | Required value | Meaning |
|---|
header[1] | 1 | Color-map type: palette present |
header[2] | 1 | Image type: uncompressed color-mapped |
header[3] | 0 | Color-map first entry index (low byte) — must be 0 |
header[4] | 0 | Color-map first entry index (high byte) — must be 0 |
header[5] | 16 | Number of palette entries (low byte) — exactly 16 |
header[6] | 0 | Number of palette entries (high byte) — must be 0 |
header[7] | 24 | 24-bit (BGR) palette entries |
header[16] | 8 | 8 bits per pixel |
header[17] | 32 or 0 | Image descriptor: 32 = top-to-bottom pixel order, 0 = bottom-to-top |
2.
GDrawIndexedTGA
void GDrawIndexedTGA(int id, int x, int y, const char* name);
id, starting at offset (x, y) within the canvas. Pixels that fall outside the canvas bounds are clipped and discarded.
If the TGA was allocated with change_palette=1, its embedded palette is applied to the global LWXGL palette before the pixels are copied: GPaletteModify is called for each of the 16 entries, with redraw=1 on the final entry to flush all changes at once with a single GRedrawAllImages call.
Parameters
| Parameter | Type | Description |
|---|
id | int | Target image canvas element ID |
x | int | Horizontal offset within the canvas |
y | int | Vertical offset within the canvas |
name | const char* | TGA asset key as passed to GAllocateTGA |
The pixel buffer filled by GDrawIndexedTGA stores palette indices from the TGA file, not resolved RGB values. If the TGA was saved against a different palette than is currently active and change_palette=0, colors will appear incorrect when the canvas is rendered.
GDrawIndexedTGA does not call GUpdateImage. You must call GUpdateImage(id) after drawing to push the updated pixel buffer to the screen.
GDeleteTGA
void GDeleteTGA(const char* name);
name does not correspond to any currently allocated asset.
Parameters
| Parameter | Type | Description |
|---|
name | const char* | TGA asset key to free |
GCreateTGAImage
int GCreateTGAImage(int id, int x, int y, const char* path, int change_palette);
GAllocateTGA + GCreateImage + GDrawIndexedTGA + GUpdateImage into a single call. Creates an image canvas element sized exactly to the TGA’s dimensions and draws the image onto it immediately. The internal TGA key used is "TGAImage_" concatenated with path.
If a TGA asset for the given path is already loaded under that key, GAllocateTGA is skipped and the existing asset is used.
Parameters
| Parameter | Type | Description |
|---|
id | int | Element ID to create |
x | int | X position of the image element in the window |
y | int | Y position of the image element in the window |
path | const char* | Filesystem path to the TGA file |
change_palette | int | Forwarded to GAllocateTGA |
Returns
| Value | Meaning |
|---|
0 | Success |
1 | File could not be opened |
2 | Invalid TGA format |
Examples
// Simple one-shot image load
if (GCreateTGAImage(5, 50, 50, "assets/logo.tga", 0) != 0) {
fprintf(stderr, "Failed to load logo.tga\n");
}
// Manual flow for repeated rendering or multiple draws per frame
GAllocateTGA("bg", "assets/background.tga", 1); // Load and use TGA's palette
GCreateImage(6, 0, 0, 320, 200);
// Every frame:
GDrawIndexedTGA(6, 0, 0, "bg");
GUpdateImage(6);
Name TGA assets with descriptive strings rather than raw paths for clarity and reuse across multiple draw calls:GAllocateTGA("player_idle", "assets/player_idle.tga", 0);