Chapter 1. Overview

Libtga is only a small library and thus has only a small API. Normally a user program only has to call three functions for reading or writing an image.

The first is TGAOpen() or TGAOpenFd(), respectively. These functions both initialize and return a pointer to a TGA structure or NULL if any error occurred. Additionally you can check the tga->last value. For example:

{
        TGA *tga;
	TGAData data;

	tga = TGAOpen("image.tga", "r");
	if(!tga || tga->last != TGA_OK) {
	        /* error handling goes here */
	}
}

Then a call to TGAReadImage() with the appropriate parameters follows. This reads in the whole image at once (if you specify the TGA_IMAGE_DATA flag). If you need to read the image in smaller chunks, i.e. scanlines, you need to do things manually by calling TGAReadHeader(), optionally TGAReadImageId() and TGAReadColorMap(), and TGAReadImage(). (Of course you can also let TGAReadImage read the header and the id and then call TGAReadScanlines().)

	/* the TGA_IMAGE_ID tells the TGAReadImage() to read the image
	id, the TGA_IMAGE_DATA tells it to read the whole image data
	and any color map data if existing. NOTE: the image header is
	read always no matter what options were specified.
	At last we pass over the TGA_RGB flag so the returned data is
	in RGB format and not BGR */
	data->flags = TGA_IMAGE_DATA | TGA_IMAGE_ID | TGA_RGB;
	if(TGAReadImage(tga, & data) != TGA_OK) {
	     /* error handling goes here */
	}

	/* ... */
}

At last close the file descriptor and free all memory:

	/* and finally cleanup */
	TGAClose(tga);

	/* NOTE: you must free the TGAData structure manually because
	   you probably want to use the data it contains after a call to 
	   TGAClose() 
        */
}