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