1
2/*
3 * Copyright 2006 The Android Open Source Project
4 *
5 * Use of this source code is governed by a BSD-style license that can be
6 * found in the LICENSE file.
7 */
8
9
10#ifndef SkTypeface_DEFINED
11#define SkTypeface_DEFINED
12
13#include "SkAdvancedTypefaceMetrics.h"
14#include "SkWeakRefCnt.h"
15
16class SkDescriptor;
17class SkFontDescriptor;
18class SkScalerContext;
19struct SkScalerContextRec;
20class SkStream;
21class SkAdvancedTypefaceMetrics;
22class SkWStream;
23
24typedef uint32_t SkFontID;
25/** Machine endian. */
26typedef uint32_t SkFontTableTag;
27
28/** \class SkTypeface
29
30    The SkTypeface class specifies the typeface and intrinsic style of a font.
31    This is used in the paint, along with optionally algorithmic settings like
32    textSize, textSkewX, textScaleX, kFakeBoldText_Mask, to specify
33    how text appears when drawn (and measured).
34
35    Typeface objects are immutable, and so they can be shared between threads.
36*/
37class SK_API SkTypeface : public SkWeakRefCnt {
38public:
39    SK_DECLARE_INST_COUNT(SkTypeface)
40
41    /** Style specifies the intrinsic style attributes of a given typeface
42    */
43    enum Style {
44        kNormal = 0,
45        kBold   = 0x01,
46        kItalic = 0x02,
47
48        // helpers
49        kBoldItalic = 0x03
50    };
51
52    /** Returns the typeface's intrinsic style attributes
53    */
54    Style style() const { return fStyle; }
55
56    /** Returns true if getStyle() has the kBold bit set.
57    */
58    bool isBold() const { return (fStyle & kBold) != 0; }
59
60    /** Returns true if getStyle() has the kItalic bit set.
61    */
62    bool isItalic() const { return (fStyle & kItalic) != 0; }
63
64    /** Returns true if the typeface claims to be fixed-pitch.
65     *  This is a style bit, advance widths may vary even if this returns true.
66     */
67    bool isFixedPitch() const { return fIsFixedPitch; }
68
69    /** Return a 32bit value for this typeface, unique for the underlying font
70        data. Will never return 0.
71     */
72    SkFontID uniqueID() const { return fUniqueID; }
73
74    /** Return the uniqueID for the specified typeface. If the face is null,
75        resolve it to the default font and return its uniqueID. Will never
76        return 0.
77    */
78    static SkFontID UniqueID(const SkTypeface* face);
79
80    /** Returns true if the two typefaces reference the same underlying font,
81        handling either being null (treating null as the default font)
82     */
83    static bool Equal(const SkTypeface* facea, const SkTypeface* faceb);
84
85    /**
86     *  Returns a ref() to the default typeface. The caller must call unref()
87     *  when they are done referencing the object. Never returns NULL.
88     */
89    static SkTypeface* RefDefault(Style style = SkTypeface::kNormal);
90
91    /** Return a new reference to the typeface that most closely matches the
92        requested familyName and style. Pass null as the familyName to return
93        the default font for the requested style. Will never return null
94
95        @param familyName  May be NULL. The name of the font family.
96        @param style       The style (normal, bold, italic) of the typeface.
97        @return reference to the closest-matching typeface. Call must call
98                unref() when they are done.
99    */
100    static SkTypeface* CreateFromName(const char familyName[], Style style);
101
102    /** Return a new reference to the typeface that most closely matches the
103        requested typeface and specified Style. Use this call if you want to
104        pick a new style from the same family of the existing typeface.
105        If family is NULL, this selects from the default font's family.
106
107        @param family  May be NULL. The name of the existing type face.
108        @param s       The style (normal, bold, italic) of the type face.
109        @return reference to the closest-matching typeface. Call must call
110                unref() when they are done.
111    */
112    static SkTypeface* CreateFromTypeface(const SkTypeface* family, Style s);
113
114    /** Return a new typeface given a file. If the file does not exist, or is
115        not a valid font file, returns null.
116    */
117    static SkTypeface* CreateFromFile(const char path[], int index = 0);
118
119    /** Return a new typeface given a stream. If the stream is
120        not a valid font file, returns null. Ownership of the stream is
121        transferred, so the caller must not reference it again.
122    */
123    static SkTypeface* CreateFromStream(SkStream* stream, int index = 0);
124
125    /** Write a unique signature to a stream, sufficient to reconstruct a
126        typeface referencing the same font when Deserialize is called.
127     */
128    void serialize(SkWStream*) const;
129
130    /** Given the data previously written by serialize(), return a new instance
131        to a typeface referring to the same font. If that font is not available,
132        return null. If an instance is returned, the caller is responsible for
133        calling unref() when they are done with it.
134     */
135    static SkTypeface* Deserialize(SkStream*);
136
137    enum Encoding {
138        kUTF8_Encoding,
139        kUTF16_Encoding,
140        kUTF32_Encoding
141    };
142
143    /**
144     *  Given an array of character codes, of the specified encoding,
145     *  optionally return their corresponding glyph IDs (if glyphs is not NULL).
146     *
147     *  @param chars pointer to the array of character codes
148     *  @param encoding how the characters are encoded
149     *  @param glyphs (optional) returns the corresponding glyph IDs for each
150     *          character code, up to glyphCount values. If a character code is
151     *          not found in the typeface, the corresponding glyph ID will be 0.
152     *  @param glyphCount number of code points in 'chars' to process. If glyphs
153     *          is not NULL, then it must point sufficient memory to write
154     *          glyphCount values into it.
155     *  @return the number of number of continuous non-zero glyph IDs computed
156     *          from the beginning of chars. This value is valid, even if the
157     *          glyphs parameter is NULL.
158     */
159    int charsToGlyphs(const void* chars, Encoding encoding, uint16_t glyphs[],
160                      int glyphCount) const;
161
162    /**
163     *  Return the number of glyphs in the typeface.
164     */
165    int countGlyphs() const;
166
167    // Table getters -- may fail if the underlying font format is not organized
168    // as 4-byte tables.
169
170    /** Return the number of tables in the font. */
171    int countTables() const;
172
173    /** Copy into tags[] (allocated by the caller) the list of table tags in
174     *  the font, and return the number. This will be the same as CountTables()
175     *  or 0 if an error occured. If tags == NULL, this only returns the count
176     *  (the same as calling countTables()).
177     */
178    int getTableTags(SkFontTableTag tags[]) const;
179
180    /** Given a table tag, return the size of its contents, or 0 if not present
181     */
182    size_t getTableSize(SkFontTableTag) const;
183
184    /** Copy the contents of a table into data (allocated by the caller). Note
185     *  that the contents of the table will be in their native endian order
186     *  (which for most truetype tables is big endian). If the table tag is
187     *  not found, or there is an error copying the data, then 0 is returned.
188     *  If this happens, it is possible that some or all of the memory pointed
189     *  to by data may have been written to, even though an error has occured.
190     *
191     *  @param fontID the font to copy the table from
192     *  @param tag  The table tag whose contents are to be copied
193     *  @param offset The offset in bytes into the table's contents where the
194     *  copy should start from.
195     *  @param length The number of bytes, starting at offset, of table data
196     *  to copy.
197     *  @param data storage address where the table contents are copied to
198     *  @return the number of bytes actually copied into data. If offset+length
199     *  exceeds the table's size, then only the bytes up to the table's
200     *  size are actually copied, and this is the value returned. If
201     *  offset > the table's size, or tag is not a valid table,
202     *  then 0 is returned.
203     */
204    size_t getTableData(SkFontTableTag tag, size_t offset, size_t length,
205                        void* data) const;
206
207    /**
208     *  Return the units-per-em value for this typeface, or zero if there is an
209     *  error.
210     */
211    int getUnitsPerEm() const;
212
213    /**
214     *  Given a run of glyphs, return the associated horizontal adjustments.
215     *  Adjustments are in "design units", which are integers relative to the
216     *  typeface's units per em (see getUnitsPerEm).
217     *
218     *  Some typefaces are known to never support kerning. Calling this method
219     *  with all zeros (e.g. getKerningPairAdustments(NULL, 0, NULL)) returns
220     *  a boolean indicating if the typeface might support kerning. If it
221     *  returns false, then it will always return false (no kerning) for all
222     *  possible glyph runs. If it returns true, then it *may* return true for
223     *  somne glyph runs.
224     *
225     *  If count is non-zero, then the glyphs parameter must point to at least
226     *  [count] valid glyph IDs, and the adjustments parameter must be
227     *  sized to at least [count - 1] entries. If the method returns true, then
228     *  [count-1] entries in the adjustments array will be set. If the method
229     *  returns false, then no kerning should be applied, and the adjustments
230     *  array will be in an undefined state (possibly some values may have been
231     *  written, but none of them should be interpreted as valid values).
232     */
233    bool getKerningPairAdjustments(const uint16_t glyphs[], int count,
234                                   int32_t adjustments[]) const;
235
236    struct LocalizedString {
237        SkString fString;
238        SkString fLanguage;
239    };
240    class LocalizedStrings : ::SkNoncopyable {
241    public:
242        virtual ~LocalizedStrings() { }
243        virtual bool next(LocalizedString* localizedString) = 0;
244        void unref() { SkDELETE(this); }
245    };
246    /**
247     *  Returns an iterator which will attempt to enumerate all of the
248     *  family names specified by the font.
249     *  It is the caller's responsibility to unref() the returned pointer.
250     */
251    LocalizedStrings* createFamilyNameIterator() const;
252
253    /**
254     *  Return the family name for this typeface. It will always be returned
255     *  encoded as UTF8, but the language of the name is whatever the host
256     *  platform chooses.
257     */
258    void getFamilyName(SkString* name) const;
259
260    /**
261     *  Return a stream for the contents of the font data, or NULL on failure.
262     *  If ttcIndex is not null, it is set to the TrueTypeCollection index
263     *  of this typeface within the stream, or 0 if the stream is not a
264     *  collection.
265     */
266    SkStream* openStream(int* ttcIndex) const;
267
268    /**
269     *  Return a scalercontext for the given descriptor. If this fails, then
270     *  if allowFailure is true, this returns NULL, else it returns a
271     *  dummy scalercontext that will not crash, but will draw nothing.
272     */
273    SkScalerContext* createScalerContext(const SkDescriptor*,
274                                         bool allowFailure = false) const;
275
276    // PRIVATE / EXPERIMENTAL -- do not call
277    void filterRec(SkScalerContextRec* rec) const {
278        this->onFilterRec(rec);
279    }
280    // PRIVATE / EXPERIMENTAL -- do not call
281    void getFontDescriptor(SkFontDescriptor* desc, bool* isLocal) const {
282        this->onGetFontDescriptor(desc, isLocal);
283    }
284
285protected:
286    /** uniqueID must be unique and non-zero
287    */
288    SkTypeface(Style style, SkFontID uniqueID, bool isFixedPitch = false);
289    virtual ~SkTypeface();
290
291    /** Sets the fixedPitch bit. If used, must be called in the constructor. */
292    void setIsFixedPitch(bool isFixedPitch) { fIsFixedPitch = isFixedPitch; }
293
294    friend class SkScalerContext;
295    static SkTypeface* GetDefaultTypeface(Style style = SkTypeface::kNormal);
296
297    virtual SkScalerContext* onCreateScalerContext(const SkDescriptor*) const = 0;
298    virtual void onFilterRec(SkScalerContextRec*) const = 0;
299    virtual SkAdvancedTypefaceMetrics* onGetAdvancedTypefaceMetrics(
300                        SkAdvancedTypefaceMetrics::PerGlyphInfo perGlyphInfo,
301                        const uint32_t* glyphIDs,
302                        uint32_t glyphIDsCount) const = 0;
303
304    virtual SkStream* onOpenStream(int* ttcIndex) const = 0;
305    virtual void onGetFontDescriptor(SkFontDescriptor*, bool* isLocal) const = 0;
306
307    virtual int onCharsToGlyphs(const void* chars, Encoding, uint16_t glyphs[],
308                                int glyphCount) const = 0;
309    virtual int onCountGlyphs() const = 0;
310
311    virtual int onGetUPEM() const = 0;
312    virtual bool onGetKerningPairAdjustments(const uint16_t glyphs[], int count,
313                                             int32_t adjustments[]) const;
314
315    /** Returns the family name of the typeface as known by its font manager.
316     *  This name may or may not be produced by the family name iterator.
317     */
318    virtual void onGetFamilyName(SkString* familyName) const = 0;
319
320    /** Returns an iterator over the family names in the font. */
321    virtual LocalizedStrings* onCreateFamilyNameIterator() const = 0;
322
323    virtual int onGetTableTags(SkFontTableTag tags[]) const = 0;
324    virtual size_t onGetTableData(SkFontTableTag, size_t offset,
325                                  size_t length, void* data) const = 0;
326
327private:
328    friend class SkGTypeface;
329    friend class SkPDFFont;
330    friend class SkPDFCIDFont;
331    friend class GrPathRendering;
332    friend class GrGLPathRendering;
333
334    /** Retrieve detailed typeface metrics.  Used by the PDF backend.
335     @param perGlyphInfo Indicate what glyph specific information (advances,
336     names, etc.) should be populated.
337     @param glyphIDs  For per-glyph info, specify subset of the font by
338     giving glyph ids.  Each integer represents a glyph
339     id.  Passing NULL means all glyphs in the font.
340     @param glyphIDsCount Number of elements in subsetGlyphIds. Ignored if
341     glyphIDs is NULL.
342     @return The returned object has already been referenced.
343     */
344    SkAdvancedTypefaceMetrics* getAdvancedTypefaceMetrics(
345                          SkAdvancedTypefaceMetrics::PerGlyphInfo perGlyphInfo,
346                          const uint32_t* glyphIDs = NULL,
347                          uint32_t glyphIDsCount = 0) const;
348
349private:
350    static SkTypeface* CreateDefault(int style);  // SkLazyPtr requires an int, not a Style.
351    static void        DeleteDefault(SkTypeface*);
352
353    SkFontID    fUniqueID;
354    Style       fStyle;
355    bool        fIsFixedPitch;
356
357    friend class SkPaint;
358    friend class SkGlyphCache;  // GetDefaultTypeface
359    // just so deprecated fonthost can call protected methods
360    friend class SkFontHost;
361
362    typedef SkWeakRefCnt INHERITED;
363};
364
365#endif
366