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 two bitmap formats for static image assets: TGA (8-bit indexed / palette-mapped Targa) and XBM (monochrome X11 bitmap). Both formats are decoded into an internal cache keyed by a caller-supplied name string, then blitted into any ImageElement canvas with DrawIndexedTGA. Convenience functions (CreateTGAImage, CreateXBMImage) wrap the full allocate → create → draw → update pipeline into a single call. A CaptureRegion function is also provided to snap a rectangular region of the back-buffer back into a TGA-formatted byte array for screenshots or compositing.

​
AllocateTGA

Loads an 8-bit indexed TGA file from disk into the internal TGA cache. 
int AllocateTGA(const char* name, const char* path, int change_palette, int transparent);
LWXGL validates that the file is an 8-bit, 16-color indexed TGA (type 1 uncompressed or type 9 RLE) before loading. The palette must be 16 entries × 3 bytes (48 bytes total). If a TGA is already cached under name, it is freed before the new one is stored. Return values:
ValueMeaning
0Success.
1File not found or could not be opened.
2Invalid TGA format (wrong bit depth, type, or palette size).
​
name
const char*
required
Unique cache key used to reference this TGA in subsequent calls. Must be a null-terminated string.
​
path
const char*
required
Filesystem path to the .tga file.
​
change_palette
int
required
If non-zero, calling DrawIndexedTGA with this TGA will replace the global 16-entry LWXGL palette with the colors embedded in the TGA file.
​
transparent
int
required
Palette index (0–15) to treat as transparent when drawing. Pixels with this index are skipped. Pass -1 for no transparency.

​
AllocateMemoryTGA

Identical to AllocateTGA but reads TGA data from a memory buffer instead of a file path. 
int AllocateMemoryTGA(const char* name, const char* buffer, int size, int change_palette, int transparent);
Internally creates an anonymous memfd file descriptor, writes buffer into it, then calls AllocateTGA via the /proc/self/fd/N path. The file descriptor is closed immediately after loading. Useful for embedding TGA assets in compiled code as byte arrays or for loading images received over a network.
Due to a parameter-swap bug in the implementation, change_palette and transparent are passed to the internal AllocateTGA call in reversed order. In practice, the value you pass as change_palette is used as the transparent index, and the value you pass as transparent is used as the change_palette flag. Pass transparent where the signature says change_palette and vice versa until this is corrected upstream.
​
name
const char*
required
Unique cache key for the loaded TGA.
​
buffer
const char*
required
Pointer to raw TGA file bytes in memory.
​
size
int
required
Number of bytes in buffer.
​
change_palette
int
required
Non-zero to apply the TGA’s embedded palette to the global LWXGL palette on draw. Note: due to the parameter-swap bug described above, pass this value in the transparent argument position to get the intended behavior.
​
transparent
int
required
Palette index (0–15) to treat as transparent, or -1 for none. Note: due to the parameter-swap bug, pass this value in the change_palette argument position to get the intended behavior.

​
DeleteTGA

Frees the palette and pixel buffers associated with a named TGA cache entry. 
void DeleteTGA(const char* name);
If name does not exist in the cache the call is a safe no-op. After deletion, any subsequent DrawIndexedTGA call using the same name will silently return without drawing anything.
​
name
const char*
required
Cache key of the TGA to free.

​
DrawIndexedTGA

Renders a previously allocated TGA into an image element’s pixel buffer at a given offset. 
void DrawIndexedTGA(int id, int x, int y, const char* name);
Pixel values from the TGA’s pixel array are written directly into the ImageElement data buffer. If change_palette was set when the TGA was allocated, the 16-entry global palette is updated from the TGA’s embedded BGR palette data before the pixels are drawn — each entry is applied sequentially and RedrawAllImages() is triggered on the final entry (index 15). Pixels whose index matches the transparent value are skipped. Pixels that fall outside the element bounds are clipped.
Call UpdateImage(id) after DrawIndexedTGA to push the pixel buffer changes to the X11 pixmap and make them visible on screen.
​
id
int
required
ID of the target ImageElement.
​
x
int
required
Horizontal offset within the image element where the TGA top-left should land.
​
y
int
required
Vertical offset within the image element where the TGA top-left should land.
​
name
const char*
required
Cache key of the previously allocated TGA to draw.

​
CreateTGAImage

Convenience function: loads a TGA from path, creates an image element sized to the TGA, draws it, and calls UpdateImage. 
int CreateTGAImage(int id, int x, int y, const char* path, int change_palette);
Internally generates the cache key "TGAImage_" + path. If a TGA is already cached under that key (e.g., from a previous call with the same path), the allocation step is skipped. The transparent index is always set to -1 (no transparency). Returns 0 on success or the AllocateTGA error code on failure.
​
id
int
required
ID to assign to the newly created image element.
​
x
int
required
X position of the image element within the window.
​
y
int
required
Y position of the image element within the window.
​
path
const char*
required
Path to the .tga file. Also used as part of the internal cache key.
​
change_palette
int
required
Non-zero to apply the TGA’s embedded palette to the global LWXGL palette.

​
AllocateXBM

Loads a monochrome XBM bitmap and stores it in the TGA cache as a two-color indexed image. 
int AllocateXBM(const char* name, const char* path, int colors, int transparent);
Uses Xlib’s XReadBitmapFileData to parse the XBM. Each bit in the bitmap is mapped to one of two palette indices encoded in the colors parameter: the upper nibble becomes the foreground color (bit = 1) and the lower nibble the background color (bit = 0). Return values:
ValueMeaning
1Success.
0File not found or XBM parse error.
​
name
const char*
required
Cache key for the loaded bitmap (shared with the TGA cache).
​
path
const char*
required
Filesystem path to the .xbm file.
​
colors
int
required
Packed byte: upper nibble = foreground palette index (set bits), lower nibble = background palette index (clear bits). Example: 0xF0 = white foreground, black background.
​
transparent
int
required
Controls which color is transparent when drawn. 1 = foreground index is transparent, 0 = background index is transparent, any other value = no transparency.

​
CreateXBMImage

Convenience function: loads an XBM, creates an image element, draws it, and calls UpdateImage. 
int CreateXBMImage(int id, int x, int y, const char* path, int colors);
Generates the cache key "XBMImage_" + path and skips re-allocation if the key is already cached. The transparent index is set to -1 (no transparency). Returns 1 on success or 0 on XBM load failure.
​
id
int
required
ID to assign to the newly created image element.
​
x
int
required
X position of the image element within the window.
​
y
int
required
Y position of the image element within the window.
​
path
const char*
required
Path to the .xbm file.
​
colors
int
required
Packed foreground/background palette indices (upper/lower nibble).

​
CaptureRegion

Reads a rectangular region of the LWXGL back-buffer and returns it as a heap-allocated TGA file image. 
unsigned char* CaptureRegion(int x, int y, unsigned short w, unsigned short h);
The returned buffer is a complete, valid TGA file in memory: 18 bytes of header, followed by 48 bytes of palette data (queried from the current LWXGL colormap), followed by w × h bytes of palette-indexed pixel data. The pixel data is stored top-to-bottom (origin flag byte 0x20 in the header). The buffer is heap-allocated with calloc — the caller is responsible for calling free() on it.
The returned buffer must be freed by the caller. Failing to call free() on it will leak memory equal to 66 + w * h bytes per capture.
​
x
int
required
Left edge of the capture region in back-buffer coordinates.
​
y
int
required
Top edge of the capture region in back-buffer coordinates.
​
w
unsigned short
required
Width of the capture region in pixels.
​
h
unsigned short
required
Height of the capture region in pixels.
Returns: Pointer to a heap buffer containing a complete TGA file, or NULL on allocation failure.

​
Code example

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

int main(void) {
    CreateWindow(400, 300, "TGA Demo", CLR_BLACK);

    // Load a 16-color indexed TGA; apply its palette to the global palette
    if (AllocateTGA("tileset", "assets/tileset.tga", 1, 0) != 0) {
        fprintf(stderr, "Failed to load tileset.tga\n");
        return 1;
    }

    // Create an image element sized manually and blit the TGA into it
    CreateImage(10, 10, 10, 128, 128);
    DrawIndexedTGA(10, 0, 0, "tileset");
    UpdateImage(10);

    // Load a monochrome XBM icon — white on black, background transparent
    CreateXBMImage(20, 160, 10, "assets/icon.xbm", 0xF0);

    // After a 3-second delay, capture the whole window and write it to disk
    NewQueuedTask(TASK_RUN_AFTER, 3.0, []() {
        unsigned char* screenshot = CaptureRegion(0, 0, 400, 300);
        if (screenshot) {
            FILE* f = fopen("screenshot.tga", "wb");
            fwrite(screenshot, 1, 66 + 400 * 300, f);
            fclose(f);
            free(screenshot);
        }
    });

    MainWindowLoop(30, NULL);

    DeleteTGA("tileset");
    TerminateWindow();
    return 0;
}
When loading many TGA assets at startup, call AllocateTGA for all of them before calling CreateWindow — or at least before the first DrawIndexedTGA — to batch-load assets without any per-frame stall.

Build docs developers (and LLMs) love

Get started for freeTalk to us