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]
|