thirdparty/freetype-2.3.12/include/freetype/ftstroke.h

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