/src/freetype/include/freetype/ftoutln.h

https://bitbucket.org/cabalistic/ogredeps/ · C++ Header · 540 lines · 70 code · 51 blank · 419 comment · 0 complexity · 08244f49210bf608a9f1794ab8b1ab6e MD5 · raw file

  1. /***************************************************************************/
  2. /* */
  3. /* ftoutln.h */
  4. /* */
  5. /* Support for the FT_Outline type used to store glyph shapes of */
  6. /* most scalable font formats (specification). */
  7. /* */
  8. /* Copyright 1996-2003, 2005-2011 by */
  9. /* David Turner, Robert Wilhelm, and Werner Lemberg. */
  10. /* */
  11. /* This file is part of the FreeType project, and may only be used, */
  12. /* modified, and distributed under the terms of the FreeType project */
  13. /* license, LICENSE.TXT. By continuing to use, modify, or distribute */
  14. /* this file you indicate that you have read the license and */
  15. /* understand and accept it fully. */
  16. /* */
  17. /***************************************************************************/
  18. #ifndef __FTOUTLN_H__
  19. #define __FTOUTLN_H__
  20. #include <ft2build.h>
  21. #include FT_FREETYPE_H
  22. #ifdef FREETYPE_H
  23. #error "freetype.h of FreeType 1 has been loaded!"
  24. #error "Please fix the directory search order for header files"
  25. #error "so that freetype.h of FreeType 2 is found first."
  26. #endif
  27. FT_BEGIN_HEADER
  28. /*************************************************************************/
  29. /* */
  30. /* <Section> */
  31. /* outline_processing */
  32. /* */
  33. /* <Title> */
  34. /* Outline Processing */
  35. /* */
  36. /* <Abstract> */
  37. /* Functions to create, transform, and render vectorial glyph images. */
  38. /* */
  39. /* <Description> */
  40. /* This section contains routines used to create and destroy scalable */
  41. /* glyph images known as `outlines'. These can also be measured, */
  42. /* transformed, and converted into bitmaps and pixmaps. */
  43. /* */
  44. /* <Order> */
  45. /* FT_Outline */
  46. /* FT_OUTLINE_FLAGS */
  47. /* FT_Outline_New */
  48. /* FT_Outline_Done */
  49. /* FT_Outline_Copy */
  50. /* FT_Outline_Translate */
  51. /* FT_Outline_Transform */
  52. /* FT_Outline_Embolden */
  53. /* FT_Outline_Reverse */
  54. /* FT_Outline_Check */
  55. /* */
  56. /* FT_Outline_Get_CBox */
  57. /* FT_Outline_Get_BBox */
  58. /* */
  59. /* FT_Outline_Get_Bitmap */
  60. /* FT_Outline_Render */
  61. /* */
  62. /* FT_Outline_Decompose */
  63. /* FT_Outline_Funcs */
  64. /* FT_Outline_MoveTo_Func */
  65. /* FT_Outline_LineTo_Func */
  66. /* FT_Outline_ConicTo_Func */
  67. /* FT_Outline_CubicTo_Func */
  68. /* */
  69. /*************************************************************************/
  70. /*************************************************************************/
  71. /* */
  72. /* <Function> */
  73. /* FT_Outline_Decompose */
  74. /* */
  75. /* <Description> */
  76. /* Walk over an outline's structure to decompose it into individual */
  77. /* segments and Bézier arcs. This function also emits `move to' */
  78. /* operations to indicate the start of new contours in the outline. */
  79. /* */
  80. /* <Input> */
  81. /* outline :: A pointer to the source target. */
  82. /* */
  83. /* func_interface :: A table of `emitters', i.e., function pointers */
  84. /* called during decomposition to indicate path */
  85. /* operations. */
  86. /* */
  87. /* <InOut> */
  88. /* user :: A typeless pointer which is passed to each */
  89. /* emitter during the decomposition. It can be */
  90. /* used to store the state during the */
  91. /* decomposition. */
  92. /* */
  93. /* <Return> */
  94. /* FreeType error code. 0~means success. */
  95. /* */
  96. FT_EXPORT( FT_Error )
  97. FT_Outline_Decompose( FT_Outline* outline,
  98. const FT_Outline_Funcs* func_interface,
  99. void* user );
  100. /*************************************************************************/
  101. /* */
  102. /* <Function> */
  103. /* FT_Outline_New */
  104. /* */
  105. /* <Description> */
  106. /* Create a new outline of a given size. */
  107. /* */
  108. /* <Input> */
  109. /* library :: A handle to the library object from where the */
  110. /* outline is allocated. Note however that the new */
  111. /* outline will *not* necessarily be *freed*, when */
  112. /* destroying the library, by @FT_Done_FreeType. */
  113. /* */
  114. /* numPoints :: The maximal number of points within the outline. */
  115. /* */
  116. /* numContours :: The maximal number of contours within the outline. */
  117. /* */
  118. /* <Output> */
  119. /* anoutline :: A handle to the new outline. */
  120. /* */
  121. /* <Return> */
  122. /* FreeType error code. 0~means success. */
  123. /* */
  124. /* <Note> */
  125. /* The reason why this function takes a `library' parameter is simply */
  126. /* to use the library's memory allocator. */
  127. /* */
  128. FT_EXPORT( FT_Error )
  129. FT_Outline_New( FT_Library library,
  130. FT_UInt numPoints,
  131. FT_Int numContours,
  132. FT_Outline *anoutline );
  133. FT_EXPORT( FT_Error )
  134. FT_Outline_New_Internal( FT_Memory memory,
  135. FT_UInt numPoints,
  136. FT_Int numContours,
  137. FT_Outline *anoutline );
  138. /*************************************************************************/
  139. /* */
  140. /* <Function> */
  141. /* FT_Outline_Done */
  142. /* */
  143. /* <Description> */
  144. /* Destroy an outline created with @FT_Outline_New. */
  145. /* */
  146. /* <Input> */
  147. /* library :: A handle of the library object used to allocate the */
  148. /* outline. */
  149. /* */
  150. /* outline :: A pointer to the outline object to be discarded. */
  151. /* */
  152. /* <Return> */
  153. /* FreeType error code. 0~means success. */
  154. /* */
  155. /* <Note> */
  156. /* If the outline's `owner' field is not set, only the outline */
  157. /* descriptor will be released. */
  158. /* */
  159. /* The reason why this function takes an `library' parameter is */
  160. /* simply to use ft_mem_free(). */
  161. /* */
  162. FT_EXPORT( FT_Error )
  163. FT_Outline_Done( FT_Library library,
  164. FT_Outline* outline );
  165. FT_EXPORT( FT_Error )
  166. FT_Outline_Done_Internal( FT_Memory memory,
  167. FT_Outline* outline );
  168. /*************************************************************************/
  169. /* */
  170. /* <Function> */
  171. /* FT_Outline_Check */
  172. /* */
  173. /* <Description> */
  174. /* Check the contents of an outline descriptor. */
  175. /* */
  176. /* <Input> */
  177. /* outline :: A handle to a source outline. */
  178. /* */
  179. /* <Return> */
  180. /* FreeType error code. 0~means success. */
  181. /* */
  182. FT_EXPORT( FT_Error )
  183. FT_Outline_Check( FT_Outline* outline );
  184. /*************************************************************************/
  185. /* */
  186. /* <Function> */
  187. /* FT_Outline_Get_CBox */
  188. /* */
  189. /* <Description> */
  190. /* Return an outline's `control box'. The control box encloses all */
  191. /* the outline's points, including Bézier control points. Though it */
  192. /* coincides with the exact bounding box for most glyphs, it can be */
  193. /* slightly larger in some situations (like when rotating an outline */
  194. /* which contains Bézier outside arcs). */
  195. /* */
  196. /* Computing the control box is very fast, while getting the bounding */
  197. /* box can take much more time as it needs to walk over all segments */
  198. /* and arcs in the outline. To get the latter, you can use the */
  199. /* `ftbbox' component which is dedicated to this single task. */
  200. /* */
  201. /* <Input> */
  202. /* outline :: A pointer to the source outline descriptor. */
  203. /* */
  204. /* <Output> */
  205. /* acbox :: The outline's control box. */
  206. /* */
  207. /* <Note> */
  208. /* See @FT_Glyph_Get_CBox for a discussion of tricky fonts. */
  209. /* */
  210. FT_EXPORT( void )
  211. FT_Outline_Get_CBox( const FT_Outline* outline,
  212. FT_BBox *acbox );
  213. /*************************************************************************/
  214. /* */
  215. /* <Function> */
  216. /* FT_Outline_Translate */
  217. /* */
  218. /* <Description> */
  219. /* Apply a simple translation to the points of an outline. */
  220. /* */
  221. /* <InOut> */
  222. /* outline :: A pointer to the target outline descriptor. */
  223. /* */
  224. /* <Input> */
  225. /* xOffset :: The horizontal offset. */
  226. /* */
  227. /* yOffset :: The vertical offset. */
  228. /* */
  229. FT_EXPORT( void )
  230. FT_Outline_Translate( const FT_Outline* outline,
  231. FT_Pos xOffset,
  232. FT_Pos yOffset );
  233. /*************************************************************************/
  234. /* */
  235. /* <Function> */
  236. /* FT_Outline_Copy */
  237. /* */
  238. /* <Description> */
  239. /* Copy an outline into another one. Both objects must have the */
  240. /* same sizes (number of points & number of contours) when this */
  241. /* function is called. */
  242. /* */
  243. /* <Input> */
  244. /* source :: A handle to the source outline. */
  245. /* */
  246. /* <Output> */
  247. /* target :: A handle to the target outline. */
  248. /* */
  249. /* <Return> */
  250. /* FreeType error code. 0~means success. */
  251. /* */
  252. FT_EXPORT( FT_Error )
  253. FT_Outline_Copy( const FT_Outline* source,
  254. FT_Outline *target );
  255. /*************************************************************************/
  256. /* */
  257. /* <Function> */
  258. /* FT_Outline_Transform */
  259. /* */
  260. /* <Description> */
  261. /* Apply a simple 2x2 matrix to all of an outline's points. Useful */
  262. /* for applying rotations, slanting, flipping, etc. */
  263. /* */
  264. /* <InOut> */
  265. /* outline :: A pointer to the target outline descriptor. */
  266. /* */
  267. /* <Input> */
  268. /* matrix :: A pointer to the transformation matrix. */
  269. /* */
  270. /* <Note> */
  271. /* You can use @FT_Outline_Translate if you need to translate the */
  272. /* outline's points. */
  273. /* */
  274. FT_EXPORT( void )
  275. FT_Outline_Transform( const FT_Outline* outline,
  276. const FT_Matrix* matrix );
  277. /*************************************************************************/
  278. /* */
  279. /* <Function> */
  280. /* FT_Outline_Embolden */
  281. /* */
  282. /* <Description> */
  283. /* Embolden an outline. The new outline will be at most 4~times */
  284. /* `strength' pixels wider and higher. You may think of the left and */
  285. /* bottom borders as unchanged. */
  286. /* */
  287. /* Negative `strength' values to reduce the outline thickness are */
  288. /* possible also. */
  289. /* */
  290. /* <InOut> */
  291. /* outline :: A handle to the target outline. */
  292. /* */
  293. /* <Input> */
  294. /* strength :: How strong the glyph is emboldened. Expressed in */
  295. /* 26.6 pixel format. */
  296. /* */
  297. /* <Return> */
  298. /* FreeType error code. 0~means success. */
  299. /* */
  300. /* <Note> */
  301. /* The used algorithm to increase or decrease the thickness of the */
  302. /* glyph doesn't change the number of points; this means that certain */
  303. /* situations like acute angles or intersections are sometimes */
  304. /* handled incorrectly. */
  305. /* */
  306. /* If you need `better' metrics values you should call */
  307. /* @FT_Outline_Get_CBox or @FT_Outline_Get_BBox. */
  308. /* */
  309. /* Example call: */
  310. /* */
  311. /* { */
  312. /* FT_Load_Glyph( face, index, FT_LOAD_DEFAULT ); */
  313. /* if ( face->slot->format == FT_GLYPH_FORMAT_OUTLINE ) */
  314. /* FT_Outline_Embolden( &face->slot->outline, strength ); */
  315. /* } */
  316. /* */
  317. FT_EXPORT( FT_Error )
  318. FT_Outline_Embolden( FT_Outline* outline,
  319. FT_Pos strength );
  320. /*************************************************************************/
  321. /* */
  322. /* <Function> */
  323. /* FT_Outline_Reverse */
  324. /* */
  325. /* <Description> */
  326. /* Reverse the drawing direction of an outline. This is used to */
  327. /* ensure consistent fill conventions for mirrored glyphs. */
  328. /* */
  329. /* <InOut> */
  330. /* outline :: A pointer to the target outline descriptor. */
  331. /* */
  332. /* <Note> */
  333. /* This function toggles the bit flag @FT_OUTLINE_REVERSE_FILL in */
  334. /* the outline's `flags' field. */
  335. /* */
  336. /* It shouldn't be used by a normal client application, unless it */
  337. /* knows what it is doing. */
  338. /* */
  339. FT_EXPORT( void )
  340. FT_Outline_Reverse( FT_Outline* outline );
  341. /*************************************************************************/
  342. /* */
  343. /* <Function> */
  344. /* FT_Outline_Get_Bitmap */
  345. /* */
  346. /* <Description> */
  347. /* Render an outline within a bitmap. The outline's image is simply */
  348. /* OR-ed to the target bitmap. */
  349. /* */
  350. /* <Input> */
  351. /* library :: A handle to a FreeType library object. */
  352. /* */
  353. /* outline :: A pointer to the source outline descriptor. */
  354. /* */
  355. /* <InOut> */
  356. /* abitmap :: A pointer to the target bitmap descriptor. */
  357. /* */
  358. /* <Return> */
  359. /* FreeType error code. 0~means success. */
  360. /* */
  361. /* <Note> */
  362. /* This function does NOT CREATE the bitmap, it only renders an */
  363. /* outline image within the one you pass to it! Consequently, the */
  364. /* various fields in `abitmap' should be set accordingly. */
  365. /* */
  366. /* It will use the raster corresponding to the default glyph format. */
  367. /* */
  368. /* The value of the `num_grays' field in `abitmap' is ignored. If */
  369. /* you select the gray-level rasterizer, and you want less than 256 */
  370. /* gray levels, you have to use @FT_Outline_Render directly. */
  371. /* */
  372. FT_EXPORT( FT_Error )
  373. FT_Outline_Get_Bitmap( FT_Library library,
  374. FT_Outline* outline,
  375. const FT_Bitmap *abitmap );
  376. /*************************************************************************/
  377. /* */
  378. /* <Function> */
  379. /* FT_Outline_Render */
  380. /* */
  381. /* <Description> */
  382. /* Render an outline within a bitmap using the current scan-convert. */
  383. /* This function uses an @FT_Raster_Params structure as an argument, */
  384. /* allowing advanced features like direct composition, translucency, */
  385. /* etc. */
  386. /* */
  387. /* <Input> */
  388. /* library :: A handle to a FreeType library object. */
  389. /* */
  390. /* outline :: A pointer to the source outline descriptor. */
  391. /* */
  392. /* <InOut> */
  393. /* params :: A pointer to an @FT_Raster_Params structure used to */
  394. /* describe the rendering operation. */
  395. /* */
  396. /* <Return> */
  397. /* FreeType error code. 0~means success. */
  398. /* */
  399. /* <Note> */
  400. /* You should know what you are doing and how @FT_Raster_Params works */
  401. /* to use this function. */
  402. /* */
  403. /* The field `params.source' will be set to `outline' before the scan */
  404. /* converter is called, which means that the value you give to it is */
  405. /* actually ignored. */
  406. /* */
  407. /* The gray-level rasterizer always uses 256 gray levels. If you */
  408. /* want less gray levels, you have to provide your own span callback. */
  409. /* See the @FT_RASTER_FLAG_DIRECT value of the `flags' field in the */
  410. /* @FT_Raster_Params structure for more details. */
  411. /* */
  412. FT_EXPORT( FT_Error )
  413. FT_Outline_Render( FT_Library library,
  414. FT_Outline* outline,
  415. FT_Raster_Params* params );
  416. /**************************************************************************
  417. *
  418. * @enum:
  419. * FT_Orientation
  420. *
  421. * @description:
  422. * A list of values used to describe an outline's contour orientation.
  423. *
  424. * The TrueType and PostScript specifications use different conventions
  425. * to determine whether outline contours should be filled or unfilled.
  426. *
  427. * @values:
  428. * FT_ORIENTATION_TRUETYPE ::
  429. * According to the TrueType specification, clockwise contours must
  430. * be filled, and counter-clockwise ones must be unfilled.
  431. *
  432. * FT_ORIENTATION_POSTSCRIPT ::
  433. * According to the PostScript specification, counter-clockwise contours
  434. * must be filled, and clockwise ones must be unfilled.
  435. *
  436. * FT_ORIENTATION_FILL_RIGHT ::
  437. * This is identical to @FT_ORIENTATION_TRUETYPE, but is used to
  438. * remember that in TrueType, everything that is to the right of
  439. * the drawing direction of a contour must be filled.
  440. *
  441. * FT_ORIENTATION_FILL_LEFT ::
  442. * This is identical to @FT_ORIENTATION_POSTSCRIPT, but is used to
  443. * remember that in PostScript, everything that is to the left of
  444. * the drawing direction of a contour must be filled.
  445. *
  446. * FT_ORIENTATION_NONE ::
  447. * The orientation cannot be determined. That is, different parts of
  448. * the glyph have different orientation.
  449. *
  450. */
  451. typedef enum FT_Orientation_
  452. {
  453. FT_ORIENTATION_TRUETYPE = 0,
  454. FT_ORIENTATION_POSTSCRIPT = 1,
  455. FT_ORIENTATION_FILL_RIGHT = FT_ORIENTATION_TRUETYPE,
  456. FT_ORIENTATION_FILL_LEFT = FT_ORIENTATION_POSTSCRIPT,
  457. FT_ORIENTATION_NONE
  458. } FT_Orientation;
  459. /**************************************************************************
  460. *
  461. * @function:
  462. * FT_Outline_Get_Orientation
  463. *
  464. * @description:
  465. * This function analyzes a glyph outline and tries to compute its
  466. * fill orientation (see @FT_Orientation). This is done by computing
  467. * the direction of each global horizontal and/or vertical extrema
  468. * within the outline.
  469. *
  470. * Note that this will return @FT_ORIENTATION_TRUETYPE for empty
  471. * outlines.
  472. *
  473. * @input:
  474. * outline ::
  475. * A handle to the source outline.
  476. *
  477. * @return:
  478. * The orientation.
  479. *
  480. */
  481. FT_EXPORT( FT_Orientation )
  482. FT_Outline_Get_Orientation( FT_Outline* outline );
  483. /* */
  484. FT_END_HEADER
  485. #endif /* __FTOUTLN_H__ */
  486. /* END */
  487. /* Local Variables: */
  488. /* coding: utf-8 */
  489. /* End: */