                         *******************
                         * TGA File Format *   
                         *******************
                            By Peter Flynn

(If this file looks funny set tab stops to 5 . . . sorry :-)
   
   This info took several hours of searching on the Web to find. My main
source is Truevision's original TGA Specification, which I got from their FTP
site (ftp://ftp.truevision.com). I wasn't sure if it was Ok to upload the
file without their permission, so I will just write this little text instead.
   Sorry if there are spelling mistakes, I have a lot of work to do and I
want to get this uploaded soon. Please send me EMail if you have any
questions/comments/etc... My address is 102712,415.

DISCLAIMER:
    The author (Peter Flynn) is not and will not be liable for any sort of
damages that result from the use or misuse of the data in this document. You
can copy this file and distribute it wherever you wish as long as it is
unmodified and credit is given to the author.
   That was my first try at dense legal text. I hope it is Ok.

TGA FILE BASICS:
    TGA images are actually quite complex. They support three different color
modes, an alpha channel, all kinds of mapping, thumbnails, and reserved
comment, develeloper, and extension areas. The Truevision TGA specs are about
35 pages long, so I will give a simplified version of the format.
    I have included info for all of the TGA format except for the extension
and developer's areas. With this info you can create standard, completely
valid TGA files. If you want details on how to do more complex TGA files,
please EMail me. Note that in order to implement a full-featured TGA reader
that supports the TGA Extensions area, you need to get details on the fields
contained within it.
    The table below contains the length and meaning/use of each data field. I
have also included the values that would be placed in each field for a
simple, non-RLE 24-bit TGA file (AKA "type 2" TGA). There are also some notes
at the end of the table on details of image encoding.

    Fields that are exactly 2 bytes long should be assumed to contain SHORT
values, and fields that are 4 bytes long should be assumed to contain LONG
values. All sets of bytes are stored low-order byte first, as per Intel CPU
standards.
    "Not present" for value means that no bytes are stored for that field,
so skip to the next one. "0 (n/a)" means that the byte(s) for the field are
stored but not used. "Whatever" means that the data will vary depending upon 
the exact image stored.

Field | Length |   Description                               |   Value
------|--------|-------------------------------------------- |--------------
  1   |  1     | Length of Field 6 in Bytes. 0 if not present|    0
  2   |  1     | Color map type. 1=present, 0=not present    |    0
  3   |  1     | Image type: 1=8-bit palette style           |    2
      |        |        2=Direct [A]RGB image                |
      |        |        3=grayscale                          |
      |        |        9=RLE version of Type 1              |
      |        |       10=RLE version of Type 2              |
      |        |       11=RLE version of Type 3              |
  4.1 |  2     | Index # of first item in colormap, if any   |    0 (n/a)
  4.2 |  2     | Number of entries in colormap               |    0 (n/a)
  4.3 |  1     | Number of bits per entry (must be an even # |    0 (n/a)
      |        |  of bytes)                                  |
  5.1 |  2     | X offset of image from *lower-left* corner  |    0
  5.2 |  2     | Y offset    "       "       "       "       |    0
  5.3 |  2     | Width of image in pixels                    |  whatever
  5.4 |  2     | Height    "      "                          |  whatever
  5.5 |  1     | # of bits per pixel, including Alpha (must  |    24
      |        |  be an even # of bytes)                     |
  5.6 |  1     | Attributes: bits 0-3=# of Alpha bits per pxl|    0
      |        |          bit 4=Reverse L-R order of pixels  |    0
      |        | (clarified: 1st pixel stored for @ row is   |
      |        |  the rightmost pixel instead of the leftmst)|
      |        |          bit 5=Reverse top-bottom order     |    0
      |        | (set this bit for "bottom-up" TGA files)    |
      |        |          bits 6-7=Always 0                  |    0
  6   |[Fld 1] | Short description of image in ASCII format. |  not present
  7   | var    | Colormap. Size determined by Flds 4.2 &     |  not present
      |        |  4.3. Used in Type 1 images.                |
  8   | var    | ACTUAL IMAGE DATA. [Fld 5.3] * [Fld 5.4]    |   whatever
      |        |  pixels are stored (unless RLE... see below)|
          THE NEXT TWO ARE ONLY PRESENT SOMETIMES - SEE FOOTER
  9   | var    | Developer's directory. Don't worry about it.|  not present
 10-27|  495   | Extended data area. Don't worry about it.   |  not present
          EVERYTHING BELOW HERE IS PART OF THE TGA FILE FOOTER
 28   |  4     | Offset from top of file to Extension area.  |     0
      |        |  Set to 0 if not present.                   |
 29   |  4     | Offset from top of file to Developer's area.|     0
      |        |  Set to 0 if not present.                   |
 30/31|  17    | The string "TRUEVISION-XFILE." (including   |     -
      |        |  the period but not the quotes)             |
 32   |  1     | Always 0.                                   |     0
                              END OF FILE

    There are two versions of the TGA spec - new and old (very original names,
too). Old format TGAs simply have the header and the image data. The image
data is the last field in the file. New TGA files include the 26-byte footer,
and possibly the developer's and extension areas. In order to determine if
either area is present, simply scan the two offsets at the beginning of the
footer. The presence of the extension and developer's areas (or even the
footer) will not affect a program that is simply reading the image data,
since all of the add-ons are at the end of the file.

    For RGB or ARGB-format TGAs, each pixel is simply stored with the Blue
bits first, and the Red bits last. If there are attribute bits, then those
follow the Red bits at the end (The Truevision docs were a little unclear
about where the attribute bits go, but I am fairly sure that they're at the
end).

    TGAs can also be Run Length Encoded (RLE). Data types 9, 10, and 11 use
this method. If you know how to encode/decode PCX files, this will be a snap.
If you do not know RLE, it is fairly simple: "Runs" of identical-value pixels
are shortened to a control code that says to repeat the pixel value the
appropriate number of times. This saves tons of disk space on images such as
cartoons, where there are many pixels in a row with the same color.
    Unlike PCX files, TGA files use "packets" to store RLE data. Each packet 
consists of a 1-byte info section, followed by one pixel value, which is 
stored exactly as normal pixels are stored in non-RLE TGA files.
    There are two types of packets, run and raw. A run packet is followed by
a single pixel value, which is repeated a specified number of times. A raw
packet is followed by a variable number of pixels, which are inserted into
the image without repetition.
    This diagram will hopefully show how to decode the info byte:

                 7    6    5    4    3    2    1    0
               +---------------------------------------+
     High bit  | ** |    |    |    |    |    |    |    |   Low bit
               +---------------------------------------+
               |====|==================================|
                 ^                     ^
                 |                     |
 This bit specifies what type |  If the packet is a run packet, these bits 
of packet we are looking at.  | tell how many times to repeat the next pixel.
  0 = raw packet              |  If this is a raw packet, these bits tell how
  1 = run packet              | many pixels are in the raw packet. After that
                              | many pixel values, you will encounter the
                              | start of the next packet.

 There are two catches here:

     * Runs can never wrap from one row of pixels to the next (all of the
 pixels in a run must have the same Y). If they did, it would screw up the
 scan line table included in the Extension Area.

     * THE NUMBER STORED IN THE INFO BYTE OF EACH PACKET IS ONE LESS THAN IT
 SHOULD BE! Add one to the number stored in the packet in order to get the
 correct value. Therefore, if the number in the byte is 0, the number of reps
 (or pixels, as the case may be), is 1; if the number is 41, the actual
 number of reps is 42.
     This was done because there will never be a run of 0 reps or a raw packet
 containing 0 pixels. Therefore, to expand the maximum length of the runs and
 raw pixel strings, every value was bumped back one.


    So, now that you have a fairly complete version of the TGA file
specifications, you should be able to add support for TGA file reading and
writing to your programs. Unless you need to access developer-specific info
or the details in the extension area (neither or which are inlucded
particularly often anyway), everything you need to know is included above.
    If you do need more details, EMail me and I'll write up a more detailed
version as soon as I can. The original (slightly scrambled) RTF file for the
official specs is available at FTP://ftp.truevision.com. If you have any
questions or comments, feel free to mail me.
