Technical Q&A QA1193

QuickDraw Text Anti-Aliasing using Quartz 2D

Q: How do I turn on Quartz 2D anti-aliasing of QuickDraw text for my application?

A: Starting in Mac OS X 10.1.5, Apple added a feature that allows developers to draw QuickDraw text using the anti-aliasing from Core Graphics (Quartz 2D). This feature was added to help developers that cannot migrate completely to UniCode imaging through DrawThemeTextBox or ATSUI but still want to provide a consistent look in their applications.

In 10.1.5, only the API name of SwapQDTextFlags is available and it is not exported via CFM so CFM applications will need to use CFBundleGetFunctionPointerForName from the Core Foundation framework to look up the SwapQDTextFlags symbol in the Application Services framework. See the CallMachOFramework sample in the CarbonLib SDK for more information on how to look up and call Mach-O symbols from a CFM application.

Starting in Mac OS X 10.2 (Jaguar), a new API name, QDSwapTextFlags, is supported that functions identically to SwapQDTextFlags. In addition, Jaguar supports a new port-based API named QDSwapPortTextFlags to allow developers to control the setting on a port-by-port basis.

      Function:
          // In 10.1.5 and later
          SwapQDTextFlags - Returns current flags and optionally sets new flags.
          UInt32 SwapQDTextFlags(UInt32 newFlags);
          // In 10.2 and later
          QDSwapTextFlags - Returns current flags and optionally sets new flags.
          UInt32 QDSwapTextFlags(UInt32 newFlags);
      Parameter:
    UInt32 newFlags;
      Supported Flags:
          // Sets whatever is specified in system defaults.
          // Currently sets kQDUseTrueTypeScalerGlyphs if nothing is specified.
          kQDUseDefaultTextRendering    = 0
          // bit 0
          kQDUseTrueTypeScalerGlyphs    = (1 << 0)
          // bit 1
          kQDUseCGTextRendering    = (1 << 1)
          // bit 2
          // As of Mac OS X 10.2, kQDUseCGTextMetrics implies kQDUseCGTextRendering
          kQDUseCGTextMetrics        = (1 << 2)
          kQDSupportedFlags        = kQDUseTrueTypeScalerGlyphs
                      | kQDUseCGTextRendering
                      | kQDUseCGTextMetrics
          // to request the current state, without changing anything
          kQDDontChangeFlags        = 0xFFFFFFFF
      Suggested Usage:
          UInt32 savedFlags = SwapQDTextFlags(newFlags);
          // ... draw text under the conditions of "newFlags"...
          // restore previous setting
          (void)SwapQDTextFlags(savedFlags);
      Port-based API:
          // In 10.2 and later
          QDSwapPortTextFlags - Returns current flags and optionally sets new flags for the given port.
          UInt32 QDSwapPortTextFlags(CGrafPtr port, UInt32 newFlags);
      Parameters:
          CGrafPtr port;        // Settings per port override any global settings
                // If port == NULL then the current port is used
          UInt32 newFlags;        // As per SwapQDTextFlags and QDSwapTextFlags above

Discussion:

Use SwapQDTextFlags(kQDUseCGTextRendering) without kQDUseCGTextMetrics only if compatibility with existing documents is required (to avoid reflow). The old QuickdrawText metrics are derived from the instructed (grid-fitted) outlines, and are sometimes too different from the ideal (unhinted) metrics corresponding to the ideal outlines used by CG text rendering.

The SwapQDTextFlags function itself does not have any measurable performance impact; the flags can be changed at any time. The setting is per application (like SetFractEnable(), SetOutlinePreferred() etc.), not per GrafPort. Use QDSwapPortTextFlags for a per-port setting.

Limitations:

SrcOr is the only supported text transfer mode. In all other cases, we fall back to the old QuickdrawText rendering. Developers who need special transfer mode effects need to draw the text into an offscreen and use CopyBits (which is basically what QuickDrawText does, too, for the other transfer modes).

Similarly, only bold and italic are supported as algorithmic styles (when there is no intrinsic font for the type face). Outline and shadow are not supported.

Underlines always are continuous lines, whereas QuickdrawText spares out descenders.

Avoid double-drawing the same text because anti-aliased areas darken with repeated over-drawing.

As with Cocoa text, fonts with very fine lines are drawn so light that readability may be a problem.

Certain glyphs in certain fonts exceed the ascent and/or descent values of the vertical metrics in QD's FontInfo. By default (unless SetPreserveGlyph(true) is called), QuickDrawText forces them to fit between ascent and descent, such that text editing code that assumes that all text is drawn within that range doesn't leave dirty pixels around or clip off the accents. CG text rendering has no support for "squishing" these glyphs. In particular, this may affect certain localizations where diacriticals on uppercase characters are used, "undercommas", etc. The workaround is to avoid fonts that have the design flaw of "lying" about their metrics. These are mainly TrueType fonts for which legacy bitmap fonts existed with the same font name. The TrueType outlines were designed under the constraints to match the existing bitmap fonts as much as possible and also to preserve the vertical metrics, which created the conflicts with certain additional glyphs.

In Mac OS X 10.1.5, these flags only support anti-aliasing for text in fonts larger that 10 points regardless of the anti-aliasing setting in the General System Preferences panel. In Mac OS X 10.2, the System Preferences setting is respected.

[Oct 29 2002]