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