1 | /* |
2 | * Copyright 2006 The Android Open Source Project |
3 | * |
4 | * Use of this source code is governed by a BSD-style license that can be |
5 | * found in the LICENSE file. |
6 | */ |
7 | |
8 | #ifndef SkTypeface_DEFINED |
9 | #define SkTypeface_DEFINED |
10 | |
11 | #include "include/core/SkFontArguments.h" |
12 | #include "include/core/SkFontParameters.h" |
13 | #include "include/core/SkFontStyle.h" |
14 | #include "include/core/SkFontTypes.h" |
15 | #include "include/core/SkRect.h" |
16 | #include "include/core/SkString.h" |
17 | #include "include/private/SkOnce.h" |
18 | #include "include/private/SkWeakRefCnt.h" |
19 | |
20 | class SkData; |
21 | class SkDescriptor; |
22 | class SkFontData; |
23 | class SkFontDescriptor; |
24 | class SkScalerContext; |
25 | class SkStream; |
26 | class SkStreamAsset; |
27 | class SkWStream; |
28 | struct SkAdvancedTypefaceMetrics; |
29 | struct SkScalerContextEffects; |
30 | struct SkScalerContextRec; |
31 | |
32 | typedef uint32_t SkFontID; |
33 | /** Machine endian. */ |
34 | typedef uint32_t SkFontTableTag; |
35 | |
36 | /** \class SkTypeface |
37 | |
38 | The SkTypeface class specifies the typeface and intrinsic style of a font. |
39 | This is used in the paint, along with optionally algorithmic settings like |
40 | textSize, textSkewX, textScaleX, kFakeBoldText_Mask, to specify |
41 | how text appears when drawn (and measured). |
42 | |
43 | Typeface objects are immutable, and so they can be shared between threads. |
44 | */ |
45 | class SK_API SkTypeface : public SkWeakRefCnt { |
46 | public: |
47 | /** Returns the typeface's intrinsic style attributes. */ |
48 | SkFontStyle fontStyle() const { |
49 | return fStyle; |
50 | } |
51 | |
52 | /** Returns true if style() has the kBold bit set. */ |
53 | bool isBold() const { return fStyle.weight() >= SkFontStyle::kSemiBold_Weight; } |
54 | |
55 | /** Returns true if style() has the kItalic bit set. */ |
56 | bool isItalic() const { return fStyle.slant() != SkFontStyle::kUpright_Slant; } |
57 | |
58 | /** Returns true if the typeface claims to be fixed-pitch. |
59 | * This is a style bit, advance widths may vary even if this returns true. |
60 | */ |
61 | bool isFixedPitch() const { return fIsFixedPitch; } |
62 | |
63 | /** Copy into 'coordinates' (allocated by the caller) the design variation coordinates. |
64 | * |
65 | * @param coordinates the buffer into which to write the design variation coordinates. |
66 | * @param coordinateCount the number of entries available through 'coordinates'. |
67 | * |
68 | * @return The number of axes, or -1 if there is an error. |
69 | * If 'coordinates != nullptr' and 'coordinateCount >= numAxes' then 'coordinates' will be |
70 | * filled with the variation coordinates describing the position of this typeface in design |
71 | * variation space. It is possible the number of axes can be retrieved but actual position |
72 | * cannot. |
73 | */ |
74 | int getVariationDesignPosition(SkFontArguments::VariationPosition::Coordinate coordinates[], |
75 | int coordinateCount) const; |
76 | |
77 | /** Copy into 'parameters' (allocated by the caller) the design variation parameters. |
78 | * |
79 | * @param parameters the buffer into which to write the design variation parameters. |
80 | * @param coordinateCount the number of entries available through 'parameters'. |
81 | * |
82 | * @return The number of axes, or -1 if there is an error. |
83 | * If 'parameters != nullptr' and 'parameterCount >= numAxes' then 'parameters' will be |
84 | * filled with the variation parameters describing the position of this typeface in design |
85 | * variation space. It is possible the number of axes can be retrieved but actual parameters |
86 | * cannot. |
87 | */ |
88 | int getVariationDesignParameters(SkFontParameters::Variation::Axis parameters[], |
89 | int parameterCount) const; |
90 | |
91 | /** Return a 32bit value for this typeface, unique for the underlying font |
92 | data. Will never return 0. |
93 | */ |
94 | SkFontID uniqueID() const { return fUniqueID; } |
95 | |
96 | /** Return the uniqueID for the specified typeface. If the face is null, |
97 | resolve it to the default font and return its uniqueID. Will never |
98 | return 0. |
99 | */ |
100 | static SkFontID UniqueID(const SkTypeface* face); |
101 | |
102 | /** Returns true if the two typefaces reference the same underlying font, |
103 | handling either being null (treating null as the default font) |
104 | */ |
105 | static bool Equal(const SkTypeface* facea, const SkTypeface* faceb); |
106 | |
107 | /** Returns the default normal typeface, which is never nullptr. */ |
108 | static sk_sp<SkTypeface> MakeDefault(); |
109 | |
110 | /** Creates a new reference to the typeface that most closely matches the |
111 | requested familyName and fontStyle. This method allows extended font |
112 | face specifiers as in the SkFontStyle type. Will never return null. |
113 | |
114 | @param familyName May be NULL. The name of the font family. |
115 | @param fontStyle The style of the typeface. |
116 | @return reference to the closest-matching typeface. Call must call |
117 | unref() when they are done. |
118 | */ |
119 | static sk_sp<SkTypeface> MakeFromName(const char familyName[], SkFontStyle fontStyle); |
120 | |
121 | /** Return a new typeface given a file. If the file does not exist, or is |
122 | not a valid font file, returns nullptr. |
123 | */ |
124 | static sk_sp<SkTypeface> MakeFromFile(const char path[], int index = 0); |
125 | |
126 | /** Return a new typeface given a stream. If the stream is |
127 | not a valid font file, returns nullptr. Ownership of the stream is |
128 | transferred, so the caller must not reference it again. |
129 | */ |
130 | static sk_sp<SkTypeface> MakeFromStream(std::unique_ptr<SkStreamAsset> stream, int index = 0); |
131 | |
132 | /** Return a new typeface given a SkData. If the data is null, or is not a valid font file, |
133 | * returns nullptr. |
134 | */ |
135 | static sk_sp<SkTypeface> MakeFromData(sk_sp<SkData>, int index = 0); |
136 | |
137 | /** Return a new typeface given font data and configuration. If the data |
138 | is not valid font data, returns nullptr. |
139 | */ |
140 | static sk_sp<SkTypeface> MakeFromFontData(std::unique_ptr<SkFontData>); |
141 | |
142 | /** Return a new typeface based on this typeface but parameterized as specified in the |
143 | SkFontArguments. If the SkFontArguments does not supply an argument for a parameter |
144 | in the font then the value from this typeface will be used as the value for that |
145 | argument. If the cloned typeface would be exaclty the same as this typeface then |
146 | this typeface may be ref'ed and returned. May return nullptr on failure. |
147 | */ |
148 | sk_sp<SkTypeface> makeClone(const SkFontArguments&) const; |
149 | |
150 | /** |
151 | * A typeface can serialize just a descriptor (names, etc.), or it can also include the |
152 | * actual font data (which can be large). This enum controls how serialize() decides what |
153 | * to serialize. |
154 | */ |
155 | enum class SerializeBehavior { |
156 | kDoIncludeData, |
157 | kDontIncludeData, |
158 | kIncludeDataIfLocal, |
159 | }; |
160 | |
161 | /** Write a unique signature to a stream, sufficient to reconstruct a |
162 | typeface referencing the same font when Deserialize is called. |
163 | */ |
164 | void serialize(SkWStream*, SerializeBehavior = SerializeBehavior::kIncludeDataIfLocal) const; |
165 | |
166 | /** |
167 | * Same as serialize(SkWStream*, ...) but returns the serialized data in SkData, instead of |
168 | * writing it to a stream. |
169 | */ |
170 | sk_sp<SkData> serialize(SerializeBehavior = SerializeBehavior::kIncludeDataIfLocal) const; |
171 | |
172 | /** Given the data previously written by serialize(), return a new instance |
173 | of a typeface referring to the same font. If that font is not available, |
174 | return nullptr. |
175 | Does not affect ownership of SkStream. |
176 | */ |
177 | static sk_sp<SkTypeface> MakeDeserialize(SkStream*); |
178 | |
179 | /** |
180 | * Given an array of UTF32 character codes, return their corresponding glyph IDs. |
181 | * |
182 | * @param chars pointer to the array of UTF32 chars |
183 | * @param number of chars and glyphs |
184 | * @param glyphs returns the corresponding glyph IDs for each character. |
185 | */ |
186 | void unicharsToGlyphs(const SkUnichar uni[], int count, SkGlyphID glyphs[]) const; |
187 | |
188 | /** |
189 | * Return the glyphID that corresponds to the specified unicode code-point |
190 | * (in UTF32 encoding). If the unichar is not supported, returns 0. |
191 | * |
192 | * This is a short-cut for calling unicharsToGlyphs(). |
193 | */ |
194 | SkGlyphID unicharToGlyph(SkUnichar unichar) const; |
195 | |
196 | /** |
197 | * Return the number of glyphs in the typeface. |
198 | */ |
199 | int countGlyphs() const; |
200 | |
201 | // Table getters -- may fail if the underlying font format is not organized |
202 | // as 4-byte tables. |
203 | |
204 | /** Return the number of tables in the font. */ |
205 | int countTables() const; |
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. If tags == NULL, this only returns the count |
210 | * (the same as calling countTables()). |
211 | */ |
212 | int getTableTags(SkFontTableTag tags[]) const; |
213 | |
214 | /** Given a table tag, return the size of its contents, or 0 if not present |
215 | */ |
216 | size_t getTableSize(SkFontTableTag) const; |
217 | |
218 | /** Copy the contents of a table into data (allocated by the caller). Note |
219 | * that the contents of the table will be in their native endian order |
220 | * (which for most truetype tables is big endian). If the table tag is |
221 | * not found, or there is an error copying the data, then 0 is returned. |
222 | * If this happens, it is possible that some or all of the memory pointed |
223 | * to by data may have been written to, even though an error has occured. |
224 | * |
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 | size_t getTableData(SkFontTableTag tag, size_t offset, size_t length, |
238 | void* data) const; |
239 | |
240 | /** |
241 | * Return an immutable copy of the requested font table, or nullptr if that table was |
242 | * not found. This can sometimes be faster than calling getTableData() twice: once to find |
243 | * the length, and then again to copy the data. |
244 | * |
245 | * @param tag The table tag whose contents are to be copied |
246 | * @return an immutable copy of the table's data, or nullptr. |
247 | */ |
248 | sk_sp<SkData> copyTableData(SkFontTableTag tag) const; |
249 | |
250 | /** |
251 | * Return the units-per-em value for this typeface, or zero if there is an |
252 | * error. |
253 | */ |
254 | int getUnitsPerEm() const; |
255 | |
256 | /** |
257 | * Given a run of glyphs, return the associated horizontal adjustments. |
258 | * Adjustments are in "design units", which are integers relative to the |
259 | * typeface's units per em (see getUnitsPerEm). |
260 | * |
261 | * Some typefaces are known to never support kerning. Calling this method |
262 | * with all zeros (e.g. getKerningPairAdustments(NULL, 0, NULL)) returns |
263 | * a boolean indicating if the typeface might support kerning. If it |
264 | * returns false, then it will always return false (no kerning) for all |
265 | * possible glyph runs. If it returns true, then it *may* return true for |
266 | * somne glyph runs. |
267 | * |
268 | * If count is non-zero, then the glyphs parameter must point to at least |
269 | * [count] valid glyph IDs, and the adjustments parameter must be |
270 | * sized to at least [count - 1] entries. If the method returns true, then |
271 | * [count-1] entries in the adjustments array will be set. If the method |
272 | * returns false, then no kerning should be applied, and the adjustments |
273 | * array will be in an undefined state (possibly some values may have been |
274 | * written, but none of them should be interpreted as valid values). |
275 | */ |
276 | bool getKerningPairAdjustments(const SkGlyphID glyphs[], int count, |
277 | int32_t adjustments[]) const; |
278 | |
279 | struct LocalizedString { |
280 | SkString fString; |
281 | SkString fLanguage; |
282 | }; |
283 | class LocalizedStrings { |
284 | public: |
285 | LocalizedStrings() = default; |
286 | virtual ~LocalizedStrings() { } |
287 | virtual bool next(LocalizedString* localizedString) = 0; |
288 | void unref() { delete this; } |
289 | |
290 | private: |
291 | LocalizedStrings(const LocalizedStrings&) = delete; |
292 | LocalizedStrings& operator=(const LocalizedStrings&) = delete; |
293 | }; |
294 | /** |
295 | * Returns an iterator which will attempt to enumerate all of the |
296 | * family names specified by the font. |
297 | * It is the caller's responsibility to unref() the returned pointer. |
298 | */ |
299 | LocalizedStrings* createFamilyNameIterator() const; |
300 | |
301 | /** |
302 | * Return the family name for this typeface. It will always be returned |
303 | * encoded as UTF8, but the language of the name is whatever the host |
304 | * platform chooses. |
305 | */ |
306 | void getFamilyName(SkString* name) const; |
307 | |
308 | /** |
309 | * Return a stream for the contents of the font data, or NULL on failure. |
310 | * If ttcIndex is not null, it is set to the TrueTypeCollection index |
311 | * of this typeface within the stream, or 0 if the stream is not a |
312 | * collection. |
313 | * The caller is responsible for deleting the stream. |
314 | */ |
315 | std::unique_ptr<SkStreamAsset> openStream(int* ttcIndex) const; |
316 | |
317 | /** |
318 | * Return the font data, or nullptr on failure. |
319 | */ |
320 | std::unique_ptr<SkFontData> makeFontData() const; |
321 | |
322 | /** |
323 | * Return a scalercontext for the given descriptor. It may return a |
324 | * dummy scalercontext that will not crash, but will draw nothing. |
325 | */ |
326 | std::unique_ptr<SkScalerContext> createScalerContext(const SkScalerContextEffects&, |
327 | const SkDescriptor*) const; |
328 | |
329 | /** |
330 | * Return a rectangle (scaled to 1-pt) that represents the union of the bounds of all |
331 | * of the glyphs, but each one positioned at (0,). This may be conservatively large, and |
332 | * will not take into account any hinting or other size-specific adjustments. |
333 | */ |
334 | SkRect getBounds() const; |
335 | |
336 | // PRIVATE / EXPERIMENTAL -- do not call |
337 | void filterRec(SkScalerContextRec* rec) const { |
338 | this->onFilterRec(rec); |
339 | } |
340 | // PRIVATE / EXPERIMENTAL -- do not call |
341 | void getFontDescriptor(SkFontDescriptor* desc, bool* isLocal) const { |
342 | this->onGetFontDescriptor(desc, isLocal); |
343 | } |
344 | // PRIVATE / EXPERIMENTAL -- do not call |
345 | void* internal_private_getCTFontRef() const { |
346 | return this->onGetCTFontRef(); |
347 | } |
348 | |
349 | protected: |
350 | /** uniqueID must be unique and non-zero |
351 | */ |
352 | SkTypeface(const SkFontStyle& style, bool isFixedPitch = false); |
353 | virtual ~SkTypeface(); |
354 | |
355 | virtual sk_sp<SkTypeface> onMakeClone(const SkFontArguments&) const = 0; |
356 | |
357 | /** Sets the fixedPitch bit. If used, must be called in the constructor. */ |
358 | void setIsFixedPitch(bool isFixedPitch) { fIsFixedPitch = isFixedPitch; } |
359 | /** Sets the font style. If used, must be called in the constructor. */ |
360 | void setFontStyle(SkFontStyle style) { fStyle = style; } |
361 | |
362 | // Must return a valid scaler context. It can not return nullptr. |
363 | virtual SkScalerContext* onCreateScalerContext(const SkScalerContextEffects&, |
364 | const SkDescriptor*) const = 0; |
365 | virtual void onFilterRec(SkScalerContextRec*) const = 0; |
366 | friend class SkScalerContext; // onFilterRec |
367 | |
368 | // Subclasses *must* override this method to work with the PDF backend. |
369 | virtual std::unique_ptr<SkAdvancedTypefaceMetrics> onGetAdvancedMetrics() const = 0; |
370 | // For type1 postscript fonts only, set the glyph names for each glyph. |
371 | // destination array is non-null, and points to an array of size this->countGlyphs(). |
372 | // Backends that do not suport type1 fonts should not override. |
373 | virtual void getPostScriptGlyphNames(SkString*) const = 0; |
374 | |
375 | // The mapping from glyph to Unicode; array indices are glyph ids. |
376 | // For each glyph, give the default Unicode value, if it exists. |
377 | // dstArray is non-null, and points to an array of size this->countGlyphs(). |
378 | virtual void getGlyphToUnicodeMap(SkUnichar* dstArray) const = 0; |
379 | |
380 | virtual std::unique_ptr<SkStreamAsset> onOpenStream(int* ttcIndex) const = 0; |
381 | // TODO: make pure virtual. |
382 | virtual std::unique_ptr<SkFontData> onMakeFontData() const; |
383 | |
384 | virtual int onGetVariationDesignPosition( |
385 | SkFontArguments::VariationPosition::Coordinate coordinates[], |
386 | int coordinateCount) const = 0; |
387 | |
388 | virtual int onGetVariationDesignParameters( |
389 | SkFontParameters::Variation::Axis parameters[], int parameterCount) const = 0; |
390 | |
391 | virtual void onGetFontDescriptor(SkFontDescriptor*, bool* isLocal) const = 0; |
392 | |
393 | virtual void onCharsToGlyphs(const SkUnichar* chars, int count, SkGlyphID glyphs[]) const = 0; |
394 | virtual int onCountGlyphs() const = 0; |
395 | |
396 | virtual int onGetUPEM() const = 0; |
397 | virtual bool onGetKerningPairAdjustments(const SkGlyphID glyphs[], int count, |
398 | int32_t adjustments[]) const; |
399 | |
400 | /** Returns the family name of the typeface as known by its font manager. |
401 | * This name may or may not be produced by the family name iterator. |
402 | */ |
403 | virtual void onGetFamilyName(SkString* familyName) const = 0; |
404 | |
405 | /** Returns an iterator over the family names in the font. */ |
406 | virtual LocalizedStrings* onCreateFamilyNameIterator() const = 0; |
407 | |
408 | virtual int onGetTableTags(SkFontTableTag tags[]) const = 0; |
409 | virtual size_t onGetTableData(SkFontTableTag, size_t offset, |
410 | size_t length, void* data) const = 0; |
411 | virtual sk_sp<SkData> onCopyTableData(SkFontTableTag) const; |
412 | |
413 | virtual bool onComputeBounds(SkRect*) const; |
414 | |
415 | virtual void* onGetCTFontRef() const { return nullptr; } |
416 | |
417 | private: |
418 | /** Retrieve detailed typeface metrics. Used by the PDF backend. */ |
419 | std::unique_ptr<SkAdvancedTypefaceMetrics> getAdvancedMetrics() const; |
420 | friend class SkRandomTypeface; // getAdvancedMetrics |
421 | friend class SkPDFFont; // getAdvancedMetrics |
422 | |
423 | /** Style specifies the intrinsic style attributes of a given typeface */ |
424 | enum Style { |
425 | kNormal = 0, |
426 | kBold = 0x01, |
427 | kItalic = 0x02, |
428 | |
429 | // helpers |
430 | kBoldItalic = 0x03 |
431 | }; |
432 | static SkFontStyle FromOldStyle(Style oldStyle); |
433 | static SkTypeface* GetDefaultTypeface(Style style = SkTypeface::kNormal); |
434 | |
435 | friend class SkFontPriv; // GetDefaultTypeface |
436 | friend class SkPaintPriv; // GetDefaultTypeface |
437 | friend class SkFont; // getGlyphToUnicodeMap |
438 | |
439 | private: |
440 | SkFontID fUniqueID; |
441 | SkFontStyle fStyle; |
442 | mutable SkRect fBounds; |
443 | mutable SkOnce fBoundsOnce; |
444 | bool fIsFixedPitch; |
445 | |
446 | typedef SkWeakRefCnt INHERITED; |
447 | }; |
448 | #endif |
449 | |