Table Of Content

Truevision TGAª FILE FORMAT SPECIFICATION Version 2.0 Documentpreparedby: Truevision,Inc. 7340ShadelandStation Indianapolis,IN46256-3925 800-729-2656-phone 317-576-7700-FAX 317-577-8777-BBS http://www.truevision.com/ TechnicalManualVersion2.2 January,1991 Copyright©1989,1990,1991Truevision,Inc. TruevisionisaregisteredtrademarkofTruevision,Inc. TARGAisaregisteredtrademarkofTruevision,Inc. TrueVistaisaregisteredtrademarkofTruevision,Inc. ATVistaisaregisteredtrademarkofTruevision,Inc. NuVistaisaregisteredtrademarkofTruevision,Inc. TIPSisaregisteredtrademarkofTruevision,Inc. TGAisatrademarkofTruevision,Inc. Disclaimer of Warranties and Limitations of Liabilities ThismanualandtheenclosedsoftwarewerepreparedbyTruevision,Inc. Whiletheauthorsandprogram developershavetakenreasonablecareinpreparingthismanualtoassureaccuracy,theauthorsassumeno liabilityresultingfromanyinaccuracyoromissionscontainedinthemorfromtheuseoftheinformationor programscontainedherein. 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. INTRODUCTION.........................................................................................................................1 DEFINITIONS.............................................................................................................................2 TGAFILEFORMATSPECIFICATION........................................................................................4 TGAFILEHEADER....................................................................................................................6 IDLength-Field1(1byte):............................................................................................6 ColorMapType-Field2(1byte):..................................................................................6 ImageType-Field3(1byte):.........................................................................................6 ColorMapSpecification-Field4(5bytes):...................................................................7 ImageSpecification-Field5(10bytes):........................................................................8 IMAGE/COLOR MAP DATA...........................................................10 ImageID-Field6(variable):.........................................................................................10 ColorMapData-Field7(variable):..............................................................................10 ImageData-Field8(variable):.....................................................................................10 DEVELOPER AREA........................................................................11 DeveloperData-Field9(variable):..............................................................................11 EXTENSION AREA.........................................................................13 ExtensionSize-Field10(2Bytes):..............................................................................13 AuthorName-Field11(41Bytes):..............................................................................13 AuthorComments-Field12(324Bytes):....................................................................13 Date/TimeStamp-Field13(12Bytes):........................................................................14 JobName/ID-Field14(41Bytes):...............................................................................14 JobTime-Field15(6Bytes):.......................................................................................14 SoftwareID-Field16(41Bytes):.................................................................................15 SoftwareVersion-Field17(3Bytes):..........................................................................15 KeyColor-Field18(4Bytes):......................................................................................15 Pixel AspectRatio-Field19(4Bytes):........................................................................16 ColorCorrectionOffset-Field21(4Bytes):...............................................................16 PostageStampOffset-Field22(4Bytes):..................................................................16 ScanLineOffset-Field23(4Bytes):...........................................................................17 AttributesType-Field24(1Byte):..............................................................................17 ScanLineTable-Field25(Variable):..........................................................................18 Postage StampImage-Field26(Variable):................................................................18 ColorCorrectionTable-Field27(2KBytes):..............................................................18 TGA FILE FOOTER.........................................................................19 Byte0-3-ExtensionAreaOffset-Field28..................................................................19 Byte4-7-DeveloperDirectoryOffset-Field29..........................................................19 Byte8-23-Signature-Field30....................................................................................20 Byte24-ReservedCharacter-Field31.......................................................................20 Byte25-BinaryZeroStringTerminator-Field32......................................................20 IMAGE TYPES ...............................................................................21 DATATYPE1-COLOR-MAPPEDIMAGES..................................................................21 DATATYPE2-TRUE-COLORIMAGES.......................................................................21 DATATYPE3-BLACKANDWHITE(UNMAPPED)IMAGES.......................................22 DATATYPE9-RUN-LENGTHENCODED(RLE),COLOR-MAPPED IMAGES.........................................................................................................................22 DATATYPE10-RUN-LENGTHENCODED(RLE),TRUE-COLOR IMAGES.........................................................................................................................23 DATATYPE11-RUN-LENGTHENCODED(RLE), ......................................................23 BLACKANDWHITEIMAGES.......................................................................................23 RUN-LENGTH ENCODING OF IMAGES........................................24 Run-LengthPacket:......................................................................................................25 RawPacket (i.e.,Non-Run-LengthEncoded):............................................................26 1 INTRODUCTION ThesuccessoftheTGAªFileFormatforstoringcolorimagescanbeattributedtoitseaseofuse,thesmall amountofprogrammemoryneededtoparsethefile,andthefactthatitwasthefirsttrue-colorfileformat widelyavailable. Truevision¨definedtheTGAfileformatin1984forusewithitsfirstvideographics products. Sincethen,ithasbeenestimatedthattodayover80percentofthecolor imagesstoredonhard drivesemploysomevariationoftheTGAfileformat. Manygovernmentoffices,corporations,service bureaus,productionshopsandnearlyallTruevisiondevelopershavestandardizedontheTGAformatasa meansofallowingcross-productandcross-applicationcompatibility. Truevisionrecommendsthatthis formatbeusedbyallsoftwaredevelopedforTruevisionproductssinceitallowscustomersflexibilityin combiningmanyapplicationstogethertoprovideatotalsolutiontomeettheirneeds. TheoriginalTruevisionTGAFileFormathasbeenwidelyacceptedbythegraphicsindustry. However, newertechnologyandtechniqueshavecreatedtheneedforadditionalimageinformationtoberecordedin thefile. In1989,TruevisionintroducedextensionstotheTGAFileFormattosatisfyrequestsmadebythe graphicsindustryandtoensurethatthestandardwillmeetfutureneedsofthecolorimagingmarketplace. Theextensionsareoptionalandwillhavenoimpactonexistingpackages(assumingthepackagesfollowed theoriginalTGAFileFormatguidelines). Inparticular,thenewTGAFileFormataddressesthefollowing needs: *Theinclusionofascaled-down“postagestamp”copyoftheimage *DateandTimeofimagefilecreation *AuthorName *AuthorComments *JobName *JobAccumulatedTime *GammaValue *CorrectColorLUT *PixelAspectRatio *ScanLineOffsetTable *KeyColor *SoftwarePackageNameandVersionNumber *DeveloperDefinableAreas *Attribute(Alpha)channelType *Theabilityforsimpleexpansion 2 DEFINITIONS Throughoutthisdocument,wewillbeusingthetermsPseudo-Color,True-ColorandDirect-Color. Thesetermsaredefinedasfollows: Pseudo-Color-Eachpixelvalueisusedasasingleindexintoaprogrammablecolormapwhichcontains theactualred,greenandblueintensitiestobedisplayed. TheTruevisionproductsthatusethistype ofimageare: VDA,VDA/D,TARGA¨M8,ATVista¨,NuVista¨andHRªvideographicsboards. True-Color-Eachpixelvalueissub-dividedintored,greenandbluefieldsthatdirectlydeterminethe intensitiesofeachprimarycolor. TheTruevisionproductsthatusethistypeofimageare: ICB, TARGA16,TARGA24,TARGA32,ATVistaandNuVistavideographicsboards. Direct-Color-Eachpixelvalueissub-dividedintored,greenandbluefieldswhichare usedasseparate indicestoaccessindependent,programmablelook-uptables. Theoutputsoftheindividualcolor mapsdirectlydeterminetheintensitiesofeachprimarycolor. ADirect-Colorsystemissimilarto Pseudo-Colorexceptthatthevaluesinthecolormapscanbealteredindividuallyforthered,green andbluechannels;whereas,thered,greenandbluevaluesinaPseudo-Colorsystemareloadedinto onemapwhichisaccessedbyasingleindex. Truevisionproductsthatusethistypeofimageare: ATVistaandNuVistavideographicsboards. TheTrueVista¨(ATVistaandNuVista)videographicscardscanbeprogrammedtoacceptimageswhich arePseudo-Color,True-ColorandDirect-Color. WhentheyarefunctioninginanyoftheLinkedModes, theyaresaidtobeactingasPseudo-Colordevices. WhentheyareconfiguredforanyoftheIndependent Modes,theyaresaidtobeactingasDirect-Colordevices. Whenbypassingthelook-uptablesaltogether, theyaresaidtobeactingasTrue-Colordevices. TheVDA,VDA/D,TARGAM8andHRcanonlybeusedasPseudo-Colordevices. TheICB,TARGA16, 24and32canonlybeusedasTrue-Colordevices. Long=32bitvalue Short=16bitvalue Byte=8bitvalue ASCII=sequenceofbytesconformingtotheASCIIdefinition(TruevisionrecommendsthattheASCII fieldscontainonlyprintableASCIIcharacters,withexceptionofthenullterminator,andthatall formattingbeperformedbytheapplication) BitNumbering(fordiagramsinthisdocument) 3 ByteOrdering TGAfilesarestoredusingtheIntelbyteorderingconvention(leastsignificantbytefirst,mostsignificant bytelast). Forthisreason,applicationsrunningonMotorola-basedsystemswillneedtoinverttheordering ofbytesforshortandlongvaluesafterafilehasbeenread. Suffix andFileTypeDefinitions Sincethereisagreatneedtobeabletolocatefileseasilyonmassstoragedevices,wehavedefineda filenamesuffixforDOSandUNIXoperatingsystems,andafiletypefortheMacintoshenvironment. You shouldusethisfilenamesuffixorfiletypeforallTGAimagefiles. 1. DOS,UNIXandXENIXenvironments-Appendtotheendofthefilenameathreecharactersuffix “TGA”afterthe“.”indicator. Example:“Image.tga.” 2. Macintoshenvironment-Useafiletypeof“TPIC”. However,thedemonstrationsoftwareandtheprogramsintheTruevisionsoftwareseriescurrentlyusethe suffixes,“.VDA”,“.ICB”,“.TGA”,and“.VST”,forVDA/D,ICB,TARGAand ATVistaimages. Itis thereforesuggestedthatapplicationsshouldallowtheuserthecapabilityofreadingimageswithanyof theseextensions,butshouldonlyusetheextension“.TGA”whenwritingimages. Asfutureversionsof Truevisionsoftwareproductsaremadeavailable,theywillconverttousingthe“.TGA”and“TPIC” conventions exclusively. 4 TGA FILE FORMAT SPECIFICATION Figure1-TGAFileFormat 5 WhileFigure1demonstratesonepossiblearrangementforthevariousdatablockswithinaTGAFile,other arrangementsarepossiblesincemanyofthedatablocksarereferencedbyanoffsetpositionfromthe beginningofthefile. Inparticular,developersmayfinditeasiertocreatethefileiftheScanLineTable, thePostageStampImageandtheColorCorrectionTablearelocatedbeforetheExtensionSizefield(Field 10). TheTruevisionTGAFileFormatcomprises 5areas,eachofwhichcontainsoneormorefieldsof fixedorvariablelength. The5fileareasare:(1)TGAFileHeader, (2)Image/ColorMapData, (3) DeveloperArea, (4)ExtensionAreaand(5)TGAFileFooter. Thelast3areas,theDeveloperArea,theExtensionAreaandtheTGAFileFooterarenewtothefile specificationasofSeptember,1989. Forthisreason,imagescreatedwithsoftwarewrittenbefore September,1989willprobablynotcontainthesethreefields. Inthisdocument,theTGAFileformatprior toSeptember,1989willbereferredtoastheOriginalTGAFormatwhilethecurrentTGAFileformatwill bereferredtoastheNewTGAFormat. 1. ATGAReadershouldbeginbydeterminingwhetherthedesiredfileisintheOriginalTGA FormatortheNewTGAFormat. Thisisaccomplishedbyexaminingthelast26bytesofthe file(mostoperatingsystemssupportsometypeofSEEKfunction). Readingthelast26bytes fromthefilewilleitherretrievethelast26bytesofimagedata(ifthefileisintheOriginal TGAFormat),oritwillretrievetheTGAFileFooter(ifthefileisintheNewTGAFormat). 2. TodeterminewhethertheacquireddataconstitutesalegalTGAFileFooter,scanbytes8-23 ofthefooterasASCIIcharactersanddeterminewhethertheymatchthesignaturestring: TRUEVISION-XFILE Thisstringisexactly16byteslongandisformattedexactlyasshownabove(capitalletters), withahyphenbetween“TRUEVISION”and“XFILE.” Ifthesignatureisdetected,thefile isassumedtobeintheNewTGAformatandMAY,therefore,containtheDeveloperArea and/ortheExtensionAreafields. Ifthesignatureisnotfound,thenthefileisassumedtobe intheOriginalTGAformatandshouldonlycontainareas1and2;therefore,thebyteformat fortheTGAFileFooterisdefinedasfollows: Bytes0-3: TheExtensionAreaOffset Bytes4-7: TheDeveloperDirectoryOffset Bytes8-23: TheSignature Byte24: ASCIICharacter “.” Byte25: Binaryzerostringterminator(0x00) Note: DEVELOPERSARENOTREQUIREDTOREAD,WRITEORUSETHEEXTENSIONOR DEVELOPERAREAS;THEYAREOPTIONAL. EVENIFTHESEAREASARENOTUSED,ITIS RECOMMENDEDTHATATGAFILEFOOTERSTILLBEINCLUDEDWITHTHEFILE. Pleasesee page19formoreinformationabouttheTGAFileFooter. 6 TGA FILE HEADER IDLength-Field1(1byte): ThisfieldidentifiesthenumberofbytescontainedinField6,theImageIDField. Themaximumnumber ofcharactersis255. AvalueofzeroindicatesthatnoImageIDfieldisincludedwiththeimage. ColorMapType-Field2(1byte): Thisfieldindicatesthetypeofcolormap(ifany)includedwiththeimage. Therearecurrently2defined valuesforthisfield: 0- indicatesthatnocolor-mapdataisincludedwiththisimage. 1- indicatesthatacolor-mapisincludedwiththisimage. Thefirst128ColorMapTypecodes(Field2)arereservedforusebyTruevision,whilethesecondsetof 128ColorMapTypecodes(128to255)maybeusedfordeveloperapplications. True-Colorimagesdonotnormallymakeuseofthecolormapfield,butsomecurrentapplicationsstore paletteinformationordeveloper-definedinformationinthisfield. ItisbesttocheckField3,ImageType, tomakesureyouhaveafilewhichcanusethedatastoredintheColorMapField. Otherwiseignorethe information. WhensavingorcreatingfilesforTrue-ColorimagesdonotusethisfieldandsetittoZeroto ensurecompatibility. PleaserefertotheDeveloperAreaspecificationformethodsofstoringdeveloper definedinformation. ImageType-Field3(1byte): TheTGAFileFormatcanbeusedtostorePseudo-Color,True-ColorandDirect-Colorimagesofvarious pixeldepths. Truevisionhascurrentlydefinedsevenimagetypes: Table1-ImageTypes 7 ImageDataTypecodes0to127arereservedforusebyTruevisionforgeneralapplications. ImageData Typecodes128to255maybeusedfordeveloperapplications. Foracompletedescriptionoftheseimage-datatypes,seetheIMAGETYPESsectionlaterinthismanual. ColorMapSpecification-Field4(5bytes): Thisfieldanditssub-fieldsdescribethecolormap(ifany)usedfortheimage. IftheColorMapTypefield issettozero,indicatingthatnocolormapexists,thenthese5bytesshouldbesettozero. Thesebytes alwaysmustbewrittentothefile. Field4.1(2bytes)- FirstEntryIndex: Indexofthefirstcolormapentry. Indexreferstothestartingentryin loadingthecolormap. Example: Ifyouwouldhave1024entriesintheentirecolormapbut youonlyneedtostore72ofthoseentries,thisfieldallowsyoutostart inthemiddleofthecolor-map(e.g.,position342). Field4.2(2bytes)- ColormapLength: Totalnumberofcolormapentriesincluded. Field4.3(1byte)- ColormapEntrySize: Establishesthenumberofbitsperentry. Typically15,16,24or32-bit valuesareused. WhenworkingwithVDAorVDA/Dcardsitispreferredthatyouselect 16bits(5bitsperprimarywith1bittoselectinterruptcontrol)andset the16thbitto0sothattheinterruptbitisdisabled. Evenifthisfieldis setto15bits(5bitsperprimary)youmuststillparsethecolormapdata 16bitsatatimeandignorethe16thbit. WhenworkingwithaTARGAM8cardyouwouldselect24bits(8bits perprimary)sincethecolormapisdefinedas256entriesof24bitcolor values. WhenworkingwithaTrueVistacard(ATVistaorNuVista)youwould select24-bit(8bitsperprimary)or32-bit(8bitsperprimaryincluding Alphachannel)dependingonyourapplication’suseoflook-uptables. Itissuggestedthatwhenworkingwith16-bitand32-bitcolorimages, youstorethemasTrue-Colorimagesanddonotusethecolormapfield tostorelook-uptables. PleaserefertotheTGAExtensionsforfields bettersuitedtostoringlook-uptableinformation. ImageSpecification-Field5(10bytes): Thisfieldanditssub-fieldsdescribetheimagescreenlocation,sizeandpixeldepth. Thesebytesare alwayswrittentothefile. Field5.1(2bytes)- X-originofImage: Thesebytesspecifytheabsolutehorizontalcoordinateforthelowerleft corneroftheimageasitispositionedonadisplaydevicehavingan originatthelowerleftofthescreen(e.g.,theTARGAseries). Field5.2(2bytes)- Y-originofImage: