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 (December 1991)
Written by Steve Glass, Eagle Berns, Art Cabral & Pete McDonald
(October 1987)
Files of this type and auxiliary type contain a Super Hi-Res picture in the
Apple-recommended format.
Changes since September 1990: Added a recommendation for more
conventional respresentation of 3200-color pictures.
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.
If you use the MULTIPAL block to store pictures with more colors than are
typically displayable on the screen, Apple recommends you also create a MAIN
block with a 16-color (or grayscale) representation of the picture, so users
may open these files in les specialized applications to at least preview the
picture enclosed.
Further Reference
This and all of the other Apple II Technical Notes have been converted
to HTML by Aaron Heiss as a public service to the Apple II community, with
permission by Apple Computer, Inc. Any and all trademarks, registered and
otherwise, are properties of their owners.