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:             */