/src/compiler/android-ndk/jni/freetype/include/freetype/ftstroke.h

http://ftk.googlecode.com/ · C++ Header · 716 lines · 90 code · 61 blank · 565 comment · 0 complexity · e976a7565afc12837e0191de677abc11 MD5 · raw file

  1. /***************************************************************************/
  2. /* */
  3. /* ftstroke.h */
  4. /* */
  5. /* FreeType path stroker (specification). */
  6. /* */
  7. /* Copyright 2002, 2003, 2004, 2005, 2006, 2008, 2009 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. #ifndef __FT_STROKE_H__
  18. #define __FT_STROKE_H__
  19. #include <ft2build.h>
  20. #include FT_OUTLINE_H
  21. #include FT_GLYPH_H
  22. FT_BEGIN_HEADER
  23. /************************************************************************
  24. *
  25. * @section:
  26. * glyph_stroker
  27. *
  28. * @title:
  29. * Glyph Stroker
  30. *
  31. * @abstract:
  32. * Generating bordered and stroked glyphs.
  33. *
  34. * @description:
  35. * This component generates stroked outlines of a given vectorial
  36. * glyph. It also allows you to retrieve the `outside' and/or the
  37. * `inside' borders of the stroke.
  38. *
  39. * This can be useful to generate `bordered' glyph, i.e., glyphs
  40. * displayed with a coloured (and anti-aliased) border around their
  41. * shape.
  42. */
  43. /**************************************************************
  44. *
  45. * @type:
  46. * FT_Stroker
  47. *
  48. * @description:
  49. * Opaque handler to a path stroker object.
  50. */
  51. typedef struct FT_StrokerRec_* FT_Stroker;
  52. /**************************************************************
  53. *
  54. * @enum:
  55. * FT_Stroker_LineJoin
  56. *
  57. * @description:
  58. * These values determine how two joining lines are rendered
  59. * in a stroker.
  60. *
  61. * @values:
  62. * FT_STROKER_LINEJOIN_ROUND ::
  63. * Used to render rounded line joins. Circular arcs are used
  64. * to join two lines smoothly.
  65. *
  66. * FT_STROKER_LINEJOIN_BEVEL ::
  67. * Used to render beveled line joins; i.e., the two joining lines
  68. * are extended until they intersect.
  69. *
  70. * FT_STROKER_LINEJOIN_MITER ::
  71. * Same as beveled rendering, except that an additional line
  72. * break is added if the angle between the two joining lines
  73. * is too closed (this is useful to avoid unpleasant spikes
  74. * in beveled rendering).
  75. */
  76. typedef enum FT_Stroker_LineJoin_
  77. {
  78. FT_STROKER_LINEJOIN_ROUND = 0,
  79. FT_STROKER_LINEJOIN_BEVEL,
  80. FT_STROKER_LINEJOIN_MITER
  81. } FT_Stroker_LineJoin;
  82. /**************************************************************
  83. *
  84. * @enum:
  85. * FT_Stroker_LineCap
  86. *
  87. * @description:
  88. * These values determine how the end of opened sub-paths are
  89. * rendered in a stroke.
  90. *
  91. * @values:
  92. * FT_STROKER_LINECAP_BUTT ::
  93. * The end of lines is rendered as a full stop on the last
  94. * point itself.
  95. *
  96. * FT_STROKER_LINECAP_ROUND ::
  97. * The end of lines is rendered as a half-circle around the
  98. * last point.
  99. *
  100. * FT_STROKER_LINECAP_SQUARE ::
  101. * The end of lines is rendered as a square around the
  102. * last point.
  103. */
  104. typedef enum FT_Stroker_LineCap_
  105. {
  106. FT_STROKER_LINECAP_BUTT = 0,
  107. FT_STROKER_LINECAP_ROUND,
  108. FT_STROKER_LINECAP_SQUARE
  109. } FT_Stroker_LineCap;
  110. /**************************************************************
  111. *
  112. * @enum:
  113. * FT_StrokerBorder
  114. *
  115. * @description:
  116. * These values are used to select a given stroke border
  117. * in @FT_Stroker_GetBorderCounts and @FT_Stroker_ExportBorder.
  118. *
  119. * @values:
  120. * FT_STROKER_BORDER_LEFT ::
  121. * Select the left border, relative to the drawing direction.
  122. *
  123. * FT_STROKER_BORDER_RIGHT ::
  124. * Select the right border, relative to the drawing direction.
  125. *
  126. * @note:
  127. * Applications are generally interested in the `inside' and `outside'
  128. * borders. However, there is no direct mapping between these and the
  129. * `left' and `right' ones, since this really depends on the glyph's
  130. * drawing orientation, which varies between font formats.
  131. *
  132. * You can however use @FT_Outline_GetInsideBorder and
  133. * @FT_Outline_GetOutsideBorder to get these.
  134. */
  135. typedef enum FT_StrokerBorder_
  136. {
  137. FT_STROKER_BORDER_LEFT = 0,
  138. FT_STROKER_BORDER_RIGHT
  139. } FT_StrokerBorder;
  140. /**************************************************************
  141. *
  142. * @function:
  143. * FT_Outline_GetInsideBorder
  144. *
  145. * @description:
  146. * Retrieve the @FT_StrokerBorder value corresponding to the
  147. * `inside' borders of a given outline.
  148. *
  149. * @input:
  150. * outline ::
  151. * The source outline handle.
  152. *
  153. * @return:
  154. * The border index. @FT_STROKER_BORDER_RIGHT for empty or invalid
  155. * outlines.
  156. */
  157. FT_EXPORT( FT_StrokerBorder )
  158. FT_Outline_GetInsideBorder( FT_Outline* outline );
  159. /**************************************************************
  160. *
  161. * @function:
  162. * FT_Outline_GetOutsideBorder
  163. *
  164. * @description:
  165. * Retrieve the @FT_StrokerBorder value corresponding to the
  166. * `outside' borders of a given outline.
  167. *
  168. * @input:
  169. * outline ::
  170. * The source outline handle.
  171. *
  172. * @return:
  173. * The border index. @FT_STROKER_BORDER_LEFT for empty or invalid
  174. * outlines.
  175. */
  176. FT_EXPORT( FT_StrokerBorder )
  177. FT_Outline_GetOutsideBorder( FT_Outline* outline );
  178. /**************************************************************
  179. *
  180. * @function:
  181. * FT_Stroker_New
  182. *
  183. * @description:
  184. * Create a new stroker object.
  185. *
  186. * @input:
  187. * library ::
  188. * FreeType library handle.
  189. *
  190. * @output:
  191. * astroker ::
  192. * A new stroker object handle. NULL in case of error.
  193. *
  194. * @return:
  195. * FreeType error code. 0~means success.
  196. */
  197. FT_EXPORT( FT_Error )
  198. FT_Stroker_New( FT_Library library,
  199. FT_Stroker *astroker );
  200. /**************************************************************
  201. *
  202. * @function:
  203. * FT_Stroker_Set
  204. *
  205. * @description:
  206. * Reset a stroker object's attributes.
  207. *
  208. * @input:
  209. * stroker ::
  210. * The target stroker handle.
  211. *
  212. * radius ::
  213. * The border radius.
  214. *
  215. * line_cap ::
  216. * The line cap style.
  217. *
  218. * line_join ::
  219. * The line join style.
  220. *
  221. * miter_limit ::
  222. * The miter limit for the FT_STROKER_LINEJOIN_MITER style,
  223. * expressed as 16.16 fixed point value.
  224. *
  225. * @note:
  226. * The radius is expressed in the same units as the outline
  227. * coordinates.
  228. */
  229. FT_EXPORT( void )
  230. FT_Stroker_Set( FT_Stroker stroker,
  231. FT_Fixed radius,
  232. FT_Stroker_LineCap line_cap,
  233. FT_Stroker_LineJoin line_join,
  234. FT_Fixed miter_limit );
  235. /**************************************************************
  236. *
  237. * @function:
  238. * FT_Stroker_Rewind
  239. *
  240. * @description:
  241. * Reset a stroker object without changing its attributes.
  242. * You should call this function before beginning a new
  243. * series of calls to @FT_Stroker_BeginSubPath or
  244. * @FT_Stroker_EndSubPath.
  245. *
  246. * @input:
  247. * stroker ::
  248. * The target stroker handle.
  249. */
  250. FT_EXPORT( void )
  251. FT_Stroker_Rewind( FT_Stroker stroker );
  252. /**************************************************************
  253. *
  254. * @function:
  255. * FT_Stroker_ParseOutline
  256. *
  257. * @description:
  258. * A convenience function used to parse a whole outline with
  259. * the stroker. The resulting outline(s) can be retrieved
  260. * later by functions like @FT_Stroker_GetCounts and @FT_Stroker_Export.
  261. *
  262. * @input:
  263. * stroker ::
  264. * The target stroker handle.
  265. *
  266. * outline ::
  267. * The source outline.
  268. *
  269. * opened ::
  270. * A boolean. If~1, the outline is treated as an open path instead
  271. * of a closed one.
  272. *
  273. * @return:
  274. * FreeType error code. 0~means success.
  275. *
  276. * @note:
  277. * If `opened' is~0 (the default), the outline is treated as a closed
  278. * path, and the stroker generates two distinct `border' outlines.
  279. *
  280. * If `opened' is~1, the outline is processed as an open path, and the
  281. * stroker generates a single `stroke' outline.
  282. *
  283. * This function calls @FT_Stroker_Rewind automatically.
  284. */
  285. FT_EXPORT( FT_Error )
  286. FT_Stroker_ParseOutline( FT_Stroker stroker,
  287. FT_Outline* outline,
  288. FT_Bool opened );
  289. /**************************************************************
  290. *
  291. * @function:
  292. * FT_Stroker_BeginSubPath
  293. *
  294. * @description:
  295. * Start a new sub-path in the stroker.
  296. *
  297. * @input:
  298. * stroker ::
  299. * The target stroker handle.
  300. *
  301. * to ::
  302. * A pointer to the start vector.
  303. *
  304. * open ::
  305. * A boolean. If~1, the sub-path is treated as an open one.
  306. *
  307. * @return:
  308. * FreeType error code. 0~means success.
  309. *
  310. * @note:
  311. * This function is useful when you need to stroke a path that is
  312. * not stored as an @FT_Outline object.
  313. */
  314. FT_EXPORT( FT_Error )
  315. FT_Stroker_BeginSubPath( FT_Stroker stroker,
  316. FT_Vector* to,
  317. FT_Bool open );
  318. /**************************************************************
  319. *
  320. * @function:
  321. * FT_Stroker_EndSubPath
  322. *
  323. * @description:
  324. * Close the current sub-path in the stroker.
  325. *
  326. * @input:
  327. * stroker ::
  328. * The target stroker handle.
  329. *
  330. * @return:
  331. * FreeType error code. 0~means success.
  332. *
  333. * @note:
  334. * You should call this function after @FT_Stroker_BeginSubPath.
  335. * If the subpath was not `opened', this function `draws' a
  336. * single line segment to the start position when needed.
  337. */
  338. FT_EXPORT( FT_Error )
  339. FT_Stroker_EndSubPath( FT_Stroker stroker );
  340. /**************************************************************
  341. *
  342. * @function:
  343. * FT_Stroker_LineTo
  344. *
  345. * @description:
  346. * `Draw' a single line segment in the stroker's current sub-path,
  347. * from the last position.
  348. *
  349. * @input:
  350. * stroker ::
  351. * The target stroker handle.
  352. *
  353. * to ::
  354. * A pointer to the destination point.
  355. *
  356. * @return:
  357. * FreeType error code. 0~means success.
  358. *
  359. * @note:
  360. * You should call this function between @FT_Stroker_BeginSubPath and
  361. * @FT_Stroker_EndSubPath.
  362. */
  363. FT_EXPORT( FT_Error )
  364. FT_Stroker_LineTo( FT_Stroker stroker,
  365. FT_Vector* to );
  366. /**************************************************************
  367. *
  368. * @function:
  369. * FT_Stroker_ConicTo
  370. *
  371. * @description:
  372. * `Draw' a single quadratic Bézier in the stroker's current sub-path,
  373. * from the last position.
  374. *
  375. * @input:
  376. * stroker ::
  377. * The target stroker handle.
  378. *
  379. * control ::
  380. * A pointer to a Bézier control point.
  381. *
  382. * to ::
  383. * A pointer to the destination point.
  384. *
  385. * @return:
  386. * FreeType error code. 0~means success.
  387. *
  388. * @note:
  389. * You should call this function between @FT_Stroker_BeginSubPath and
  390. * @FT_Stroker_EndSubPath.
  391. */
  392. FT_EXPORT( FT_Error )
  393. FT_Stroker_ConicTo( FT_Stroker stroker,
  394. FT_Vector* control,
  395. FT_Vector* to );
  396. /**************************************************************
  397. *
  398. * @function:
  399. * FT_Stroker_CubicTo
  400. *
  401. * @description:
  402. * `Draw' a single cubic Bézier in the stroker's current sub-path,
  403. * from the last position.
  404. *
  405. * @input:
  406. * stroker ::
  407. * The target stroker handle.
  408. *
  409. * control1 ::
  410. * A pointer to the first Bézier control point.
  411. *
  412. * control2 ::
  413. * A pointer to second Bézier control point.
  414. *
  415. * to ::
  416. * A pointer to the destination point.
  417. *
  418. * @return:
  419. * FreeType error code. 0~means success.
  420. *
  421. * @note:
  422. * You should call this function between @FT_Stroker_BeginSubPath and
  423. * @FT_Stroker_EndSubPath.
  424. */
  425. FT_EXPORT( FT_Error )
  426. FT_Stroker_CubicTo( FT_Stroker stroker,
  427. FT_Vector* control1,
  428. FT_Vector* control2,
  429. FT_Vector* to );
  430. /**************************************************************
  431. *
  432. * @function:
  433. * FT_Stroker_GetBorderCounts
  434. *
  435. * @description:
  436. * Call this function once you have finished parsing your paths
  437. * with the stroker. It returns the number of points and
  438. * contours necessary to export one of the `border' or `stroke'
  439. * outlines generated by the stroker.
  440. *
  441. * @input:
  442. * stroker ::
  443. * The target stroker handle.
  444. *
  445. * border ::
  446. * The border index.
  447. *
  448. * @output:
  449. * anum_points ::
  450. * The number of points.
  451. *
  452. * anum_contours ::
  453. * The number of contours.
  454. *
  455. * @return:
  456. * FreeType error code. 0~means success.
  457. *
  458. * @note:
  459. * When an outline, or a sub-path, is `closed', the stroker generates
  460. * two independent `border' outlines, named `left' and `right'.
  461. *
  462. * When the outline, or a sub-path, is `opened', the stroker merges
  463. * the `border' outlines with caps. The `left' border receives all
  464. * points, while the `right' border becomes empty.
  465. *
  466. * Use the function @FT_Stroker_GetCounts instead if you want to
  467. * retrieve the counts associated to both borders.
  468. */
  469. FT_EXPORT( FT_Error )
  470. FT_Stroker_GetBorderCounts( FT_Stroker stroker,
  471. FT_StrokerBorder border,
  472. FT_UInt *anum_points,
  473. FT_UInt *anum_contours );
  474. /**************************************************************
  475. *
  476. * @function:
  477. * FT_Stroker_ExportBorder
  478. *
  479. * @description:
  480. * Call this function after @FT_Stroker_GetBorderCounts to
  481. * export the corresponding border to your own @FT_Outline
  482. * structure.
  483. *
  484. * Note that this function appends the border points and
  485. * contours to your outline, but does not try to resize its
  486. * arrays.
  487. *
  488. * @input:
  489. * stroker ::
  490. * The target stroker handle.
  491. *
  492. * border ::
  493. * The border index.
  494. *
  495. * outline ::
  496. * The target outline handle.
  497. *
  498. * @note:
  499. * Always call this function after @FT_Stroker_GetBorderCounts to
  500. * get sure that there is enough room in your @FT_Outline object to
  501. * receive all new data.
  502. *
  503. * When an outline, or a sub-path, is `closed', the stroker generates
  504. * two independent `border' outlines, named `left' and `right'
  505. *
  506. * When the outline, or a sub-path, is `opened', the stroker merges
  507. * the `border' outlines with caps. The `left' border receives all
  508. * points, while the `right' border becomes empty.
  509. *
  510. * Use the function @FT_Stroker_Export instead if you want to
  511. * retrieve all borders at once.
  512. */
  513. FT_EXPORT( void )
  514. FT_Stroker_ExportBorder( FT_Stroker stroker,
  515. FT_StrokerBorder border,
  516. FT_Outline* outline );
  517. /**************************************************************
  518. *
  519. * @function:
  520. * FT_Stroker_GetCounts
  521. *
  522. * @description:
  523. * Call this function once you have finished parsing your paths
  524. * with the stroker. It returns the number of points and
  525. * contours necessary to export all points/borders from the stroked
  526. * outline/path.
  527. *
  528. * @input:
  529. * stroker ::
  530. * The target stroker handle.
  531. *
  532. * @output:
  533. * anum_points ::
  534. * The number of points.
  535. *
  536. * anum_contours ::
  537. * The number of contours.
  538. *
  539. * @return:
  540. * FreeType error code. 0~means success.
  541. */
  542. FT_EXPORT( FT_Error )
  543. FT_Stroker_GetCounts( FT_Stroker stroker,
  544. FT_UInt *anum_points,
  545. FT_UInt *anum_contours );
  546. /**************************************************************
  547. *
  548. * @function:
  549. * FT_Stroker_Export
  550. *
  551. * @description:
  552. * Call this function after @FT_Stroker_GetBorderCounts to
  553. * export all borders to your own @FT_Outline structure.
  554. *
  555. * Note that this function appends the border points and
  556. * contours to your outline, but does not try to resize its
  557. * arrays.
  558. *
  559. * @input:
  560. * stroker ::
  561. * The target stroker handle.
  562. *
  563. * outline ::
  564. * The target outline handle.
  565. */
  566. FT_EXPORT( void )
  567. FT_Stroker_Export( FT_Stroker stroker,
  568. FT_Outline* outline );
  569. /**************************************************************
  570. *
  571. * @function:
  572. * FT_Stroker_Done
  573. *
  574. * @description:
  575. * Destroy a stroker object.
  576. *
  577. * @input:
  578. * stroker ::
  579. * A stroker handle. Can be NULL.
  580. */
  581. FT_EXPORT( void )
  582. FT_Stroker_Done( FT_Stroker stroker );
  583. /**************************************************************
  584. *
  585. * @function:
  586. * FT_Glyph_Stroke
  587. *
  588. * @description:
  589. * Stroke a given outline glyph object with a given stroker.
  590. *
  591. * @inout:
  592. * pglyph ::
  593. * Source glyph handle on input, new glyph handle on output.
  594. *
  595. * @input:
  596. * stroker ::
  597. * A stroker handle.
  598. *
  599. * destroy ::
  600. * A Boolean. If~1, the source glyph object is destroyed
  601. * on success.
  602. *
  603. * @return:
  604. * FreeType error code. 0~means success.
  605. *
  606. * @note:
  607. * The source glyph is untouched in case of error.
  608. */
  609. FT_EXPORT( FT_Error )
  610. FT_Glyph_Stroke( FT_Glyph *pglyph,
  611. FT_Stroker stroker,
  612. FT_Bool destroy );
  613. /**************************************************************
  614. *
  615. * @function:
  616. * FT_Glyph_StrokeBorder
  617. *
  618. * @description:
  619. * Stroke a given outline glyph object with a given stroker, but
  620. * only return either its inside or outside border.
  621. *
  622. * @inout:
  623. * pglyph ::
  624. * Source glyph handle on input, new glyph handle on output.
  625. *
  626. * @input:
  627. * stroker ::
  628. * A stroker handle.
  629. *
  630. * inside ::
  631. * A Boolean. If~1, return the inside border, otherwise
  632. * the outside border.
  633. *
  634. * destroy ::
  635. * A Boolean. If~1, the source glyph object is destroyed
  636. * on success.
  637. *
  638. * @return:
  639. * FreeType error code. 0~means success.
  640. *
  641. * @note:
  642. * The source glyph is untouched in case of error.
  643. */
  644. FT_EXPORT( FT_Error )
  645. FT_Glyph_StrokeBorder( FT_Glyph *pglyph,
  646. FT_Stroker stroker,
  647. FT_Bool inside,
  648. FT_Bool destroy );
  649. /* */
  650. FT_END_HEADER
  651. #endif /* __FT_STROKE_H__ */
  652. /* END */
  653. /* Local Variables: */
  654. /* coding: utf-8 */
  655. /* End: */