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.