Legacy Document

Inside Macintosh: Text /

Chapter 3 - QuickDraw Text / Using QuickDraw Text

Specifying the Transfer Mode

The value of the current graphics port transfer mode (txMode) field determines the way glyphs are placed in the bit image and how the text is to appear. It defines the way text to be drawn interacts with text and graphics already drawn. (When a glyph is drawn, QuickDraw does a bit-by-bit comparison based on the mode and stores the resulting bits into the bit image.) You set the text mode by calling the TextMode procedure.

By default, the transfer mode field is set to srcOr, which specifies that text to be drawn should overlay the existing graphics. The srcOr transfer mode produces the best results for drawing text because it writes only those bits that make up the actual glyph. In most situations, when drawing text with the basic transfer modes, you should use only srcOr or srcBic; all other modes can result in clipping of glyphs by adjacent glyphs. For example, the Copy operation paints over what already exists on the destination, replacing it entirely.

Basic Transfer Mode Operations

For each type of drawing mode, there are four basic kinds of operations: Copy, Or, Xor, and Bic (bit clear). For Color QuickDraw, there are additional arithmetic drawing mode operations designed specifically for use with color. They are discussed later in this section, and fully in Inside Macintosh: Imaging.

The transfer mode operation determines how the text is to be displayed: for each bit in the item to be drawn, the corresponding bit in the destination bitmap is identified, the specified Boolean operation is performed on the pair of bits, and the resulting bit is stored into the destination bit image. When you work with color pixels, transfer modes produce different results on indexed and direct devices.

In addition to drawing the entire glyph in all cases, the srcOr mode is recommended for all applications because it uses the least memory. The srcOr mode only affects other parts of existing glyphs if the glyphs overlap. In srcOr mode the color of the glyph is determined by the foreground color.

The maximum stack space required for a text drawing operation can be considerable. Text drawing uses a minimum amount of stack if the following conditions are true:

• The transfer mode is srcOr.
• The foreground color is black.
• The destination of the text is contained within a rectangular portion of the region of the graphics port that is actually visible on the screen.
• The text is not scaled.
• The text does not have to be italicized, outlined, or shadowed by QuickDraw.

Otherwise, the amount of stack space required to draw all of the text at once depends most on the size and the width of the text and the depth of the destination.

If QuickDraw can't get enough stack space to draw an entire text segment at once, it draws the segment in pieces. This can produce unusual results in modes other than srcOr or srcBic if some of the glyphs overlap because of kerning or italicizing. If the mode is srcCopy, overlapping glyphs are clipped by the last drawn glyph. If the mode is srcXor, pixels where the glyphs overlap are not drawn at all. If the mode is one of the arithmetic modes, the arithmetic rules are followed, ignoring that the destination may include part of the text being drawn.

The stack space required for a drawing operation in Color QuickDraw is roughly estimated by the following calculation.

(text width) * (text height) * (font depth) / (8 bits per byte) + 3K

Pixel depth normally equals the screen depth. If the amount of stack space available is small (less than 3.5K), QuickDraw instead uses a pixel depth of 1, which is slow, but uses less stack space.

For the original QuickDraw, the required stack space is roughly estimated by the following calculation.

(text width) * (text height) / (8 bits per byte) + 2K

Arithmetic Transfer Mode Operations

Arithmetic transfer modes calculate pixel values by adding, subtracting, or averaging the RGB components of the source and destination pixels. The arithmetic modes change the destination pixels by performing arithmetic operations on the source and destination pixels.

Each drawing routine converts the source and destination pixels to their RGB (red, green, and blue) components, performs an operation on each pair of components to produce a new RGB value for the destination, and then assigns the destination to a pixel value close to the calculated RGB value. The arithmetic drawing modes are addOver, addPin, subOver, subPin, adMax, adMin, and blend. To specify an arithmetic mode, you pass the operation to be used to the TextMode procedure. For example, the following calls save the current state of the text mode field, then set it to the transfer mode blend.

oldTextMode := theport.^txMode; 
TextMode(blend);

The arithmetic modes were designed for use with color. They are most useful for 8-bit color, but they work on 4-bit and 2-bit color also. When the destination bitmap is one bit deep, the mode reverts to the basic transfer mode that best approximates the arithmetic mode requested. For more information about arithmetic mode operations, see the QuickDraw chapters in Inside Macintosh: Imaging.

Note

To help make color work well on different screen depths, Color QuickDraw does some validity checking of the foreground and background colors. If your application is drawing to a CGrafPort with a depth equal to 1 or 2, and if the RGB values of the foreground and background colors aren't the same, but both of them map to the same pixel value, then the foreground color is inverted. This ensures that, for instance, red text drawn on a green background doesn't map to black on black.

The grayishTextOr Transfer Mode

You can use the text drawing mode, grayishTextOr, to draw dimmed text on the screen. It is especially useful for displaying disabled user interface items. If the destination device is color and grayishTextOr is the transfer mode, QuickDraw draws with a blend of the foreground and background colors. If the destination device is black and white, the grayishTextOr mode dithers black and white. Dithering is a technique that creates the effect of additional colors, if the destination device is color. If the destination device is black-and-white, dithering creates the effect of levels of gray.

Note that grayishTextOr is not considered a standard transfer mode because currently it is not stored in pictures, and printing with it is undefined. (It does not pass through the QuickDraw bottleneck procedure.) The following calls show how to use grayishTextOr. They save the current state of the text mode field, then set it to grayishTextOr.

oldTextMode := theport.^txMode;
TextMode(grayishTextOr);

Text Mask Mode

You can add the mask constant to another transfer mode to cause only the glyph portion of the text to be applied in the current transfer mode to the destination. If the text font contains more than one color or if the drawing mode is an arithmetic mode, the mask mode causes only the portion of the glyphs not equal to the background to be drawn.

The arithmetic transfer modes apply the glyph's background to the destination; this can lead to undesirable results if you draw the text in pieces. QuickDraw draws the leftmost part of a piece of text on top of a previous piece if the font kerns to the left. Using maskMode in addition to these modes causes only the foreground part of the glyph to be drawn.

Because the rightmost glyph is clipped, to kern to the right in text mask mode, you should use srcOr, or add trailing spaces. The following call sets the transfer mode to blend with mask mode.

TextMode(blend + mask);

Transparent Transfer Mode

The transparent mode replaces the destination pixel with the source pixel when the source pixel isn't equal to the background color. For a complete description of the transparent mode, see the QuickDraw chapters in Inside Macintosh: Imaging.

The arithmetic transfer modes apply the glyph's background to the destination; this can produce undesirable results if you draw the text in pieces. QuickDraw draws the leftmost part of a piece of text on top of a previous piece if the font kerns to the left. If you use the mask mode (maskMode) in addition to these modes, QuickDraw draws only the foreground part of the glyph. Because the rightmost glyph is clipped, to kern to the right in text mask mode, you should use srcOr. For an explanation of kerning, see the chapter "Font Manager" in this book.

Transfer Modes and Multibit Fonts

Multibit fonts can have a specific color. Some transfer modes may not produce the desired results with a multibit font. However, the arithmetic mode and transparent mode work equally well with single bit and multibit fonts.

Unlike single bit fonts, multibit fonts draw quickly in srcOr mode only if the foreground is white. Single bit fonts draw quickly in srcOr mode only if the foreground is black. Grayscale fonts produce a spectrum of colors, rather than just the foreground and background colors.