SkFontHost.h revision 77407ca019ca1bb98dd65f940be825d38719e983
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 SkFontHost_DEFINED 11#define SkFontHost_DEFINED 12 13#include "SkScalerContext.h" 14#include "SkTypeface.h" 15 16class SkDescriptor; 17class SkStream; 18class SkWStream; 19 20typedef uint32_t SkFontTableTag; 21 22/** \class SkFontHost 23 24 This class is ported to each environment. It is responsible for bridging 25 the gap between the (sort of) abstract class SkTypeface and the 26 platform-specific implementation that provides access to font files. 27 28 One basic task is for each create (subclass of) SkTypeface, the FontHost is 29 resonsible for assigning a uniqueID. The ID should be unique for the 30 underlying font file/data, not unique per typeface instance. Thus it is 31 possible/common to request a typeface for the same font more than once 32 (e.g. asking for the same font by name several times). The FontHost may 33 return seperate typeface instances in that case, or it may choose to use a 34 cache and return the same instance (but calling typeface->ref(), since the 35 caller is always responsible for calling unref() on each instance that is 36 returned). Either way, the fontID for those instance(s) will be the same. 37 In addition, the fontID should never be set to 0. That value is used as a 38 sentinel to indicate no-font-id. 39 40 The major aspects are: 41 1) Given either a name/style, return a subclass of SkTypeface that 42 references the closest matching font available on the host system. 43 2) Given the data for a font (either in a stream or a file name), return 44 a typeface that allows access to that data. 45 3) Each typeface instance carries a 32bit ID for its corresponding font. 46 SkFontHost turns that ID into a stream to access the font's data. 47 4) Given a font ID, return a subclass of SkScalerContext, which connects a 48 font scaler (e.g. freetype or other) to the font's data. 49 5) Utilites to manage the font cache (budgeting) and gamma correction 50*/ 51class SK_API SkFontHost { 52public: 53 /** Return a new, closest matching typeface given either an existing family 54 (specified by a typeface in that family) or by a familyName and a 55 requested style, or by a set of Unicode codepoitns to cover in a given 56 style. 57 1) If familyFace is null, use familyName. 58 2) If familyName is null, use data (UTF-16 to cover). 59 3) If all are null, return the default font that best matches style 60 */ 61 static SkTypeface* CreateTypeface(const SkTypeface* familyFace, 62 const char familyName[], 63 const void* data, size_t bytelength, 64 SkTypeface::Style style); 65 66 /** Return a new typeface given the data buffer. If the data does not 67 represent a valid font, returns null. 68 69 If a typeface instance is returned, the caller is responsible for 70 calling unref() on the typeface when they are finished with it. 71 72 The returned typeface may or may not have called ref() on the stream 73 parameter. If the typeface has not called ref(), then it may have made 74 a copy of the releveant data. In either case, the caller is still 75 responsible for its refcnt ownership of the stream. 76 */ 77 static SkTypeface* CreateTypefaceFromStream(SkStream*); 78 79 /** Return a new typeface from the specified file path. If the file does not 80 represent a valid font, this returns null. If a typeface is returned, 81 the caller is responsible for calling unref() when it is no longer used. 82 */ 83 static SkTypeface* CreateTypefaceFromFile(const char path[]); 84 85 /////////////////////////////////////////////////////////////////////////// 86 87 /** Returns true if the specified unique ID matches an existing font. 88 Returning false is similar to calling OpenStream with an invalid ID, 89 which will return NULL in that case. 90 */ 91 static bool ValidFontID(SkFontID uniqueID); 92 93 /** Return a new stream to read the font data, or null if the uniqueID does 94 not match an existing typeface. .The caller must call stream->unref() 95 when it is finished reading the data. 96 */ 97 static SkStream* OpenStream(SkFontID uniqueID); 98 99 /** Some fonts are stored in files. If that is true for the fontID, then 100 this returns the byte length of the full file path. If path is not null, 101 then the full path is copied into path (allocated by the caller), up to 102 length bytes. If index is not null, then it is set to the truetype 103 collection index for this font, or 0 if the font is not in a collection. 104 105 Note: GetFileName does not assume that path is a null-terminated string, 106 so when it succeeds, it only copies the bytes of the file name and 107 nothing else (i.e. it copies exactly the number of bytes returned by the 108 function. If the caller wants to treat path[] as a C string, it must be 109 sure that it is allocated at least 1 byte larger than the returned size, 110 and it must copy in the terminating 0. 111 112 If the fontID does not correspond to a file, then the function returns 113 0, and the path and index parameters are ignored. 114 115 @param fontID The font whose file name is being queried 116 @param path Either NULL, or storage for receiving up to length bytes 117 of the font's file name. Allocated by the caller. 118 @param length The maximum space allocated in path (by the caller). 119 Ignored if path is NULL. 120 @param index Either NULL, or receives the TTC index for this font. 121 If the font is not a TTC, then will be set to 0. 122 @return The byte length of th font's file name, or 0 if the font is not 123 baked by a file. 124 */ 125 static size_t GetFileName(SkFontID fontID, char path[], size_t length, 126 int32_t* index); 127 128 /////////////////////////////////////////////////////////////////////////// 129 130 /** Write a unique identifier to the stream, so that the same typeface can 131 be retrieved with Deserialize(). 132 */ 133 static void Serialize(const SkTypeface*, SkWStream*); 134 135 /** Given a stream created by Serialize(), return a new typeface (like 136 CreateTypeface) or return NULL if no match is found. 137 */ 138 static SkTypeface* Deserialize(SkStream*); 139 140 /////////////////////////////////////////////////////////////////////////// 141 142 /** Return a subclass of SkScalarContext 143 */ 144 static SkScalerContext* CreateScalerContext(const SkDescriptor* desc); 145 146 /** 147 * Given a "current" fontID, return the next logical fontID to use 148 * when searching fonts for a given unicode value. Typically the caller 149 * will query a given font, and if a unicode value is not supported, they 150 * will call this, and if 0 is not returned, will search that font, and so 151 * on. This process must be finite, and when the fonthost sees a 152 * font with no logical successor, it must return 0. 153 * 154 * The original fontID is also provided. This is the initial font that was 155 * stored in the typeface of the caller. It is provided as an aid to choose 156 * the best next logical font. e.g. If the original font was bold or serif, 157 * but the 2nd in the logical chain was plain, then a subsequent call to 158 * get the 3rd can still inspect the original, and try to match its 159 * stylistic attributes. 160 */ 161 static SkFontID NextLogicalFont(SkFontID currFontID, SkFontID origFontID); 162 163 /////////////////////////////////////////////////////////////////////////// 164 165 /** Given a filled-out rec, the fonthost may decide to modify it to reflect 166 what the host is actually capable of fulfilling. For example, if the 167 rec is requesting a level of hinting that, for this host, maps some 168 other level (e.g. kFull -> kNormal), it should update the rec to reflect 169 what will actually be done. This is an optimization so that the font 170 cache does not contain different recs (i.e. keys) that in reality map to 171 the same output. 172 173 A lazy (but valid) fonthost can do nothing in its FilterRec routine. 174 */ 175 static void FilterRec(SkScalerContext::Rec* rec); 176 177 /////////////////////////////////////////////////////////////////////////// 178 179 /** Retrieve detailed typeface metrics. Used by the PDF backend. 180 @param perGlyphInfo Indicate what glyph specific information (advances, 181 names, etc.) should be populated. 182 @return The returned object has already been referenced. NULL is 183 returned if the font is not found. 184 @param glyphIDs For per-glyph info, specify subset of the font by 185 giving glyph ids. Each integer represents a glyph 186 id. Passing NULL means all glyphs in the font. 187 @param glyphIDsCount Number of elements in subsetGlyphIds. Ignored if 188 glyphIDs is NULL. 189 */ 190 static SkAdvancedTypefaceMetrics* GetAdvancedTypefaceMetrics( 191 SkFontID fontID, 192 SkAdvancedTypefaceMetrics::PerGlyphInfo perGlyphInfo, 193 const uint32_t* glyphIDs, 194 uint32_t glyphIDsCount); 195 196 /** Return the number of tables in the font 197 */ 198 static int CountTables(SkFontID); 199 200 /** Copy into tags[] (allocated by the caller) the list of table tags in 201 the font, and return the number. This will be the same as CountTables() 202 or 0 if an error occured. 203 */ 204 static int GetTableTags(SkFontID, SkFontTableTag[]); 205 206 /** Given a table tag, return the size of its contents, or 0 if not present 207 */ 208 static size_t GetTableSize(SkFontID, SkFontTableTag); 209 210 /** Copy the contents of a table into data (allocated by the caller). Note 211 that the contents of the table will be in their native endian order 212 (which for most truetype tables is big endian). If the table tag is 213 not found, or there is an error copying the data, then 0 is returned. 214 If this happens, it is possible that some or all of the memory pointed 215 to by data may have been written to, even though an error has occured. 216 217 @param fontID the font to copy the table from 218 @param tag The table tag whose contents are to be copied 219 @param offset The offset in bytes into the table's contents where the 220 copy should start from. 221 @param length The number of bytes, starting at offset, of table data 222 to copy. 223 @param data storage address where the table contents are copied to 224 @return the number of bytes actually copied into data. If offset+length 225 exceeds the table's size, then only the bytes up to the table's 226 size are actually copied, and this is the value returned. If 227 offset > the table's size, or tag is not a valid table, 228 then 0 is returned. 229 */ 230 static size_t GetTableData(SkFontID fontID, SkFontTableTag tag, 231 size_t offset, size_t length, void* data); 232 233 /////////////////////////////////////////////////////////////////////////// 234 235 /** Return SkScalerContext gamma flag, or 0, based on the paint that will be 236 used to draw something with antialiasing. 237 */ 238 static int ComputeGammaFlag(const SkPaint& paint); 239 240 /** Return NULL or a pointer to 256 bytes for the black (table[0]) and 241 white (table[1]) gamma tables. 242 */ 243 static void GetGammaTables(const uint8_t* tables[2]); 244 245 /////////////////////////////////////////////////////////////////////////// 246 247 /** LCDs either have their color elements arranged horizontally or 248 vertically. When rendering subpixel glyphs we need to know which way 249 round they are. 250 251 Note, if you change this after startup, you'll need to flush the glyph 252 cache because it'll have the wrong type of masks cached. 253 */ 254 enum LCDOrientation { 255 kHorizontal_LCDOrientation = 0, //!< this is the default 256 kVertical_LCDOrientation = 1, 257 }; 258 259 static void SetSubpixelOrientation(LCDOrientation orientation); 260 static LCDOrientation GetSubpixelOrientation(); 261 262 /** LCD color elements can vary in order. For subpixel text we need to know 263 the order which the LCDs uses so that the color fringes are in the 264 correct place. 265 266 Note, if you change this after startup, you'll need to flush the glyph 267 cache because it'll have the wrong type of masks cached. 268 269 kNONE_LCDOrder means that the subpixel elements are not spatially 270 separated in any usable fashion. 271 */ 272 enum LCDOrder { 273 kRGB_LCDOrder = 0, //!< this is the default 274 kBGR_LCDOrder = 1, 275 kNONE_LCDOrder = 2, 276 }; 277 278 static void SetSubpixelOrder(LCDOrder order); 279 static LCDOrder GetSubpixelOrder(); 280 281#ifdef ANDROID 282 /////////////////////////////////////////////////////////////////////////// 283 284 /** 285 * Return the number of font units per em. 286 * 287 * @param fontID the font to query. 288 * @return the number of font units per em or 0 on error. 289 */ 290 static uint32_t GetUnitsPerEm(SkFontID fontID); 291#endif 292}; 293 294#endif 295