Subversion Repositories Kolibri OS

Rev

Go to most recent revision | Blame | Last modification | View Log | RSS feed

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