Drawing Environments

A graphics port is a complete drawing environment that defines where and how graphics operations take place. You can have many graphics ports open at once; each one has its own local coordinate system, drawing pattern, background pattern, pen size and location, font and font style, and bitmap or pixel map (for a color graphics port). You can quickly switch from one graphics port to another.

The Window Manager incorporates a graphics port in each window record it creates.

Your application performs all graphics operations in graphics ports. A graphics port is a drawing environment—defined by a GrafPort record for a basic graphics port or a CGrafPort record for a color graphics port—that contains the information QuickDraw needs to transmit drawing operations from bits in memory to onscreen pixels. A basic graphics port is the drawing environment provided by basic QuickDraw; a basic graphics port contains the information that basic QuickDraw uses to create and manipulate onscreen either black-and-white images or color images that employ a basic eight-color system. A color graphics port is the sophisticated color drawing environment provided by Color QuickDraw; a color graphics port contains the information that Color QuickDraw uses to create and manipulate grayscale and color images onscreen.

While your application can draw directly into basic and color graphics ports, you can improve your application’s appearance and performance by constructing images in offscreen graphics worlds and then copying them to onscreen graphics ports. An offscreen graphics world is a sophisticated environment for preparing complex color, grayscale, or black-and-white images before displaying them on the screen. Defined in a private data structure referred to by a pointer of type GWorldPtr, an offscreen graphics world also contains a graphics port of its own.

Your application can print the images it prepares in graphics ports by drawing into a printing graphics port using QuickDraw drawing routines.** A printing graphics port** is the printing environment defined by a TPrPort record, which contains a graphics port plus additional information used by the printer driver and system software.

The visible image for a graphics port is contained in either a bitmap or a pixel map. A bitmap is defined by a data structure of type BitMap, and it represents the positions and states of a corresponding set of pixels, which can be either black and white or the eight predefined colors provided by basic QuickDraw. A bitmap is contained within a basic graphics port. A pixel map is defined by a data structure of type PixMap, and it represents the positions and states of a corresponding set of color pixels. A handle to a pixel map is contained within a color graphics port.

A graphics port does the following:

• It specifies the bitmap or pixel map that points to the area of memory in which your drawing operations take place. The bitmap or pixel map contains information about how that memory should be arranged to map bits to the screen.
• It contains a metaphorical graphics pen with which to perform drawing operations. You can set this pen to different sizes, patterns, and colors.
• It holds information about text: if your application or its user writes characters, they will be styled and sized according to information in your application’s graphics port.

The fields of a graphics port are maintained by QuickDraw, and you should never write directly into those fields. However, QuickDraw provides routines for changing the fields of a graphics port: you can point to an image in a different area of memory, reshape and resize the pen, change the pen’s pattern and color, and switch fonts. You can, and often must, read the fields of a graphics port.

An application uses the Window Manager function GetNewCWindow to create a new window on a grayscale screen; GetNewCWindow automatically uses Color QuickDraw to create the graphics port for the empty window. The application uses Color QuickDraw procedures to fill the graphics port’s pixel map with an image and to draw the image onscreen.

The Coordinate Plane

The plane is a two-dimensional grid whose coordinates range from -32768 to 32767. On a user’s computer, there is one global coordinate system that represents all potential QuickDraw drawing space. The origin of the global coordinate system—that is, the point with a horizontal coordinate of 0 and a vertical coordinate of 0—is at the upper-left corner of the user’s main screen. Each graphics port on that user’s computer has its own local coordinate system, which is defined relative to the port rectangle of the graphics port. Typically, the upper-left corner of a port rectangle is assigned a local horizontal coordinate of 0 and a local vertical coordinate of 0, although you can use the SetOrigin procedure to change the coordinates of this corner.

Points

A point is located by the combination of a vertical coordinate and a horizontal coordinate. Points themselves are dimensionless; if a visible pixel is located at a point, the pixel hangs down and to the right of the point. You can store the coordinates of a point into a variable of type Point, which QuickDraw defines as a record of two integers.

VAR 
   westPt, eastPt: Point;

westPt.v := 40; westPt.h := 60; // individual access
eastPt.vh[v] := 90; eastPt.vh[h] := 110; // array access

Rectangles

Any two points can define the upper-left and lower-right corners of a rectangle. Just as points are infinitely small, the borders of the rectangle are infinitely thin.

The data type for rectangles is Rect, and the data structure consists of either four integers or two points.

VAR
   shipRect: Rect;

{specify rectangle with boundary coordinates}
shipRect.top := 20; shipRect.left := 20; shipRect.bottom := 70; 
   shipRect.right := 70;

{specify rectangle with upper-left and bottom-right points}
shipRect.topLeft := (20,20); shipRect.botRight := (70,70);

{specify individual coordinates for rectangles upper-left }
{ and bottom-right points}
shipRect.topLeft.v := 20; shipRect.topLeft.h :=20; 
   shipRect.botRight.v := 70; shipRect.botRight.h :70;

{specify individual coordinates for rectangles upper-left }
{ and bottom-right points, where the points are arrays}
shipRect.topLeft.vh[v] := 20; shipRect.topLeft.vh[h] := 20;
   shipRect.botRight.vh[v] := 70; shipRect.botRight.vh[h] := 70;

About Color QuickDraw

Color QuickDraw performs its operations in a graphics port called a** color graphics port**, which is based on a data structure of type CGrafPort. As with basic graphics ports (which are based on a data structure of type GrafPort), each color graphics port has its own local coordinate system. All fields in a CGrafPort record are expressed in these coordinates, and all calculations and actions that Color QuickDraw performs use its local coordinate system.

Pixel Maps

The portPixMap field of a CGrafPort record contains a handle to a ** pixel map,** a data structure of type PixMap. Just as basic QuickDraw does all of its drawing in a bitmap, Color QuickDraw draws in a pixel map.

The representation of a color image in memory is a pixel image, analogous to the bit image used by basic QuickDraw. A PixMap record includes a pointer to a pixel image, its dimensions, storage format, depth, resolution, and color usage.

The baseAddr field of a PixMap record contains a pointer to the beginning of the onscreen pixel image for a pixel map. The pixel image that appears on a screen is normally stored on a graphics card rather than in main memory. (There can be several pixel maps pointing to the same pixel image, each imposing its own coordinate system on it.)