Apple II
File Type Notes
_____________________________________________________________________________
                                                  Developer Technical Support

File Type:         $C0 (192)
Auxiliary Type:    $0002

Full Name:     Apple IIgs Super Hi-Res Picture File
Short Name:    "Apple Preferred" Picture

Revised by:    Matt Deatherage    September 1990
Written by:    Steve Glass, Eagle Berns, Art Cabral              October 1987
               & Pete McDonald

Files of this type and auxiliary type contain a Super Hi-Res picture in the 
Apple-recommended format.
Changes since May 1990:  Added a description of the MULTIPAT block to the 
optional blocks section.  Changed Palette to be ColorTable because that's what 
was really meant.
_____________________________________________________________________________

Files of type $C0 and auxiliary type $0002 contain a Super Hi-Res picture in 
the format recommended by Apple.  The file consists of a series of variable-
length blocks (in any order), each with the same general format:

    Length               Long    Defines the length of this block, 
                                 including Length itself.
    Kind                 String  String used to identify the type of 
                                 block.  The string is stored as a 
                                 series of case-sensitive ASCII 
                                 characters preceded by a length 
                                 byte.  To avoid confusion, the use 
                                 of uppercase characters only is 
                                 recommended.
    Data                 Bytes   Variable amount of block-specific 
                                 data.

With this scheme, the file format is flexible and can be extended.  Standard 
blocks which most applications want are defined below, however, these are not 
required.  Individual applications can define other blocks.  Application-
dependent information can be stored to allow other applications to ignore it.  
Your application should simply ignore blocks it finds which it is not prepared 
to interpret.

Data Types

    Integer              16-bit signed word.
    LongInt              32-bit signed long word.
    ColorEntry           16-bit word. The nibbles in the word are 
                         interpreted as RGB values as follows:  $0RGB.  
                         The high nibble of the high byte must be zero 
                         and should be ignored when reading files.  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 (see Figure 16-19 on 
                         page 16-31 of the Apple IIgs Toolbox Reference).
    ColorTable           16 words:  array [0..15] of ColorEntry
    ModeWord             16-bit word.  The high byte determines the 
                         definition of the mode. If high byte = 0, then 
                         the low byte is the mode bit portion of the SCB 
                         for the scan line  (see Figure 16-22 on page 16-
                         34 of the Apple IIgs Toolbox Reference).  Other 
                         bits are reserved and must be zero, as other 
                         modes are not yet defined.
    DirEntry             A two-word structure used to define the 
                         characteristics of each packed line:
                             Integer:     Number of bytes to unpack
                             ModeWord:    Mode
    PatternData          32 bytes of pattern information


MAIN Information Block

Every file usually, but not necessarily (i.e., a file of palettes only), 
includes a MAIN block.

    Length               LongInt
    Kind                 String "MAIN"
    MasterMode           ModeWord (from the MasterSCB of QuickDraw II.  
                         When reading a file, this word should 
                         be used in a SetMasterSCB call.)
    PixelsPerScanLine    Integer (must not be zero)
    NumColorTables       Integer (may be zero)
    ColorTableArray      [0..NumColorTables-1] of ColorTable
    NumScanLines         Integer (must not be zero)
    ScanLineDirectory    [0..NumScanLines-1] of DirEntry
    PackedScanlines      [0..NumScanLines-1] of Packed Data 
                         (Obtained by performing a PackBytes call 
                         on the pixel image of a single scan line.)


PATS Information Block

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

    Length               LongInt
    Kind                 String "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.  This information is used by paint programs that want to 
save a foreground pattern, a background pattern, and a frame pattern with the 
image.

    Length               LongInt
    Kind                 String "SCIB"
    ForegroundPattern    PatternData
    BackgroundPattern    PatternData
    FramePattern         PatternData


PALETTES Information Block

The PALETTES block contains information on the color tables.  Its use is 
intended for color table files.  If the file being saved contains a pixel 
image, then the color tables associated with that picture should be saved in 
the MAIN block, and this block would not be used.

    Length               LongInt
    Kind                 String "PALETTES"
    NumColorTables       Integer (must not be zero)
    ColorTableArray      [0..NumPalettes-1] of ColorTable


Other Information Blocks

Apple Preferred Format is an extensible graphics file format.  Since its 
release, some developers have contributed other block definitions that other 
developers may find to be useful.  Please feel free to incorporate these 
blocks into Apple Preferred files, but you must be prepared to deal with Apple 
Preferred files that do not contain these additional blocks.

MASK Information Block

The MASK block contains information on which portions of a graphic image 
should be modified.  The structure is similar to that of the MAIN block.  
However, the MASK array of PackedScanLines contains zeroes where no drawing is 
to occur (where the image is transparent) and ones where drawing may occur 
(where the image is solid).  The structural similarity to the MAIN block can 
help by allowing some of your code to do double work.

    Length               LongInt
    Kind                 String "MASK"
    MasterMode           ModeWord (from the MasterSCB of QuickDraw II.  
                         When reading a file, this word should 
                         be used in a SetMasterSCB call.)
    PixelsPerScanLine    Integer (must not be zero)
    NumColorTables       Integer (must be zero)
    NumScanLines         Integer (must not be zero)
    ScanLineDirectory    [0..NumScanLines-1] of DirEntry
    PackedScanlines      [0..NumScanLines-1] of Packed Data 
                         (Obtained by performing a PackBytes call 
                         on the pixel image of a single scan line.)

    Note:  There is no ColorTableArray, as indicated by a zero value 
           in NumColorTables.
    Note:  The scan lines to be packed should only contain mask values 
           of one and zero.

MULTIPAL Information Block

The MUTLIPAL block contains extra color tables necessary for displaying 
pictures that contain up to 3,200 colors on the screen.

    Length               LongInt
    Kind                 String "MULTIPAL"
    NumColorTables       Integer (should be the same as NumScanLines 
                         in MAIN).  This is typically 200, but any value 
                         is legal.
    ColorTableArray      [0..NumColorTables-1] of ColorTable.  
                         These are in the regular (0-15) order.


Further Reference
_____________________________________________________________________________
  o  Apple IIgs Toolbox Reference
  o  Apple IIgs Technical Note #94, Packing It In (and Out)

