Quartz 2D and QuickDraw

The core of the Mac OS X drawing and windowing architecture is called Quartz. It has two pieces:

• Quartz 2D--one of several graphics libraries that provide 2D text- and graphics-rendering services

• Quartz Compositor--the window server and Quartz Extreme, the component that interfaces to the computer's graphics-acceleration hardware

As you can see from the diagram below, QuickDraw is one of the graphics rendering libraries that you can use for drawing graphics under Mac OS X.

Under Mac OS X, QuickDraw thinks it is drawing directly to the graphics memory, just as it did in the earlier versions of Mac OS. In actuality, though, it is drawing to an off-screen graphics buffer. The Quartz Compositor combines this off-screen buffer with other graphics information (for example, soft-edge shadows and window transparency information) to produce the final pixmap. The Quartz Compositor delivers the final graphics image to the graphics hardware in a way that minimizes the delay in displaying changes to the screen, while maintaining the highest possible image quality (by preventing screen flicker and other visual artifacts).

Color QuickDraw

Just as the Win32 platform added new graphics capabilities as display hardware became more powerful, so did the Mac OS platform. The original QuickDraw, which handled only one-bit black-and-white graphics, was replaced by the more powerful Color QuickDraw, which handles both indexed and direct color graphics. The Color QuickDraw API is an almost perfect superset of the original QuickDraw API, though some irregularities exist.

Inside Macintosh: Imaging with QuickDraw is the reference book you will use for learning QuickDraw. In it, the section on Color QuickDraw is an extension to the section on the original QuickDraw API; this means that you need to read both sections, even though you are interested in Color QuickDraw only.

Windows

While programming, you need a way to refer to a window. Under Win32, you identify a window through its display context. (Granted, in some cases you are manipulating the device context of the graphics hardware, but this Guide simplifies things by always using the term "display context.") In QuickDraw, you refer to a window by its CGrafPort (a programming shorthand for "color graphics port").

In QuickDraw, drawing commands have a slightly different form from their Win32 counterparts. While Win32 drawing commands always take a display context as their first argument, QuickDraw commands do not. Instead, QuickDraw always assume that any drawing command is intended for the current graphics port. Therefore, to draw into a different window, you must first "set the graphics port" (that is, set the CGrafPort of the desired window to be the current port), then issue the drawing commands for the new window.

There is one terminology difference you need to be aware of. Whereas the Win32/GDI API simply speaks of bitmaps, which can be black-and-white (one bit per pixel) or color (multiple bits per pixel), past and current versions of the Mac OS operating systems--and their documentation--use separate terms: bitmap for a one-bit black-and-white pixel image, and pixmap for a color pixel image.

Table 1 summarizes the differences regarding windows under the Win32/GDI and QuickDraw drawing environments.

If you are interested in accessing the pixel map associated with a CGrafPort, see the documentation for the following routines: GetWindowPort, LockPortBits, GetPortPixMap, LockPixels, GetPixBaseAddr, GetPixRowBytes, UnlockPixels, and UnlockPortBits.

Coordinate Systems

Apple has always controlled both the hardware and the operating-system software of its computers, so it was able to ensure that pixels are "square" – that is, that a pixel displayed on the screen is exactly as tall as it is wide. Because of this, the designers of QuickDraw did not have to deal with both logical and device coordinate systems, which possibly (in older computers) were not identical.

In QuickDraw, there is only one coordinate system, and it is a simple one. Unless you specify otherwise, the point (0,0) is the upper left corner of the client area of a window (if you are talking about the "local" coordinate system of a given window) or of the desktop itself.

Another subtle but very important difference between the Win32/GDI and QuickDraw coordinate systems is the relationship between the abstract coordinate grid and the pixels and lines drawn in relation to them. On the Win32 side, pixels (which have a measurable diameter) are drawn so that their centers correspond to the intersection of the appropriate horizontal and vertical grid lines, and the thickness of drawn lines straddle their corresponding coordinate lines.

In QuickDraw, pixels and lines are drawn in the spaces between coordinate lines. To be specific, they are drawn immediately to the right of and below the points that define them. The original QuickDraw engineers felt that this method leads to less confusion when questioning whether, for example, a 10-by-10 square drawn with its upper left corner at (0,0) includes the pixel corresponding to the point (10, 10). In QuickDraw, the answer is "yes," while in Win32/GDI, the answer is "no," and Win32 programmers must keep this "up to but not including" rule in mind.

Table 2 summarizes the differences regarding coordinate systems between the Win32/GDI and QuickDraw drawing environments.

Pens

Win32/GDI pens have evolved over time, so you now have different kinds of pens available for use — stock pens, logical pens, and geometric and cosmetic extended pens. In contrast, QuickDraw has only one kind of pen.

Just as QuickDraw always draws into the current port, it always draws with the current pen, and you use such routines as PenSize, PenPixPat, and PenMode to change the pen's size, pixel pattern, and drawing mode. If you have pens that you use frequently, you should create subroutines for defining them; that way, you can switch between pens with a single subroutine call.

In QuickDraw, a pen can draw in a solid color, optionally modified by an arbitrary one-bit pattern, or it can draw using an arbitrary pixmap. In addition, the drawing process can also be modified by the use of different transfer modes, though these are infrequently used.

The QuickDraw pen always has a pen pattern, a pen mode, a foreground color, and a background color, all of which affect how pen drawing works. The pen pattern, unlike the Win32/GDI hatch pattern, is defined by the programmer and can take on any value. QuickDraw defaults to using a solid black pen pattern and the patCopy pen mode, which results in an easy-to-understand pen that draws in the CGrafPort's foreground color. However, the pen's behavior can become quite complex:

• If the pen pattern is a bitmap, depending on the pen mode used, a pixel "touched" by the pen can become the foreground color or the background color, it can be inverted, or it can remain unchanged.

• If the pen pattern is a pixmap, the pixmap itself is used to draw whatever line or area that is requested by the pen-drawing command. In this case, any pixel touched by the pen is replaced by the appropriate pixel from the pixmap.

• Also, when the pen is used to draw a line or outline a shape, it does not draw with its width straddling the path. Instead, the upper left corner of the pen is dragged along the path, meaning that "ink" is always deposited below and to the right of the current point on the path.

If your application makes heavy use of drawing features not found in QuickDraw, you should consider porting your Win32 application to Mac OS X using the Quartz 2D API. See "Using Quartz 2D," later in this document, for details.

Table 3 summarizes the most important differences regarding pens between the Win32/GDI and QuickDraw drawing environments. This summary should make the process of learning about QuickDraw pens easier.

Geometric Shapes

Though the Win32/GDI and QuickDraw environments have roughly the same capabilities when it comes to drawing geometric shapes, each environment structures the drawing process differently. QuickDraw does not have an equivalent to the Win32/GDI brush. Instead, when you are drawing shapes, you use a different command depending on how you wish to draw its interior, and the drawing can be accomplished with either the pen or an arbitrary bitmap or pixmap.

The verb at the beginning of each shape-drawing command's name indicates how the drawing is accomplished:

• Commands starting with "Frame" (for example, FrameOval ) draw the outline of the shape using the pen and its behavior as described earlier; the interior of the shape is not affected.

• Commands starting with "Paint" (for example, PaintOval ) paints the shape's interior using the pen and its behavior described earlier. The outline of the shape is not stroked by the pen.

• Commands starting with "FillC" (for example, FillCOval ) fills the shape's interior using an arbitrary pixel pattern (not the pen pattern). Any pixel touched by the pen is replaced by the appropriate color pixel from the pixmap. The command for setting this pixel pattern is PenPixPat.

Table 4 summarizes the most important differences regarding geometric shapes between the Win32/GDI and QuickDraw drawing environments.

Polygons

In QuickDraw, the drawing of polygons mirrors the drawing of geometric shapes in most respects (see Table 5, below). One difference from the Win32/GDI model is that in QuickDraw, you must explicitly create the polygon as a data structure before you can draw it.

Win32/GDI Paths, Win32/GDI Regions, and QuickDraw Regions

A QuickDraw region performs the same task as a Win32/GDI path in that you can use either to draw lines and fill areas based on a prerecorded set of graphic operations (see Table 6).

QuickDraw regions can also perform the same drawing and clipping tasks as Win32/GDI regions (see Table 7). When creating a QuickDraw region, you can use certain drawing commands that cannot be used to create a Win32/GDI region. However, this difference is largely negated by the fact that you can create a Win32/GDI path that is equivalent to the QuickDraw region, then convert it to a Win32/GDI region.

Offscreen Bitmaps and GWorlds

On most computer systems, if you issue drawing commands that write directly to video memory, such commands will occasionally do so just as the video hardware is reading its memory and displaying the results. This results in unintended visual artifacts or "glitches" that degrade the quality of the display. The classic solution for this problem is to first draw the image in an offscreen bitmap, then transfer that image to video memory in one fast operation (called a bit-block transfer, or bitblt).

When Apple engineers created Color QuickDraw, they added a new data structure called a GWorld (a shortened version of the phrase "graphics world"). A GWorld behaves like a Win32/GDI offscreen bitmap, and in Color QuickDraw, you set the graphics port for both (on-screen) windows and (offscreen) and GWorlds with the command SetGWorld. You can learn about GWorlds and how to use them in the "Offscreen Graphics Worlds" chapter of Inside Macintosh: Imaging with QuickDraw.

As part of the Quartz drawing architecture, QuickDraw automatically draws into an offscreen bitmap; in fact, it cannot be used in any other way. Therefore, you do not need to use GWorlds if your only intent is to prevent visual artifacts from occurring in your display. However, there still are reasons to use GWorld s. If, for example, you need to draw a complicated image that you will be reusing, you can first draw the image into a GWorld and then save the result for reuse.

Bit-Block Transfers (BitBlts)

QuickDraw has one drawing command, CopyBits, that performs the same functions as the BitBlt and StretchBlt commands in Win32/GDI. Though CopyBits is most often used simply to copy a pixmap to new location, be aware that you can also use it to transform the image in various ways during the copy process; see the “Color QuickDraw” chapter of Inside Macintosh: Imaging with QuickDraw for details.

Table 8 summarizes the differences regarding bit-block transfers between the Win32/GDI and QuickDraw drawing environments.

Metafiles and Picture Files

Just as the Win32/GDI drawing environment has metafiles, a mechanism for storing and playing back a set of drawing commands, QuickDraw has its equivalent: the picture record (also called a QuickDraw picture, or PICT). And, just as the original .wmf format was largely replaced by the enhanced .emf metafile, the original PICT format was largely replaced by a color-based "version 2" PICT format.

As with everything else in QuickDraw, PICT s are measured in pixels, and you can easily retrieve the size of the PICT from its header. You create PICT s by executing the OpenCPicture command, some drawing commands, then finally the CloseCPicture command. Later, you can draw them into a rectangular portion of a window or GWorld using the DrawPicture command.

The PICT format is also a standard format for the Clipboard. Along with the plain-text format, every Mac OS X application should be able to cut, copy, and paste PICT resources.

Text

Very little needs to be said about using QuickDraw to draw text, since you will probably use functions outside QuickDraw to do so. However, QuickDraw does include a DrawText command for simple text drawing. Just as there is only one pen associated with a CGrafPort , you also have only one "text tool" to work with, but you can change the font, style, size, and drawing mode of the current CGrafPort before using the DrawText command.

Table 9 summarizes the differences regarding text between the Win32/GDI and QuickDraw drawing environments.

Quartz 2D and Your Porting Effort

Porting an application to a new platform always has its own challenges, and these determine what development choices you have. When you port your Win32 application to Mac OS X, you have three choices:

• to port using QuickDraw only

• to port using QuickDraw, with occasional uses of Quartz 2D

• to port using Quartz 2D only

The Mac OS X implementation of QuickDraw includes two routines, QDBeginCGContext and QDEndCGContext , that enable you to switch to Quartz 2D temporarily for graphic operations that are not available in QuickDraw.

To compete with other Mac OS X applications similar to yours, you will eventually want to rewrite your application to use Quartz 2D exclusively. If your schedule allows it, you may want to consider porting your Win32 code directly to Quartz 2D instead of QuickDraw. This will give you a stronger initial product that will be easier to upgrade in the future.