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
20class SkData;
21class SkDescriptor;
22class SkFontData;
23class SkFontDescriptor;
24class SkScalerContext;
25class SkStream;
26class SkStreamAsset;
27class SkWStream;
28struct SkAdvancedTypefaceMetrics;
29struct SkScalerContextEffects;
30struct SkScalerContextRec;
31
32typedef uint32_t SkFontID;
33/** Machine endian. */
34typedef 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*/
45class SK_API SkTypeface : public SkWeakRefCnt {
46public:
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
349protected:
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
417private:
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
439private:
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