Using the LibTarga library
CS 559
Mark Pingel

updated for FlTk 1.11 by Mike Gleicher,
September 20, 2001

updated by Chi Man Liu,
September 11, 2007


LibTarga is a library for reading and writing images in the TARGA image file format. It was written by Alex Mohr for use by students in CS559, and for other graphics projects.

If you want to get your own copy of LibTarga, it actually only consists of

LibTarga stores TARGA images as 1-dimensional arrays of unsigned bytes (unsigned char*). Each pixel is represented by either 3 or 4 bytes, depending on whether we want to support an alpha channel. For 3 bytes per pixel, the bytes represent the R, G, B values (in that order) of the pixel. For 4 bytes, they are RGBA (premultiplied).

IMPORTANT: When reading and writing images using the LibTarga functions, the lower-left hand corner of an image is treated as location 0,0. The image array is loaded left to right from bottom to top. However, image handling functions of other libraries may use a different coordinate system (e.g. FLTK uses the upper-left hand corner as 0,0). In that case, the image array should be flipped to match the target coordinate system.

Note: LibTarga does not deal with premultiplied TGA files correctly.

List of Functions

void* tga_create(int width, int height, unsigned int format);
Creates a new image (with uninitialized pixel values) with specified width and height. format specifies the number of bits used by each pixel, which can be TGA_TRUECOLOR_24 or TGA_TRUECOLOR_32. NULL is returned if there was an error.

void* tga_load(const char* file, int* width, int* height, unsigned int format);
Loads an image from a file. width and height are pointers to integers whose values will be filled in appropriately by the function. format is the format we wish it being loaded. Possible values are TGA_TRUECOLOR_24 and TGA_TRUECOLOR_32. NULL is returned if there was an error.

int tga_write_raw(const char* file, int width, int height, unsigned char* dat, unsigned int format);
Writes an image to a TGA file. dat is the array holding the image data. width and height are the known dimensions of the image. "format" is the format we wish it being stored. Possible values are TGA_TRUECOLOR_24 and TGA_TRUECOLOR_32. The output file is always non-premultiplied. This function returns 1 if successful and 0 otherwise.

int tga_write_rle(const char* file, int width, int height, unsigned char* dat, unsigned int format);
Writes an image to TGA file. This function is the same as tga_write_raw except that the image is written out in run-length encoded format.

int tga_get_last_error();
Returns the error code of the last error occurred when calling the above functions.

const char* tga_error_string(int error_code);
Returns the string description of an error code.


Reading a TARGA image

The following sample code reads an image from a file.

unsigned char* targaimage;
int wdt, hgt;
targaimage = (unsigned char*)tga_load("input.tga", &wdt, &hgt, TGA_TRUECOLOR_32);

To check for errors, we can write:

if (targaimage == NULL)
  printf("Failed to read image!\n");

Remember to deallocate the memory that tga_load allocates:


Writing a TARGA iamge

The following sample code writes an image to a file.

if (!tga_write_raw("output.tga", wdt, hgt, targaimage, TGA_TRUECOLOR_32)) {
  printf("Failed to write image!\n");

Flipping an image

We mentioned that some libraries (e.g. FLTK) handle images using a different coordinate system. The following sample code flips an image upside down. Assume that the image's format is TGA_TRUECOLOR_32.

unsigned char *tmp = new unsigned char[wdt * hgt * 4];

for (unsigned int i = 0; i < hgt; i++)
  for (unsigned int j = 0; j < wdt; j++)
    tmp[(i*wdt+j)*4] = targaimage[((hgt-i-1)*wdt+j)*4];
    tmp[(i*wdt+j)*4+1] = targaimage[((hgt-i-1)*wdt+j)*4+1];
    tmp[(i*wdt+j)*4+2] = targaimage[((hgt-i-1)*wdt+j)*4+2];
    tmp[(i*wdt+j)*4+3] = targaimage[((hgt-i-1)*wdt+j)*4+3];

delete [] targaimage;
targaimage = tmp;