TGA_File_Format_Spec.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!-- saved from url=(0066)http://www.cubic.org/source/archive/fileform/graphic/tga/tga2.html -->
<HTML><HEAD><TITLE>TGA File Format Spec</TITLE>
<META content="text/html; charset=windows-1252" http-equiv=Content-Type>
<META content="MSHTML 5.00.2919.6307" name=GENERATOR></HEAD>
<BODY><B>
<P align=center>Truevision TGA</P>
<P align=center>FILE FORMAT SPECIFICATION</P>
<P align=center>Version 2.0</P></B>
<P>Document prepared by:</P>
<P align=center>Truevision, Inc.<BR>7340 Shadeland Station<BR>Indianapolis, IN 
46256-3925<BR>800-729-2656 - phone<BR>317-576-7700 - FAX<BR>317-577-8777 - 
BBS<BR>http://www.truevision.com/</ P> 
<P>Technical Manual Version 2.2 January, 1991<BR>Copyright 1989, 1990, 1991 
Truevision, Inc.<BR>Truevision is a registered trademark of Truevision, 
Inc.<BR>TARGA is a registered trademark of Truevision, Inc.<BR>TrueVista is a 
registered trademark of Truevision, Inc.<BR>ATVista is a registered trademark of 
Truevision, Inc.<BR>NuVista is a registered trademark of Truevision, 
Inc.<BR>TIPS is a registered trademark of Truevision, Inc.<BR>TGA is a trademark 
of Truevision, Inc.</P><B>
<P>Disclaimer of Warranties and Limitations of Liabilities</P></B>
<P>This manual and the enclosed software were prepared by Truevision, Inc. While 
the authors and program developers have taken reasonable care in preparing this 
manual to assure accuracy, the authors assume no liability resulting from any 
inaccuracy or omissions contained in them or from the use of the information or 
programs contained herein.;</P>
<P>The authors and Truevision, Inc. have no expressed or implied warranty of any 
kind with regard to these programs or to the supplemental documentation in this 
manual. In no event shall the authors, the program developers, or Truevision, 
Inc. be liable for incidental or consequential damages in connection with or 
arising out of the furnishing, performance or use of any of these programs or 
documentation. This disclaimer includes but is not limited to any loss of 
service, loss of business or anticipatory profits, or consequential damages 
resulting from the use or operation of the enclosed software.;</P>
<P>The success of the TGA File Format for storing color images can be 
attributed to its ease of use, the small amount of program memory needed to 
parse the file, and the fact that it was the first true-color file format widely 
available. Truevision defined the TGA file format in 1984 for use with its 
first videographics products. Since then, it has been estimated that today over 
80 percent of the color images stored on hard drives employ some variation of 
the TGA file format. Many government offices, corporations, service bureaus, 
production shops and nearly all Truevision developers have standardized on the 
TGA format as a means of allowing cross-product and cross-application 
compatibility. Truevision recommends that this format be used by all software 
developed for Truevision products since it allows customers flexibility in 
combining many applications together to provide a total solution to meet their 
needs.</P>
<P>The original Truevision TGA File Format has been widely accepted by the 
graphics industry. However, newer technology and techniques have created the 
need for additional image information to be recorded in the file. In 1989, 
Truevision introduced extensions to the TGA File Format to satisfy requests made 
by the graphics industry and to ensure that the standard will meet future needs 
of the color imaging marketplace. The extensions are optional and will have no 
impact on existing packages (assuming the packages followed the original TGA 
File Format guidelines). In particular, the new TGA File Format addresses the 
following needs:</P>
<P>* The inclusion of a scaled-down "postage stamp" copy of the image</P>
<P>* Date and Time of image file creation</P>
<P>* Author Name</P>
<P>* Author Comments</P>
<P>* Job Name</P>
<P>* Job Accumulated Time</P>
<P>* Gamma Value</P>
<P>* Correct Color LUT</P>
<P>* Pixel Aspect Ratio</P>
<P>* Scan Line Offset Table</P>
<P>* Key Color</P>
<P>* Software Package Name and Version Number</P>
<P>* Developer Definable Areas</P>
<P>* Attribute (Alpha) channel Type</P>
<P>* The ability for simple expansion</P><B>
<P>DEFINITIONS</P></B>
<P>Throughout this document, we will be using the terms <B>Pseudo-Color</B>, 
<B>True-Color</B> and <B>Direct-Color</B>. These terms are defined as 
follows:</P><B><U>
<P>Pseudo-Color</B></U> - Each pixel value is used as a single index into a 
programmable color map which contains the actual red, green and blue intensities 
to be displayed. The Truevision products that use this type of image are: VDA, 
VDA/D, TARGA M8, ATVista, NuVista and HR videographics boards.</P><B><U>
<P>True-Color</B></U> - Each pixel value is sub-divided into red, green and blue 
fields that directly determine the intensities of each primary color. The 
Truevision products that use this type of image are: ICB, TARGA 16, TARGA 24, 
TARGA 32, ATVista and NuVista videographics boards.</P><B><U>
<P>Direct-Color</B></U> - Each pixel value is sub-divided into red, green and 
blue fields which are used as separate indices to access independent, 
programmable look-up tables. The outputs of the individual color maps directly 
determine the intensities of each primary color. A Direct-Color system is 
similar to Pseudo-Color except that the values in the color maps can be altered 
individually for the red, green and blue channels; whereas, the red, green and 
blue values in a Pseudo-Color system are loaded into one map which is accessed 
by a single index. Truevision products that use this type of image are: ATVista 
and NuVista videographics boards.</P>
<P>The TrueVista (ATVista and NuVista) videographics cards can be programmed to 
accept images which are Pseudo-Color, True-Color and Direct-Color. When they are 
functioning in any of the Linked Modes, they are said to be acting as 
Pseudo-Color devices. When they are configured for any of the Independent Modes, 
they are said to be acting as Direct-Color devices. When bypassing the look-up 
tables altogether, they are said to be acting as True-Color devices.</P>
<P>The VDA, VDA/D, TARGA M8 and HR can only be used as Pseudo-Color devices.</P>
<P>The ICB, TARGA 16, 24 and 32 can only be used as True-Color 
devices.</P><B><U>
<P>Long</B> </U>= 32 bit value</P><B><U>
<P>Short </B></U>= 16 bit value</P><B><U>
<P>Byte </B></U>= 8 bit value</P><B><U>
<P>ASCII </B></U>= sequence of bytes conforming to the ASCII definition 
(Truevision recommends that the ASCII fields contain only printable ASCII 
characters, with exception of the null terminator, and that all formatting be 
performed by the application)</P><B><U>
<P>Bit Numbering (for diagrams in this document)</P></B></U><B><U>
<P>Byte Ordering</P></B></U>
<P>TGA files are stored using the Intel byte ordering convention (least 
significant byte first, most significant byte last). For this reason, 
applications running on Motorola-based systems will need to invert the ordering 
of bytes for short and long values after a file has been read.</P><B><U>
<P>Suffix and File Type Definitions</P></B></U>
<P>Since there is a great need to be able to locate files easily on mass storage 
devices, we have defined a filename suffix for DOS and UNIX operating systems, 
and a file type for the Macintosh environment. You should use this filename 
suffix or file type for all TGA image files.</P>
<P>1. DOS, UNIX and XENIX environments - Append to the end of the filename a 
three character suffix "TGA" after the "." indicator. Example: "Image.tga."</P>
<P>2. Macintosh environment - Use a file type of "TPIC".</P>
<P>However, the demonstration software and the programs in the Truevision 
software series currently use the suffixes, ".VDA", ".ICB", ".TGA", and ".VST", 
for VDA/D, ICB, TARGA and ATVista images. It is therefore suggested that 
applications should allow the user the capability of reading images with any of 
these extensions, but should only use the extension ".TGA" when writing images. 
As future versions of Truevision software products are made available, they will 
convert to using the ".TGA" and "TPIC" conventions exclusively.</P><B>
<P>TGA FILE FORMAT SPECIFICATION</P></B>
<P align=center>Figure 1 - TGA File Format</P>
<P>While Figure 1 demonstrates one possible arrangement for the various data 
blocks within a TGA File, other arrangements are possible since many of the data 
blocks are referenced by an offset position from the beginning of the file. In 
particular, developers may find it easier to create the file if the Scan Line 
Table, the Postage Stamp Image and the Color Correction Table are located before 
the Extension Size field (Field 10). The Truevision TGA File Format comprises 5 
areas, each of which contains one or more fields of fixed or variable length. 
The 5 file areas are: (1) TGA File Header, (2) Image/ColorMap Data, (3) 
Developer Area, (4) Extension Area and (5) TGA File Footer.</P>
<P>The last 3 areas, the Developer Area, the Extension Area and the TGA File 
Footer are new to the file specification as of September, 1989. For this reason, 
images created with software written before September, 1989 will probably not 
contain these three fields. In this document, the TGA File format prior to 
September, 1989 will be referred to as the Original TGA Format while the current 
TGA File format will be referred to as the New TGA Format.</P>
<P>1. A TGA Reader should begin by determining whether the desired file is in 
the Original TGA Format or the New TGA Format. This is accomplished by examining 
the last 26 bytes of the file (most operating systems support some type of SEEK 
function). Reading the last 26 bytes from the file will either retrieve the last 
26 bytes of image data (if the file is in the Original TGA Format), or it will 
retrieve the TGA File Footer (if the file is in the New TGA Format).</P>
<P>2. To determine whether the acquired data constitutes a legal TGA File 
Footer, scan bytes 8-23 of the footer as ASCII characters and determine whether 
they match the signature string:</P><B>
<P align=center>TRUEVISION-XFILE</P></B>
<P>This string is exactly 16 bytes long and is formatted exactly as shown above 
(capital letters), with a hyphen between "TRUEVISION" and "XFILE." If the 
signature is detected, the file is assumed to be in the New TGA format and MAY, 
therefore, contain the Developer Area and/or the Extension Area fields. If the 
signature is not found, then the file is assumed to be in the Original TGA 
format and should only contain areas 1 and 2; therefore, the byte format for the 
TGA File Footer is defined as follows:</P>
<P>Bytes 0-3: The Extension Area Offset</P>
<P>Bytes 4-7: The Developer Directory Offset</P>
<P>Bytes 8-23: The Signature</P>
<P>Byte 24: ASCII Character "."</P>
<P>Byte 25: Binary zero string terminator (0x00)</P>
<P>Note: DEVELOPERS ARE NOT REQUIRED TO READ, WRITE OR USE THE EXTENSION OR 
DEVELOPER AREAS; THEY ARE OPTIONAL. EVEN IF THESE AREAS ARE NOT USED, IT IS 
RECOMMENDED THAT A TGA FILE FOOTER STILL BE INCLUDED WITH THE FILE. Please see 
page 19 for more information about the TGA File Footer.</P><B>
<P>TGA FILE HEADER</P></B><B>
<P>ID Length - Field 1 (1 byte):</P></B>
<P>This field identifies the number of bytes contained in Field 6, the Image ID 
Field. The maximum number of characters is 255. A value of zero indicates that 
no Image ID field is included with the image.</P><B>
<P>Color Map Type - Field 2 (1 byte):</P></B>
<P>This field indicates the type of color map (if any) included with the image. 
There are currently 2 defined values for this field:</P>
<P>0 - indicates that no color-map data is included with this image.</P>
<P>1 - indicates that a color-map is included with this image.</P>
<P>The first 128 Color Map Type codes (Field 2) are reserved for use by 
Truevision, while the second set of 128 Color Map Type codes (128 to 255) may be 
used for developer applications.</P>
<P>True-Color images do not normally make use of the color map field, but some 
current applications store palette information or developer-defined information 
in this field. It is best to check Field 3, Image Type, to make sure you have a 
file which can use the data stored in the Color Map Field. Otherwise ignore the 
information. When saving or creating files for True-Color images do not use this 
field and set it to Zero to ensure compatibility. Please refer to the Developer 
Area specification for methods of storing developer defined information.</P><B>
<P>Image Type - Field 3 (1 byte):</P></B>
<P></P>
<P>The TGA File Format can be used to store Pseudo-Color, True-Color and 
Direct-Color images of various pixel depths. Truevision has currently defined 
seven image types:</P>
<P align=center>Table 1 - Image Types</P>
<P>Image Data Type codes 0 to 127 are reserved for use by Truevision for general 
applications. Image Data Type codes 128 to 255 may be used for developer 
applications.</P>
<P>For a complete description of these image-data types, see the IMAGE TYPES 
section later in this manual.</P><B>
<P>Color Map Specification - Field 4 (5 bytes):</P></B>
<P>This field and its sub-fields describe the color map (if any) used for the 
image. If the Color Map Type field is set to zero, indicating that no color map 
exists, then these 5 bytes should be set to zero. These bytes always must be 
written to the file.</P><U>
<P>Field 4.1 (2 bytes) - First Entry Index:</P></U>
<P>Index of the first color map entry. Index refers to the starting entry in 
loading the color map.</P>
<P>Example: If you would have 1024 entries in the entire color map but you only 
need to store 72 of those entries, this field allows you to start in the middle 
of the color-map (e.g., position 342).</P><U>
<P>Field 4.2 (2 bytes) - Color map Length:</P></U>
<P>Total number of color map entries included.</P><U>
<P>Field 4.3 (1 byte) - Color map Entry Size:</P></U>
<P>Establishes the number of bits per entry. Typically 15, 16, 24 or 32-bit 
values are used.</P>
<P>When working with VDA or VDA/D cards it is preferred that you select 16 bits 
(5 bits per primary with 1 bit to select interrupt control) and set the 16th bit 
to 0 so that the interrupt bit is disabled. Even if this field is set to 15 bits 
(5 bits per primary) you must still parse the color map data 16 bits at a time 
and ignore the 16th bit.</P>
<P>When working with a TARGA M8 card you would select 24 bits (8 bits per 
primary) since the color map is defined as 256 entries of 24 bit color 
values.</P>
<P>When working with a TrueVista card (ATVista or NuVista) you would select 
24-bit (8 bits per primary) or 32-bit (8 bits per primary including Alpha 
channel) depending on your applications use of look-up tables. It is suggested 
that when working with 16-bit and 32-bit color images, you store them as 
True-Color images and do not use the color map field to store look-up tables. 
Please refer to the TGA Extensions for fields better suited to storing look-up 
table information.</P><B>
<P>Image Specification - Field 5 (10 bytes):</P></B>
<P></P>
<P>This field and its sub-fields describe the image screen location, size and 
pixel depth. These bytes are always written to the file.</P><U>
<P>Field 5.1 (2 bytes) - X-origin of Image:</P></U>
<P>These bytes specify the absolute horizontal coordinate for the lower left 
corner of the image as it is positioned on a display device having an origin at 
the lower left of the screen (e.g., the TARGA series). </P><U>
<P>Field 5.2 (2 bytes) - Y-origin of Image:</P></U>
<P>These bytes specify the absolute vertical coordinate for the lower left 
corner of the image as it is positioned on a display device having an origin at 
the lower left of the screen (e.g., the TARGA series). </P><U>
<P>Field 5.3 (2 bytes) - Image Width:</P></U>
<P>This field specifies the width of the image in pixels.</P><U>
<P>Field 5.4 (2 bytes) - Image Height:</P></U>
<P>This field specifies the height of the image in pixels.</P><U>
<P>Field 5.5 (1 byte) - Pixel Depth:</P></U>
<P>This field indicates the number of bits per pixel. This number includes the 
Attribute or Alpha channel bits. Common values are 8, 16, 24 and 32 but other 
pixel depths could be used.</P><U>
<P>Field 5.6 (1 byte) - Image Descriptor:</P></U><U>
<P>Bits 3-0:</U> These bits specify the number of attribute bits per pixel. In 
the case of the TrueVista, these bits indicate the number of bits per pixel 
which are designated as Alpha Channel bits. For the ICB and TARGA products, 
these bits indicate the number of overlay bits available per pixel. See field 24 
(Attributes Type) for more information.</P><U>
<P>Bits 5 &amp; 4: </U>These bits are used to indicate the order in which pixel 
data is transferred from the file to the screen. Bit 4 is for left-to-right 
ordering and bit 5 is for top-to-bottom ordering as shown below.</P>
<P align=center>Table 2 - Image Origin</P><U>
<P>Bits 7 &amp; 6: </U>Must be zero to insure future compatibility.</P><B>
<P>IMAGE/COLOR MAP DATA</P></B><B>
<P>Image ID - Field 6 (variable):</P></B>
<P>This optional field contains identifying information about the image. The 
maximum length for this field is 255 bytes. Refer to Field 1 for the length of 
this field. If field 1 is set to Zero indicating that no Image ID exists then 
these bytes are not written to the file.</P><B>
<P>Color Map Data - Field 7 (variable):</P></B>
<P>If the Color Map Type (field 2) field is set to zero indicating that no 
Color-Map exists then this field will not be present (i.e., no bytes written to 
the file).</P>
<P>This variable-length field contains the actual color map information (LUT 
data). Field 4.3 specifies the width in bits of each color map entry while Field 
4.2 specifies the number of color map entries in this field. These two fields 
together are used to determine the number of bytes contained in field 7.</P>
<P>Each color map entry is stored using an integral number of bytes. The RGB 
specification for each color map entry is stored in successive bit-fields in the 
multi-byte entries. Each color bit-field is assumed to be MIN(Field4.3/3, 8) 
bits in length. If Field 4.3 contains 24, then each color specification is 8 
bits in length; if Field 4.3 contains 32, then each color specification is also 
8 bits (32/3 gives 10, but 8 is smaller). Unused bit(s) in the multi-byte 
entries are assumed to specify attribute bits. The attribute bit field is often 
called the Alpha Channel, Overlay Bit(s) or Interrupt Bit(s).</P>
<P>For the TARGA M-8, ATVista and NuVista, the number of bits in a color map 
specification is 24 (or 32). The red, green, and blue components are each 
represented by one byte.</P><B>
<P>Image Data - Field 8 (variable):</P></B>
<P>This field contains (Width)x(Height) pixels. Each pixel specifies image data 
in one of the following formats: a single color-map index for Pseudo-Color; 
Attribute, Red, Green and Blue ordered data for True-Color; and independent 
color-map indices for Direct-Color. The values for Width and Height are 
specified in Fields 5.3 and 5.4 respectively.</P>
<P>The number of attribute and color-definition bits for each pixel are defined 
in Fields 5.6 and 5.5, respectively. Each pixel is stored as an integral number 
of bytes.</P><B>
<P>DEVELOPER AREA</P></B><B>
<P>Developer Data - Field 9 (variable):</P></B>
<P>Truevision created the Developer Area to satisfy the needs of developers who 
have already created similar areas on their own. We have made an attempt to 
remain upwardly compatible with these developers methods.</P>
<P>The Developer Area is an area which may be used to store any type of 
information, although it is recommended that it be used only for application 
specific information, that is, information which would not be applicable to 
other products, and which is not already covered by the TGA File Format.</P>
<P>The size and format of the Developer Fields is totally up to the developer. 
Readers of files containing these fields should ignore the fields unless they 
have an understanding of their organization and content.</P>
<P>Since a file may contain more than one Developer Field, a Developer Directory 
was created which contains a "map" to the fields included in the Developer Area. 
The Developer Directory is located by using the offset pointer contained in 
bytes 4-7 of the TGA File Footer. The contents of this field are a byte offset 
from the beginning of the file to the start of the Developer Directory. If the 
Offset is ZERO (binary zero) no directory and no Developer Area fields 
exist.</P>
<P align=center>Figure 2 - Developer Directory</P>
<P>The first SHORT in the directory specifies the number of tags which are 
currently in the directory. The rest of the directory contains a series of TAG, 
OFFSET and SIZE combinations. Each TAG is a SHORT value in the range of 0 to 
65535. Values from <BR>0 - 32767 are available for developer use, while values 
from 32768 - 65535 are reserved for Truevision. Truevision will maintain a list 
of tags assigned to companies. To get a tag assignment for a product, simply 
contact Truevision Developer Services to request the next assignable tag. If you 
wish to supply Truevision with the data format of your field, we will make this 
information available to other developers who may wish to read your data (this 
is at your request only).</P>
<P>Following each TAG is an OFFSET. This OFFSET is a LONG value which specifies 
the number of bytes from the beginning of the file to the start of the field 
referenced by the tag.</P>
<P>Following the OFFSET is a FIELD SIZE. The FIELD SIZE is a LONG value which 
specifies the number of bytes in the field. This is useful for the allocation of 
buffer space for reading the field and for determining when the end of the field 
has been reached. There is no termination character to indicate the end of a 
fields data. </P>
<P>Each TAG, OFFSET, SIZE set references a particular field of data in the 
Developer Area. The TAGS may appear in any order in the directory (i.e., they do 
not need to be sorted). Since each set is 10 bytes in size (1 short, 2 longs), 
the total size of the directory will be:</P>
<P>(NUMBER_OF_TAGS_IN_THE_DIRECTORY * 10) + 2</P>
<P>bytes in size. The "+ 2" includes the 2 bytes for the SHORT value specifying 
the number of tags in the directory.</P>
<P>Although the size and format of the actual Developer Area fields are totally 
up to the developer, please define your formats to address future considerations 
you might have concerning your fields. This means that if you anticipate 
changing a field, build flexibility into the format to make these changes easy 
on other developers. Major changes to an existing TAGs definition should never 
happen. If major changes are required, we would prefer that you request another 
TAG number so as not to confuse programs which may honor your existing tag. 
Additionally, the developer should take care that the field is COMPLETE. That 
is, if there are any variable sized sub-fields, they should be INSIDE the field 
and the SIZE indicated in TAG, OFFSET and SIZE should contain the complete size. 
In this way, programs which may not understand a particular TAG and associated 
field can still preserve the data (i.e., pass it on in the file) without worry 
that data pointed to by a potential offset was not copied.</P><B>
<P>EXTENSION AREA</P></B>
<P>The Extension Area was created to satisfy requests from developers for 
additional file information. Every attempt has been made to keep the format of 
the Extension Area simple yet flexible enough to satisfy most developers 
needs.</P>
<P>The Extension Area is pointed to by the Extension Area Offset in the TGA File 
Footer. If the Offset is ZERO (binary zero) then no Extension Area exists. 
Otherwise, this value is the offset from the beginning of the file to the 
beginning of the Extension Area.</P>
<P>The combination of the Developer Area and the Extension Area should serve 
Truevision and its developer community well into the future. However, should 
technology dictate additional changes to the specification, they will be quite 
easy to implement. The first field of the Extension Area is the "Extension Size" 
field. This field currently contains the value 495, indicating that there are 
495 bytes in the fixed-length portion of the Extension Area. If future 
development warrants additional fields, then this value may change to indicate 
that new fields have been added. Any change in the number of bytes in the 
Extension Area will be made by Truevision and will be relayed to the Developer 
community via a revised TGA File Format Specification. TGA readers should only 
parse as much as they understand (i.e., 495 bytes for this first release). If 
they encounter additional bytes (as specified by the "Extension Size") they 
should not preserve them if rebuilding the file, since they do not know the 
nature of the extra bytes.</P><B>
<P>Extension Size - Field 10 (2 Bytes):</P></B>
<P>Bytes 0-1 - This field is a SHORT field which specifies the number of BYTES 
in the fixed-length portion of the Extension Area. For Version 2.0 of the TGA 
File Format, this number should be set to 495. If the number found in this field 
is not 495, then the file will be assumed to be of a version other than 2.0. If 
it ever becomes necessary to alter this number, the change will be controlled by 
Truevision, and will be accompanied by a revision to the TGA File Format with an 
accompanying change in the version number.</P><B>
<P>Author Name - Field 11 (41 Bytes):</P></B>
<P>Bytes 2-42 - This field is an ASCII field of 41 bytes where the last byte 
must be a null (binary zero). This gives a total of 40 ASCII characters for the 
name. If the field is used, it should contain the name of the person who created 
the image(author). If the field is not used, you may fill it with nulls or a 
series of blanks (spaces) terminated by a null. The 41st byte must always be a 
null.</P><B>
<P>Author Comments - Field 12 (324 Bytes):</P></B>
<P>Bytes 43-366 - This is an ASCII field consisting of 324 bytes which are 
organized as four lines of 80 characters, each followed by a null terminator. 
This field is provided, in addition to the original IMAGE ID field (in the 
original TGA format), because it was determined that a few developers had used 
the IMAGE ID field for their own purposes. This field gives the developer four 
lines of 80 characters each, to use as an Author Comment area. Each line is 
fixed to 81 bytes which makes access to the four lines easy. Each line must be 
terminated by a null. If you do not use all 80 available characters in the line, 
place the null after the last character and blank or null fill the rest of the 
line. The 81st byte of each of the four lines must be null.</P><B>
<P>Date/Time Stamp - Field 13 (12 Bytes):</P></B>
<P>Bytes 367-378 - This field contains a series of 6 SHORT values which define 
the integer value for the date and time that the image was saved. This data is 
formatted as follows:</P>
<P>SHORT 0: Month (1 - 12)</P>
<P>SHORT 1: Day (1 - 31)</P>
<P>SHORT 2: Year (4 digit, ie. 1989)</P>
<P>SHORT 3: Hour (0 - 23)</P>
<P>SHORT 4: Minute (0 - 59)</P>
<P>SHORT 5: Second (0 - 59)</P>
<P></P>
<P>Even though operating systems typically time- and date-stamp files, this 
feature is provided because the operating system may change the time and date 
stamp if the file is copied. By using this area, you are guaranteed an 
unmodified region for date and time recording. If the fields are not used, you 
should fill them with binary zeros (0).</P><B>
<P>Job Name/ID - Field 14 (41 Bytes):</P></B>
<P>Bytes 379-419 - This field is an ASCII field of 41 bytes where the last byte 
must be a binary zero. This gives a total of 40 ASCII characters for the job 
name or the ID. If the field is used, it should contain a name or id tag which 
refers to the job with which the image was associated. This allows production 
companies (and others) to tie images with jobs by using this field as a job name 
(i.e., CITY BANK) or job id number (i.e., CITY023). If the field is not used, 
you may fill it with a null terminated series of blanks (spaces) or nulls. In 
any case, the 41st byte must be a null.</P><B>
<P>Job Time - Field 15 (6 Bytes):</P></B>
<P>Bytes 420-425 - This field contains a series of 3 SHORT values which define 
the integer value for the job elapsed time when the image was saved. This data 
is formatted as follows:</P>
<P>SHORT 0: Hours (0 - 65535)</P>
<P>SHORT 1: Minutes (0 - 59)</P>
<P>SHORT 2: Seconds (0 - 59)</P>
<P></P>
<P>The purpose of this field is to allow production houses (and others) to keep 
a running total of the amount of time invested in a particular image. This may 
be useful for billing, costing, and time estimating. If the fields are not used, 
you should fill them with binary zeros (0).</P><B>
<P>Software ID - Field 16 (41 Bytes):</P></B>
<P>Bytes 426-466 - This field is an ASCII field of 41 bytes where the last byte 
must be a binary zero (null). This gives a total of 40 ASCII characters for the 
Software ID. The purpose of this field is to allow software to determine and 
record with what program a particular image was created. If the field is not 
used, you may fill it with a null terminated series of blanks (spaces) or nulls. 
The 41st byte must always be a null.</P><B>
<P>Software Version - Field 17 (3 Bytes):</P></B>
<P>Bytes 467-469 - This field consists of two sub-fields, a SHORT and an ASCII 
BYTE. The purpose of this field is to define the version of software defined by 
the "Software ID" field above. The SHORT contains the version number as a binary 
integer times 100. Therefore, software version 4.17 would be the integer value 
417. This allows for two decimal positions of sub-version. The ASCII BYTE 
supports developers who also tag a release letter to the end. For example, if 
the version number is 1.17b, then the SHORT would contain 117. and the ASCII 
BYTE would contain "b". The organization is as follows:</P>
<P>SHORT (Bytes 0 - 1): Version Number * 100</P>
<P>BYTE (Byte 2): Version Letter</P>
<P>If you do not use this field, set the SHORT to binary zero, and the BYTE to a 
space (" ").</P><B>
<P>Key Color - Field 18 (4 Bytes):</P></B>
<P>Bytes 470-473 - This field contains a long value which is the key color in 
effect at the time the image is saved. The format is in A:R:G:B where A (most 
significant byte) is the alpha channel key color (if you dont have an alpha 
channel in your application, keep this byte zero [0]).</P>
<P>The Key Color can be thought of as the background color or transparent 
color. This is the color of the non image area of the screen, and the same 
color that the screen would be cleared to if erased in the application. If you 
dont use this field, set it to all zeros (0). Setting the field to all zeros is 
the same as selecting a key color of black.</P>
<P>A good example of a key color is the transparent color used in TIPS for 
WINDOW loading/saving.</P><B>
<P>Pixel Aspect Ratio - Field 19 (4 Bytes):</P></B>
<P>Bytes 474-477 - This field contains two SHORT sub-fields, which when taken 
together specify a pixel size ratio. The format is as follows:</P>
<P>SHORT 0: Pixel Ratio Numerator (pixel width)</P>
<P>SHORT 1: Pixel Ratio Denominator (pixel height)</P>
<P>These sub-fields may be used to determine the aspect ratio of a pixel. This 
is useful when it is important to preserve the proper aspect ratio of the saved 
image. If the two values are set to the same non-zero value, then the image is 
composed of square pixels. A zero in the second sub-field (denominator) 
indicates that no pixel aspect ratio is specified.</P><B>
<P>Gamma Value - Field 20 (4 Bytes):</P></B>
<P>Bytes 478-481 - This field contains two SHORT sub-fields, which when taken 
together in a ratio, provide a fractional gamma value. The format is as 
follows:</P>
<P>SHORT 0: Gamma Numerator</P>
<P>SHORT 1: Gamma Denominator</P>
<P>The resulting value should be in the range of 0.0 to 10.0, with only one 
decimal place of precision necessary. An uncorrected image (an image with no 
gamma) should have the value 1.0 as the result. This may be accomplished by 
placing the same, non-zero values in both positions (i.e., 1/1). If you decide 
to totally ignore this field, please set the denominator (the second SHORT) to 
the value zero. This will indicate that the Gamma Value field is not being 
used.</P><B>
<P>Color Correction Offset - Field 21 (4 Bytes):</P></B>
<P>Bytes 482-485 - This field is a 4-byte field containing a single offset 
value. This is an offset from the beginning of the file to the start of the 
Color Correction table. This table may be written anywhere between the end of 
the Image Data field (field 8) and the start of the TGA File Footer. If the 
image has no Color Correction Table or if the Gamma Value setting is sufficient, 
set this value to zero and do not write a Correction Table anywhere.</P><B>
<P>Postage Stamp Offset - Field 22 (4 Bytes):</P></B>
<P>Bytes 486-489 - This field is a 4-byte field containing a single offset 
value. This is an offset from the beginning of the file to the start of the 
Postage Stamp Image. The Postage Stamp Image must be written after Field 25 
(Scan Line Table) but before the start of the TGA File Footer. If no postage 
stamp is stored, set this field to the value zero (0).</P><B>
<P>Scan Line Offset - Field 23 (4 Bytes):</P></B>
<P>Bytes 490-493 - This field is a 4-byte field containing a single offset 
value. This is an offset from the beginning of the file to the start of the Scan 
Line Table. </P><B>
<P>Attributes Type - Field 24 (1 Byte):</P></B>
<P>Byte 494 - This single byte field contains a value which specifies the type 
of Alpha channel data contained in the file.</P>
<P></P>
<P>Value Meaning</P>
<P></P>
<P>0: no Alpha data included (bits 3-0 of field 5.6 should also be </P>
<P>set to zero)</P>
<P>1: undefined data in the Alpha field, can be ignored</P>
<P>2: undefined data in the Alpha field, but should be retained</P>
<P>3: useful Alpha channel data is present</P>
<P>4: pre-multiplied Alpha (see description below)</P>
<P>5 -127: RESERVED</P>
<P>128-255: Un-assigned</P>
<P><U>Pre-multiplied Alpha Example</U>: Suppose the Alpha channel data is being 
used to specify the opacity of each pixel (for use when the image is overlayed 
on another image), where 0 indicates that the pixel is completely transparent 
and a value of 1 indicates that the pixel is completely opaque (assume all 
component values have been normalized). A quadruple (a, r, g, b) of ( 0.5, 1, 0, 
0) would indicate that the pixel is pure red with a transparency of one-half. 
For numerous reasons (including image compositing) is is better to pre-multiply 
the individual color components with the value in the Alpha channel. A 
pre-multiplication of the above would produce a quadruple (0.5, 0.5, 0, 0).</P>
<P>A value of 3 in the Attributes Type Field (field 23) would indicate that the 
color components of the pixel have already been scaled by the value in the Alpha 
channel. For more information concerning pre-multiplied values, refer to the 
1984 SIGGRAPH Conference Proceedings.</P>
<P>Porter, T., T. Duff, "Compositing Digital Images," SIGGRAPH 84 Conference 
Proceedings, vol. 18, no. 3, p. 254 , ACM, July 1984.</P><B>
<P>Scan Line Table - Field 25 (Variable):</P></B>
<P>This information is provided, at the developers request, for two 
purposes:</P>
<P>1) To make random access of compressed images easy.</P>
<P>2) To allow "giant picture" access in smaller "chunks".</P>
<P>This table should contain a series of 4-byte offsets. Each offset you write 
should point to the start of the next scan line, in the order that the image was 
saved (i.e., top down or bottom up). The offset should be from the start of the 
file. Therefore, you will have a four byte value for each scan line in your 
image. This means that if your image is 768 pixels tall, you will have 768, 
4-byte offset pointers (for a total of 3072 bytes). This size is not extreme, 
and thus this table can be built and maintained in memory, and then written out 
at the proper time.</P><B>
<P>Postage Stamp Image - Field 26 (Variable):</P></B>
<P>The Postage Stamp area is a smaller representation of the original image. 
This is useful for "browsing" a collection of image files. If your application 
can deal with a postage stamp image, it is recommended that you create one using 
sub-sampling techniques to create the best representation possible. The postage 
stamp image must be stored in the same format as the normal image specified in 
the file, but without any compression. The first byte of the postage stamp image 
specifies the X size of the stamp in pixels, the second byte of the stamp image 
specifies the Y size of the stamp in pixels. Truevision does not recommend 
stamps larger than 64 x 64 pixels, and suggests that any stamps stored larger be 
clipped. Obviously, the storage of the postage stamp relies heavily on the 
storage of the image. The two images are stored using the same format under the 
assumption that if you can read the image, then you can read the postage stamp. 
If the original image is color mapped, DO NOT average the postage stamp, as you 
will create new colors not in your map.</P><B>
<P>Color Correction Table - Field 27 (2K Bytes):</P></B>
<P>The Color Correction Table is a block of 256 x 4 SHORT values, where each set 
of four contiguous values are the desired A:R:G:B correction for that entry. 
This allows the user to store a correction table for image remapping or LUT 
driving. Since each color in the block is a SHORT, the maximum value for a color 
gun (i.e., A, R, G, B) is 65535, and the minimum value is zero. Therefore, BLACK 
maps to 0, 0, 0, 0 and WHITE maps to 65535, 65535, 65535, 65535.</P><B>
<P>TGA FILE FOOTER</P></B>
<P>1. A TGA Reader should begin by determining whether the desired file is in 
the Original TGA Format or the New TGA Format. This is accomplished by examining 
the last 26 bytes of the file (most operating systems support some type of SEEK 
function). Reading the last 26 bytes from the file will either retrieve the last 
26 bytes of image data (if the file is in the Original TGA Format), or it will 
retrieve the TGA File Footer (if the file is in the New TGA Format).</P>
<P>2. To determine whether the acquired data constitutes a legal TGA File 
Footer, scan bytes 8-23 of the footer as ASCII characters and determine whether 
they match the signature string:</P><B>
<P align=center>TRUEVISION-XFILE</P></B>
<P>This string is exactly 16 bytes long and is formatted exactly as shown above 
(capital letters), with a hyphen between "TRUEVISION" and "XFILE." If the 
signature is detected, the file is assumed to be in the New TGA format and MAY, 
therefore, contain the Developer Area and/or the Extension Area fields. If the 
signature is not found, then the file is assumed to be in the Original TGA 
format and should only contain areas 1 and 2; therefore, the byte format for the 
TGA File Footer is defined as follows:</P>
<P>Bytes 0-3: The Extension Area Offset</P>
<P>Bytes 4-7: The Developer Directory Offset</P>
<P>Bytes 8-23: The Signature</P>
<P>Byte 24: ASCII Character "."</P>
<P>Byte 25: Binary zero string terminator (0x00)</P>
<P>Note: DEVELOPERS ARE NOT REQUIRED TO READ, WRITE OR USE THE EXTENSION OR 
DEVELOPER AREAS; THEY ARE OPTIONAL. EVEN IF THESE AREAS ARE NOT USED, IT IS 
RECOMMENDED THAT A TGA FILE FOOTER STILL BE INCLUDED WITH THE FILE. Please see 
page 19 for more information about the TGA File Footer.</P><B>
<P>Byte 0-3 - Extension Area Offset - Field 28</P></B>
<P>The first four bytes (bytes 0-3, the first LONG) of the TGA File Footer 
contain an offset from the beginning of the file to the start of the Extension 
Area. Simply SEEK to this location to position to the start of the Extension 
Area. If the Extension Area Offset is zero, no Extension Area exists in the 
file.</P><B>
<P>Byte 4-7 - Developer Directory Offset - Field 29</P></B>
<P>The next four bytes (bytes 4-7, the second LONG) contain an offset from the 
beginning of the file to the start of the Developer Directory. If the Developer 
Directory Offset is zero, then the Developer Area does not exist.</P><B>
<P>Byte 8-23 - Signature - Field 30 </P></B>
<P>This string is exactly 16 bytes long and is formatted exactly as shown below 
capital letters), with a hyphen between "TRUEVISION" and "XFILE." If the 
signature is detected, the file is assumed to be of the New TGA format and MAY, 
therefore, contain the Developer Area and/or the Extension Area fields. If the 
signature is not found, then the file is assumed to be in the Original TGA 
format.</P>
<P><B>TRUEVISION-XFILE</P></B><B>
<P>Byte 24 - Reserved Character - Field 31</P></B>
<P>Byte 24 is an ASCII character "." (period). This character MUST BE a period 
or the file is not considered a proper TGA file.</P><B>
<P>Byte 25 - Binary Zero String Terminator - Field 32</P></B>
<P>Byte 25 is a binary zero which acts as a final terminator and allows the 
entire TGA File Footer to be read and utilized as a "C" string.</P><B>
<P>IMAGE TYPES </P></B><B>
<P>DATA TYPE 1 - COLOR-MAPPED IMAGES</P></B><U>
<P>Application:</P></U>
<P>This data type is used for storing color-mapped images (e.g., VDA/D, TARGA M8 
or Color-Mapped TrueVista images). Images stored in this format can be retrieved 
and displayed rapidly; however, a full-screen (256 x 200) VDA image requires 51K 
bytes of storage. This format is desirable where storage and display time are 
critical but where file size is not. </P>
<P>This file format also provides a compact way to store limited-color 
True-Color TARGA images. Software can easily display color-mapped images in 
real-color display modes by mapping pixels when it copies them to the display 
memory.</P><U>
<P>File Format Requirements:</P></U>
<P>Field 2 - Color-Map Type (1 Byte):</P>
<P>This value MUST be 1 (0x01) for this type. </P>
<P>Field 3 - Image Type (1 Byte): </P>
<P>This value is 1 (0x01) for this data type.</P><B>
<P>DATA TYPE 2 - TRUE-COLOR IMAGES</P></B><U>
<P>Application: </P></U>
<P>This data type is used for storing images where each pixel is represented by 
its red, green, and blue values (e.g. ICB, TARGA 16, TARGA 24, TARGA 32, and 
TrueVISTA images). This format is useful where storage and display time are 
critical and where file size is not.</P><U>
<P>File Format Requirements:</P></U>
<P>Field 2 - Color-Map Type (1 Byte): </P>
<P>This value MUST be 0 (0x00). TIPS from Truevision sets this value to 1 and 
stores a color pallet in this area. It is wise to check the image type to know 
when a color-map is needed, otherwise ignore the information. When new releases 
of Truevision software products are made available they will meet the TGA 
standard file format and no longer put pallet information in the color-map 
area.</P>
<P>Field 3 - Image Type (1 Byte): </P>
<P>This value must be 2 (0x02) for this data type.</P><B>
<P>DATA TYPE 3 - BLACK AND WHITE (UNMAPPED) IMAGES</P></B><U>
<P>Application:</U> </P>
<P>This data type is used for storing raster images where each pixel can be 
represented by a grey-scale value (e.g., the TARGA 8, TARGA M8 and some 
TrueVista modes).</P>
<P>This file format is used by the demonstration programs distributed with the 
TARGA 8.</P><U>
<P>File Format Requirements:</P></U>
<P>Field 2 - Color-Map Type (1 Byte):</P>
<P>This value is always Zero (0x00) for unmapped images.</P>
<P>Field 3 - Image Type (1 Byte):</P>
<P>This value is 3 (0x03) for this data type.</P><B>
<P>DATA TYPE 9 - RUN-LENGTH ENCODED (RLE), COLOR-MAPPED IMAGES</P></B><U>
<P>Application:</U> </P>
<P>This data type is used for storing images where each pixel is represented by 
a color map index. The information is encoded so that successive pixels with the 
same color value are run-length encoded. This format is designed for use with 
computer-generated (as opposed to captured) images which have large contiguous 
sections containing the same colors.</P><U>
<P>File Format Requirements:</P></U>
<P>Field 2 - Color Map Type (1 Byte):</P>
<P>This value is always 1 (0x01) for color-mapped images.</P>
<P>Field 3 - Image Type (1 Byte):</P>
<P>This value is 9 (0x09) for this data type.</P><B>
<P>DATA TYPE 10 - RUN-LENGTH ENCODED (RLE), TRUE-COLOR IMAGES</P></B><U>
<P>Application: </P></U>
<P>This data type is used for storing raster images where each pixel is 
represented by its red, green, and blue components. The infromation is encoded 
so that successive pixels with the same color value are run-length encoded.</P>
<P>Use this format for storing ICB, TARGA (16, 24, and 32), and TrueVISTA 
(16-bit RGB and 32-bit RGB modes) images. This type was primarily designed for 
computer generated (as opposed to captured) images which have large sections 
containing the same colors.</P><U>
<P>File Format Requirements:</P></U>
<P>Field 2 - Color Map Type (1 Byte):</P>
<P>This value is always Zero (0x00) for True-Color images.</P>
<P>Field 3 - Image Type Code (1 Byte):</P>
<P>This value is 10 (0x0A) for this data type.</P><B>
<P>DATA TYPE 11 - RUN-LENGTH ENCODED (RLE), </P>
<P>BLACK AND WHITE IMAGES</P></B><U>
<P>Application:</U> </P>
<P>This data type is used for storing raster images where each pixel is 
represented by a grey level. The information is encoded so that successive 
pixels with the same color value are run-length encoded.</P>
<P>This format is used for storing black and white TARGA 8 and TARGA M8 images 
and was primarily designed for use with computer-generated (as opposed to 
captured) images which have large sections containing the same gray 
values.</P><U>
<P>File Format Requirements:</P></U>
<P>Field 2 Color Map Type (1 Byte):</P>
<P>This value is always Zero (0x00) for True-Color images.</P>
<P>Field 3 Image Type Code (1 Byte):</P>
<P>This value is 11 (0x0B) for this data type.</P><B>
<P>RUN-LENGTH ENCODING OF IMAGES</P></B>
<P>Some of the Image Types described above are stored using a compression 
algorithm called Run-length Encoding. This type of encoding is used with file 
types 9 (Run-length Encoded Color-mapped Images), 10 (Run-length Encoded 
True-Color Images) and 11 (Run-length Encoded Black-and-white Images).</P>
<P>Run-length encoding takes advantage of the fact that many types of images 
have large sections in which the pixel values are all the same. This situation 
occurs more often in graphic images as opposed to captured, video images. In 
those images where large areas contain pixels of the same value, run-length 
encoding can greatly reduce the size of the stored image.</P>
<P>Run-length encoded (RLE) images comprise two types of data elements: 
Run-length Packets and Raw Packets.</P>
<P>The first field (1 byte) of each packet is called the Repetition Count field. 
The second field is called the Pixel Value field. For Run-length Packets, the 
Pixel Value field contains a single pixel value. For Raw Packets, the field is a 
variable number of pixel values.</P>
<P>The highest order bit of the Repetition Count indicates whether the packet is 
a Raw Packet or a Run-length Packet. If bit 7 of the Repetition Count is set to 
1, then the packet is a Run-length Packet. If bit 7 is set to zero, then the 
packet is a Raw Packet.</P>
<P>The lower 7 bits of the Repetition Count specify how many pixel values are 
represented by the packet. In the case of a Run-length packet, this count 
indicates how many successive pixels have the pixel value specified by the Pixel 
Value field. For Raw Packets, the Repetition Count specifies how many pixel 
values are actually contained in the next field. This 7 bit value is actually 
encoded as 1 less than the number of pixels in the packet (a value of 0 implies 
1 pixel while a value of 0x7F implies 128 pixels).</P>
<P>Run-length Packets should never encode pixels from more than one scan line. 
Even if the end of one scan line and the beginning of the next contain pixels of 
the same value, the two should be encoded as separate packets. In other words, 
Run-length Packets should not wrap from one line to another. This scheme allows 
software to create and use a scan line table for rapid, random access of 
individual lines. Scan line tables are discussed in further detail in the 
Extension Area section of this document.</P>
<P>As an example of the difference between the two packet types, consider a 
section of a single scan line with 128, 24-bit (3 byte) pixels all with the same 
value (color). The Raw Packet would require 1 byte for the Repetition Count and 
128 pixels values each being 3 bytes long (384 bytes). The total number of bytes 
required to specify the chosen data using the Raw Packet is, therefore, 385 
bytes. The Run-length Packet would require 1 byte for the Repetition Count and a 
single, 3-byte pixel value. The total number of bytes required to specify the 
chosen data using the Run-length Packet is, therefore, just 4 bytes!</P><B>
<P>Run-Length Packet:</P></B>
<P>Run-length packets are composed of two parts. The first is a repetition count 
and the second is the pixel value to repeat.</P>
<P align=center>Table 3 - Run-length Packet</P>
<P>1. Pixel Count: The pixel count can range from 0 to 127. Since a run-length 
packet never encodes zero pixels, and in order to make use of all of the values 
available with seven bits, a zero (0) in Pixel Count is defined to mean that 1 
pixel is encoded by the packet. A 1 in Pixel Count means that 2 pixels are 
actually contained in the packet. In other words, the value in Pixel Count is 
always 1 less than the actual number of pixels encoded in the packet. Thus, you 
may encode between 1 and 128 pixels with a single packet. If you have a run 
which is longer than 128 bytes, you must encode it using multiple packets.</P>
<P>Note: The high-order bit of this subfield is always set to 1 to indicate that 
the packet type is Run-length.</P>
<P>2. Pixel Data: This field contains a single pixel value to be repeated. The 
number of bits in this field is specified in Field 5.5 of the TGA File 
Header.</P>
<P>If 19 contiguous pixels in a scan line had the value 0x36 (assuming 
8-bits-per-pixel) then the Run-length Packet would be encoded as follows:</P><U>
<P>Remember that the Repetition Count contains 1 less than the actual number of 
pixels being encoded</U>. Since we were encoding 19 (0x13) pixels, a value of 18 
(0x12) was placed in the repetition count. Also, since this is a Run-length 
Packet, the high-order bit is set to 1. This changes the Repetition Count byte 
from a 0x12 to a 0x92. The resulting packet is, therefore, 0x9236.</P><B>
<P>Raw Packet (i.e., Non-Run-Length Encoded):</P></B>
<P>The raw packet is always composed of two fields. The first field is the 
Repetition Count and the second field is the Pixel Data field.</P>
<P align=center>Table 4 - Raw Packet</P>
<P>1. Pixel Count: The pixel count can range from 0 to 127. Since a raw packet 
never encodes zero pixels, and in order to make use of all of the values 
available with seven bits, a zero (0) in Pixel Count is defined to mean that 1 
pixel is included in the packet. A 1 in Pixel Count means that 2 pixels are 
actually contained in the packet. In other words, the value in Pixel Count is 
always 1 less than the actual number of pixels contained in the packet. Thus, 
you may encode between 1 and 128 pixels with a single packet. If you have a run 
which is longer than 128 bytes, you must encode it using multiple packets.</P>
<P>Note: The high-order bit of this subfield is always set to 0 to indicate that 
the packet type is a Raw Packet.</P>
<P>2. Pixel Data: Non-Run-Length Encoded pixel data. The pixels will be 
displayed in the order that they are stored.</P></BODY></HTML>
#	Change	User	Description	Committed
#1	4860	Matt Attaway	Adding information of Qt image plugins. This change includes sample source code, a list...	20 years ago