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 based on this typeface but parameterized as specified in the
138 SkFontArguments. If the SkFontArguments does not supply an argument for a parameter
139 in the font then the value from this typeface will be used as the value for that
140 argument. If the cloned typeface would be exaclty the same as this typeface then
141 this typeface may be ref'ed and returned. May return nullptr on failure.
142 */
143 sk_sp<SkTypeface> makeClone(const SkFontArguments&) const;
144
145 /**
146 * A typeface can serialize just a descriptor (names, etc.), or it can also include the
147 * actual font data (which can be large). This enum controls how serialize() decides what
148 * to serialize.
149 */
150 enum class SerializeBehavior {
151 kDoIncludeData,
152 kDontIncludeData,
153 kIncludeDataIfLocal,
154 };
155
156 /** Write a unique signature to a stream, sufficient to reconstruct a
157 typeface referencing the same font when Deserialize is called.
158 */
159 void serialize(SkWStream*, SerializeBehavior = SerializeBehavior::kIncludeDataIfLocal) const;
160
161 /**
162 * Same as serialize(SkWStream*, ...) but returns the serialized data in SkData, instead of
163 * writing it to a stream.
164 */
165 sk_sp<SkData> serialize(SerializeBehavior = SerializeBehavior::kIncludeDataIfLocal) const;
166
167 /** Given the data previously written by serialize(), return a new instance
168 of a typeface referring to the same font. If that font is not available,
169 return nullptr.
170 Does not affect ownership of SkStream.
171 */
172 static sk_sp<SkTypeface> MakeDeserialize(SkStream*);
173
174 /**
175 * Given an array of UTF32 character codes, return their corresponding glyph IDs.
176 *
177 * @param chars pointer to the array of UTF32 chars
178 * @param number of chars and glyphs
179 * @param glyphs returns the corresponding glyph IDs for each character.
180 */
181 void unicharsToGlyphs(const SkUnichar uni[], int count, SkGlyphID glyphs[]) const;
182
183 /**
184 * Return the glyphID that corresponds to the specified unicode code-point
185 * (in UTF32 encoding). If the unichar is not supported, returns 0.
186 *
187 * This is a short-cut for calling unicharsToGlyphs().
188 */
189 SkGlyphID unicharToGlyph(SkUnichar unichar) const;
190
191 /**
192 * Return the number of glyphs in the typeface.
193 */
194 int countGlyphs() const;
195
196 // Table getters -- may fail if the underlying font format is not organized
197 // as 4-byte tables.
198
199 /** Return the number of tables in the font. */
200 int countTables() const;
201
202 /** Copy into tags[] (allocated by the caller) the list of table tags in
203 * the font, and return the number. This will be the same as CountTables()
204 * or 0 if an error occured. If tags == NULL, this only returns the count
205 * (the same as calling countTables()).
206 */
207 int getTableTags(SkFontTableTag tags[]) const;
208
209 /** Given a table tag, return the size of its contents, or 0 if not present
210 */
211 size_t getTableSize(SkFontTableTag) const;
212
213 /** Copy the contents of a table into data (allocated by the caller). Note
214 * that the contents of the table will be in their native endian order
215 * (which for most truetype tables is big endian). If the table tag is
216 * not found, or there is an error copying the data, then 0 is returned.
217 * If this happens, it is possible that some or all of the memory pointed
218 * to by data may have been written to, even though an error has occured.
219 *
220 * @param tag The table tag whose contents are to be copied
221 * @param offset The offset in bytes into the table's contents where the
222 * copy should start from.
223 * @param length The number of bytes, starting at offset, of table data
224 * to copy.
225 * @param data storage address where the table contents are copied to
226 * @return the number of bytes actually copied into data. If offset+length
227 * exceeds the table's size, then only the bytes up to the table's
228 * size are actually copied, and this is the value returned. If
229 * offset > the table's size, or tag is not a valid table,
230 * then 0 is returned.
231 */
232 size_t getTableData(SkFontTableTag tag, size_t offset, size_t length,
233 void* data) const;
234
235 /**
236 * Return an immutable copy of the requested font table, or nullptr if that table was
237 * not found. This can sometimes be faster than calling getTableData() twice: once to find
238 * the length, and then again to copy the data.
239 *
240 * @param tag The table tag whose contents are to be copied
241 * @return an immutable copy of the table's data, or nullptr.
242 */
243 sk_sp<SkData> copyTableData(SkFontTableTag tag) const;
244
245 /**
246 * Return the units-per-em value for this typeface, or zero if there is an
247 * error.
248 */
249 int getUnitsPerEm() const;
250
251 /**
252 * Given a run of glyphs, return the associated horizontal adjustments.
253 * Adjustments are in "design units", which are integers relative to the
254 * typeface's units per em (see getUnitsPerEm).
255 *
256 * Some typefaces are known to never support kerning. Calling this method
257 * with all zeros (e.g. getKerningPairAdustments(NULL, 0, NULL)) returns
258 * a boolean indicating if the typeface might support kerning. If it
259 * returns false, then it will always return false (no kerning) for all
260 * possible glyph runs. If it returns true, then it *may* return true for
261 * somne glyph runs.
262 *
263 * If count is non-zero, then the glyphs parameter must point to at least
264 * [count] valid glyph IDs, and the adjustments parameter must be
265 * sized to at least [count - 1] entries. If the method returns true, then
266 * [count-1] entries in the adjustments array will be set. If the method
267 * returns false, then no kerning should be applied, and the adjustments
268 * array will be in an undefined state (possibly some values may have been
269 * written, but none of them should be interpreted as valid values).
270 */
271 bool getKerningPairAdjustments(const SkGlyphID glyphs[], int count,
272 int32_t adjustments[]) const;
273
274 struct LocalizedString {
275 SkString fString;
276 SkString fLanguage;
277 };
278 class LocalizedStrings {
279 public:
280 LocalizedStrings() = default;
281 virtual ~LocalizedStrings() { }
282 virtual bool next(LocalizedString* localizedString) = 0;
283 void unref() { delete this; }
284
285 private:
286 LocalizedStrings(const LocalizedStrings&) = delete;
287 LocalizedStrings& operator=(const LocalizedStrings&) = delete;
288 };
289 /**
290 * Returns an iterator which will attempt to enumerate all of the
291 * family names specified by the font.
292 * It is the caller's responsibility to unref() the returned pointer.
293 */
294 LocalizedStrings* createFamilyNameIterator() const;
295
296 /**
297 * Return the family name for this typeface. It will always be returned
298 * encoded as UTF8, but the language of the name is whatever the host
299 * platform chooses.
300 */
301 void getFamilyName(SkString* name) const;
302
303 /**
304 * Return a stream for the contents of the font data, or NULL on failure.
305 * If ttcIndex is not null, it is set to the TrueTypeCollection index
306 * of this typeface within the stream, or 0 if the stream is not a
307 * collection.
308 * The caller is responsible for deleting the stream.
309 */
310 std::unique_ptr<SkStreamAsset> openStream(int* ttcIndex) const;
311
312 /**
313 * Return a scalercontext for the given descriptor. It may return a
314 * stub scalercontext that will not crash, but will draw nothing.
315 */
316 std::unique_ptr<SkScalerContext> createScalerContext(const SkScalerContextEffects&,
317 const SkDescriptor*) const;
318
319 /**
320 * Return a rectangle (scaled to 1-pt) that represents the union of the bounds of all
321 * of the glyphs, but each one positioned at (0,). This may be conservatively large, and
322 * will not take into account any hinting or other size-specific adjustments.
323 */
324 SkRect getBounds() const;
325
326 // PRIVATE / EXPERIMENTAL -- do not call
327 void filterRec(SkScalerContextRec* rec) const {
328 this->onFilterRec(rec);
329 }
330 // PRIVATE / EXPERIMENTAL -- do not call
331 void getFontDescriptor(SkFontDescriptor* desc, bool* isLocal) const {
332 this->onGetFontDescriptor(desc, isLocal);
333 }
334 // PRIVATE / EXPERIMENTAL -- do not call
335 void* internal_private_getCTFontRef() const {
336 return this->onGetCTFontRef();
337 }
338
339protected:
340 /** uniqueID must be unique and non-zero
341 */
342 SkTypeface(const SkFontStyle& style, bool isFixedPitch = false);
343 ~SkTypeface() override;
344
345 virtual sk_sp<SkTypeface> onMakeClone(const SkFontArguments&) const = 0;
346
347 /** Sets the fixedPitch bit. If used, must be called in the constructor. */
348 void setIsFixedPitch(bool isFixedPitch) { fIsFixedPitch = isFixedPitch; }
349 /** Sets the font style. If used, must be called in the constructor. */
350 void setFontStyle(SkFontStyle style) { fStyle = style; }
351
352 // Must return a valid scaler context. It can not return nullptr.
353 virtual SkScalerContext* onCreateScalerContext(const SkScalerContextEffects&,
354 const SkDescriptor*) const = 0;
355 virtual void onFilterRec(SkScalerContextRec*) const = 0;
356 friend class SkScalerContext; // onFilterRec
357
358 // Subclasses *must* override this method to work with the PDF backend.
359 virtual std::unique_ptr<SkAdvancedTypefaceMetrics> onGetAdvancedMetrics() const = 0;
360 // For type1 postscript fonts only, set the glyph names for each glyph.
361 // destination array is non-null, and points to an array of size this->countGlyphs().
362 // Backends that do not suport type1 fonts should not override.
363 virtual void getPostScriptGlyphNames(SkString*) const = 0;
364
365 // The mapping from glyph to Unicode; array indices are glyph ids.
366 // For each glyph, give the default Unicode value, if it exists.
367 // dstArray is non-null, and points to an array of size this->countGlyphs().
368 virtual void getGlyphToUnicodeMap(SkUnichar* dstArray) const = 0;
369
370 virtual std::unique_ptr<SkStreamAsset> onOpenStream(int* ttcIndex) const = 0;
371
372 virtual int onGetVariationDesignPosition(
373 SkFontArguments::VariationPosition::Coordinate coordinates[],
374 int coordinateCount) const = 0;
375
376 virtual int onGetVariationDesignParameters(
377 SkFontParameters::Variation::Axis parameters[], int parameterCount) const = 0;
378
379 virtual void onGetFontDescriptor(SkFontDescriptor*, bool* isLocal) const = 0;
380
381 virtual void onCharsToGlyphs(const SkUnichar* chars, int count, SkGlyphID glyphs[]) const = 0;
382 virtual int onCountGlyphs() const = 0;
383
384 virtual int onGetUPEM() const = 0;
385 virtual bool onGetKerningPairAdjustments(const SkGlyphID glyphs[], int count,
386 int32_t adjustments[]) const;
387
388 /** Returns the family name of the typeface as known by its font manager.
389 * This name may or may not be produced by the family name iterator.
390 */
391 virtual void onGetFamilyName(SkString* familyName) const = 0;
392
393 /** Returns an iterator over the family names in the font. */
394 virtual LocalizedStrings* onCreateFamilyNameIterator() const = 0;
395
396 virtual int onGetTableTags(SkFontTableTag tags[]) const = 0;
397 virtual size_t onGetTableData(SkFontTableTag, size_t offset,
398 size_t length, void* data) const = 0;
399 virtual sk_sp<SkData> onCopyTableData(SkFontTableTag) const;
400
401 virtual bool onComputeBounds(SkRect*) const;
402
403 virtual void* onGetCTFontRef() const { return nullptr; }
404
405private:
406 /** Retrieve detailed typeface metrics. Used by the PDF backend. */
407 std::unique_ptr<SkAdvancedTypefaceMetrics> getAdvancedMetrics() const;
408 friend class SkRandomTypeface; // getAdvancedMetrics
409 friend class SkPDFFont; // getAdvancedMetrics
410
411 /** Style specifies the intrinsic style attributes of a given typeface */
412 enum Style {
413 kNormal = 0,
414 kBold = 0x01,
415 kItalic = 0x02,
416
417 // helpers
418 kBoldItalic = 0x03
419 };
420 static SkFontStyle FromOldStyle(Style oldStyle);
421 static SkTypeface* GetDefaultTypeface(Style style = SkTypeface::kNormal);
422
423 friend class SkFontPriv; // GetDefaultTypeface
424 friend class SkPaintPriv; // GetDefaultTypeface
425 friend class SkFont; // getGlyphToUnicodeMap
426
427private:
428 SkFontID fUniqueID;
429 SkFontStyle fStyle;
430 mutable SkRect fBounds;
431 mutable SkOnce fBoundsOnce;
432 bool fIsFixedPitch;
433
434 typedef SkWeakRefCnt INHERITED;
435};
436#endif
437