TGA and XBM Image Loading — LWXGL External Image API

LWXGL supports two external image formats: indexed-color TGA (Truevision TARGA, type 1 raw or type 9 RLE) and 1-bit XBM (X BitMap). Both are decoded into the same internal pixel store — an array of palette indices — and then drawn into image elements with DrawIndexedTGA. A capture function lets you snapshot any rectangular region of the back-buffer as a TGA binary.

TGA Format Requirements

LWXGL only accepts TGA files that meet all of the following criteria:

Color-map type (header[1]): 1 (color-mapped)
Image type (header[2]): 1 (uncompressed) or 9 (RLE-compressed)
Color-map origin (header[3-4]): 0 (must start at entry 0)
Color-map length (header[5]): 16 (exactly 16 palette entries)
Color-map entry size (header[6-7]): 0, 24 (24-bit BGR entries)
Bits per pixel (header[16]): 8
Image descriptor (header[17]): 32 (top-left origin) or 0 (bottom-left origin)

Files that do not match every field listed above are rejected with return code 2. Use an image editor that can export 8bpp indexed TGA with a 16-entry palette (e.g. GIMP with an indexed-color image).

AllocateTGA

int AllocateTGA(const char* name, const char* path,
                int change_palette, int transparent);

Loads an indexed TGA file from disk and stores it in an internal hash map under the key name. The decoded pixel data (palette indices) and 48-byte BGR palette are malloc’d and retained until DeleteTGA or program exit. If a TGA with the same name already exists it is freed and replaced. Return values:

Value	Meaning
`0`	Success
`1`	File not found / could not open
`2`	Invalid TGA format (header check failed)

name

const char*

required

Unique string key used to reference this image in subsequent calls.

path

const char*

required

Filesystem path to the .tga file.

change_palette

int

required

If non-zero, DrawIndexedTGA will replace the global 16-color palette with the palette embedded in this TGA file every time it is drawn.

transparent

int

required

Palette index to treat as fully transparent (skipped when drawing). Pass -1 to disable transparency.

DrawIndexedTGA

void DrawIndexedTGA(int id, int x, int y, const char* name);

Draws a previously allocated TGA into image element id at offset (x, y) (image-local coordinates). Pixels equal to the transparent index are skipped. Pixels outside the image bounds are clipped. If the TGA was loaded with change_palette = 1, the global palette is updated entry-by-entry before drawing, with a full RedrawAllImages triggered on the last entry.

int

required

Element slot index of the target image element.

int

required

X offset within the image where the TGA top-left corner is placed.

int

required

Y offset within the image where the TGA top-left corner is placed.

name

const char*

required

Key string used when the TGA was allocated. If not found, the call is a no-op.

CreateTGAImage

int CreateTGAImage(int id, int x, int y, const char* path, int change_palette);

Convenience wrapper. Allocates the TGA (if not already loaded), creates an image element sized exactly to the TGA dimensions, draws the TGA at offset (0, 0), and calls UpdateImage. The internal allocation key is "TGAImage_" + path.

int

required

Element slot index to assign the new image element.

int

required

Window X position of the image element.

int

required

Window Y position of the image element.

path

const char*

required

Filesystem path to the .tga file.

change_palette

int

required

Passed through to AllocateTGA. See AllocateTGA for details.

Returns 0 on success, or the AllocateTGA error code (1 or 2) on failure.

AllocateMemoryTGA

int AllocateMemoryTGA(const char* name, const char* buffer,
                      int size, int change_palette, int transparent);

Loads a TGA from an in-memory buffer rather than from disk. Internally, the buffer is written to an anonymous memfd_create file descriptor and passed to AllocateTGA via the /proc/self/fd/<n> path. Return values are identical to AllocateTGA.

Due to a quirk in the source implementation, AllocateMemoryTGA passes its transparent and change_palette arguments to AllocateTGA in swapped order: transparent fills the change_palette slot and change_palette fills the transparent slot. The result is that the change_palette parameter of AllocateMemoryTGA controls palette-index transparency, and the transparent parameter controls whether the global palette is replaced on draw. This matches the actual runtime behavior and is documented here accurately.

name

const char*

required

Unique string key to store the loaded image under.

buffer

const char*

required

Pointer to the raw TGA file bytes in memory.

size

int

required

Number of bytes in the buffer.

change_palette

int

required

Due to the argument swap described above, this value is received by AllocateTGA’s transparent parameter — it is treated as the palette index to skip when drawing (or -1 for no transparency).

transparent

int

required

Due to the argument swap described above, this value is received by AllocateTGA’s change_palette parameter — if non-zero, DrawIndexedTGA will replace the global palette with the TGA’s embedded palette every time it draws.

AllocateMemoryTGA uses memfd_create, which is Linux-specific. It is not available on BSD or macOS.

DeleteTGA

void DeleteTGA(const char* name);

Frees the palette and pixel data for the named TGA and removes it from the internal map. Safe to call on a name that has not been loaded (no-op).

name

const char*

required

Key string of the TGA to remove.

AllocateXBM

int AllocateXBM(const char* name, const char* path,
                int colors, int transparent);

Loads a 1-bit XBM file and stores it in the same internal map as TGAs (so it can be drawn with DrawIndexedTGA). Each 1-bit pixel is mapped to one of two palette indices packed into the colors byte:

High nibble of colors (H(colors)) → palette index for bit-value 1
Low nibble of colors (L(colors)) → palette index for bit-value 0

The transparent parameter controls which bit value is treated as transparent:

`transparent`	Transparent pixel
`1`	Bit-value 1 (high nibble index)
`0`	Bit-value 0 (low nibble index)
any other	No transparency

Returns 1 on success, 0 on error (XBM file could not be read).

name

const char*

required

Unique string key for the loaded bitmap.

path

const char*

required

Filesystem path to the .xbm file.

colors

int

required

Two palette indices packed into one byte. High nibble = color for 1 bits; low nibble = color for 0 bits. Example: 0xFC maps 1→CLR_WHITE(15), 0→CLR_CYAN(12).

transparent

int

required

1 = 1-bits are transparent, 0 = 0-bits are transparent, any other = no transparency.

CreateXBMImage

int CreateXBMImage(int id, int x, int y, const char* path, int colors);

Convenience wrapper for XBM loading. Allocates the XBM (if not already loaded), creates an image element sized to the bitmap, draws it, and calls UpdateImage. The key is "XBMImage_" + path. Returns 1 on success, 0 on failure.

int

required

Element slot index to assign the new image element.

int

required

Window X position of the image element.

int

required

Window Y position of the image element.

path

const char*

required

Filesystem path to the .xbm file.

colors

int

required

Color mapping byte; same as AllocateXBM.

CaptureRegion

unsigned char* CaptureRegion(int x, int y, unsigned short w, unsigned short h);

Reads a w × h pixel rectangle from the back-buffer starting at window coordinates (x, y) and encodes it as a valid indexed TGA binary in a freshly malloc’d buffer. The returned buffer layout:

Offset	Size	Content
`0`	18 bytes	TGA header (type 1, 8bpp, top-left origin)
`18`	48 bytes	16-entry BGR palette (current LWXGL palette)
`66`	`w * h` bytes	Pixel data, row-major, each byte a palette index

Total size: 66 + w * h bytes. The caller is responsible for calling free() on the returned pointer.

int

required

Left edge of the capture region, in window coordinates.

int

required

Top edge of the capture region, in window coordinates.

unsigned short

required

Width of the capture region in pixels.

unsigned short

required

Height of the capture region in pixels.

You must free() the buffer returned by CaptureRegion when you are done with it. Failing to do so is a memory leak.

Code Example

#include "libLWXGL.h"
#include <stdio.h>
#include <stdlib.h>

void save_screenshot(void) {
    // Capture the top-left 160×100 pixels of the window
    unsigned char* tga = CaptureRegion(0, 0, 160, 100);

    FILE* f = fopen("screenshot.tga", "wb");
    if (f) {
        fwrite(tga, 1, 66 + 160 * 100, f);
        fclose(f);
    }

    free(tga);
}

void on_frame(int tick, float dt) {
    // Draw TGA sprite into image element 2 at (10, 10)
    DrawIndexedTGA(2, 10, 10, "player");
    UpdateImage(2);
}

int main(void) {
    CreateWindow(320, 200, "TGA Demo", CLR_BLACK, FLAG_NONE);

    // Load a sprite TGA; palette index 0 is transparent
    if (AllocateTGA("player", "assets/player.tga", 0, 0) != 0) {
        return 1;
    }

    // Create an image element sized to the TGA (assume 32×32)
    CreateImage(2, 10, 10, 32, 32);

    MainWindowLoop(60, on_frame);

    DeleteTGA("player");
    TerminateWindow();
    return 0;
}

Window & Lifecycle

UI Elements

Graphics & Images

Events & Input

Utilities

TGA and XBM Image Loading — LWXGL External Image API

TGA Format Requirements

AllocateTGA

DrawIndexedTGA

CreateTGAImage

AllocateMemoryTGA

DeleteTGA

AllocateXBM

CreateXBMImage

CaptureRegion

Code Example

Build docs developers (and LLMs) love

Window & Lifecycle

UI Elements

Graphics & Images

Events & Input

Utilities

Documentation Index

​TGA Format Requirements

​AllocateTGA

​DrawIndexedTGA

​CreateTGAImage

​AllocateMemoryTGA

​DeleteTGA

​AllocateXBM

​CreateXBMImage

​CaptureRegion

​Code Example

Build docs developers (and LLMs) love

TGA Format Requirements

AllocateTGA

DrawIndexedTGA

CreateTGAImage

AllocateMemoryTGA

DeleteTGA

AllocateXBM

CreateXBMImage

CaptureRegion

Code Example