Inside Macintosh: Imaging With QuickDraw /

Chapter 2 - Basic QuickDraw

Summary of Basic QuickDraw

Pascal Summary

Data Types

TYPE  Point = 
      RECORD CASE Integer OF
         0: (v:\xDD\xDD       Integer;    {vertical coordinate}
             h:\xDD\xDD       Integer);   {horizontal coordinate}
         1: (vh:\xDD       ARRAY[VHSelect] OF Integer);
      END;
Rect = 
      RECORD CASE Integer OF        {cases: 4 boundaries or 2 corners}
         0: (top:       Integer;    {upper boundary of rectangle}
             left:      Integer;    {left boundary of rectangle}
             bottom:    Integer;    {lower boundary of rectangle}
             right:     Integer);   {right boundary of rectangle}
         1: (topLeft:   Point;      {upper-left corner of rectangle}
             botRight:  Point);     {lower-right corner of rectangle}
      END;
RgnHandle = ^RgnPtr;
      RgnPtr =    ^Region;
      Region = 
      RECORD
         rgnSize: Integer; {size in bytes}
         rgnBBox: Rect;    {enclosing rectangle}
         {more data if not rectangular}
      END;
BitMap =
      RECORD
         baseAddr:   Ptr;     {pointer to bit image}
         rowBytes:   Integer; {row width}
         bounds:     Rect;    {boundary rectangle}
      END;
GrafPtr =      ^GrafPort;
      WindowPtr =    GrafPtr;
GrafPort =  {basic graphics port}
      RECORD
         device:     Integer;    {device-specific information}
         portBits:   BitMap;     {bitmap}
         portRect:   Rect;       {port rectangle}
         visRgn:     RgnHandle;  {visible region}
         clipRgn:    RgnHandle;  {clipping region}
         bkPat:      Pattern;    {background pattern}
         fillPat:    Pattern;    {fill pattern}
         pnLoc:      Point;      {pen location}
         pnSize:     Point;      {pen size}
         pnMode:     Integer;    {pattern mode}
         pnPat:      Pattern;    {pen pattern}
         pnVis:      Integer;    {pen visibility}
         txFont:     Integer;    {font number for text}
         txFace:     Style;      {text's font style}
         txMode:     Integer;    {source mode for text}
         txSize:     Integer;    {font size for text}
         spExtra:    Fixed;      {extra space}
         fgColor:    LongInt;    {foreground color}
         bkColor:    LongInt;    {background color}
         colrBit:    Integer;    {color bit}
         patStretch: Integer;    {used internally}
         picSave:    Handle;     {picture being saved, used internally}
         rgnSave:    Handle;     {region being saved, used internally}
         polySave:   Handle;     {polygon being saved, used internally}
         grafProcs:  QDProcsPtr; {low-level drawing routines}
      END;

Routines

Initializing QuickDraw

PROCEDURE InitGraf       (globalPtr: Ptr);

Opening and Closing Basic Graphics Ports

PROCEDURE OpenPort       (port:\xDDGrafPtr);
PROCEDURE InitPort       (port: GrafPtr); 
PROCEDURE ClosePort      (port:\xDDGrafPtr);

Saving and Restoring Graphics Ports

PROCEDURE GetPort        (VAR port: GrafPtr);
PROCEDURE SetPort        (port: GrafPtr);

Managing Bitmaps, Port Rectangles, and Clipping Regions

PROCEDURE ScrollRect     (r:\xDDRect; dh,dv: Integer; updateRgn: RgnHandle);
PROCEDURE SetOrigin      (h,v: Integer);
PROCEDURE PortSize       (width,height:\xDDInteger);
PROCEDURE MovePortTo     (leftGlobal,topGlobal:\xDDInteger);
PROCEDURE GetClip        (rgn: RgnHandle);
PROCEDURE SetClip        (rgn: RgnHandle);
PROCEDURE ClipRect       (r: Rect);
FUNCTION BitMapToRegion  (region: RgnHandle; bMap: BitMap): OSErr;
PROCEDURE SetPortBits    (bm: BitMap);

Manipulating Points in Graphics Ports

PROCEDURE GlobalToLocal  (VAR pt: Point);
PROCEDURE LocalToGlobal  (VAR pt: Point);
PROCEDURE AddPt          (srcPt: Point; VAR dstPt:\xDDPoint);
PROCEDURE SubPt          (srcPt:\xDDPoint; VAR dstPt:\xDDPoint);
FUNCTION DeltaPoint      (ptA: Point; ptB: Point): LongInt;
PROCEDURE SetPt          (VAR pt:\xDDPoint; h,v:\xDDInteger);
FUNCTION EqualPt         (pt1,pt2: Point): Boolean;
FUNCTION GetPixel        (h,v:\xDDInteger):\xDDBoolean;

C Summary

Data Types

struct Point {
      short v;    /* vertical coordinate */
      short h;    /* horizontal coordinate */
   };
struct Rect {
      short top;     /* upper boundary of rectangle */
      short left;    /* left boundary of rectangle */
      short bottom;  /* lower boundary of rectangle */
      short right;   /* right boundary of rectangle */
   };
struct Region {
      short rgnSize;          /* size in bytes */
      Rect  rgnBBox;          /* enclosing rectangle */
      /* more data if not rectangular */
   };
typedef struct Region Region;
typedef Region *RgnPtr, **RgnHandle;
struct BitMap {
      Ptr   baseAddr;         /* pointer to bit image */
      short rowBytes;         /* row width */
      Rect  bounds;           /* boundary rectangle */
   };
struct GrafPort {             /* basic graphics port */
      short       device;     /* device-specific information */
      BitMap      portBits;   /* bitmap */
      Rect        portRect;   /* port rectangle */
      RgnHandle   visRgn;     /* visible region */
      RgnHandle   clipRgn;    /* clipping region */
      Pattern     bkPat;      /* background pattern */
      Pattern     fillPat;    /* fill pattern */
      Point       pnLoc;      /* pen location */
      Point       pnSize;     /* pen size */
      short       pnMode;     /* pattern mode */
      Pattern     pnPat;      /* pen pattern */
      short       pnVis;      /* pen visibility */
      short       txFont;     /* font number for text */
      Style       txFace;     /* text's font style */
      char        filler;
      short       txMode;     /* source mode for text */
      short       txSize;     /* font size for text */
      Fixed       spExtra;    /* extra space */
      long        fgColor;    /* foreground color */
      long        bkColor;    /* background color */
      short       colrBit;    /* color bit */
      short       patStretch; /* used internally */
      Handle      picSave;    /* picture being saved, used internally */
      Handle      rgnSave;    /* region being saved, used internally */
      Handle      polySave;   /* polygon being saved, used internally */
      QDProcsPtr  grafProcs;  /* low-level drawing routines */
   };
typedef struct GrafPort GrafPort;
typedef GrafPort *GrafPtr;
typedef GrafPtr WindowPtr;

Functions

Initializing QuickDraw

pascal void InitGraf            (void *globalPtr);

Opening and Closing Basic Graphics Ports

pascal void OpenPort            (GrafPtr port);
pascal void InitPort            (GrafPtr port); 
pascal void ClosePort           (GrafPtr port);

Saving and Restoring Graphics Ports

pascal void GetPort             (GrafPtr *port);
pascal void SetPort             (GrafPtr port);

Managing Bitmaps, Port Rectangles, and Clipping Regions

pascal void ScrollRect          (const Rect *r, short dh, short dv, 
                                 RgnHandle updateRgn);
pascal void SetOrigin           (short h, short v);
pascal void PortSize            (short width, short height);
pascal void MovePortTo          (short leftGlobal, short topGlobal);
pascal void GetClip             (RgnHandle rgn);
pascal void SetClip             (RgnHandle rgn);
pascal void ClipRect            (const Rect *r);
pascal OSErr BitMapToRegion     (RgnHandle region, const BitMap *bMap); 
pascal void SetPortBits         (const BitMap *bm);

Manipulating Points in Graphics Ports

pascal void GlobalToLocal       (Point *pt);
pascal void LocalToGlobal       (Point *pt);
pascal void AddPt               (Point src, Point *dst);
pascal void SubPt               (Point src, Point *dst);
pascal long DeltaPoint          (Point ptA, Point ptB);
pascal void SetPt               (Point *pt, short h, short v);
pascal Boolean EqualPt          (Point pt1, Point pt2);
pascal Boolean GetPixel         (short h, short v);

Assembly-Language Summary

Data Structures

Point Data Structure

0	v	word	vertical coordinate
2	h	word	horizontal coordinate

Rectangle Data Structure

0	topLeft	long	upper-left corner of rectangle
4	botRight	long	lower-right corner of rectangle
0	top	word	upper boundary of rectangle
2	left	word	left boundary of rectangle
4	bottom	word	lower boundary of rectangle
6	right	word	right boundary of rectangle

Region Data Structure

0	rgnSize	word	size in bytes
2	rgnBBox	8 bytes	enclosing rectangle
10	rgnData	array	region data

Bitmap Data Structure

0	baseAddr	long	pointer to bit image
4	rowBytes	word	row width
6	bounds	8 bytes	boundary rectangle

GrafPort Data Structure

0	device	word	device-specific information
2	portBits	14 bytes	bitmap
16	portBounds	8 bytes	boundary rectangle
24	portRect	8 bytes	port rectangle
32	visRgn	long	visible region
36	clipRgn	long	clipping region
40	bkPat	8 bytes	background pattern
48	fillPat	8 bytes	fill pattern
56	pnLoc	long	pen location
60	pnSize	long	pen size
64	pnMode	word	pattern mode
66	pnPat	8 bytes	pen pattern
74	pnVis	word	pen visibility
76	txFont	word	font number for text
78	txFace	word	text's font style
80	txMode	word	source mode for text
82	txSize	word	font size for text
84	spExtra	long	extra space
88	fgColor	long	foreground color
92	bkColor	long	background color
96	colrBit	word	color bit
98	patStretch	word	used internally
100	picSave	long	picture being saved, used internally
104	rgnSave	long	region being saved, used internally
108	polySave	long	polygon being saved, used internally
112	grafProcs	long	low-level drawing routines

Global Variables

arrow	The standard arrow cursor.
black	An all-black pattern.
dkGray	A 75% gray pattern.
gray	A 50% gray pattern.
ltGray	A 25% gray pattern.
randSeed	Where the random sequence begins.
screenBits	The main screen.
thePort	The current graphics port.
white	An all-white pattern.

Result Codes

pixmapTooDeepErr	-148	Pixel map is deeper than 1 bit per pixel
rgnTooBigErr	-500	Bitmap would convert to a region greater than 64 KB