# QuickDraw

QuickDraw was the 2D graphics library and associated application programming interface (API) which is a core part of classic Mac OS. It was initially written by Bill Atkinson and Andy Hertzfeld. QuickDraw still existed as part of the libraries of Mac OS X, but had been largely superseded by the more modern Quartz graphics system. In Mac OS X Tiger, QuickDraw has been officially deprecated. In Mac OS X Leopard applications using QuickDraw cannot make use of the added 64-bit support. In OS X Mountain Lion, QuickDraw header support was removed from the operating system. Applications using QuickDraw still ran under OS X Mountain Lion to macOS High Sierra; however, the current versions of Xcode and the macOS SDK do not contain the header files to compile such programmes.

## Principles of QuickDraw

QuickDraw was grounded in the Apple Lisa's LisaGraf of the early 1980s and was designed to fit well with the Pascal-based interfaces and development environments of the early Apple systems. In addition, QuickDraw was a raster graphics system, which defines the pixel as its basic unit of graphical information. This is in contrast to vector graphics systems, where graphics primitives are defined in mathematical terms and rasterized as required to the display resolution. A raster system requires much less processing power however, and was the prevailing paradigm at the time that QuickDraw was developed.
QuickDraw defined a key data structure, the graphics port, or GrafPort. This was a logical drawing area where graphics could be drawn. The most obvious on-screen "object" corresponding to a GrafPort was a window, but the entire desktop view could be a GrafPort, and off-screen ports could also exist.
The GrafPort defined a coordinate system. In QuickDraw, this had a resolution of 16 bits, giving 65,536 unique vertical and horizontal locations. These are numbered from -32,767 on the extreme left (or top), to +32,767 on the extreme right (or bottom). A window was usually set up so that the top, left corner of its content area was located at 0,0 in the associated GrafPort. A window's content area did not include the window's frame, drop shadow or title bar (if any).
QuickDraw coordinates referred to the infinitely thin lines between pixel locations. An actual pixel was drawn in the space to the immediate right and below the coordinate. This made it easier for programmers to avoid graphical glitches caused by off-by-one errors.
On the Macintosh, pixels were square, and a GrafPort had a default resolution of 72 pixels per inch, chosen to match conventions established by the printing industry of having 72 points per inch.
QuickDraw also contained a number of scaling and mapping functions.
QuickDraw maintained a number of global variables per process, chief among these being the current port. This originally simplified the API, since all operations pertained to "the current port," but as the OS developed, this use of global state has also made QuickDraw much harder to integrate with modern design approaches such as multi-threading and pre-emptive multitasking. To address these problems, the Carbon API (a bridge between Mac OS 9 and Mac OS X) added additional parameters to some of the routines, allowing for the (opaque) storage of thread information and a new (non-polled) event structure.

## Graphics primitives

Everything seen on a classic Mac OS screen is drawn by QuickDraw, but the library itself is quite low level. The primitive objects it can draw are:
* Lines
* Rectangles
* Rounded (and oval) cornered rectangles
* Ovals (including circles and ellipses)
* Arcs (and wedges), both circular and oval
* Polygons (arbitrary closed shapes built from a list of points joined by lines)
* Regions (arbitrary sets of pixels—see below)
* Bitmaps and Pixmaps
* Text
Each of these objects (except text) may be drawn using a "pen", which can have any rectangular dimensions, pattern or color. Note that, because the pen is rectangular and axis-aligned, diagonal lines will end up thicker than horizontal or vertical ones. Shapes may be drawn filled or framed, using any pattern or color. A filled Arc forms a wedge. Text may be drawn in any installed font, in a variety of stylistic variations, and at any size and color. Depending on how the selected font is stored, text can be scaled in a variety of ways - TrueType fonts will scale smoothly to any size, whereas bitmap fonts do not usually scale well.
An important feature of QuickDraw was support for transfer modes, which governed how a destination pixel value was related to its previous value and the color of the object being drawn.
The set of attributes of the pen and text drawing are associated with the GrafPort.
Regions are a key data structure in QuickDraw. They define an arbitrary set of pixels, rather like a bitmap, but in a compressed form which can be very rapidly manipulated in complex ways. Regions can be combined (union), subtracted (difference), and XORed to form other Regions. They can be used within a GrafPort for clipping, or drawn filled or framed like any other shape. A series of framed shapes and connected lines may be combined into a Region. A Region need not consist of a contiguous set of pixels - disconnected regions are possible and common. Although regions could allow powerful graphic manipulations they are limited by the current implementation that restricts the maximum region data storage size to a sixteen bit value and so are not practical as a general-purpose drawing composition tool and practical use at high resolution is also restricted. Regions underpin the rest of QuickDraw, permitting clipping to arbitrary shapes, essential for the implementation of multiple overlapping windows. Invented by Bill Atkinson, Regions were patented as a separate invention by Apple.
A region is specified (after initial creation) by an opening of the region, drawing various QuickDraw shapes, and closing the region. Hidden routines construct the region as the QuickDraw commands are executed. Bitmaps may also be converted to regions, and bitmaps may be made from regions by "painting" or "filling" the region into a graphics port.
The internal structure of a region, other than the storage length and its bounding rectangle, is opaque - there are no Apple-published documents available, though the mechanism is outlined in the patent. Regions are implemented using both vertical and horizontal compression. A region is stored as a series of horizontal scan lines ("rasters"), each of which contains a vertical coordinate followed by a list of horizontal inversion coordinates. Each inversion point can be thought of as toggling inclusion in the region for all the points after it: the first point turns the region on, the second turns it off, and so on. Further compression is achieved by storing each line differentially: each line contains only the differences from the previous line rather than a full set of inversion points. Finally, identical adjacent scan lines are efficiently encoded by simply skipping them. In this way, a commonly used region, the rounded corner rectangle, is efficiently encoded, and complex operations such as region composition and image clipping may be done without requiring either extensive processor cycles or large amounts of memory. (The original systems executing QuickDraw code used processors operating at 8 megahertz clock rates and systems had but 128 kilobytes of writable memory.)
Because regions are bound to a specific orientation, a ninety degree rotation of a region would require both detailed reverse engineering of the structure and extensive coding. A general rotation is impractical when compared to rotating the original source boundary description and simply creating a new region. However, the API includes conversion routines to and from BitMaps. (Bitmaps may also be rotated using well known methods, but with various degrees of image degradation depending upon angle chosen, the storage and processor cycles available to the operation, and the complexity of the algorithm.)
Apple has recently (in the Carbon API) defined regions as an opaque structure under some program compilation options.

## Higher level operations

Any series of graphics calls to QuickDraw can be recorded in a structure called a Picture. This can then be saved in memory and "played back" at any time, reproducing the graphics sequence. At playback time the picture may be placed at new coordinates or scaled without the loss of resolution commonly encountered in bitmap scaling. A picture can be saved to disk in which form it defines the Apple PICT format.
An entire BitMap (or PixMap, when referring to color images) may be copied from one GrafPort to another, with scaling and clipping. Known as blitting, or CopyBits, after the name of the function, this operation is the basis for most animation and sprite-like effects on the Mac.
QuickDraw provides a similar blitting function which is designed to implement scrolling within a GrafPort - the image in the port can be shifted to a new location without scaling (but with clipping if desired).
Each graphics primitive operation is vectored through the StdProcs, a series of function pointers stored in the GrafPort. This limited polymorphism permits individual operations to be overridden or replaced by custom functions, allowing printer drivers to intercept graphics commands and translate them to suitable printer operations. In this way, QuickDraw can be rendered using PostScript, a fact that enabled the Macintosh to practically invent desktop publishing.
Similar to a subclass, the Window data structure began with the associated GrafPort, thus basically making windows exchangeable with any GrafPort. While convenient, this made it easy to write erroneous code that passed an offscreen graphics port into API that expected a full-blown window.

## History

QuickDraw started life as Lisa Graf as part of the Apple Lisa development. For the Macintosh it was initially simplified, but then later extended. Originally, QuickDraw GrafPorts only supported a bit depth of 1, that is one bit per pixel, or black and white. This suited the built-in screen of the early Macintosh, with its fixed size of 512×342 pixels. Limited color was supported using a crude planar model, allowing QuickDraw to drive some types of dot-matrix printer that used multi-colored ribbons, but very few applications supported this feature.
In 1987, the Macintosh II was launched, which was designed as a more conventional three-box design - Computer, monitor and keyboard all separate. Because the monitor was separate, and larger than the original Mac, the video architecture had to necessarily change. In addition, the Mac II took the Macintosh from black-and-white to full color. Apple also decided at this time to support a seamless desktop spanning multiple monitors, an industry first. Thus Color QuickDraw, a significant extension of the original QuickDraw, was created. At this time Bill Atkinson was busy with HyperCard, so the Color QuickDraw work was done by Ernie Beernink (then still 23 years old): Apple's Dave Allen also credited Dave Fung. The original architecture lacked much provision for expandability, but using a series of hacks, the Apple developers managed to make the addition of color and the new video architecture virtually seamless to both developers and end users.
Color QuickDraw introduced new data structures, including GDevices to represent each attached video card/monitor, and a new color GrafPort (CGrafPort) structure to handle color, as well as PixMaps instead of BitMaps for multiple bits-per-pixel images. One of the hacks for compatibility used here was that the new structure was exactly the same size as the old one, with most data members in the same place, but with additional handles and pointers to color structures in place of the BitMap fields. The upper two bits of the rowBytes field were pressed into use as flags to distinguish a GrafPort from a CGrafPort (they were always zero on old-style GrafPorts because a BitMap could never feasibly be so wide as to ever set these bits). The use of these two high bits would come back to haunt QuickDraw later, as it forced a maximum row width of just 4,095 on 32-bit PixMaps, which became problematic for high-resolution graphics work. Later development (Mac OS 8.5/Carbon) eliminated this limitation but was not fully backward compatible. A Palette Manager was also added in Color QuickDraw which managed the arbitration of colors on indexed video devices. Most graphics primitives operations remained either unchanged (but would operate in color), or else new color versions of the black and white APIs were added.
Initially, Color QuickDraw was only capable of operating with 1, 2, 4 and 8-bit video cards, which were all that was available at the time. Soon after however, 24-bit video cards appeared (so-called true color), and QuickDraw was updated again to support up to 32 bits per pixel (in reality, 24 bits, with 8 unused) of color data ("32-Bit QuickDraw"). The architecture always allowed for this, however, so no new APIs were necessary. The color data structures themselves allowed a color depth of 1, 2, 4, 8, 15 and 24 bits, yielding 2, 4, 16, 256, 32,768 and 16,777,216 colors respectively, or 4, 16 and 256 scales of grey. QuickDraw took care of managing the resampling of colors to the available color depths of the actual video hardware, or transfer between offscreen image buffers, including optionally dithering images down to a lower depth to improve image quality. A set of color sampling utilities were also added so that programmers could generate optimal color palettes for use with indexed video devices.
The architecture of QuickDraw had always allowed the creation of GrafPorts and their associated BitMaps or PixMaps "offscreen", where graphics could be composed in memory without it being visible immediately on the screen. Pixels could be transferred between these offscreen ports and the screen using the QuickDraw blitting function CopyBits. Such offscreen compositing is the workhorse for games and graphics-intensive applications. However, until the advent of 32-Bit QuickDraw, such offscreen worlds had to be created and set up by hand by programmers within their applications. This could be error-prone, as it involved three or more separate and fairly complex data structures (CGrafPort, PixMap and GDevice, and for indexed devices, the color look-up table and its inverse). With 32-Bit QuickDraw, OS support for handling this was added, with the "Offscreen Graphics World" or GWorld. The video buffer (PixMap) of a GWorld could be stored in main memory, or when available in unused parts of video ram where copying to the screen could be optimized for speed by avoiding the need to transfer a large amount of pixel data across the main memory bus.
With the advent of QuickTime, QuickDraw gained the ability to deal with compressed raster data, such as JPEG. The QuickTime Image Compression Manager integrated closely with QuickDraw: in particular, image decompression calls were full-fledged QuickDraw drawing calls, and if a picture was being recorded, the compressed data would be saved as part of the picture, for display when the picture was later drawn. The Image Compression Manager also added integration with ColorSync color matching.
After this, apart from back-end changes to optimize for new processor architectures (PowerPC), QuickDraw remained largely unchanged throughout the rest of the life of the classic Mac OS. QuickDraw GX and QuickDraw 3D shared the QuickDraw name and were able to interoperate with QuickDraw PixMap and picture data structures, but were otherwise completely separate in functionality.
With Mac OS X, QuickDraw became part of the Carbon API. In 2005, with the release of Mac OS X 10.4, QuickDraw was officially deprecated.
In 2010 with MacPaint 1.3's source code release through the Computer History Museum, a historical version of QuickDraw source code became available too.