SkScalerContext.h revision 2d2a68c51b4a71bd60760510bf2b2e58bc9890b2 
1/*
2 * Copyright 2006 The Android Open Source Project
3 *
4 * Use of this source code is governed by a BSD-style license that can be
5 * found in the LICENSE file.
6 */
7
8#ifndef SkScalerContext_DEFINED
9#define SkScalerContext_DEFINED
10
11#include "SkMask.h"
12#include "SkMaskGamma.h"
13#include "SkMatrix.h"
14#include "SkPaint.h"
15#include "SkTypeface.h"
16
17#ifdef SK_BUILD_FOR_ANDROID
18    #include "SkPaintOptionsAndroid.h"
19#endif
20
21struct SkGlyph;
22class SkDescriptor;
23class SkMaskFilter;
24class SkPathEffect;
25class SkRasterizer;
26
27/*
28 *  To allow this to be forward-declared, it must be its own typename, rather
29 *  than a nested struct inside SkScalerContext (where it started).
30 */
31struct SkScalerContextRec {
32    uint32_t    fOrigFontID;
33    uint32_t    fFontID;
34    SkScalar    fTextSize, fPreScaleX, fPreSkewX;
35    SkScalar    fPost2x2[2][2];
36    SkScalar    fFrameWidth, fMiterLimit;
37
38    //These describe the parameters to create (uniquely identify) the pre-blend.
39    uint32_t    fLumBits;
40    uint8_t     fDeviceGamma; //2.6, (0.0, 4.0) gamma, 0.0 for sRGB
41    uint8_t     fPaintGamma;  //2.6, (0.0, 4.0) gamma, 0.0 for sRGB
42    uint8_t     fContrast;    //0.8+1, [0.0, 1.0] artificial contrast
43    uint8_t     fReservedAlign;
44
45    SkScalar getDeviceGamma() const {
46        return SkIntToScalar(fDeviceGamma) / (1 << 6);
47    }
48    void setDeviceGamma(SkScalar dg) {
49        SkASSERT(0 <= dg && dg < SkIntToScalar(4));
50        fDeviceGamma = SkScalarFloorToInt(dg * (1 << 6));
51    }
52
53    SkScalar getPaintGamma() const {
54        return SkIntToScalar(fPaintGamma) / (1 << 6);
55    }
56    void setPaintGamma(SkScalar pg) {
57        SkASSERT(0 <= pg && pg < SkIntToScalar(4));
58        fPaintGamma = SkScalarFloorToInt(pg * (1 << 6));
59    }
60
61    SkScalar getContrast() const {
62        return SkIntToScalar(fContrast) / ((1 << 8) - 1);
63    }
64    void setContrast(SkScalar c) {
65        SkASSERT(0 <= c && c <= SK_Scalar1);
66        fContrast = SkScalarRoundToInt(c * ((1 << 8) - 1));
67    }
68
69    /**
70     *  Causes the luminance color and contrast to be ignored, and the
71     *  paint and device gamma to be effectively 1.0.
72     */
73    void ignorePreBlend() {
74        setLuminanceColor(SK_ColorTRANSPARENT);
75        setPaintGamma(SK_Scalar1);
76        setDeviceGamma(SK_Scalar1);
77        setContrast(0);
78    }
79
80    uint8_t     fMaskFormat;
81    uint8_t     fStrokeJoin;
82    uint16_t    fFlags;
83    // Warning: when adding members note that the size of this structure
84    // must be a multiple of 4. SkDescriptor requires that its arguments be
85    // multiples of four and this structure is put in an SkDescriptor in
86    // SkPaint::MakeRec.
87
88    void    getMatrixFrom2x2(SkMatrix*) const;
89    void    getLocalMatrix(SkMatrix*) const;
90    void    getSingleMatrix(SkMatrix*) const;
91
92    inline SkPaint::Hinting getHinting() const;
93    inline void setHinting(SkPaint::Hinting);
94
95    SkMask::Format getFormat() const {
96        return static_cast<SkMask::Format>(fMaskFormat);
97    }
98
99    SkColor getLuminanceColor() const {
100        return fLumBits;
101    }
102
103    void setLuminanceColor(SkColor c) {
104        fLumBits = c;
105    }
106};
107
108//The following typedef hides from the rest of the implementation the number of
109//most significant bits to consider when creating mask gamma tables. Two bits
110//per channel was chosen as a balance between fidelity (more bits) and cache
111//sizes (fewer bits). Three bits per channel was chosen when #303942; (used by
112//the Chrome UI) turned out too green.
113typedef SkTMaskGamma<3, 3, 3> SkMaskGamma;
114
115class SkScalerContext {
116public:
117    typedef SkScalerContextRec Rec;
118
119    enum Flags {
120        kFrameAndFill_Flag        = 0x0001,
121        kDevKernText_Flag         = 0x0002,
122        kEmbeddedBitmapText_Flag  = 0x0004,
123        kEmbolden_Flag            = 0x0008,
124        kSubpixelPositioning_Flag = 0x0010,
125        kForceAutohinting_Flag    = 0x0020,  // Use auto instead of bytcode hinting if hinting.
126        kVertical_Flag            = 0x0040,
127
128        // together, these two flags resulting in a two bit value which matches
129        // up with the SkPaint::Hinting enum.
130        kHinting_Shift            = 7, // to shift into the other flags above
131        kHintingBit1_Flag         = 0x0080,
132        kHintingBit2_Flag         = 0x0100,
133
134        // Pixel geometry information.
135        // only meaningful if fMaskFormat is LCD16 or LCD32
136        kLCD_Vertical_Flag        = 0x0200,    // else Horizontal
137        kLCD_BGROrder_Flag        = 0x0400,    // else RGB order
138
139        // Generate A8 from LCD source (for GDI and CoreGraphics).
140        // only meaningful if fMaskFormat is kA8
141        kGenA8FromLCD_Flag        = 0x0800, // could be 0x200 (bit meaning dependent on fMaskFormat)
142    };
143
144    // computed values
145    enum {
146        kHinting_Mask   = kHintingBit1_Flag | kHintingBit2_Flag,
147    };
148
149
150    SkScalerContext(SkTypeface*, const SkDescriptor*);
151    virtual ~SkScalerContext();
152
153    SkTypeface* getTypeface() const { return fTypeface.get(); }
154
155    SkMask::Format getMaskFormat() const {
156        return (SkMask::Format)fRec.fMaskFormat;
157    }
158
159    bool isSubpixel() const {
160        return SkToBool(fRec.fFlags & kSubpixelPositioning_Flag);
161    }
162
163    // remember our glyph offset/base
164    void setBaseGlyphCount(unsigned baseGlyphCount) {
165        fBaseGlyphCount = baseGlyphCount;
166    }
167
168    /** Return the corresponding glyph for the specified unichar. Since contexts
169        may be chained (under the hood), the glyphID that is returned may in
170        fact correspond to a different font/context. In that case, we use the
171        base-glyph-count to know how to translate back into local glyph space.
172     */
173    uint16_t charToGlyphID(SkUnichar uni);
174
175    /** Map the glyphID to its glyph index, and then to its char code. Unmapped
176        glyphs return zero.
177    */
178    SkUnichar glyphIDToChar(uint16_t glyphID);
179
180    unsigned    getGlyphCount() { return this->generateGlyphCount(); }
181    void        getAdvance(SkGlyph*);
182    void        getMetrics(SkGlyph*);
183    void        getImage(const SkGlyph&);
184    void        getPath(const SkGlyph&, SkPath*);
185    void        getFontMetrics(SkPaint::FontMetrics*);
186
187    /** Return the size in bytes of the associated gamma lookup table
188     */
189    static size_t GetGammaLUTSize(SkScalar contrast, SkScalar paintGamma, SkScalar deviceGamma,
190                                  int* width, int* height);
191
192    /** Get the associated gamma lookup table. The 'data' pointer must point to pre-allocated
193        memory, with size in bytes greater than or equal to the return value of getGammaLUTSize().
194     */
195    static void   GetGammaLUTData(SkScalar contrast, SkScalar paintGamma, SkScalar deviceGamma,
196                                  void* data);
197
198#ifdef SK_BUILD_FOR_ANDROID
199    unsigned getBaseGlyphCount(SkUnichar charCode);
200
201    // This function must be public for SkTypeface_android.h, but should not be
202    // called by other callers
203    SkFontID findTypefaceIdForChar(SkUnichar uni);
204#endif
205
206    static void MakeRec(const SkPaint&, const SkDeviceProperties* deviceProperties,
207                        const SkMatrix*, Rec* rec);
208    static inline void PostMakeRec(const SkPaint&, Rec*);
209
210    static SkMaskGamma::PreBlend GetMaskPreBlend(const Rec& rec);
211
212protected:
213    Rec         fRec;
214    unsigned    fBaseGlyphCount;
215
216    /** Generates the contents of glyph.fAdvanceX and glyph.fAdvanceY.
217     *  May call getMetrics if that would be just as fast.
218     */
219    virtual void generateAdvance(SkGlyph* glyph) = 0;
220
221    /** Generates the contents of glyph.fWidth, fHeight, fTop, fLeft,
222     *  as well as fAdvanceX and fAdvanceY if not already set.
223     *
224     *  TODO: fMaskFormat is set by getMetrics later; cannot be set here.
225     */
226    virtual void generateMetrics(SkGlyph* glyph) = 0;
227
228    /** Generates the contents of glyph.fImage.
229     *  When called, glyph.fImage will be pointing to a pre-allocated,
230     *  uninitialized region of memory of size glyph.computeImageSize().
231     *  This method may change glyph.fMaskFormat if the new image size is
232     *  less than or equal to the old image size.
233     *
234     *  Because glyph.computeImageSize() will determine the size of fImage,
235     *  generateMetrics will be called before generateImage.
236     */
237    virtual void generateImage(const SkGlyph& glyph) = 0;
238
239    /** Sets the passed path to the glyph outline.
240     *  If this cannot be done the path is set to empty;
241     *  this is indistinguishable from a glyph with an empty path.
242     *  This does not set glyph.fPath.
243     *
244     *  TODO: path is always glyph.fPath, no reason to pass separately.
245     */
246    virtual void generatePath(const SkGlyph& glyph, SkPath* path) = 0;
247
248    /** Retrieves font metrics.
249     *  TODO: there is now a vertical bit, no need for two parameters.
250     */
251    virtual void generateFontMetrics(SkPaint::FontMetrics* mX,
252                                     SkPaint::FontMetrics* mY) = 0;
253
254    /** Returns the number of glyphs in the font. */
255    virtual unsigned generateGlyphCount() = 0;
256
257    /** Returns the glyph id for the given unichar.
258     *  If there is no 1:1 mapping from the unichar to a glyph id, returns 0.
259     */
260    virtual uint16_t generateCharToGlyph(SkUnichar unichar) = 0;
261
262    /** Returns the unichar for the given glyph id.
263     *  If there is no 1:1 mapping from the glyph id to a unichar, returns 0.
264     *  The default implementation always returns 0, indicating failure.
265     */
266    virtual SkUnichar generateGlyphToChar(uint16_t glyphId);
267
268    void forceGenerateImageFromPath() { fGenerateImageFromPath = true; }
269
270private:
271    // never null
272    SkAutoTUnref<SkTypeface> fTypeface;
273
274#ifdef SK_BUILD_FOR_ANDROID
275    SkPaintOptionsAndroid fPaintOptionsAndroid;
276#endif
277
278    // optional object, which may be null
279    SkPathEffect*   fPathEffect;
280    SkMaskFilter*   fMaskFilter;
281    SkRasterizer*   fRasterizer;
282
283    // if this is set, we draw the image from a path, rather than
284    // calling generateImage.
285    bool fGenerateImageFromPath;
286
287    void internalGetPath(const SkGlyph& glyph, SkPath* fillPath,
288                         SkPath* devPath, SkMatrix* fillToDevMatrix);
289
290    // Return the context associated with the next logical typeface, or NULL if
291    // there are no more entries in the fallback chain.
292    SkScalerContext* allocNextContext() const;
293
294    // return the next context, treating fNextContext as a cache of the answer
295    SkScalerContext* getNextContext();
296
297    // returns the right context from our link-list for this glyph. If no match
298    // is found, just returns the original context (this)
299    SkScalerContext* getGlyphContext(const SkGlyph& glyph);
300
301    // returns the right context from our link-list for this char. If no match
302    // is found it returns NULL. If a match is found then the glyphID param is
303    // set to the glyphID that maps to the provided char.
304    SkScalerContext* getContextFromChar(SkUnichar uni, uint16_t* glyphID);
305
306    // link-list of context, to handle missing chars. null-terminated.
307    SkScalerContext* fNextContext;
308
309    // SkMaskGamma::PreBlend converts linear masks to gamma correcting masks.
310protected:
311    // Visible to subclasses so that generateImage can apply the pre-blend directly.
312    const SkMaskGamma::PreBlend fPreBlend;
313private:
314    // When there is a filter, previous steps must create a linear mask
315    // and the pre-blend applied as a final step.
316    const SkMaskGamma::PreBlend fPreBlendForFilter;
317};
318
319#define kRec_SkDescriptorTag            SkSetFourByteTag('s', 'r', 'e', 'c')
320#define kPathEffect_SkDescriptorTag     SkSetFourByteTag('p', 't', 'h', 'e')
321#define kMaskFilter_SkDescriptorTag     SkSetFourByteTag('m', 's', 'k', 'f')
322#define kRasterizer_SkDescriptorTag     SkSetFourByteTag('r', 'a', 's', 't')
323#ifdef SK_BUILD_FOR_ANDROID
324#define kAndroidOpts_SkDescriptorTag    SkSetFourByteTag('a', 'n', 'd', 'r')
325#endif
326
327///////////////////////////////////////////////////////////////////////////////
328
329enum SkAxisAlignment {
330    kNone_SkAxisAlignment,
331    kX_SkAxisAlignment,
332    kY_SkAxisAlignment
333};
334
335/**
336 *  Return the axis (if any) that the baseline for horizontal text will land on
337 *  after running through the specified matrix.
338 *
339 *  As an example, the identity matrix will return kX_SkAxisAlignment
340 */
341SkAxisAlignment SkComputeAxisAlignmentForHText(const SkMatrix& matrix);
342
343///////////////////////////////////////////////////////////////////////////////
344
345SkPaint::Hinting SkScalerContextRec::getHinting() const {
346    unsigned hint = (fFlags & SkScalerContext::kHinting_Mask) >>
347                                            SkScalerContext::kHinting_Shift;
348    return static_cast<SkPaint::Hinting>(hint);
349}
350
351void SkScalerContextRec::setHinting(SkPaint::Hinting hinting) {
352    fFlags = (fFlags & ~SkScalerContext::kHinting_Mask) |
353                                (hinting << SkScalerContext::kHinting_Shift);
354}
355
356
357#endif
358