SkFont.h 20 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518
  1. /*
  2. * Copyright 2014 Google Inc.
  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. #ifndef SkFont_DEFINED
  8. #define SkFont_DEFINED
  9. #include "include/core/SkFontTypes.h"
  10. #include "include/core/SkScalar.h"
  11. #include "include/core/SkTypeface.h"
  12. class SkMatrix;
  13. class SkPaint;
  14. class SkPath;
  15. struct SkFontMetrics;
  16. /** \class SkFont
  17. SkFont controls options applied when drawing and measuring text.
  18. */
  19. class SK_API SkFont {
  20. public:
  21. /** Whether edge pixels draw opaque or with partial transparency.
  22. */
  23. enum class Edging {
  24. kAlias, //!< no transparent pixels on glyph edges
  25. kAntiAlias, //!< may have transparent pixels on glyph edges
  26. kSubpixelAntiAlias, //!< glyph positioned in pixel using transparency
  27. };
  28. /** Constructs SkFont with default values.
  29. @return default initialized SkFont
  30. */
  31. SkFont();
  32. /** Constructs SkFont with default values with SkTypeface and size in points.
  33. @param typeface font and style used to draw and measure text
  34. @param size typographic height of text
  35. @return initialized SkFont
  36. */
  37. SkFont(sk_sp<SkTypeface> typeface, SkScalar size);
  38. /** Constructs SkFont with default values with SkTypeface.
  39. @param typeface font and style used to draw and measure text
  40. @return initialized SkFont
  41. */
  42. explicit SkFont(sk_sp<SkTypeface> typeface);
  43. /** Constructs SkFont with default values with SkTypeface and size in points,
  44. horizontal scale, and horizontal skew. Horizontal scale emulates condensed
  45. and expanded fonts. Horizontal skew emulates oblique fonts.
  46. @param typeface font and style used to draw and measure text
  47. @param size typographic height of text
  48. @param scaleX text horizontal scale
  49. @param skewX additional shear on x-axis relative to y-axis
  50. @return initialized SkFont
  51. */
  52. SkFont(sk_sp<SkTypeface> typeface, SkScalar size, SkScalar scaleX, SkScalar skewX);
  53. /** Compares SkFont and font, and returns true if they are equivalent.
  54. May return false if SkTypeface has identical contents but different pointers.
  55. @param font font to compare
  56. @return true if SkFont pair are equivalent
  57. */
  58. bool operator==(const SkFont& font) const;
  59. /** Compares SkFont and font, and returns true if they are not equivalent.
  60. May return true if SkTypeface has identical contents but different pointers.
  61. @param font font to compare
  62. @return true if SkFont pair are not equivalent
  63. */
  64. bool operator!=(const SkFont& font) const { return !(*this == font); }
  65. /** If true, instructs the font manager to always hint glyphs.
  66. Returned value is only meaningful if platform uses FreeType as the font manager.
  67. @return true if all glyphs are hinted
  68. */
  69. bool isForceAutoHinting() const { return SkToBool(fFlags & kForceAutoHinting_PrivFlag); }
  70. /** Returns true if font engine may return glyphs from font bitmaps instead of from outlines.
  71. @return true if glyphs may be font bitmaps
  72. */
  73. bool isEmbeddedBitmaps() const { return SkToBool(fFlags & kEmbeddedBitmaps_PrivFlag); }
  74. /** Returns true if glyphs may be drawn at sub-pixel offsets.
  75. @return true if glyphs may be drawn at sub-pixel offsets.
  76. */
  77. bool isSubpixel() const { return SkToBool(fFlags & kSubpixel_PrivFlag); }
  78. /** Returns true if font and glyph metrics are requested to be linearly scalable.
  79. @return true if font and glyph metrics are requested to be linearly scalable.
  80. */
  81. bool isLinearMetrics() const { return SkToBool(fFlags & kLinearMetrics_PrivFlag); }
  82. /** Returns true if bold is approximated by increasing the stroke width when creating glyph
  83. bitmaps from outlines.
  84. @return bold is approximated through stroke width
  85. */
  86. bool isEmbolden() const { return SkToBool(fFlags & kEmbolden_PrivFlag); }
  87. /** Sets whether to always hint glyphs.
  88. If forceAutoHinting is set, instructs the font manager to always hint glyphs.
  89. Only affects platforms that use FreeType as the font manager.
  90. @param forceAutoHinting setting to always hint glyphs
  91. */
  92. void setForceAutoHinting(bool forceAutoHinting);
  93. /** Requests, but does not require, to use bitmaps in fonts instead of outlines.
  94. @param embeddedBitmaps setting to use bitmaps in fonts
  95. */
  96. void setEmbeddedBitmaps(bool embeddedBitmaps);
  97. /** Requests, but does not require, that glyphs respect sub-pixel positioning.
  98. @param subpixel setting for sub-pixel positioning
  99. */
  100. void setSubpixel(bool subpixel);
  101. /** Requests, but does not require, linearly scalable font and glyph metrics.
  102. For outline fonts 'true' means font and glyph metrics should ignore hinting and rounding.
  103. Note that some bitmap formats may not be able to scale linearly and will ignore this flag.
  104. @param linearMetrics setting for linearly scalable font and glyph metrics.
  105. */
  106. void setLinearMetrics(bool linearMetrics);
  107. /** Increases stroke width when creating glyph bitmaps to approximate a bold typeface.
  108. @param embolden setting for bold approximation
  109. */
  110. void setEmbolden(bool embolden);
  111. /** Whether edge pixels draw opaque or with partial transparency.
  112. @return one of: Edging::kAlias, Edging::kAntiAlias, Edging::kSubpixelAntiAlias
  113. */
  114. Edging getEdging() const { return (Edging)fEdging; }
  115. /** Requests, but does not require, that edge pixels draw opaque or with
  116. partial transparency.
  117. @param edging one of: Edging::kAlias, Edging::kAntiAlias, Edging::kSubpixelAntiAlias
  118. */
  119. void setEdging(Edging edging);
  120. /** Sets level of glyph outline adjustment.
  121. Does not check for valid values of hintingLevel.
  122. @param hintingLevel one of: SkFontHinting::kNone, SkFontHinting::kSlight,
  123. SkFontHinting::kNormal, SkFontHinting::kFull
  124. */
  125. void setHinting(SkFontHinting hintingLevel);
  126. /** Returns level of glyph outline adjustment.
  127. @return one of: SkFontHinting::kNone, SkFontHinting::kSlight, SkFontHinting::kNormal,
  128. SkFontHinting::kFull
  129. */
  130. SkFontHinting getHinting() const { return (SkFontHinting)fHinting; }
  131. /** Returns a font with the same attributes of this font, but with the specified size.
  132. Returns nullptr if size is less than zero, infinite, or NaN.
  133. @param size typographic height of text
  134. @return initialized SkFont
  135. */
  136. SkFont makeWithSize(SkScalar size) const;
  137. /** Returns SkTypeface if set, or nullptr.
  138. Does not alter SkTypeface SkRefCnt.
  139. @return SkTypeface if previously set, nullptr otherwise
  140. */
  141. SkTypeface* getTypeface() const {return fTypeface.get(); }
  142. /** Returns SkTypeface if set, or the default typeface.
  143. Does not alter SkTypeface SkRefCnt.
  144. @return SkTypeface if previously set or, a pointer to the default typeface if not
  145. previously set.
  146. */
  147. SkTypeface* getTypefaceOrDefault() const;
  148. /** Returns text size in points.
  149. @return typographic height of text
  150. */
  151. SkScalar getSize() const { return fSize; }
  152. /** Returns text scale on x-axis.
  153. Default value is 1.
  154. @return text horizontal scale
  155. */
  156. SkScalar getScaleX() const { return fScaleX; }
  157. /** Returns text skew on x-axis.
  158. Default value is zero.
  159. @return additional shear on x-axis relative to y-axis
  160. */
  161. SkScalar getSkewX() const { return fSkewX; }
  162. /** Increases SkTypeface SkRefCnt by one.
  163. @return SkTypeface if previously set, nullptr otherwise
  164. */
  165. sk_sp<SkTypeface> refTypeface() const { return fTypeface; }
  166. /** Increases SkTypeface SkRefCnt by one.
  167. @return SkTypeface if previously set or, a pointer to the default typeface if not
  168. previously set.
  169. */
  170. sk_sp<SkTypeface> refTypefaceOrDefault() const;
  171. /** Sets SkTypeface to typeface, decreasing SkRefCnt of the previous SkTypeface.
  172. Pass nullptr to clear SkTypeface and use the default typeface. Increments
  173. tf SkRefCnt by one.
  174. @param tf font and style used to draw text
  175. */
  176. void setTypeface(sk_sp<SkTypeface> tf) { fTypeface = tf; }
  177. /** Sets text size in points.
  178. Has no effect if textSize is not greater than or equal to zero.
  179. @param textSize typographic height of text
  180. */
  181. void setSize(SkScalar textSize);
  182. /** Sets text scale on x-axis.
  183. Default value is 1.
  184. @param scaleX text horizontal scale
  185. */
  186. void setScaleX(SkScalar scaleX);
  187. /** Sets text skew on x-axis.
  188. Default value is zero.
  189. @param skewX additional shear on x-axis relative to y-axis
  190. */
  191. void setSkewX(SkScalar skewX);
  192. /** Converts text into glyph indices.
  193. Returns the number of glyph indices represented by text.
  194. SkTextEncoding specifies how text represents characters or glyphs.
  195. glyphs may be nullptr, to compute the glyph count.
  196. Does not check text for valid character codes or valid glyph indices.
  197. If byteLength equals zero, returns zero.
  198. If byteLength includes a partial character, the partial character is ignored.
  199. If encoding is SkTextEncoding::kUTF8 and text contains an invalid UTF-8 sequence,
  200. zero is returned.
  201. When encoding is SkTextEncoding::kUTF8, SkTextEncoding::kUTF16, or
  202. SkTextEncoding::kUTF32; then each Unicode codepoint is mapped to a
  203. single glyph. This function uses the default character-to-glyph
  204. mapping from the SkTypeface and maps characters not found in the
  205. SkTypeface to zero.
  206. If maxGlyphCount is not sufficient to store all the glyphs, no glyphs are copied.
  207. The total glyph count is returned for subsequent buffer reallocation.
  208. @param text character storage encoded with SkTextEncoding
  209. @param byteLength length of character storage in bytes
  210. @param encoding one of: SkTextEncoding::kUTF8, SkTextEncoding::kUTF16,
  211. SkTextEncoding::kUTF32, SkTextEncoding::kGlyphID
  212. @param glyphs storage for glyph indices; may be nullptr
  213. @param maxGlyphCount storage capacity
  214. @return number of glyphs represented by text of length byteLength
  215. */
  216. int textToGlyphs(const void* text, size_t byteLength, SkTextEncoding encoding,
  217. SkGlyphID glyphs[], int maxGlyphCount) const;
  218. /** Returns glyph index for Unicode character.
  219. If the character is not supported by the SkTypeface, returns 0.
  220. @param uni Unicode character
  221. @return glyph index
  222. */
  223. SkGlyphID unicharToGlyph(SkUnichar uni) const;
  224. void unicharsToGlyphs(const SkUnichar uni[], int count, SkGlyphID glyphs[]) const;
  225. /** Returns number of glyphs represented by text.
  226. If encoding is SkTextEncoding::kUTF8, SkTextEncoding::kUTF16, or
  227. SkTextEncoding::kUTF32; then each Unicode codepoint is mapped to a
  228. single glyph.
  229. @param text character storage encoded with SkTextEncoding
  230. @param byteLength length of character storage in bytes
  231. @param encoding one of: SkTextEncoding::kUTF8, SkTextEncoding::kUTF16,
  232. SkTextEncoding::kUTF32, SkTextEncoding::kGlyphID
  233. @return number of glyphs represented by text of length byteLength
  234. */
  235. int countText(const void* text, size_t byteLength, SkTextEncoding encoding) const {
  236. return this->textToGlyphs(text, byteLength, encoding, nullptr, 0);
  237. }
  238. /** Returns the advance width of text.
  239. The advance is the normal distance to move before drawing additional text.
  240. Returns the bounding box of text if bounds is not nullptr.
  241. @param text character storage encoded with SkTextEncoding
  242. @param byteLength length of character storage in bytes
  243. @param encoding one of: SkTextEncoding::kUTF8, SkTextEncoding::kUTF16,
  244. SkTextEncoding::kUTF32, SkTextEncoding::kGlyphID
  245. @param bounds returns bounding box relative to (0, 0) if not nullptr
  246. @return number of glyphs represented by text of length byteLength
  247. */
  248. SkScalar measureText(const void* text, size_t byteLength, SkTextEncoding encoding,
  249. SkRect* bounds = nullptr) const {
  250. return this->measureText(text, byteLength, encoding, bounds, nullptr);
  251. }
  252. /** Returns the advance width of text.
  253. The advance is the normal distance to move before drawing additional text.
  254. Returns the bounding box of text if bounds is not nullptr. paint
  255. stroke width or SkPathEffect may modify the advance with.
  256. @param text character storage encoded with SkTextEncoding
  257. @param byteLength length of character storage in bytes
  258. @param encoding one of: SkTextEncoding::kUTF8, SkTextEncoding::kUTF16,
  259. SkTextEncoding::kUTF32, SkTextEncoding::kGlyphID
  260. @param bounds returns bounding box relative to (0, 0) if not nullptr
  261. @param paint optional; may be nullptr
  262. @return number of glyphs represented by text of length byteLength
  263. */
  264. SkScalar measureText(const void* text, size_t byteLength, SkTextEncoding encoding,
  265. SkRect* bounds, const SkPaint* paint) const;
  266. /** DEPRECATED
  267. Retrieves the advance and bounds for each glyph in glyphs.
  268. Both widths and bounds may be nullptr.
  269. If widths is not nullptr, widths must be an array of count entries.
  270. if bounds is not nullptr, bounds must be an array of count entries.
  271. @param glyphs array of glyph indices to be measured
  272. @param count number of glyphs
  273. @param widths returns text advances for each glyph; may be nullptr
  274. @param bounds returns bounds for each glyph relative to (0, 0); may be nullptr
  275. */
  276. void getWidths(const SkGlyphID glyphs[], int count, SkScalar widths[], SkRect bounds[]) const {
  277. this->getWidthsBounds(glyphs, count, widths, bounds, nullptr);
  278. }
  279. // DEPRECATED
  280. void getWidths(const SkGlyphID glyphs[], int count, SkScalar widths[], std::nullptr_t) const {
  281. this->getWidths(glyphs, count, widths);
  282. }
  283. /** Retrieves the advance and bounds for each glyph in glyphs.
  284. Both widths and bounds may be nullptr.
  285. If widths is not nullptr, widths must be an array of count entries.
  286. if bounds is not nullptr, bounds must be an array of count entries.
  287. @param glyphs array of glyph indices to be measured
  288. @param count number of glyphs
  289. @param widths returns text advances for each glyph
  290. */
  291. void getWidths(const SkGlyphID glyphs[], int count, SkScalar widths[]) const {
  292. this->getWidthsBounds(glyphs, count, widths, nullptr, nullptr);
  293. }
  294. /** Retrieves the advance and bounds for each glyph in glyphs.
  295. Both widths and bounds may be nullptr.
  296. If widths is not nullptr, widths must be an array of count entries.
  297. if bounds is not nullptr, bounds must be an array of count entries.
  298. @param glyphs array of glyph indices to be measured
  299. @param count number of glyphs
  300. @param widths returns text advances for each glyph; may be nullptr
  301. @param bounds returns bounds for each glyph relative to (0, 0); may be nullptr
  302. @param paint optional, specifies stroking, SkPathEffect and SkMaskFilter
  303. */
  304. void getWidthsBounds(const SkGlyphID glyphs[], int count, SkScalar widths[], SkRect bounds[],
  305. const SkPaint* paint) const;
  306. /** Retrieves the bounds for each glyph in glyphs.
  307. bounds must be an array of count entries.
  308. If paint is not nullptr, its stroking, SkPathEffect, and SkMaskFilter fields are respected.
  309. @param glyphs array of glyph indices to be measured
  310. @param count number of glyphs
  311. @param bounds returns bounds for each glyph relative to (0, 0); may be nullptr
  312. @param paint optional, specifies stroking, SkPathEffect, and SkMaskFilter
  313. */
  314. void getBounds(const SkGlyphID glyphs[], int count, SkRect bounds[],
  315. const SkPaint* paint) const {
  316. this->getWidthsBounds(glyphs, count, nullptr, bounds, paint);
  317. }
  318. /** Retrieves the positions for each glyph, beginning at the specified origin. The caller
  319. must allocated at least count number of elements in the pos[] array.
  320. @param glyphs array of glyph indices to be positioned
  321. @param count number of glyphs
  322. @param pos returns glyphs positions
  323. @param origin location of the first glyph. Defaults to {0, 0}.
  324. */
  325. void getPos(const SkGlyphID glyphs[], int count, SkPoint pos[], SkPoint origin = {0, 0}) const;
  326. /** Retrieves the x-positions for each glyph, beginning at the specified origin. The caller
  327. must allocated at least count number of elements in the xpos[] array.
  328. @param glyphs array of glyph indices to be positioned
  329. @param count number of glyphs
  330. @param xpos returns glyphs x-positions
  331. @param origin x-position of the first glyph. Defaults to 0.
  332. */
  333. void getXPos(const SkGlyphID glyphs[], int count, SkScalar xpos[], SkScalar origin = 0) const;
  334. /** Returns path corresponding to glyph outline.
  335. If glyph has an outline, copies outline to path and returns true.
  336. path returned may be empty.
  337. If glyph is described by a bitmap, returns false and ignores path parameter.
  338. @param glyphID index of glyph
  339. @param path pointer to existing SkPath
  340. @return true if glyphID is described by path
  341. */
  342. bool getPath(SkGlyphID glyphID, SkPath* path) const;
  343. /** Returns path corresponding to glyph array.
  344. @param glyphIDs array of glyph indices
  345. @param count number of glyphs
  346. @param glyphPathProc function returning one glyph description as path
  347. @param ctx function context
  348. */
  349. void getPaths(const SkGlyphID glyphIDs[], int count,
  350. void (*glyphPathProc)(const SkPath* pathOrNull, const SkMatrix& mx, void* ctx),
  351. void* ctx) const;
  352. /** Returns SkFontMetrics associated with SkTypeface.
  353. The return value is the recommended spacing between lines: the sum of metrics
  354. descent, ascent, and leading.
  355. If metrics is not nullptr, SkFontMetrics is copied to metrics.
  356. Results are scaled by text size but does not take into account
  357. dimensions required by text scale, text skew, fake bold,
  358. style stroke, and SkPathEffect.
  359. @param metrics storage for SkFontMetrics; may be nullptr
  360. @return recommended spacing between lines
  361. */
  362. SkScalar getMetrics(SkFontMetrics* metrics) const;
  363. /** Returns the recommended spacing between lines: the sum of metrics
  364. descent, ascent, and leading.
  365. Result is scaled by text size but does not take into account
  366. dimensions required by stroking and SkPathEffect.
  367. Returns the same result as getMetrics().
  368. @return recommended spacing between lines
  369. */
  370. SkScalar getSpacing() const { return this->getMetrics(nullptr); }
  371. /** Dumps fields of the font to SkDebugf. May change its output over time, so clients should
  372. * not rely on this for anything specific. Used to aid in debugging.
  373. */
  374. void dump() const;
  375. private:
  376. enum PrivFlags {
  377. kForceAutoHinting_PrivFlag = 1 << 0,
  378. kEmbeddedBitmaps_PrivFlag = 1 << 1,
  379. kSubpixel_PrivFlag = 1 << 2,
  380. kLinearMetrics_PrivFlag = 1 << 3,
  381. kEmbolden_PrivFlag = 1 << 4,
  382. };
  383. static constexpr unsigned kAllFlags = 0x1F;
  384. sk_sp<SkTypeface> fTypeface;
  385. SkScalar fSize;
  386. SkScalar fScaleX;
  387. SkScalar fSkewX;
  388. uint8_t fFlags;
  389. uint8_t fEdging;
  390. uint8_t fHinting;
  391. SkScalar setupForAsPaths(SkPaint*);
  392. bool hasSomeAntiAliasing() const;
  393. friend class GrTextBlob;
  394. friend class SkFontPriv;
  395. friend class SkGlyphRunListPainter;
  396. friend class SkTextBlobCacheDiffCanvas;
  397. friend class SkStrikeSpec;
  398. };
  399. #endif