src/third_party/skia/include/core/SkTypeface.h

   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
  16 class SkDescriptor;
  17 class SkFontDescriptor;
  18 class SkScalerContext;
  19 struct SkScalerContextRec;
  20 class SkStream;
  21 class SkAdvancedTypefaceMetrics;
  22 class SkWStream;
  23
  24 typedef uint32_t SkFontID;
  25 /** Machine endian. */
  26 typedef 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 */
  37 class SK_API SkTypeface : public SkWeakRefCnt {
  38 public:
  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[]);
 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);
 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
 285 protected:
 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     virtual LocalizedStrings* onCreateFamilyNameIterator() const = 0;
 316
 317     virtual int onGetTableTags(SkFontTableTag tags[]) const = 0;
 318     virtual size_t onGetTableData(SkFontTableTag, size_t offset,
 319                                   size_t length, void* data) const = 0;
 320
 321 private:
 322     friend class SkGTypeface;
 323     friend class SkPDFFont;
 324     friend class SkPDFCIDFont;
 325
 326     /** Retrieve detailed typeface metrics.  Used by the PDF backend.
 327      @param perGlyphInfo Indicate what glyph specific information (advances,
 328      names, etc.) should be populated.
 329      @param glyphIDs  For per-glyph info, specify subset of the font by
 330      giving glyph ids.  Each integer represents a glyph
 331      id.  Passing NULL means all glyphs in the font.
 332      @param glyphIDsCount Number of elements in subsetGlyphIds. Ignored if
 333      glyphIDs is NULL.
 334      @return The returned object has already been referenced.
 335      */
 336     SkAdvancedTypefaceMetrics* getAdvancedTypefaceMetrics(
 337                           SkAdvancedTypefaceMetrics::PerGlyphInfo perGlyphInfo,
 338                           const uint32_t* glyphIDs = NULL,
 339                           uint32_t glyphIDsCount = 0) const;
 340
 341 private:
 342     static void create_default_typeface(Style style);
 343
 344     SkFontID    fUniqueID;
 345     Style       fStyle;
 346     bool        fIsFixedPitch;
 347
 348     friend class SkPaint;
 349     friend class SkGlyphCache;  // GetDefaultTypeface
 350     // just so deprecated fonthost can call protected methods
 351     friend class SkFontHost;
 352
 353     typedef SkWeakRefCnt INHERITED;
 354 };
 355
 356 #endif