TRUEVISION TARGA IMAGE FILE The TGA (Truevision Graphics Adapter) format is used widely in paint, graphics, and imaging applications that require the storage of image data containing up to 32 bits per pixel. Its format is maintained by Truevision, Inc. Although there was only one original TGA file format, applications using it created many different filename extensions. Therefore, .VDA, .ICB, .TGA, and .VST image files created by Truevision applications all are actually in TGA format. Today, the only filename extensions supported are TGA and TPIC on the Macintosh and .TGA on the PC and other platforms. In 1989, the TGA format was revised, and Truevision has chosen to designate the old and new formats as original TGA format and new TGA format, respectively. The original TGA format is very simple in design and quite easy to implement in code. This makes it an appealing format for developers to work with. As the available hardware technology has become more complex, however, additional file format features, such as the storage of gamma and color correction information and pixel aspect ratio data, have become necessary. The new TGA format was created as a wrapper around the original TGA format to add functionality without sacrificing backwards compatibility with older applications. TGA comes in several flavors, the most common of which are usually referred to as the Targa 16, Targa 24, and Targa 32 formats. These designations identify the type of Truevision hardware that created the file, and the numbers indicate the depth (number of bits per pixel) of the image data the files contain. Less commonly found variants include VDA, ICB, and Targa M8. File Structure The original TGA format (v1.0) is structured as follows: HEADER required 18 bytes IMAGE IDENTIFICATION FIELD optional variable-length COLOR MAP DATA optional variable-length IMAGE DATA optional variable-length The new TGA format contains all of the structures included in the original TGA format and also appends several data structures onto the end of the original TGA format. The following structures may follow the bitmap data: DEVELOPER DIRECTORY optional variable-length DEVELOPER AREA optional variable-length EXTENSION AREA optional 495 bytes COLOR-CORRECTION TABLE optional 1000 bytes THUMBNAIL IMAGE optional variable-length SCAN-LINE TABLE optional variable-length FOOTER required 26 bytes Both the new and original TGA format files are identical in structure from the header to the image data area. For this reason, applications that read only original TGA format image files should have no problem reading new TGA format images. All information occurring after the image data may be ignored. Header The file begins with a 18-byte long header defined as follows: CHAR idLength; // Length of idField, in bytes. CHAR cMapPresent; // Declares the inclusion of a palette chunk. CHAR imageType; // Image type. WORD cMapStart; // First index used in palette. WORD cMapLength; // Length of palette, in colors. CHAR cMapDepth; // Bits per color. WORD imageOriginX; // Canvas lower (or upper) left corner (X). WORD imageOriginY; // Canvas lower (or upper) left corner (Y). WORD imageWidth; // Width of image, in pixels. WORD imageHeight; // Height of image, in pixels. CHAR imageDepth; // Bits per pixels. CHAR imageDescriptor; // Image descriptor. Here is a discussion of various fields: idLength This field is a 1-byte unsigned integer, specifying the length of idField in bytes. Its range is 0 to 255. A value of 0 means that no idFiled is included. cMapPresent This one-byte field indicates whether or not a palette is included with the file. If the value is 0, there's no color map included. If the value is 1, a color map is present after the Image Identification Field (or the header if there's no Image Identification Field). If the image is color-mapped, then cMapPresent should be 1. Note that it is entirely possible for direct color images to include a palette block. Value Meaning 0 No color map is included. 1 Color map included. imageType This 1-byte field indicates how pixels and colors are stored within the the file. Supported values are: Value Meaning 0 No image data included. 1 Uncompressed, color-mapped images. 2 Uncompressed, direct color images. 3 Uncompressed, grayscale images. 9 Run-length encoded, color-mapped images. 10 Run-length encoded, direct color images. 11 Run-length encoded, grayscale images. cMapStart Index of the first color map entry, usually 0. Note: if cMapPresent is 0, the content of this field is ignored. cMapLength Count of color map entries (all entries are contiguous). Note: if cMapPresent is 0, the content of this field is ignored. cMapDepth Number of bits in each color map entry. Must be 16 (or 15), 24 or 32. This field may hold a value different of imageDepth. Note: if cMapPresent is 0, the content of this field is ignored. imageOriginX, imageOriginY Horizontal and vertical canvas position on the screen. ImageOriginX always refer to the left-most position of the image rendering starting point. imageOriginY may refer to the top or bottom position of the image rendering starting point depending on bit 5 of the imageDescriptor. imageWidth, imageHeight Image width and height, in pixels. Although most programs out there supports very large images, the specification requires the image to be at most 512 pixels wide by 482 pixels high. imageDepth This 1-byte field specifies the size of each pixel in the Image Data block, including the attribute bits if any. When 24 or 32 the normal conventions apply. For 16 bits each color component is stored as 5 bits and the remaining bit is a binary alpha value. The color components are converted into single byte components by simply shifting each component up by 3 bits (see Color Map Data for more detail). Value Meaning 8 Color-mapped pixels. 16 Direct color, 16 bits per pixel. 24 Direct color, 24 bits per pixel. 32 Direct color, 32 bits per pixel (24 bits per color plus extra attribute byte) imageDescriptor This 1-byte value contains 4 bit fields describing how each pixel of the image should be displayed. Bits Meaning 3-0 Number of attribute bits associated with each pixel, only used if imageDepth is 16 or 32. 4 Reserved, must be set to NULL. 5 Screen origin bit. 0 = Origin in lower left-hand corner. 1 = Origin in upper left-hand corner. Must be 0 for Truevision images. 7-6 Reserved, must be set to NULL. Image Identification Field Right after the header may appear a field of variable-length called the image identification field. Its size is specified by idLength. Programs are free to store whatever information they need in this field, although it is usually omitted. If more than 255 characters are needed, another field is available in the footer. CHAR idField[]; // Image Identification Field, meta data. Color Map Data If cMapPresent is 0, this block doesn't exist. Read cMapLength entries of 2, 3 or 4 bytes each depending on the content of cMapDepth. The first attribute read should be placed at the index specified by cMapStart. Composition of an entry in the color map if cMapDepth is 16: WORD intensities; // Alpha, Red, Green and Blue Bits Meaning 4-0 Blue intensity, 0 to 31 (multiply by 8). 9-5 Green intensity, 0 to 31 (multiply by 8). 14-10 Red intensity, 0 to 31 (multiply by 8). 15 Alpha (0 = see-through, 1 = opaque). Composition of an entry in the color map if cMapDepth is 24: CHAR blue; // Blue intensity, 0 to 255. CHAR green; // Green intensity, 0 to 255. CHAR red; // Red intensity, 0 to 255. Composition of an entry in the color map if cMapDepth is 32: CHAR alpha; // Opacity level, 0 to 255. CHAR blue; // Blue intensity, 0 to 255. CHAR green; // Green intensity, 0 to 255. CHAR red; // Red intensity, 0 to 255. Image Data This block contains the actual image information. If imageType is 0 it doesn't exist. Pixels are stored left to right and top to bottom (or bottom to top, depending on imageOriginY and bit 5 of imageDescriptor). imageType 1: Color-Mapped The block contains imageWidth x imageHeight entries. Each entry in the block refers to a color index in the Color Map. The length of entries depends on the value provided by imageDepth (typically, imageDepth will be 8, resulting in each entry being 1 byte long). imageType 2: Direct Color The block contains imageWidth x imageHeight entries. Each entry is a direct RGB triplet, sometimes followed by an extra attribute (alpha channel) whose length depends on the data provided by bits 3-0 of imageDescriptor. The composition of the entry is identical to the way colors are stored in the Color Map. imageType 3: Grayscale The block contains imageWidth x imageHeight entries. Each entry is a 1-byte gray attribute. Use that value for all RGB channels. imageType 9: Run-Length Color-Mapped The RLE encoding method used by the TGA format encodes runs of identical pixels rather than runs of identical bits or bytes. This achieves a higher compression ratio over a bit-wise or byte-wise RLE scheme, because TGA pixel data often occurs as multiple-byte values rather than single-byte values. Therefore, contiguous runs of identical bytes in TGA image data often occur only in very short lengths. The picture information is stored in packets. Each packet starts with a 8-bit header which contains two bit fields: Bits Meaning 6-0 Pixel count to write, minus 1 (0 to 127 -> 1 to 128). 7 Packet type. 0 = RAW packet, write multiple colors once. 1 = RLE packet, write one color multiple times. For RLE packets, the following entry is the color index in the Color Map to write to the video buffer. For RAW packets read as many entries as specified by the header pixel count. Note that RLE packets may cross scanlines. imageType 10: Run-Length Direct Color The compression scheme is identical to imageType 9, except the information following the packet header is a direct color attribute. Once decompressed the block works exactly like imageType 2. imageType 11: Run-Length Grayscale The compression scheme is identical to imageType 9, except the information following the packet header is a 1-byte gray attribute. Once decompressed the block works exactly like imageType 3. Footer The footer is 26 bytes in length and is always the last piece of information found in a New TGA format file. An original TGA format file may be converted by simply appending the 26-byte footer. It is defined as follows: DWORD extensionOffset; // Extension area offset. DWORD developerOffset; // Developer directory offset. CHAR signature[18]; // New TGA format signature. Here is a discussion of various fields: extensionOffset Contains the offset value of the extension area of the TGA file relative to the beginning of the file (byte 0). If this value is zero, then there is no extension area present in the TGA file. developerOffset Number of bytes relative to the beginning of the file (byte 0) to the first byte of the developer directory. If this value is zero, then the TGA file does not contain a Developer Area. signature The identifying signature is a 18-byte long, NULL-terminated string that reads "TRUEVISION-XFILE." followed by NULL (0x00). Developer Area The developer area is a collection of tags. It begins with a directory that contains all tags used by the TGA file, while the data associated with each tag is stored elsewhere in the file. The directory is structured as follows: WORD directoryLength; // Length of the directory, in entries. TgaTag entry[]; // Tag. Each entry is 10 bytes long and is structured as follows: WORD tagNumber; // ID number of the tag. DWORD dataOffset; // Offset location of the tag data. DWORD dataSize; // Size of the tag data in bytes. Here is a discussion of various fields: tagNumber Identification number of the tag. Tag number values from 0 to 32767 are reserved for developer use, while tag number values 32768 to 65535 are reserved for use by Truevision only. Tags may be registered with the Truevision Developer Services to assure permanent and exclusive use by your application. dataOffset Contains the offset value of the tag data relative to the beginning of the file (byte 0). dataSize Length in bytes of the data. Extension Area The Extension Area is first an additional header of 495 bytes that contains meta data and offsets to new blocks not present in the original TGA format. The offset of the Extension Area is stored in the footer. It is structured as follows: WORD Size; // Extension Size. CHAR AuthorName[41]; // Author Name. CHAR AuthorComment[324];// Author Comment. WORD StampMonth; // Date/Time Stamp: Month WORD StampDay; // Date/Time Stamp: Day WORD StampYear; // Date/Time Stamp: Year WORD StampHour; // Date/Time Stamp: Hour WORD StampMinute; // Date/Time Stamp: Minute WORD StampSecond; // Date/Time Stamp: Second CHAR JobName[41]; // Job Name/ID WORD JobHour; // Job Time: Hours WORD JobMinute; // Job Time: Minutes WORD JobSecond; // Job Time: Seconds CHAR SoftwareId[41]; // Software ID WORD VersionNumber; // Software Version Number BYTE VersionLetter; // Software Version Letter DWORD KeyColor; // Key Color WORD PixelNumerator; // Pixel Aspect Ratio WORD PixelDenominator; // Pixel Aspect Ratio WORD GammaNumerator; // Gamma Value WORD GammaDenominator; // Gamma Value DWORD ColorOffset; // Color Correction Offset DWORD StampOffset; // Postage Stamp Offset DWORD ScanOffset; // Scan-Line Table Offset BYTE AttributesType; // Attributes Types Here is a discussion of various fields: Size Specifies the length in bytes of the extension area. This value is 495 for the New TGA format. AuthorName NULL-terminated, space-padded string containing the name of the author of the TGA file. AuthorComment NULL-terminated, space-padded string containing comments from the author. StampMonth, StampDay, StampYear StampHour, StampMinute, StampSecond Month (1 to 12), day (1 to 31), year (1 to 9999), hour (0 to 23), minute (0 to 59) and second (0 to 59) the image was created or last modified. Unused fields should be set to NULL. JobName NULL-terminated string identifying the production job with which the image is associated. JobHour, JobMinute, JobSecond The amount of time expended on the job, format is identical to StampHour, StampMinute and StampSecond. SoftwareId NULL-terminated string that identifies the software application that created the file. VersionNumber, VersionLetter Version of the software application that created the file. KeyColor Background color of the image used to paint the areas of the display screen not covered by the image or the color used to clear the screen if the image is erased. PixelNumerator, PixelDenominator Aspect ratio of the pixels used in the image. These fields are NULL if no aspect ratio is specified. GammaNumerator, GammaDenominator Gamma correction values to be used when displaying the image. These fields are NULL if no gamma is specified. ColorOffset Contains the offset value of the color correction table relative to the beginning of the file (byte 0). This field is NULL if no correction table is present. StampOffset Contains the offset value of the thumbnail image included in the TGA file. This field is NULL if no thumbnail image is present. ScanOffset Contains the offset value of the scan-line offset table. This field is NULL if no scan-line offset table present. AttributesType Describes the type of alpha channel data contained within the pixel data. A value of 0x00 indicates that the image data contains no alpha channel value. A value of 0x01, 0x02, 0x04, or 0x08 indicates the presence of alpha channel data. Scan-Line Table The scan-line table is a method of accessing scan lines at any location within raw or compressed image data. The table is an array of DWORD values. Each value is the offset location from the beginning of the file to the beginning of the corresponding scan line in the image data. There is one entry in the scan-line table per scan line in the image. Entries are written to the table in the order in which the scan lines appear within the image. Thumbnail Image The thumbnail is a smaller rendering of the primary image stored within the TGA file. It is structured as follows: CHAR thumbWidth; // Width of thumbnail, in pixels. CHAR thumbHeight; // Height of thumbnail, in pixels. CHAR thumbData[]; // The preview image. thumbWidth, thumbHeight Width and height in pixles of the thumbnail; it should not be larger than 64x64 pixels. thumbData[] Pixels for the thumbnail, typically stored in the same format as the primary image, but without compression. Color Correction Table The color correction table is an array of 256 elements of 8 bytes each. These entries are used for color remapping and are structured as follows: WORD alpha; // Alpha value, 0 to 65535. WORD red; // Red intensity, 0 to 65535. WORD green; // Green intensity, 0 to 65535. WORD blue; // Blue intensity, 0 to 65535.