freetype2/include/freetype/ftstroke.h

786 lines
22 KiB
C
Raw Normal View History

/***************************************************************************/
/* */
/* ftstroke.h */
/* */
/* FreeType path stroker (specification). */
/* */
2016-01-13 11:54:10 +01:00
/* Copyright 2002-2016 by */
/* David Turner, Robert Wilhelm, and Werner Lemberg. */
/* */
/* This file is part of the FreeType project, and may only be used, */
/* modified, and distributed under the terms of the FreeType project */
/* license, LICENSE.TXT. By continuing to use, modify, or distribute */
/* this file you indicate that you have read the license and */
/* understand and accept it fully. */
/* */
/***************************************************************************/
#ifndef FTSTROKE_H_
#define FTSTROKE_H_
#include <ft2build.h>
#include FT_OUTLINE_H
#include FT_GLYPH_H
FT_BEGIN_HEADER
/************************************************************************
*
2005-10-26 22:08:45 +02:00
* @section:
* glyph_stroker
*
2005-10-26 22:08:45 +02:00
* @title:
* Glyph Stroker
*
2005-10-26 22:08:45 +02:00
* @abstract:
* Generating bordered and stroked glyphs.
*
2005-10-26 22:08:45 +02:00
* @description:
* This component generates stroked outlines of a given vectorial
* glyph. It also allows you to retrieve the `outside' and/or the
* `inside' borders of the stroke.
*
* This can be useful to generate `bordered' glyph, i.e., glyphs
* displayed with a coloured (and anti-aliased) border around their
* shape.
*
* @order:
* FT_Stroker
*
* FT_Stroker_LineJoin
* FT_Stroker_LineCap
* FT_StrokerBorder
*
* FT_Outline_GetInsideBorder
* FT_Outline_GetOutsideBorder
*
* FT_Glyph_Stroke
* FT_Glyph_StrokeBorder
*
* FT_Stroker_New
* FT_Stroker_Set
* FT_Stroker_Rewind
* FT_Stroker_ParseOutline
* FT_Stroker_Done
*
* FT_Stroker_BeginSubPath
* FT_Stroker_EndSubPath
*
* FT_Stroker_LineTo
* FT_Stroker_ConicTo
* FT_Stroker_CubicTo
*
* FT_Stroker_GetBorderCounts
* FT_Stroker_ExportBorder
* FT_Stroker_GetCounts
* FT_Stroker_Export
*
*/
/**************************************************************
*
* @type:
* FT_Stroker
*
* @description:
* Opaque handle to a path stroker object.
*/
typedef struct FT_StrokerRec_* FT_Stroker;
/**************************************************************
*
* @enum:
* FT_Stroker_LineJoin
*
* @description:
* These values determine how two joining lines are rendered
* in a stroker.
*
* @values:
* FT_STROKER_LINEJOIN_ROUND ::
* Used to render rounded line joins. Circular arcs are used
* to join two lines smoothly.
*
* FT_STROKER_LINEJOIN_BEVEL ::
[ftstroke] Major revision. The main problems ----------------- o If FT_STROKER_LINEJOIN_BEVEL was specified, unlimited miter joins (not bevel joins) were generated. Indeed, the meanings of `miter' and `bevel' were incorrectly reversed (consistently) in both the code and comments. o The way bevel joins were constructed (whether specified explicitly, or created as a result of exceeding the miter limit) did not match what is required for stroked text in PostScript or PDF. The main fixes -------------- o The behaviour of FT_STROKER_LINEJOIN_BEVEL has been corrected. o A new line join style, FT_STROKER_LINEJOIN_MITER_FIXED, has been introduced to support PostScript and PDF miter joins. o FT_STROKER_LINEJOIN_MITER_VARIABLE has been introduced as an alias for FT_STROKER_LINEJOIN_MITER. Additionally, a variety of stroking errors have been fixed. These would cause various artifacts (including points `at infinity'), especially when stroking poor quality fonts. See http://lists.gnu.org/archive/html/freetype-devel/2011-07/msg00001.html for example documents. The FreeType stroker now produces results very similar to that produced by GhostScript and Distiller for these fonts. Other problems -------------- The following problems have been resolved: o Inside corners could be generated incorrectly. Intersecting the inside corner could cause a missing triangular area and other effects. The intersection point can only be used if the join is between two lines and both lines are long enough. The `optimization' condition in `ft_stroker_inside' has been corrected; this requires the line length to be passed into various functions and stored in `FT_StrokerRec'. o Incorrect cubic curves could be generated. The angle calculations in `FT_Stroker_CubicTo' have been corrected to handle the case of the curve crossing the +/-PI direction. o If the border radius was greater than the radius of curvature of a curve, then the negative sector would end up outside (not inside) the border. This situation is now recognized and the negative sector is circumnavigated in the opposite direction. (If round line joins are being used, this code is disabled because the line join will always cover the negative sector.) o When a curve is split, the arcs may not join smoothly (especially if the curve turns sharply back on itself). Changes in direction between adjacent arcs were not handled. A round corner is now added if the deviation from one arc to the next is greater than a suitable threshold. o The current direction wasn't retained if a the outline contained a zero length lineto or a curve that was determined to be `basically a point'. This could cause a spurious join to be added. o Cubics with close control points could be mishandled. All eight cases are now distinguished correctly. Other improvements ------------------ o Borders for cubic curves could be too `flat'. FT_SMALL_CUBIC_THRESHOLD has been reduced a little to prevent this. o The handling and use of movable points has been simplified a little. o Various values are now computed only if the results are actually needed. o The directions of the outer and inner borders have been swapped, as recommended by Graham Asher. * src/base/ftstroke.c: Revised. * include/freetype/ftstroke.h: Updated.
2011-07-02 12:09:52 +02:00
* Used to render beveled line joins. The outer corner of
* the joined lines is filled by enclosing the triangular
* region of the corner with a straight line between the
* outer corners of each stroke.
*
* FT_STROKER_LINEJOIN_MITER_FIXED ::
* Used to render mitered line joins, with fixed bevels if the
* miter limit is exceeded. The outer edges of the strokes
* for the two segments are extended until they meet at an
* angle. If the segments meet at too sharp an angle (such
2012-01-16 18:00:24 +01:00
* that the miter would extend from the intersection of the
* segments a distance greater than the product of the miter
* limit value and the border radius), then a bevel join (see
* above) is used instead. This prevents long spikes being
* created. FT_STROKER_LINEJOIN_MITER_FIXED generates a miter
[ftstroke] Major revision. The main problems ----------------- o If FT_STROKER_LINEJOIN_BEVEL was specified, unlimited miter joins (not bevel joins) were generated. Indeed, the meanings of `miter' and `bevel' were incorrectly reversed (consistently) in both the code and comments. o The way bevel joins were constructed (whether specified explicitly, or created as a result of exceeding the miter limit) did not match what is required for stroked text in PostScript or PDF. The main fixes -------------- o The behaviour of FT_STROKER_LINEJOIN_BEVEL has been corrected. o A new line join style, FT_STROKER_LINEJOIN_MITER_FIXED, has been introduced to support PostScript and PDF miter joins. o FT_STROKER_LINEJOIN_MITER_VARIABLE has been introduced as an alias for FT_STROKER_LINEJOIN_MITER. Additionally, a variety of stroking errors have been fixed. These would cause various artifacts (including points `at infinity'), especially when stroking poor quality fonts. See http://lists.gnu.org/archive/html/freetype-devel/2011-07/msg00001.html for example documents. The FreeType stroker now produces results very similar to that produced by GhostScript and Distiller for these fonts. Other problems -------------- The following problems have been resolved: o Inside corners could be generated incorrectly. Intersecting the inside corner could cause a missing triangular area and other effects. The intersection point can only be used if the join is between two lines and both lines are long enough. The `optimization' condition in `ft_stroker_inside' has been corrected; this requires the line length to be passed into various functions and stored in `FT_StrokerRec'. o Incorrect cubic curves could be generated. The angle calculations in `FT_Stroker_CubicTo' have been corrected to handle the case of the curve crossing the +/-PI direction. o If the border radius was greater than the radius of curvature of a curve, then the negative sector would end up outside (not inside) the border. This situation is now recognized and the negative sector is circumnavigated in the opposite direction. (If round line joins are being used, this code is disabled because the line join will always cover the negative sector.) o When a curve is split, the arcs may not join smoothly (especially if the curve turns sharply back on itself). Changes in direction between adjacent arcs were not handled. A round corner is now added if the deviation from one arc to the next is greater than a suitable threshold. o The current direction wasn't retained if a the outline contained a zero length lineto or a curve that was determined to be `basically a point'. This could cause a spurious join to be added. o Cubics with close control points could be mishandled. All eight cases are now distinguished correctly. Other improvements ------------------ o Borders for cubic curves could be too `flat'. FT_SMALL_CUBIC_THRESHOLD has been reduced a little to prevent this. o The handling and use of movable points has been simplified a little. o Various values are now computed only if the results are actually needed. o The directions of the outer and inner borders have been swapped, as recommended by Graham Asher. * src/base/ftstroke.c: Revised. * include/freetype/ftstroke.h: Updated.
2011-07-02 12:09:52 +02:00
* line join as used in PostScript and PDF.
*
* FT_STROKER_LINEJOIN_MITER_VARIABLE ::
* FT_STROKER_LINEJOIN_MITER ::
[ftstroke] Major revision. The main problems ----------------- o If FT_STROKER_LINEJOIN_BEVEL was specified, unlimited miter joins (not bevel joins) were generated. Indeed, the meanings of `miter' and `bevel' were incorrectly reversed (consistently) in both the code and comments. o The way bevel joins were constructed (whether specified explicitly, or created as a result of exceeding the miter limit) did not match what is required for stroked text in PostScript or PDF. The main fixes -------------- o The behaviour of FT_STROKER_LINEJOIN_BEVEL has been corrected. o A new line join style, FT_STROKER_LINEJOIN_MITER_FIXED, has been introduced to support PostScript and PDF miter joins. o FT_STROKER_LINEJOIN_MITER_VARIABLE has been introduced as an alias for FT_STROKER_LINEJOIN_MITER. Additionally, a variety of stroking errors have been fixed. These would cause various artifacts (including points `at infinity'), especially when stroking poor quality fonts. See http://lists.gnu.org/archive/html/freetype-devel/2011-07/msg00001.html for example documents. The FreeType stroker now produces results very similar to that produced by GhostScript and Distiller for these fonts. Other problems -------------- The following problems have been resolved: o Inside corners could be generated incorrectly. Intersecting the inside corner could cause a missing triangular area and other effects. The intersection point can only be used if the join is between two lines and both lines are long enough. The `optimization' condition in `ft_stroker_inside' has been corrected; this requires the line length to be passed into various functions and stored in `FT_StrokerRec'. o Incorrect cubic curves could be generated. The angle calculations in `FT_Stroker_CubicTo' have been corrected to handle the case of the curve crossing the +/-PI direction. o If the border radius was greater than the radius of curvature of a curve, then the negative sector would end up outside (not inside) the border. This situation is now recognized and the negative sector is circumnavigated in the opposite direction. (If round line joins are being used, this code is disabled because the line join will always cover the negative sector.) o When a curve is split, the arcs may not join smoothly (especially if the curve turns sharply back on itself). Changes in direction between adjacent arcs were not handled. A round corner is now added if the deviation from one arc to the next is greater than a suitable threshold. o The current direction wasn't retained if a the outline contained a zero length lineto or a curve that was determined to be `basically a point'. This could cause a spurious join to be added. o Cubics with close control points could be mishandled. All eight cases are now distinguished correctly. Other improvements ------------------ o Borders for cubic curves could be too `flat'. FT_SMALL_CUBIC_THRESHOLD has been reduced a little to prevent this. o The handling and use of movable points has been simplified a little. o Various values are now computed only if the results are actually needed. o The directions of the outer and inner borders have been swapped, as recommended by Graham Asher. * src/base/ftstroke.c: Revised. * include/freetype/ftstroke.h: Updated.
2011-07-02 12:09:52 +02:00
* Used to render mitered line joins, with variable bevels if
2012-01-16 18:00:24 +01:00
* the miter limit is exceeded. The intersection of the
* strokes is clipped at a line perpendicular to the bisector
* of the angle between the strokes, at the distance from the
* intersection of the segments equal to the product of the
* miter limit value and the border radius. This prevents
* long spikes being created.
* FT_STROKER_LINEJOIN_MITER_VARIABLE generates a mitered line
* join as used in XPS. FT_STROKER_LINEJOIN_MITER is an alias
* for FT_STROKER_LINEJOIN_MITER_VARIABLE, retained for
[ftstroke] Major revision. The main problems ----------------- o If FT_STROKER_LINEJOIN_BEVEL was specified, unlimited miter joins (not bevel joins) were generated. Indeed, the meanings of `miter' and `bevel' were incorrectly reversed (consistently) in both the code and comments. o The way bevel joins were constructed (whether specified explicitly, or created as a result of exceeding the miter limit) did not match what is required for stroked text in PostScript or PDF. The main fixes -------------- o The behaviour of FT_STROKER_LINEJOIN_BEVEL has been corrected. o A new line join style, FT_STROKER_LINEJOIN_MITER_FIXED, has been introduced to support PostScript and PDF miter joins. o FT_STROKER_LINEJOIN_MITER_VARIABLE has been introduced as an alias for FT_STROKER_LINEJOIN_MITER. Additionally, a variety of stroking errors have been fixed. These would cause various artifacts (including points `at infinity'), especially when stroking poor quality fonts. See http://lists.gnu.org/archive/html/freetype-devel/2011-07/msg00001.html for example documents. The FreeType stroker now produces results very similar to that produced by GhostScript and Distiller for these fonts. Other problems -------------- The following problems have been resolved: o Inside corners could be generated incorrectly. Intersecting the inside corner could cause a missing triangular area and other effects. The intersection point can only be used if the join is between two lines and both lines are long enough. The `optimization' condition in `ft_stroker_inside' has been corrected; this requires the line length to be passed into various functions and stored in `FT_StrokerRec'. o Incorrect cubic curves could be generated. The angle calculations in `FT_Stroker_CubicTo' have been corrected to handle the case of the curve crossing the +/-PI direction. o If the border radius was greater than the radius of curvature of a curve, then the negative sector would end up outside (not inside) the border. This situation is now recognized and the negative sector is circumnavigated in the opposite direction. (If round line joins are being used, this code is disabled because the line join will always cover the negative sector.) o When a curve is split, the arcs may not join smoothly (especially if the curve turns sharply back on itself). Changes in direction between adjacent arcs were not handled. A round corner is now added if the deviation from one arc to the next is greater than a suitable threshold. o The current direction wasn't retained if a the outline contained a zero length lineto or a curve that was determined to be `basically a point'. This could cause a spurious join to be added. o Cubics with close control points could be mishandled. All eight cases are now distinguished correctly. Other improvements ------------------ o Borders for cubic curves could be too `flat'. FT_SMALL_CUBIC_THRESHOLD has been reduced a little to prevent this. o The handling and use of movable points has been simplified a little. o Various values are now computed only if the results are actually needed. o The directions of the outer and inner borders have been swapped, as recommended by Graham Asher. * src/base/ftstroke.c: Revised. * include/freetype/ftstroke.h: Updated.
2011-07-02 12:09:52 +02:00
* backwards compatibility.
*/
2008-05-29 00:17:28 +02:00
typedef enum FT_Stroker_LineJoin_
{
[ftstroke] Major revision. The main problems ----------------- o If FT_STROKER_LINEJOIN_BEVEL was specified, unlimited miter joins (not bevel joins) were generated. Indeed, the meanings of `miter' and `bevel' were incorrectly reversed (consistently) in both the code and comments. o The way bevel joins were constructed (whether specified explicitly, or created as a result of exceeding the miter limit) did not match what is required for stroked text in PostScript or PDF. The main fixes -------------- o The behaviour of FT_STROKER_LINEJOIN_BEVEL has been corrected. o A new line join style, FT_STROKER_LINEJOIN_MITER_FIXED, has been introduced to support PostScript and PDF miter joins. o FT_STROKER_LINEJOIN_MITER_VARIABLE has been introduced as an alias for FT_STROKER_LINEJOIN_MITER. Additionally, a variety of stroking errors have been fixed. These would cause various artifacts (including points `at infinity'), especially when stroking poor quality fonts. See http://lists.gnu.org/archive/html/freetype-devel/2011-07/msg00001.html for example documents. The FreeType stroker now produces results very similar to that produced by GhostScript and Distiller for these fonts. Other problems -------------- The following problems have been resolved: o Inside corners could be generated incorrectly. Intersecting the inside corner could cause a missing triangular area and other effects. The intersection point can only be used if the join is between two lines and both lines are long enough. The `optimization' condition in `ft_stroker_inside' has been corrected; this requires the line length to be passed into various functions and stored in `FT_StrokerRec'. o Incorrect cubic curves could be generated. The angle calculations in `FT_Stroker_CubicTo' have been corrected to handle the case of the curve crossing the +/-PI direction. o If the border radius was greater than the radius of curvature of a curve, then the negative sector would end up outside (not inside) the border. This situation is now recognized and the negative sector is circumnavigated in the opposite direction. (If round line joins are being used, this code is disabled because the line join will always cover the negative sector.) o When a curve is split, the arcs may not join smoothly (especially if the curve turns sharply back on itself). Changes in direction between adjacent arcs were not handled. A round corner is now added if the deviation from one arc to the next is greater than a suitable threshold. o The current direction wasn't retained if a the outline contained a zero length lineto or a curve that was determined to be `basically a point'. This could cause a spurious join to be added. o Cubics with close control points could be mishandled. All eight cases are now distinguished correctly. Other improvements ------------------ o Borders for cubic curves could be too `flat'. FT_SMALL_CUBIC_THRESHOLD has been reduced a little to prevent this. o The handling and use of movable points has been simplified a little. o Various values are now computed only if the results are actually needed. o The directions of the outer and inner borders have been swapped, as recommended by Graham Asher. * src/base/ftstroke.c: Revised. * include/freetype/ftstroke.h: Updated.
2011-07-02 12:09:52 +02:00
FT_STROKER_LINEJOIN_ROUND = 0,
FT_STROKER_LINEJOIN_BEVEL = 1,
FT_STROKER_LINEJOIN_MITER_VARIABLE = 2,
FT_STROKER_LINEJOIN_MITER = FT_STROKER_LINEJOIN_MITER_VARIABLE,
FT_STROKER_LINEJOIN_MITER_FIXED = 3
} FT_Stroker_LineJoin;
/**************************************************************
*
* @enum:
* FT_Stroker_LineCap
*
* @description:
* These values determine how the end of opened sub-paths are
* rendered in a stroke.
*
* @values:
* FT_STROKER_LINECAP_BUTT ::
* The end of lines is rendered as a full stop on the last
* point itself.
*
* FT_STROKER_LINECAP_ROUND ::
* The end of lines is rendered as a half-circle around the
* last point.
*
* FT_STROKER_LINECAP_SQUARE ::
* The end of lines is rendered as a square around the
* last point.
*/
2008-05-29 00:17:28 +02:00
typedef enum FT_Stroker_LineCap_
{
FT_STROKER_LINECAP_BUTT = 0,
FT_STROKER_LINECAP_ROUND,
FT_STROKER_LINECAP_SQUARE
} FT_Stroker_LineCap;
/**************************************************************
*
* @enum:
* FT_StrokerBorder
*
* @description:
* These values are used to select a given stroke border
* in @FT_Stroker_GetBorderCounts and @FT_Stroker_ExportBorder.
*
* @values:
* FT_STROKER_BORDER_LEFT ::
* Select the left border, relative to the drawing direction.
*
* FT_STROKER_BORDER_RIGHT ::
* Select the right border, relative to the drawing direction.
*
* @note:
* Applications are generally interested in the `inside' and `outside'
* borders. However, there is no direct mapping between these and the
* `left' and `right' ones, since this really depends on the glyph's
* drawing orientation, which varies between font formats.
*
* You can however use @FT_Outline_GetInsideBorder and
* @FT_Outline_GetOutsideBorder to get these.
*/
2008-05-29 00:17:28 +02:00
typedef enum FT_StrokerBorder_
{
FT_STROKER_BORDER_LEFT = 0,
FT_STROKER_BORDER_RIGHT
} FT_StrokerBorder;
/**************************************************************
*
* @function:
* FT_Outline_GetInsideBorder
*
* @description:
* Retrieve the @FT_StrokerBorder value corresponding to the
* `inside' borders of a given outline.
*
* @input:
* outline ::
* The source outline handle.
*
* @return:
* The border index. @FT_STROKER_BORDER_RIGHT for empty or invalid
* outlines.
*/
FT_EXPORT( FT_StrokerBorder )
FT_Outline_GetInsideBorder( FT_Outline* outline );
/**************************************************************
*
* @function:
* FT_Outline_GetOutsideBorder
*
* @description:
* Retrieve the @FT_StrokerBorder value corresponding to the
* `outside' borders of a given outline.
*
* @input:
* outline ::
* The source outline handle.
*
* @return:
* The border index. @FT_STROKER_BORDER_LEFT for empty or invalid
* outlines.
*/
FT_EXPORT( FT_StrokerBorder )
FT_Outline_GetOutsideBorder( FT_Outline* outline );
/**************************************************************
*
* @function:
* FT_Stroker_New
*
* @description:
* Create a new stroker object.
*
* @input:
* library ::
* FreeType library handle.
*
* @output:
* astroker ::
* A new stroker object handle. NULL in case of error.
*
* @return:
* FreeType error code. 0~means success.
*/
FT_EXPORT( FT_Error )
FT_Stroker_New( FT_Library library,
FT_Stroker *astroker );
/**************************************************************
*
* @function:
* FT_Stroker_Set
*
* @description:
* Reset a stroker object's attributes.
*
* @input:
* stroker ::
* The target stroker handle.
*
* radius ::
* The border radius.
*
* line_cap ::
* The line cap style.
*
* line_join ::
* The line join style.
*
* miter_limit ::
[ftstroke] Major revision. The main problems ----------------- o If FT_STROKER_LINEJOIN_BEVEL was specified, unlimited miter joins (not bevel joins) were generated. Indeed, the meanings of `miter' and `bevel' were incorrectly reversed (consistently) in both the code and comments. o The way bevel joins were constructed (whether specified explicitly, or created as a result of exceeding the miter limit) did not match what is required for stroked text in PostScript or PDF. The main fixes -------------- o The behaviour of FT_STROKER_LINEJOIN_BEVEL has been corrected. o A new line join style, FT_STROKER_LINEJOIN_MITER_FIXED, has been introduced to support PostScript and PDF miter joins. o FT_STROKER_LINEJOIN_MITER_VARIABLE has been introduced as an alias for FT_STROKER_LINEJOIN_MITER. Additionally, a variety of stroking errors have been fixed. These would cause various artifacts (including points `at infinity'), especially when stroking poor quality fonts. See http://lists.gnu.org/archive/html/freetype-devel/2011-07/msg00001.html for example documents. The FreeType stroker now produces results very similar to that produced by GhostScript and Distiller for these fonts. Other problems -------------- The following problems have been resolved: o Inside corners could be generated incorrectly. Intersecting the inside corner could cause a missing triangular area and other effects. The intersection point can only be used if the join is between two lines and both lines are long enough. The `optimization' condition in `ft_stroker_inside' has been corrected; this requires the line length to be passed into various functions and stored in `FT_StrokerRec'. o Incorrect cubic curves could be generated. The angle calculations in `FT_Stroker_CubicTo' have been corrected to handle the case of the curve crossing the +/-PI direction. o If the border radius was greater than the radius of curvature of a curve, then the negative sector would end up outside (not inside) the border. This situation is now recognized and the negative sector is circumnavigated in the opposite direction. (If round line joins are being used, this code is disabled because the line join will always cover the negative sector.) o When a curve is split, the arcs may not join smoothly (especially if the curve turns sharply back on itself). Changes in direction between adjacent arcs were not handled. A round corner is now added if the deviation from one arc to the next is greater than a suitable threshold. o The current direction wasn't retained if a the outline contained a zero length lineto or a curve that was determined to be `basically a point'. This could cause a spurious join to be added. o Cubics with close control points could be mishandled. All eight cases are now distinguished correctly. Other improvements ------------------ o Borders for cubic curves could be too `flat'. FT_SMALL_CUBIC_THRESHOLD has been reduced a little to prevent this. o The handling and use of movable points has been simplified a little. o Various values are now computed only if the results are actually needed. o The directions of the outer and inner borders have been swapped, as recommended by Graham Asher. * src/base/ftstroke.c: Revised. * include/freetype/ftstroke.h: Updated.
2011-07-02 12:09:52 +02:00
* The miter limit for the FT_STROKER_LINEJOIN_MITER_FIXED and
* FT_STROKER_LINEJOIN_MITER_VARIABLE line join styles,
2013-01-13 01:17:05 +01:00
* expressed as 16.16 fixed-point value.
*
* @note:
* The radius is expressed in the same units as the outline
* coordinates.
2014-11-09 23:21:37 +01:00
*
* This function calls @FT_Stroker_Rewind automatically.
*/
FT_EXPORT( void )
FT_Stroker_Set( FT_Stroker stroker,
FT_Fixed radius,
FT_Stroker_LineCap line_cap,
FT_Stroker_LineJoin line_join,
FT_Fixed miter_limit );
/**************************************************************
*
* @function:
* FT_Stroker_Rewind
*
* @description:
* Reset a stroker object without changing its attributes.
* You should call this function before beginning a new
* series of calls to @FT_Stroker_BeginSubPath or
* @FT_Stroker_EndSubPath.
*
* @input:
* stroker ::
* The target stroker handle.
*/
FT_EXPORT( void )
FT_Stroker_Rewind( FT_Stroker stroker );
/**************************************************************
*
* @function:
* FT_Stroker_ParseOutline
*
* @description:
* A convenience function used to parse a whole outline with
* the stroker. The resulting outline(s) can be retrieved
* later by functions like @FT_Stroker_GetCounts and @FT_Stroker_Export.
*
* @input:
* stroker ::
* The target stroker handle.
*
* outline ::
* The source outline.
*
* opened ::
* A boolean. If~1, the outline is treated as an open path instead
* of a closed one.
*
* @return:
* FreeType error code. 0~means success.
*
* @note:
* If `opened' is~0 (the default), the outline is treated as a closed
* path, and the stroker generates two distinct `border' outlines.
*
* If `opened' is~1, the outline is processed as an open path, and the
* stroker generates a single `stroke' outline.
*
* This function calls @FT_Stroker_Rewind automatically.
*/
FT_EXPORT( FT_Error )
FT_Stroker_ParseOutline( FT_Stroker stroker,
FT_Outline* outline,
FT_Bool opened );
/**************************************************************
*
* @function:
* FT_Stroker_BeginSubPath
*
* @description:
* Start a new sub-path in the stroker.
*
* @input:
* stroker ::
* The target stroker handle.
*
* to ::
* A pointer to the start vector.
*
* open ::
* A boolean. If~1, the sub-path is treated as an open one.
*
* @return:
* FreeType error code. 0~means success.
*
* @note:
* This function is useful when you need to stroke a path that is
* not stored as an @FT_Outline object.
*/
FT_EXPORT( FT_Error )
FT_Stroker_BeginSubPath( FT_Stroker stroker,
FT_Vector* to,
FT_Bool open );
/**************************************************************
*
* @function:
* FT_Stroker_EndSubPath
*
* @description:
* Close the current sub-path in the stroker.
*
* @input:
* stroker ::
* The target stroker handle.
*
* @return:
* FreeType error code. 0~means success.
*
* @note:
* You should call this function after @FT_Stroker_BeginSubPath.
* If the subpath was not `opened', this function `draws' a
* single line segment to the start position when needed.
*/
FT_EXPORT( FT_Error )
FT_Stroker_EndSubPath( FT_Stroker stroker );
/**************************************************************
*
* @function:
* FT_Stroker_LineTo
*
* @description:
* `Draw' a single line segment in the stroker's current sub-path,
* from the last position.
*
* @input:
* stroker ::
* The target stroker handle.
*
* to ::
* A pointer to the destination point.
*
* @return:
* FreeType error code. 0~means success.
*
* @note:
* You should call this function between @FT_Stroker_BeginSubPath and
* @FT_Stroker_EndSubPath.
*/
FT_EXPORT( FT_Error )
FT_Stroker_LineTo( FT_Stroker stroker,
FT_Vector* to );
/**************************************************************
*
* @function:
* FT_Stroker_ConicTo
*
* @description:
* `Draw' a single quadratic Bézier in the stroker's current sub-path,
* from the last position.
*
* @input:
* stroker ::
* The target stroker handle.
*
* control ::
* A pointer to a Bézier control point.
*
* to ::
* A pointer to the destination point.
*
* @return:
* FreeType error code. 0~means success.
*
* @note:
* You should call this function between @FT_Stroker_BeginSubPath and
* @FT_Stroker_EndSubPath.
*/
FT_EXPORT( FT_Error )
FT_Stroker_ConicTo( FT_Stroker stroker,
FT_Vector* control,
FT_Vector* to );
/**************************************************************
*
* @function:
* FT_Stroker_CubicTo
*
* @description:
* `Draw' a single cubic Bézier in the stroker's current sub-path,
* from the last position.
*
* @input:
* stroker ::
* The target stroker handle.
*
* control1 ::
* A pointer to the first Bézier control point.
*
* control2 ::
* A pointer to second Bézier control point.
*
* to ::
* A pointer to the destination point.
*
* @return:
* FreeType error code. 0~means success.
*
* @note:
* You should call this function between @FT_Stroker_BeginSubPath and
* @FT_Stroker_EndSubPath.
*/
FT_EXPORT( FT_Error )
FT_Stroker_CubicTo( FT_Stroker stroker,
FT_Vector* control1,
FT_Vector* control2,
FT_Vector* to );
/**************************************************************
*
* @function:
* FT_Stroker_GetBorderCounts
*
* @description:
* Call this function once you have finished parsing your paths
* with the stroker. It returns the number of points and
* contours necessary to export one of the `border' or `stroke'
* outlines generated by the stroker.
*
* @input:
* stroker ::
* The target stroker handle.
*
* border ::
* The border index.
*
* @output:
* anum_points ::
* The number of points.
*
* anum_contours ::
* The number of contours.
*
* @return:
* FreeType error code. 0~means success.
*
* @note:
* When an outline, or a sub-path, is `closed', the stroker generates
* two independent `border' outlines, named `left' and `right'.
*
* When the outline, or a sub-path, is `opened', the stroker merges
* the `border' outlines with caps. The `left' border receives all
* points, while the `right' border becomes empty.
*
* Use the function @FT_Stroker_GetCounts instead if you want to
* retrieve the counts associated to both borders.
*/
FT_EXPORT( FT_Error )
FT_Stroker_GetBorderCounts( FT_Stroker stroker,
FT_StrokerBorder border,
FT_UInt *anum_points,
FT_UInt *anum_contours );
/**************************************************************
*
* @function:
* FT_Stroker_ExportBorder
*
* @description:
* Call this function after @FT_Stroker_GetBorderCounts to
* export the corresponding border to your own @FT_Outline
* structure.
*
* Note that this function appends the border points and
* contours to your outline, but does not try to resize its
* arrays.
*
* @input:
* stroker ::
* The target stroker handle.
*
* border ::
* The border index.
*
* outline ::
* The target outline handle.
*
* @note:
* Always call this function after @FT_Stroker_GetBorderCounts to
* get sure that there is enough room in your @FT_Outline object to
* receive all new data.
*
* When an outline, or a sub-path, is `closed', the stroker generates
2014-11-09 23:21:37 +01:00
* two independent `border' outlines, named `left' and `right'.
*
* When the outline, or a sub-path, is `opened', the stroker merges
2014-11-09 23:21:37 +01:00
* the `border' outlines with caps. The `left' border receives all
* points, while the `right' border becomes empty.
*
* Use the function @FT_Stroker_Export instead if you want to
* retrieve all borders at once.
*/
FT_EXPORT( void )
FT_Stroker_ExportBorder( FT_Stroker stroker,
FT_StrokerBorder border,
FT_Outline* outline );
/**************************************************************
*
* @function:
* FT_Stroker_GetCounts
*
* @description:
* Call this function once you have finished parsing your paths
* with the stroker. It returns the number of points and
* contours necessary to export all points/borders from the stroked
* outline/path.
*
* @input:
* stroker ::
* The target stroker handle.
*
* @output:
* anum_points ::
* The number of points.
*
* anum_contours ::
* The number of contours.
*
* @return:
* FreeType error code. 0~means success.
*/
FT_EXPORT( FT_Error )
FT_Stroker_GetCounts( FT_Stroker stroker,
FT_UInt *anum_points,
FT_UInt *anum_contours );
/**************************************************************
*
* @function:
* FT_Stroker_Export
*
* @description:
* Call this function after @FT_Stroker_GetBorderCounts to
2009-07-17 10:50:04 +02:00
* export all borders to your own @FT_Outline structure.
*
* Note that this function appends the border points and
* contours to your outline, but does not try to resize its
* arrays.
*
* @input:
* stroker ::
* The target stroker handle.
*
* outline ::
* The target outline handle.
*/
FT_EXPORT( void )
FT_Stroker_Export( FT_Stroker stroker,
FT_Outline* outline );
/**************************************************************
*
* @function:
* FT_Stroker_Done
*
* @description:
* Destroy a stroker object.
*
* @input:
* stroker ::
* A stroker handle. Can be NULL.
*/
FT_EXPORT( void )
FT_Stroker_Done( FT_Stroker stroker );
/**************************************************************
*
* @function:
* FT_Glyph_Stroke
*
* @description:
* Stroke a given outline glyph object with a given stroker.
*
* @inout:
* pglyph ::
* Source glyph handle on input, new glyph handle on output.
*
* @input:
* stroker ::
* A stroker handle.
*
* destroy ::
* A Boolean. If~1, the source glyph object is destroyed
* on success.
*
* @return:
* FreeType error code. 0~means success.
*
* @note:
* The source glyph is untouched in case of error.
*
* Adding stroke may yield a significantly wider and taller glyph
* depending on how large of a radius was used to stroke the glyph. You
* may need to manually adjust horizontal and vertical advance amounts
* to account for this added size.
*/
FT_EXPORT( FT_Error )
FT_Glyph_Stroke( FT_Glyph *pglyph,
FT_Stroker stroker,
FT_Bool destroy );
/**************************************************************
*
* @function:
* FT_Glyph_StrokeBorder
*
* @description:
* Stroke a given outline glyph object with a given stroker, but
* only return either its inside or outside border.
*
* @inout:
* pglyph ::
* Source glyph handle on input, new glyph handle on output.
*
* @input:
* stroker ::
* A stroker handle.
*
* inside ::
* A Boolean. If~1, return the inside border, otherwise
* the outside border.
*
* destroy ::
* A Boolean. If~1, the source glyph object is destroyed
* on success.
*
* @return:
* FreeType error code. 0~means success.
*
* @note:
* The source glyph is untouched in case of error.
*
* Adding stroke may yield a significantly wider and taller glyph
* depending on how large of a radius was used to stroke the glyph. You
* may need to manually adjust horizontal and vertical advance amounts
* to account for this added size.
*/
FT_EXPORT( FT_Error )
FT_Glyph_StrokeBorder( FT_Glyph *pglyph,
FT_Stroker stroker,
FT_Bool inside,
FT_Bool destroy );
/* */
FT_END_HEADER
#endif /* FTSTROKE_H_ */
/* END */
/* Local Variables: */
/* coding: utf-8 */
/* End: */