Author: Steven Glass (rev. Dave "Evad Snoyl" Lyons, Keith Rollin, Steven Glass, Matt Deatherage & Eric Soldan)
Year: 1988
... the low-level routines which QuickDraw II uses ... and custom bottleneck (drawing) procedures.
Apple II
Technical Notes
_____________________________________________________________________________
Developer Technical Support
Apple IIGS
#34: Low-Level QuickDraw II Routines
Revised by: Dave "Evad Snoyl" Lyons, Keith Rollin,
Steven Glass, Matt Deatherage & Eric Soldan January 1991
Written by: Steven Glass May 1988
This Technical Note describes the low-level routines which QuickDraw II uses
to do much of the work in standard calls and mechanisms for calling these
routines and accessing their data.
Changed since November 1990: Added a Note on custom bottleneck procedures and
updated information on ShieldCursor and UnShieldCursor.
_____________________________________________________________________________
QuickDraw II lets you customize low-level drawing operations by intercepting the
"bottleneck procedures." QuickDraw II calls an appropriate "bottleneck proc"
every time it receives a call to draw an object, measure text, or deal with
pictures. For example, if an application calls PaintOval, QuickDraw II calls
StdOval to do the real work, and if an application calls InvertRgn, QuickDraw II
calls StdRgn to do the work.
Installing your own bottleneck procedures is a little bit tricky. The QuickDraw
II SetStdProcs call accepts a pointer to a 56-byte ($38 hex) record and fills
that record with the addresses of the standard bottleneckprocedures of QuickDraw
II. You may modify this record by replacing those addresseswith the addresses
of your own custom bottleneck procedures minus one. (QuickDraw II pushes the
address on the stack and executes an RTL to it, so the address in the record
must point to the byte before the routine.)
Note: A custom bottleneck procedure must not begin at the first byte of a
segment. If it does, then the segment could load at the beginning of a
bank, and the address minus one would be in the wrong bank and RTL would
transfer control to the wrong location. (See Apple IIgs Technical Note
#90, 65816 Tips and Pitfalls.)
After installing your own procedures, you use SetGrafProcs to tell QuickDraw II
about them. The format of this call is as follows (taken from the E16.QUICKDRAW
file in APW):
ostdText GEQU $00 ; Pointer - QDProcs -
ostdLine GEQU $04 ; Pointer - QDProcs -
ostdRect GEQU $08 ; Pointer - QDProcs -
ostdRRect GEQU $0C ; Pointer - QDProcs -
ostdOval GEQU $10 ; Pointer - QDProcs -
ostdArc GEQU $14 ; Pointer - QDProcs -
ostdPoly GEQU $18 ; Pointer - QDProcs -
ostdRgn GEQU $1C ; Pointer - QDProcs -
ostdPixels GEQU $20 ; Pointer - QDProcs -
ostdComment GEQU $24 ; Pointer - QDProcs -
ostdTxMeas GEQU $28 ; Pointer - QDProcs -
ostdTxBnds GEQU $2C ; Pointer - QDProcs -
ostdGetPic GEQU $30 ; Pointer - QDProcs -
ostdPutPic GEQU $34 ; Pointer - QDProcs -
The following code fragment shows how you might replace the StdRect procedure
with your own for a given window:
pha ; open a test window
pha
PushLong #MWindData ; standard setup for NewWindow
_NewWindow
_SetPort
PushLong #MyProcs ; get a record to modify
_SetStdProcs
ldy #ostdRect ; get the low word of my rectangle routine
lda #myRect-1 ; (minus one) and patch it in to the record
sta myProcs,y
lda #^myRect ; do the same for the high word
sta myProcs+2,y
PushLong #MyProcs ; install the procs
_SetGrafProcs
The interface to bottleneck procedures is different from the interface to other
QuickDraw II routines; you do not make calls via the tool dispatcherand you pass
most parameters on the direct page and in registers (rather than on the stack).
To write your own bottleneck procedures, you have to know where the inputs to
each call are kept and how to call the standard procedures from inside your own
procedures.
The standard bottleneck procedures are accessed through vectors in bank $E0.
StdText $E01E04
StdLine $E01E08
StdRect $E01E0C
StdRRect $E01E10
StdOval $E01E14
StdArc $E01E18
StdPoly $E01E1C
StdRgn $E01E20
StdPixels $E01E24
StdComment $E01E28
StdTxMeas $E01E2C
StdTxBnds $E01E30
StdGetPic $E01E34
StdPutPic $E01E38
When you call any of the standard procedures, the first direct page of QuickDraw
II is active. If you pass variables on any direct page other than the first
(direct page locations greater than $FF), you can use a simpletrick to access
them. For example, to access TheFillPat ($10E) without changingthe direct page
register:
ldx #$100 ;offset to second DP
lda >$OE,X ;gets "DP" location $10E
Certain locations on the direct page are always valid:
PortRef $24
MaxWidth $20
MasterSCB $08
UserID $0A
DrawVerb is usually valid, but not always:
DrawVerb $38
Each of the bottleneck procedures uses the direct page differently.
QuickDraw II has an interesting bug relating to the standard conic bottleneck
procedures. If you replace any of the standard procedures with your own,
QuickDraw II does not perform some of the setups it normally would before
calling the standard conic procedures (stdRRect, stdOval, stdArc). For example,
if you replace StdRect with a custom rectangle routine, but leavethe other conic
pointers alone (as shown in the code fragment above), QuickDrawII will not do
all of the normal setups when calling the standard conicroutines. To deal with
this bug of QuickDraw II, you must patch out the additional bottleneck
procedures and set up those direct pages locations yourself, orthe results will
not be what you expect. The QuickDraw II direct-page variables you must
initialize yourself in this instance are bulleted (o) below.
StdText
DrawVerb $38 Describes the kind of text to draw. There
are three possible values:
DrawCharVerb 0
DrawTextVerb 1
DrawCStrVerb 2
TextPtr $DA If the draw verb is DrawTextVerb or
DrawCStrVerb, TextPtr points to the text
buffer or C string to draw.
TextLength $D8 If the draw verb is DrawTextVerb,
TextLength contains the number of bytes in
the text buffer.
CharToDraw $D6 If the draw verb is DrawCharVerb,
CharToDraw contains the character to draw.
StdLine
Y1 $A6 Starting Y value for the line to draw
X1 $A8 Starting X value for the line to draw
Y2 $AA Ending Y value for the line to draw
X2 $AB Ending X value for the line to draw
Rect2 $AE Exactly the same thing as Y1, X1, Y2 and
X2 in the top, left, bottom, and right of
the rectangle
StdRect
DrawVerb $38 One of the following five drawing verbs:
Frame 0
Paint 1
Erase 2
Invert 3
Fill 4
Rect1 $A6 The rectangle to draw in standard form
(top, left, bottom, right)
TheFillPat $10E The pattern to use for the rectangle if
the verb is Fill
Note: The QuickDraw II Auxiliary SpecialRect call does not use the
rectangle bottleneck procedures.
StdRRect
DrawVerb $38 One of the following five drawing verbs:
Frame 0
Paint 1
Erase 2
Invert 3
Fill 4
Rect1 $A6 The boundary rectangle for the round
rectangle
OvalRect $295 A copy of the boundary rectangle for the
round rectangle
OvalHeight $208 The oval height for the rounded part of
the round rectangle
OvalWidth $20A The oval width for the rounded part of the
round rectangle
o ArcAngle $D2 Must be 360
o StartAngle $D4 Must be zero
TheFillPat $10E The pattern to use for the round rectangle
if the verb is Fill
StdOval
DrawVerb $38 One of the following five drawing verbs:
Frame 0
Paint 1
Erase 2
Invert 3
Fill 4
Rect1 $A6 The boundary rectangle for the oval
OvalRect $295 A copy of the boundary rectangle for the
oval
o OvalHeight $208 Must be the height of the oval
o OvalWidth $20A Must be the width of the oval
o ArcAngle $D2 Must be 360
o StartAngle $D4 Must be zero
TheFillPat $10E The pattern to use for the oval if the
verb is Fill
StdArc
DrawVerb $38 One of the following five drawing verbs:
Frame 0
Paint 1
Erase 2
Invert 3
Fill 4
Rect1 $A6 The boundary rectangle for the arc
o OvalWidth $20A Must be the width of the boundary
rectangle for the arc
ArcAngle $D2 The number of degrees the arc will sweep
StartAngle $D4 The starting position of the arc
TheFillPat $10E The pattern to use for the arc if the verb
is Fill
StdPoly
DrawVerb $38 One of the following five drawing verbs:
Frame 0
Paint 1
Erase 2
Invert 3
Fill 4
RgnHandleA $50 The handle to the polygon data structure
TheFillPat $10E The pattern to use for the polygon if the
verb is Fill
StdRgn
DrawVerb $38 One of the following five drawing verbs:
Frame 0
Paint 1
Erase 2
Invert 3
Fill 4
RgnHandleC $70 The handle to the region to draw
TheFillPat $10E The pattern to use for the region if the
verb is Fill
StdPixels
SrcLocInfo $CC The LocInfo record for the source pixel
map
DestLocInfo $0C The LocInfo record for the destination
pixel map
SrcRect $DC The source rectangle for the operation in
local coordinates for the source pixel map
(as described in the source LocInfo
record)
DestRect $1C The destination rectangle for the
operation in local coordinates for the
destination pixel map (as described in the
destination LocInfo record)
XferMode $E4 The mode to use for data transfer
RgnHandleA $50 The handle to the first region to which
drawing is clipped (usually the ClipRgn
from the GrafPort) A NIL handle is not
allowed. To signify no clipping, pass a
handle to the WideOpen region, which is
defined as 10 bytes:
Length $A (word)
-MaxInt -$3FFF (word)
-MaxInt -$3FFF (word)
+MaxInt +$3FFF (word)
+MaxInt +$3FFF (word)
RgnHandleB $60 The handle to the second region to which
drawing is clipped (usually the VisRgn
from the GrafPort) A NIL handle is not
allowed. To signify no clipping, pass a
handle to the WideOpen region.
RgnHandleC $70 The handle to the second region to which
drawing is clipped (usually the mask
region from the CopyPixels or the
PaintPixels call) A NIL handle is not
allowed. To signify no clipping, pass a
handle to the WideOpen region.
StdComment
TheKind $A6 The kind of input for the comment
TheSize $A8 The number of bytes to put into the
picture
TheHandle $AA The data to put into the picture
StdTxMeas
DrawVerb $38 Describes the kind of text to draw. There
are three possible values:
DrawCharVerb 0
DrawTextVerb 1
DrawCStrVerb 2
TextPtr $DA If the draw verb is DrawTextVerb or
DrawCStrVerb, TextPtr points to the text
buffer or C string to draw.
TextLength $D8 If the draw verb is DrawTextVerb,
TextLength contains the number of bytes in
the text buffer.
CharToDraw $D6 If the draw verb is DrawCharVerb,
CharToDraw contains the character to
measure.
TheWidth $DE The resulting width should be put here.
StdTxBnds
DrawVerb $38 Describes the kind of text to draw. There
are three possible values:
DrawCharVerb 0
DrawTextVerb 1
DrawCStrVerb 2
TextPtr $DA If the draw verb is DrawTextVerb or
DrawCStrVerb, TextPtr points to the text
buffer or C string to draw.
TextLength $D8 If the draw verb is DrawTextVerb,
TextLength contains the number of bytes in
the text buffer.
CharToDraw $D6 If the draw verb is DrawCharVerb,
CharToDraw contains the character to draw.
RectPtr $D2 Indicates the address to put the resulting
rectangle.
StdGetPic
This call takes input on the stack rather than the direct page. This is
the one standard bottleneck procedure which you call with the direct
page register set to something other than the direct page of QuickDraw
II; it is set to a part of the stack.
Stack Diagram on Entrance to StdGetPic
Previous Contents
DataPtr Pointer to destination buffer
Count Integer (unsigned) (bytes to read)
RTL Address 3 bytes
----------------- Top of Stack
Stack Diagram just before exit from StdGetPic
Previous Contents
RTL Address 3 bytes
----------------- Top of Stack
StdPutPic
This call takes input on the stack rather than the direct page; however,
unlike StdGetPic, the direct page for QuickDraw II is active when you
call this routine.
Stack Diagram on Entrance to StdPutPic
Previous Contents
DataPtr Pointer to source buffer
Count Integer (unsigned) (bytes to read)
RTL Address 3 bytes
----------------- Top of Stack
Stack Diagram just before exit from StdPutPic
Previous Contents
RTL Address 3 bytes
----------------- Top of Stack
Dealing with the Cursor
The cursor can get in your way when you want to draw directly to the screen.
QuickDraw II has two low-level routines which help you avoid this problem:
ShieldCursor and UnshieldCursor. ShieldCursor tells QuickDraw II to hide the
cursor if it intersects the MinRect and to prevent the cursor from moving until
you call UnshieldCursor.
There is a bug in ShieldCursor for System Disks 4.0 and earlier. This bug is
related to the routine ObscureCursor. When the cursor is obscured, ShieldCursor
does not prevent the cursor from moving; therefore, the user is able to move the
cursor during a QuickDraw II operation, and this movementmay disturb the screen
image.
Calls to ShieldCursor must be balanced by calls to UnshieldCursor. You may not
call ShieldCursor successively without calling UnshieldCursor after each call to
ShieldCursor. There is no error checking, so careless use of these routines
will result in an unusable system.
MinRect is the smallest possible rectangle which encloses all the pixels that
may be affected by a drawing call. You keep MinRect on the direct page and
usually calculate it by intersecting the rectangle of the object you are drawing
with the BoundsRect, PortRect, boundary box of the VisRgn, and the boundary box
of the ClipRgn. You must set up MinRect yourself.
ShieldCursor also looks at two other fields on the direct page of QuickDraw II.
ImageRef is a long word located at $0E. If ImageRef does not point to $E12000
or $012000, QuickDraw II assumes you are not drawing to the screen, so it does
not have to shield the cursor. BoundsRect is a rectangle located at $14, and
QuickDraw II uses it to translate MinRect into global coordinates. These values
are generally correct, but under the following known circumstance,they are not
and ShieldCursor will not function properly:
1. You have just drawn to an off-screen GrafPort with QuickDraw II.
2. You switch to a GrafPort on the screen.
3. You call ShieldCursor.
ImageRef and BoundsRect are not updated until QuickDraw II is actually committed
to drawing, thus, these values are still for the off-screenGrafPort in this
case, even though you switched to a GrafPort on the screen. Therefore, when you
call ShieldCursor, you have to make sure that thesevalues are current. (If
these values are current, ShieldCursor will work correctly, no matter what the
circumstances.)
You can find the location of the QuickDraw II direct page with the GetWAP call.
For speed reasons, you may not want to make the GetWAP call for each
ShieldCursor call. You may wish to get the work area pointer value after
starting QuickDraw II and store it for future reference.
Calling ShieldCursor:
1. Set direct page for QuickDraw II.
2. Save the existing values of MinRect, ImageRef, and BoundsRect.
3. Set MinRect, ImageRef, and BoundsRect.
4. Let QuickDraw II know you've changed the contents of its direct page by
clearing the "dirty" flags bits 14 to 0:
DirtyFlags equ $EC
ldx #$200 ;index to QD's third page of work
lda DirtyFlags,x ;space
and #$8000
sta DirtyFlags,x
5. JSL to ShieldCursor.
6. Restore the previous values of MinRect, ImageRef, and BoundsRect.
Note: Saving and restoring these values was not previously mentioned in this
Note and in most circumstances it is not necessary. Saving and restoring
is now recommended. In particular, if ShieldCursor is called inside a
QuickDraw II bottleneck procedure, the system can crash if you fail to
restore the contents of direct page.
Calling UnshieldCursor:
1. Set direct page for QuickDraw II.
2. JSL to UnshieldCursor.
ShieldCursor $E01E98
MinRect $00
ImageRef $0E
BoundsRect $14
UnshieldCursor $E01E9C
Further Reference
_____________________________________________________________________________
o Apple IIGS Toolbox Reference, Volume 2