From 8dc7d5ea2680b7e397d2cdb7f83427d2c86c9de7 Mon Sep 17 00:00:00 2001 From: Victoria Lease Date: Tue, 24 Sep 2013 15:57:02 -0700 Subject: clarify Paint flag docs Bug: 10460797 Change-Id: Iae622b302cad3dc788f512b472e3a59ec227a8d7 --- graphics/java/android/graphics/Paint.java | 114 ++++++++++++++++++++++++++---- 1 file changed, 102 insertions(+), 12 deletions(-) diff --git a/graphics/java/android/graphics/Paint.java b/graphics/java/android/graphics/Paint.java index 69d9916e3456..5fc2588e4411 100644 --- a/graphics/java/android/graphics/Paint.java +++ b/graphics/java/android/graphics/Paint.java @@ -87,27 +87,113 @@ public class Paint { Align.LEFT, Align.CENTER, Align.RIGHT }; - /** bit mask for the flag enabling antialiasing */ + /** + * Paint flag that enables antialiasing when drawing. + * + *

Enabling this flag will cause all draw operations that support + * antialiasing to use it.

+ * + * @see #Paint(int) + * @see #setFlags(int) + */ public static final int ANTI_ALIAS_FLAG = 0x01; - /** bit mask for the flag enabling bitmap filtering */ + /** + * Paint flag that enables bilinear sampling on scaled bitmaps. + * + *

If cleared, scaled bitmaps will be drawn with nearest neighbor + * sampling, likely resulting in artifacts. This should generally be on + * when drawing bitmaps, unless performance-bound (rendering to software + * canvas) or preferring pixelation artifacts to blurriness when scaling + * significantly.

+ * + *

If bitmaps are scaled for device density at creation time (as + * resource bitmaps often are) the filtering will already have been + * done.

+ * + * @see #Paint(int) + * @see #setFlags(int) + */ public static final int FILTER_BITMAP_FLAG = 0x02; - /** bit mask for the flag enabling dithering */ + /** + * Paint flag that enables dithering when blitting. + * + *

Enabling this flag applies a dither to any blit operation where the + * target's colour space is more constrained than the source. + * + * @see #Paint(int) + * @see #setFlags(int) + */ public static final int DITHER_FLAG = 0x04; - /** bit mask for the flag enabling underline text */ + /** + * Paint flag that applies an underline decoration to drawn text. + * + * @see #Paint(int) + * @see #setFlags(int) + */ public static final int UNDERLINE_TEXT_FLAG = 0x08; - /** bit mask for the flag enabling strike-thru text */ + /** + * Paint flag that applies a strike-through decoration to drawn text. + * + * @see #Paint(int) + * @see #setFlags(int) + */ public static final int STRIKE_THRU_TEXT_FLAG = 0x10; - /** bit mask for the flag enabling fake-bold text */ + /** + * Paint flag that applies a synthetic bolding effect to drawn text. + * + *

Enabling this flag will cause text draw operations to apply a + * simulated bold effect when drawing a {@link Typeface} that is not + * already bold.

+ * + * @see #Paint(int) + * @see #setFlags(int) + */ public static final int FAKE_BOLD_TEXT_FLAG = 0x20; - /** bit mask for the flag enabling linear-text (no caching) */ + /** + * Paint flag that enables smooth linear scaling of text. + * + *

Enabling this flag does not actually scale text, but rather adjusts + * text draw operations to deal gracefully with smooth adjustment of scale. + * When this flag is enabled, font hinting is disabled to prevent shape + * deformation between scale factors, and glyph caching is disabled due to + * the large number of glyph images that will be generated.

+ * + *

{@link #SUBPIXEL_TEXT_FLAG} should be used in conjunction with this + * flag to prevent glyph positions from snapping to whole pixel values as + * scale factor is adjusted.

+ * + * @see #Paint(int) + * @see #setFlags(int) + */ public static final int LINEAR_TEXT_FLAG = 0x40; - /** bit mask for the flag enabling subpixel-text */ + /** + * Paint flag that enables subpixel positioning of text. + * + *

Enabling this flag causes glyph advances to be computed with subpixel + * accuracy.

+ * + *

This can be used with {@link #LINEAR_TEXT_FLAG} to prevent text from + * jittering during smooth scale transitions.

+ * + * @see #Paint(int) + * @see #setFlags(int) + */ public static final int SUBPIXEL_TEXT_FLAG = 0x80; - /** bit mask for the flag enabling device kerning for text */ + /** Legacy Paint flag, no longer used. */ public static final int DEV_KERN_TEXT_FLAG = 0x100; /** @hide bit mask for the flag enabling subpixel glyph rendering for text */ public static final int LCD_RENDER_TEXT_FLAG = 0x200; - /** bit mask for the flag enabling embedded bitmap strikes for text */ + /** + * Paint flag that enables the use of bitmap fonts when drawing text. + * + *

Disabling this flag will prevent text draw operations from using + * embedded bitmap strikes in fonts, causing fonts with both scalable + * outlines and bitmap strikes to draw only the scalable outlines, and + * fonts with only bitmap strikes to not draw at all.

+ * + * @see #Paint(int) + * @see #setFlags(int) + */ public static final int EMBEDDED_BITMAP_TEXT_FLAG = 0x400; /** @hide bit mask for the flag forcing freetype's autohinter on for text */ public static final int AUTO_HINTING_TEXT_FLAG = 0x800; @@ -118,12 +204,16 @@ public class Paint { static final int DEFAULT_PAINT_FLAGS = DEV_KERN_TEXT_FLAG | EMBEDDED_BITMAP_TEXT_FLAG; /** - * Option for {@link #setHinting}: disable hinting. + * Font hinter option that disables font hinting. + * + * @see #setHinting(int) */ public static final int HINTING_OFF = 0x0; /** - * Option for {@link #setHinting}: enable hinting. + * Font hinter option that enables font hinting. + * + * @see #setHinting(int) */ public static final int HINTING_ON = 0x1; -- cgit v1.2.3-59-g8ed1b