Author: Jeff Erickson & Keith Rollin
Year: 1988
... describes the internal format of the QuickDraw II picture data structure.
Apple II
Technical Notes
_____________________________________________________________________________
Developer Technical Support
Apple IIGS
#46: DrawPicture Data Format
Written by: Jeff Erickson & Keith Rollin November 1988
This Technical Note describes the internal format of the QuickDraw II picture
data structure.
_____________________________________________________________________________
This Technical Note presents the internal format of the QuickDraw II picture
data structure for informational purposes only. You should not use this
information to write your own bottleneck procedures; the only routines which
should create and read PICT format files are those provided in QuickDraw II.
If we added new objects to the picture definition, your program would not
operate on new pictures. This Note documents this information for debugging
purposes only.
Picture Data Structure Definition
Pictures are stored in memory in the following format:
They begin with a WORD which indicates the mode of the port which was used to
record when the picture was created. This information is useful when the
picture is played back, possibly in a different graphics mode.
Following the WORD is a RECT which indicates the frame of the picture and is
used for scaling when you redraw the picture. Following the RECT is the
version number of this PICT format, then a series of word-sized opcodes which
describe the sequences of QuickDraw II commands that were used to create the
picture.
Name Description Size (bytes)
pictSCB picture's scan line control byte 2 (high byte = 0)
picFrame picture's boundary rectangle 8
version picture version 2 (Currently $8211)
opcode operation code 2
<data> operation data variable, depending on opcode
:
opcode operation code 2
<data> operation data variable, depending on opcode
Opcodes
As mentioned above, pictures are described by a series of opcodes which are
used to record the QuickDraw II commands that created the picture. These
opcodes are two bytes long and are usually followed by a number of parameters.
All currently defined opcodes and their parameters are listed below. Any
opcodes not listed here are reserved.
Opcode Name Description Parm Bytes Parameter Description
$0000 NOP no operation 0 none
$0001 ClipRgn clip to a region [region size] region
$0002 BkPat background pattern 32 background pattern (8x8
pixels)
$0003 TxFont text font 4 Font Manager font ID
(long)
$0004 TxFace text face 2 text face (word)
$0005 TxMode text mode 2 text mode (word)
$0006 SpExtra space extra 4 space extra (fixed)
$0007 PnSize pen size 4 pen size (point)
$0008 PnMode pen mode 2 pen mode (word)
$0009 PnPat pen pattern 32 pen pattern (8x8 pixels)
$000A FillPat fill pattern 32 fill pattern (8x8
pixels)
$000B OvSize oval size 4 oval size (point)
$000C Origin origin 4 origin (point)
$000D TxSize text size 2 text size (word)
$000E FGColor foreground color 2 color (word)
$000F BGColor background color 2 color (word)
$XX11 Version version 0 none: high byte=version
(currently $82)
$0012 ChExtra character extra 4 char. extra (fixed)
$0013 PnMask pen mask 8 mask (8 bytes)
$0014 ArcRot arc rot 2 Reserved (related to
things drawn with
patterns). (word)
$0015 FontFlags font flags 2 font flags (word)
$0020 Line line 8 pnLoc (point), newPt
(point)
$0021 LineFrom line from pen loc. 4 newPt (point)
$0022 ShortLine short line 6 pnLoc (point), dv, dh
(signed bytes)
$0023 ShortLFrom ditto from pen loc 2 dv, dh (signed bytes)
$0028 LongText long text 5+text txLoc (point), count
(byte), text
$0029 DHText hor. offset text 2+text dh (unsigned byte),
count (byte), text
$002A DVText vert. offset text 2+text dv (unsigned byte),
count (byte), text
$002B DHDVText offset text 3+text dv, dh (unsigned bytes),
count (byte), text
$002C RealLongText very long text 6+text txLoc (point), count
(word), text
Opcodes between $0030 and $008C are a combination of a graphic verb and a
graphic object, as listed below (where "V" stands for the graphic verb, and
"X" is a stands for the graphic object). For example, $0069 means
PaintSameArc, and is followed by two one-word parameters.
Graphic Verbs:
$00X0 Frame... frame something [Specific to object type
see below.]
$00X1 Paint... paint something
$00X2 Erase... erase something
$00X3 Invert... invert something
$00X4 Fill... fill something
$00XV+8 ...Same... draw same thing somehow [See below; {braced}
parms do not appear.]
Graphic Objects:
$003V ...Rect draw a rectangle somehow 8 (0 if - SameRect) {rect
(2 points)}
$004V ...RRect draw a round rect somehow 8 (0) {rect (2 points)}
$005V ...Oval draw an oval somehow 8 (0) {rect (2 points)}
$006V ...Arc draw an arc somehow 12 (4) {rect (2 points)},
start, arc angle (words)
$007V ...Poly draw a polygon somehow [polygon size] (0){polygon}
$008V ...Rgn draw a region somehow [region size] (0) {region}
$0090 BitsRect copybits, rect clipped variable* (see below, but
without maskRgn)
$0091 BitsRgn copybits, rgn clipped variable* (see below)
$00A1 LongComment long comment 4+data kind (word), size
(word), data
*Bits... data:
origSCB original scan line control byte 2 SCB (word --
high byte = 0)
BWvsColor black and white vs. color 2 reserved (word)
width width of pixel image in bytes 2 width (word)
boundsRect bounds rectangle 8 rect (2 points)
srcRect source rectangle 8 rect (2 points)
destRect destination rectangle 8 rect (2 points)
mode transfer mode 2 pen mode (word)
maskRgn mask region (BitsRgn ONLY!) [region size] region
pixData pixel image [pixdata size] width*
(bounds.bottom-
bounds.top)
Differences Between IIGS Pictures and Macintosh Pictures
1. QuickDraw II pictures are modeled after PICT2 on the Macintosh,
which use two bytes for its opcodes and data (the exception to
this is the $11 (version) opcode, which is followed by a one-byte
parameter). Macintosh PICT 1.0 formats, which use one-byte
opcodes, would have to undergo extensive modifications to be
displayed on the IIGS.
2. There is no EndOfPicture opcode on the IIGS as there is on the
Macintosh. Also, the first word of the picture is a pictSCB, not
the length of the picture. The picture size is determined solely
by the size of the handle on the IIGS. There is also no picture
header on the IIGS as on the Macintosh.
3. The number sex of the Macintosh is opposite that of the Apple
IIGS. The Macintosh stores the high bytes of words and long words
first, whereas the IIGS stores the low byte first.
4. The following Macintosh picture opcodes are not available on the
IIGS: txRatio, PackBitsRect, PackBitsRgn, shortComment,
EndOfPicture.
5. QuickDraw II defines the following opcodes that the Macintosh does
not: ChExtra ($12), PnMask ($13), ArcRot ($14), FontFlags ($15),
and RealLongText ($2C).
Notes on the Interpretation of IIGS Pictures
o The state of the pen, the clip region, various patterns and
colors, and the origin of the current port is saved before a
picture is drawn, and restored afterwards. The current port is
set up in a default state equivalent to that of a newly created
port just before drawing begins. Picture opcodes act just like
their QuickDraw II tool counterparts, with a few exceptions.
o Two pen locations are tracked as the picture is drawn, one for
lines and one for text. Thus, LineFrom always draws from the end
of the last line, regardless of any intermediate text opcodes.
o Text calls do not change the position of the "text pen," as do
normal QuickDraw II text calls. Thus, if a picture contains two
lines of text, the second one directly below the first, the second
will be stored using a DVtext opcode.
o DrawPicture performs considerable setup before it draws pictures.
Among other things, it calls InstallFont, which is a Font Manager
call. If you are going to support pictures in your application,
you should load and start the Font Manager.
Further Reference
o Apple IIGS Toolbox Reference, Volume 2