____________________________________________________________
Apple // Technical Notes

Apple IIGS Technical Note #27: Graphics Image File Formats

Written by: Steve Glass, Eagle Berns, Art Cabral,
            Pete McDonald, Rilla Reynolds    October 1, 1987
____________________________________________________________

This was published previously as "Graphics Image File Format Standard for Apple IIGS," 2/26/87. Changes have been made since the 2/26 draft: QuickDraw PICT files have been included, the MAIN information block in a "Preferred" file type no longer is required, and a new PALETTES information block has been added to the "Preferred" file format description. If you have questions or suggestions, contact Developer Technical Support at the address listed in Technical Note 0.
____________________________________________________________



Unpacked Graphics Image Formats (ProDOS File Type $C1)


File Type $C1, Auxiliary Type $0000

This type contains a file with a full 32K unpacked picture image. Currently, it is being used by Apple and Activision's PaintWorks. (Note: The first release of PaintWorks assumes the palettes' colors have been ordered from highest to lowest luminance.


File Type $C1, Auxiliary Types $0001 "Unpacked QD PICT File"

Unpacked QuickDraw PICT file. This contains an unpacked QuickDraw picture. See the chapter on the QuickDraw Auxilliary Tools in the Apple IIGS Toolbox Reference for more details about pictures.


File Type $C1, Auxiliary Types $0002..$FFFF

These are not yet defined. Auxiliary types will be assigned and maintained by Developer Technical Support.



Packed Graphics Image Formats (ProDOS File Type $C0)


File Type $C0, Auxiliary Type $0000

Packed format used by Activision's PaintWorks. Its format is as follows:

   Bytes $000..$01F:  Palette
   Bytes $020..$021:  Background color
   Bytes $022..$221:  16 patterns, 32 bytes each
   Bytes $222..end:   Packed picture


FileType $C0, Auxiliary Type $0001               "PackBytes"

This type of file is created by passing a full 32K image (including SCBs and color tables) to Miscellaneous Tools' PackBytes routine.


FileType $C0, Auxiliary Type $0002         "Apple Preferred"

This is the recommended format to use and support. The file consists of a series of variable-length blocks, each with the same general format:

   Length               LongInt
                           (Length includes size of LongInt)
   Kind                 String with length byte
                           (String is case-sensitive;
                            upper case is recommended to
                            avoid confusion)
   Block-Specific Data  Variable amount of data

Standard blocks that most applications will want to put in a file are defined below. These aren't required, however. Other blocks can be defined by individual applications. Using this scheme, the format is extendable. Application-dependent information can be stored in a way that will allow other applications to ignore information not needed.

MAIN Information Block. A MAIN block usually, but not necessarily, will be in every file of this format. 

   SizeOfBlock        LongInt
   IDString           str 'MAIN'
   MasterMode         ModeWord (from QuickDraw's MasterSCB)
   PixelsPerScanLine  Integer (must not be zero)
   NumPalettes        Integer (may be zero)
   PaletteArray       [0..NumPalette-1] of Palette
   NumScanLines       Integer (must not be zero)
   ScanLineDirectory  [0..NumScanLines-1] of DirEntry
   PackedScanlines    [0..NumScanLines-1] of PackedData

The palettes in the MAIN block are numbered from 0, corresponding to modes in the scan line directory.

PATS Information Block. The PATS block contains patterns which may be associated with the picture.

   SizeOfBlock   LongInt
   IDString      str 'PATS'
   NumPats       Integer
   PatternArray  [0..NumPats-1] of PatternData

SCIB Information Block. The SCIB block contains information relating to the current drawing pattern for the "document." These are used by paint programs that want to save a foreground pattern, a background pattern, and a frame pattern with the image.

   SizeOfBlock        LongInt
   IDString           str 'SCIB'
   ForegroundPattern  PatternData
   BackgroundPattern  PatternData
   FramePattern       PatternData

PALETTES Information Block.

   SizeOfBlock   LongInt
   IDString      str 'PALETTES'
   NumPalettes   Integer (must not be zero)
   PaletteArray  [0..NumPalettes-1] of Palette

Data Types:

   Integer      word  16-bit signed quantity
   LongInt      LONG  32-bit signed quantity
   ColorEntry   word  The nibbles in the word are
                      interpreted as RGB values as follows:
                      $0RGB. The high nibble of the high
                      byte must be 0. The low nibble of the
                      high byte is the value for red. The
                      high nibble of the low byte is the
                      value for green, and the low nibble of
                      the low byte is the value for blue.
   Palette:     array [0..15] of ColorEntry
   ModeWord     word  If high byte = 0, then low byte is the
                      mode bit portion of the SCB for the
                      scanline the low four bits determine
                      the palette number and bit 7
                      determines if the mode is valid.
                      Other bits are reserved and must be
                      zero. Other modes are not yet defined.
   DirEntry:    Number of bytes to unpack   Integer
                Mode                        ModeWord
   PatternData: 32 bytes of pattern information


FileType $C0, Auxiliary Type $0003     "Packed QD PICT File"

This aux type is assigned to packed QuickDraw PICT files. This contains a packed QuickDraw picture. The picture is packed using the PackBytes routine from the Miscellaneous Tools. See the chapter on the QuickDraw Auxilliary Tools in the Apple IIGS Toolbox Reference for more details about pictures.