ftglyph.h 32 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517
  1. /***************************************************************************/
  2. /* */
  3. /* ftglyph.h */
  4. /* */
  5. /* FreeType convenience functions to handle glyphs (specification). */
  6. /* */
  7. /* Copyright 1996-2001 by */
  8. /* David Turner, Robert Wilhelm, and Werner Lemberg. */
  9. /* */
  10. /* This file is part of the FreeType project, and may only be used, */
  11. /* modified, and distributed under the terms of the FreeType project */
  12. /* license, LICENSE.TXT. By continuing to use, modify, or distribute */
  13. /* this file you indicate that you have read the license and */
  14. /* understand and accept it fully. */
  15. /* */
  16. /***************************************************************************/
  17. /*************************************************************************/
  18. /* */
  19. /* This file contains the definition of several convenience functions */
  20. /* that can be used by client applications to easily retrieve glyph */
  21. /* bitmaps and outlines from a given face. */
  22. /* */
  23. /* These functions should be optional if you are writing a font server */
  24. /* or text layout engine on top of FreeType. However, they are pretty */
  25. /* handy for many other simple uses of the library. */
  26. /* */
  27. /*************************************************************************/
  28. #ifndef __FTGLYPH_H__
  29. #define __FTGLYPH_H__
  30. #include <ft2build.h>
  31. #include FT_FREETYPE_H
  32. FT_BEGIN_HEADER
  33. /*************************************************************************/
  34. /* */
  35. /* <Section> */
  36. /* glyph_management */
  37. /* */
  38. /* <Title> */
  39. /* Glyph Management */
  40. /* */
  41. /* <Abstract> */
  42. /* Generic interface to manage individual glyph data. */
  43. /* */
  44. /* <Description> */
  45. /* This section contains definitions used to manage glyph data */
  46. /* through generic FT_Glyph objects. Each of them can contain a */
  47. /* bitmap, a vector outline, or even images in other formats. */
  48. /* */
  49. /*************************************************************************/
  50. /* forward declaration to a private type */
  51. typedef struct FT_Glyph_Class_ FT_Glyph_Class;
  52. /*************************************************************************/
  53. /* */
  54. /* <Type> */
  55. /* FT_Glyph */
  56. /* */
  57. /* <Description> */
  58. /* Handle to an object used to model generic glyph images. It is a */
  59. /* pointer to the @FT_GlyphRec structure and can contain a glyph */
  60. /* bitmap or pointer. */
  61. /* */
  62. /* <Note> */
  63. /* Glyph objects are not owned by the library. You must thus release */
  64. /* them manually (through @FT_Done_Glyph) _before_ calling */
  65. /* @FT_Done_FreeType. */
  66. /* */
  67. typedef struct FT_GlyphRec_* FT_Glyph;
  68. /*************************************************************************/
  69. /* */
  70. /* <Struct> */
  71. /* FT_GlyphRec */
  72. /* */
  73. /* <Description> */
  74. /* The root glyph structure contains a given glyph image plus its */
  75. /* advance width in 16.16 fixed float format. */
  76. /* */
  77. /* <Fields> */
  78. /* library :: A handle to the FreeType library object. */
  79. /* */
  80. /* clazz :: A pointer to the glyph's class. Private. */
  81. /* */
  82. /* format :: The format of the glyph's image. */
  83. /* */
  84. /* advance :: A 16.16 vector that gives the glyph's advance width. */
  85. /* */
  86. typedef struct FT_GlyphRec_
  87. {
  88. FT_Library library;
  89. const FT_Glyph_Class* clazz;
  90. FT_Glyph_Format format;
  91. FT_Vector advance;
  92. } FT_GlyphRec;
  93. /*************************************************************************/
  94. /* */
  95. /* <Type> */
  96. /* FT_BitmapGlyph */
  97. /* */
  98. /* <Description> */
  99. /* A handle to an object used to model a bitmap glyph image. This is */
  100. /* a sub-class of @FT_Glyph, and a pointer to @FT_BitmapGlyphRec. */
  101. /* */
  102. typedef struct FT_BitmapGlyphRec_* FT_BitmapGlyph;
  103. /*************************************************************************/
  104. /* */
  105. /* <Struct> */
  106. /* FT_BitmapGlyphRec */
  107. /* */
  108. /* <Description> */
  109. /* A structure used for bitmap glyph images. This really is a */
  110. /* `sub-class' of `FT_GlyphRec'. */
  111. /* */
  112. /* <Fields> */
  113. /* root :: The root FT_Glyph fields. */
  114. /* */
  115. /* left :: The left-side bearing, i.e., the horizontal distance */
  116. /* from the current pen position to the left border of the */
  117. /* glyph bitmap. */
  118. /* */
  119. /* top :: The top-side bearing, i.e., the vertical distance from */
  120. /* the current pen position to the top border of the glyph */
  121. /* bitmap. This distance is positive for upwards-y! */
  122. /* */
  123. /* bitmap :: A descriptor for the bitmap. */
  124. /* */
  125. /* <Note> */
  126. /* You can typecast FT_Glyph to FT_BitmapGlyph if you have */
  127. /* glyph->format == FT_GLYPH_FORMAT_BITMAP. This lets you access */
  128. /* the bitmap's contents easily. */
  129. /* */
  130. /* The corresponding pixel buffer is always owned by the BitmapGlyph */
  131. /* and is thus created and destroyed with it. */
  132. /* */
  133. typedef struct FT_BitmapGlyphRec_
  134. {
  135. FT_GlyphRec root;
  136. FT_Int left;
  137. FT_Int top;
  138. FT_Bitmap bitmap;
  139. } FT_BitmapGlyphRec;
  140. /*************************************************************************/
  141. /* */
  142. /* <Type> */
  143. /* FT_OutlineGlyph */
  144. /* */
  145. /* <Description> */
  146. /* A handle to an object used to model an outline glyph image. This */
  147. /* is a sub-class of @FT_Glyph, and a pointer to @FT_OutlineGlyphRec. */
  148. /* */
  149. typedef struct FT_OutlineGlyphRec_* FT_OutlineGlyph;
  150. /*************************************************************************/
  151. /* */
  152. /* <Struct> */
  153. /* FT_OutlineGlyphRec */
  154. /* */
  155. /* <Description> */
  156. /* A structure used for outline (vectorial) glyph images. This */
  157. /* really is a `sub-class' of `FT_GlyphRec'. */
  158. /* */
  159. /* <Fields> */
  160. /* root :: The root FT_Glyph fields. */
  161. /* */
  162. /* outline :: A descriptor for the outline. */
  163. /* */
  164. /* <Note> */
  165. /* You can typecast FT_Glyph to FT_OutlineGlyph if you have */
  166. /* glyph->format == FT_GLYPH_FORMAT_OUTLINE. This lets you access */
  167. /* the outline's content easily. */
  168. /* */
  169. /* As the outline is extracted from a glyph slot, its coordinates are */
  170. /* expressed normally in 26.6 pixels, unless the flag */
  171. /* FT_LOAD_NO_SCALE was used in FT_Load_Glyph() or FT_Load_Char(). */
  172. /* */
  173. /* The outline's tables are always owned by the object and are */
  174. /* destroyed with it. */
  175. /* */
  176. typedef struct FT_OutlineGlyphRec_
  177. {
  178. FT_GlyphRec root;
  179. FT_Outline outline;
  180. } FT_OutlineGlyphRec;
  181. /*************************************************************************/
  182. /* */
  183. /* <Function> */
  184. /* FT_Get_Glyph */
  185. /* */
  186. /* <Description> */
  187. /* A function used to extract a glyph image from a slot. */
  188. /* */
  189. /* <Input> */
  190. /* slot :: A handle to the source glyph slot. */
  191. /* */
  192. /* <Output> */
  193. /* aglyph :: A handle to the glyph object. */
  194. /* */
  195. /* <Return> */
  196. /* FreeType error code. 0 means success. */
  197. /* */
  198. FT_EXPORT( FT_Error )
  199. FT_Get_Glyph( FT_GlyphSlot slot,
  200. FT_Glyph *aglyph );
  201. /*************************************************************************/
  202. /* */
  203. /* <Function> */
  204. /* FT_Glyph_Copy */
  205. /* */
  206. /* <Description> */
  207. /* A function used to copy a glyph image. */
  208. /* */
  209. /* <Input> */
  210. /* source :: A handle to the source glyph object. */
  211. /* */
  212. /* <Output> */
  213. /* target :: A handle to the target glyph object. 0 in case of */
  214. /* error. */
  215. /* */
  216. /* <Return> */
  217. /* FreeType error code. 0 means success. */
  218. /* */
  219. FT_EXPORT( FT_Error )
  220. FT_Glyph_Copy( FT_Glyph source,
  221. FT_Glyph *target );
  222. /*************************************************************************/
  223. /* */
  224. /* <Function> */
  225. /* FT_Glyph_Transform */
  226. /* */
  227. /* <Description> */
  228. /* Transforms a glyph image if its format is scalable. */
  229. /* */
  230. /* <InOut> */
  231. /* glyph :: A handle to the target glyph object. */
  232. /* */
  233. /* <Input> */
  234. /* matrix :: A pointer to a 2x2 matrix to apply. */
  235. /* */
  236. /* delta :: A pointer to a 2d vector to apply. Coordinates are */
  237. /* expressed in 1/64th of a pixel. */
  238. /* */
  239. /* <Return> */
  240. /* FreeType error code (the glyph format is not scalable if it is */
  241. /* not zero). */
  242. /* */
  243. /* <Note> */
  244. /* The 2x2 transformation matrix is also applied to the glyph's */
  245. /* advance vector. */
  246. /* */
  247. FT_EXPORT( FT_Error )
  248. FT_Glyph_Transform( FT_Glyph glyph,
  249. FT_Matrix* matrix,
  250. FT_Vector* delta );
  251. /* */
  252. /*************************************************************************/
  253. /* */
  254. /* <Function> */
  255. /* FT_Glyph_Get_CBox */
  256. /* */
  257. /* <Description> */
  258. /* Returns a glyph's `control box'. The control box encloses all the */
  259. /* outline's points, including Bezier control points. Though it */
  260. /* coincides with the exact bounding box for most glyphs, it can be */
  261. /* slightly larger in some situations (like when rotating an outline */
  262. /* which contains Bezier outside arcs). */
  263. /* */
  264. /* Computing the control box is very fast, while getting the bounding */
  265. /* box can take much more time as it needs to walk over all segments */
  266. /* and arcs in the outline. To get the latter, you can use the */
  267. /* `ftbbox' component which is dedicated to this single task. */
  268. /* */
  269. /* <Input> */
  270. /* glyph :: A handle to the source glyph object. */
  271. /* */
  272. /* mode :: The mode which indicates how to interpret the returned */
  273. /* bounding box values. */
  274. /* */
  275. /* <Output> */
  276. /* acbox :: The glyph coordinate bounding box. Coordinates are */
  277. /* expressed in 1/64th of pixels if it is grid-fitted. */
  278. /* */
  279. /* <Note> */
  280. /* Coordinates are relative to the glyph origin, using the Y-upwards */
  281. /* convention. */
  282. /* */
  283. /* If the glyph has been loaded with FT_LOAD_NO_SCALE, `bbox_mode' */
  284. /* must be set to `ft_glyph_bbox_unscaled' to get unscaled font */
  285. /* units. */
  286. /* */
  287. /* If `bbox_mode' is set to `ft_glyph_bbox_subpixels' the bbox */
  288. /* coordinates are returned in 26.6 pixels (i.e. 1/64th of pixels). */
  289. /* */
  290. /* Note that the maximum coordinates are exclusive, which means that */
  291. /* one can compute the width and height of the glyph image (be it in */
  292. /* integer or 26.6 pixels) as: */
  293. /* */
  294. /* width = bbox.xMax - bbox.xMin; */
  295. /* height = bbox.yMax - bbox.yMin; */
  296. /* */
  297. /* Note also that for 26.6 coordinates, if `bbox_mode' is set to */
  298. /* `ft_glyph_bbox_gridfit', the coordinates will also be grid-fitted, */
  299. /* which corresponds to: */
  300. /* */
  301. /* bbox.xMin = FLOOR(bbox.xMin); */
  302. /* bbox.yMin = FLOOR(bbox.yMin); */
  303. /* bbox.xMax = CEILING(bbox.xMax); */
  304. /* bbox.yMax = CEILING(bbox.yMax); */
  305. /* */
  306. /* To get the bbox in pixel coordinates, set `bbox_mode' to */
  307. /* `ft_glyph_bbox_truncate'. */
  308. /* */
  309. /* To get the bbox in grid-fitted pixel coordinates, set `bbox_mode' */
  310. /* to `ft_glyph_bbox_pixels'. */
  311. /* */
  312. /* The default value for `bbox_mode' is `ft_glyph_bbox_pixels'. */
  313. /* */
  314. enum
  315. {
  316. ft_glyph_bbox_unscaled = 0, /* return unscaled font units */
  317. ft_glyph_bbox_subpixels = 0, /* return unfitted 26.6 coordinates */
  318. ft_glyph_bbox_gridfit = 1, /* return grid-fitted 26.6 coordinates */
  319. ft_glyph_bbox_truncate = 2, /* return coordinates in integer pixels */
  320. ft_glyph_bbox_pixels = 3 /* return grid-fitted pixel coordinates */
  321. };
  322. FT_EXPORT( void )
  323. FT_Glyph_Get_CBox( FT_Glyph glyph,
  324. FT_UInt bbox_mode,
  325. FT_BBox *acbox );
  326. /*************************************************************************/
  327. /* */
  328. /* <Function> */
  329. /* FT_Glyph_To_Bitmap */
  330. /* */
  331. /* <Description> */
  332. /* Converts a given glyph object to a bitmap glyph object. */
  333. /* */
  334. /* <InOut> */
  335. /* the_glyph :: A pointer to a handle to the target glyph. */
  336. /* */
  337. /* <Input> */
  338. /* render_mode :: An enumeration that describe how the data is */
  339. /* rendered. */
  340. /* */
  341. /* origin :: A pointer to a vector used to translate the glyph */
  342. /* image before rendering. Can be 0 (if no */
  343. /* translation). The origin is expressed in */
  344. /* 26.6 pixels. */
  345. /* */
  346. /* destroy :: A boolean that indicates that the original glyph */
  347. /* image should be destroyed by this function. It is */
  348. /* never destroyed in case of error. */
  349. /* */
  350. /* <Return> */
  351. /* FreeType error code. 0 means success. */
  352. /* */
  353. /* <Note> */
  354. /* The glyph image is translated with the `origin' vector before */
  355. /* rendering. In case of error, it it translated back to its */
  356. /* original position and the glyph is left untouched. */
  357. /* */
  358. /* The first parameter is a pointer to a FT_Glyph handle, that will */
  359. /* be replaced by this function. Typically, you would use (omitting */
  360. /* error handling): */
  361. /* */
  362. /* */
  363. /* { */
  364. /* FT_Glyph glyph; */
  365. /* FT_BitmapGlyph glyph_bitmap; */
  366. /* */
  367. /* */
  368. /* // load glyph */
  369. /* error = FT_Load_Char( face, glyph_index, FT_LOAD_DEFAUT ); */
  370. /* */
  371. /* // extract glyph image */
  372. /* error = FT_Get_Glyph( face->glyph, &glyph ); */
  373. /* */
  374. /* // convert to a bitmap (default render mode + destroy old) */
  375. /* if ( glyph->format != FT_GLYPH_FORMAT_BITMAP ) */
  376. /* { */
  377. /* error = FT_Glyph_To_Bitmap( &glyph, ft_render_mode_default, */
  378. /* 0, 1 ); */
  379. /* if ( error ) // glyph unchanged */
  380. /* ... */
  381. /* } */
  382. /* */
  383. /* // access bitmap content by typecasting */
  384. /* glyph_bitmap = (FT_BitmapGlyph)glyph; */
  385. /* */
  386. /* // do funny stuff with it, like blitting/drawing */
  387. /* ... */
  388. /* */
  389. /* // discard glyph image (bitmap or not) */
  390. /* FT_Done_Glyph( glyph ); */
  391. /* } */
  392. /* */
  393. /* */
  394. /* This function will always fail if the glyph's format isn't */
  395. /* scalable. */
  396. /* */
  397. FT_EXPORT( FT_Error )
  398. FT_Glyph_To_Bitmap( FT_Glyph* the_glyph,
  399. FT_Render_Mode render_mode,
  400. FT_Vector* origin,
  401. FT_Bool destroy );
  402. /*************************************************************************/
  403. /* */
  404. /* <Function> */
  405. /* FT_Done_Glyph */
  406. /* */
  407. /* <Description> */
  408. /* Destroys a given glyph. */
  409. /* */
  410. /* <Input> */
  411. /* glyph :: A handle to the target glyph object. */
  412. /* */
  413. FT_EXPORT( void )
  414. FT_Done_Glyph( FT_Glyph glyph );
  415. /* other helpful functions */
  416. /*************************************************************************/
  417. /* */
  418. /* <Section> */
  419. /* computations */
  420. /* */
  421. /*************************************************************************/
  422. /*************************************************************************/
  423. /* */
  424. /* <Function> */
  425. /* FT_Matrix_Multiply */
  426. /* */
  427. /* <Description> */
  428. /* Performs the matrix operation `b = a*b'. */
  429. /* */
  430. /* <Input> */
  431. /* a :: A pointer to matrix `a'. */
  432. /* */
  433. /* <InOut> */
  434. /* b :: A pointer to matrix `b'. */
  435. /* */
  436. /* <Note> */
  437. /* The result is undefined if either `a' or `b' is zero. */
  438. /* */
  439. FT_EXPORT( void )
  440. FT_Matrix_Multiply( const FT_Matrix* a,
  441. FT_Matrix* b );
  442. /*************************************************************************/
  443. /* */
  444. /* <Function> */
  445. /* FT_Matrix_Invert */
  446. /* */
  447. /* <Description> */
  448. /* Inverts a 2x2 matrix. Returns an error if it can't be inverted. */
  449. /* */
  450. /* <InOut> */
  451. /* matrix :: A pointer to the target matrix. Remains untouched in */
  452. /* case of error. */
  453. /* */
  454. /* <Return> */
  455. /* FreeType error code. 0 means success. */
  456. /* */
  457. FT_EXPORT( FT_Error )
  458. FT_Matrix_Invert( FT_Matrix* matrix );
  459. /* */
  460. FT_END_HEADER
  461. #endif /* __FTGLYPH_H__ */
  462. /* END */