/***************************************************************************/ | |
/* */ | |
/* ftstroke.h */ | |
/* */ | |
/* FreeType path stroker (specification). */ | |
/* */ | |
/* Copyright 2002-2015 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 __FT_STROKE_H__ | |
#define __FT_STROKE_H__ | |
#include <ft2build.h> | |
#include FT_OUTLINE_H | |
#include FT_GLYPH_H | |
FT_BEGIN_HEADER | |
/************************************************************************ | |
* | |
* @section: | |
* glyph_stroker | |
* | |
* @title: | |
* Glyph Stroker | |
* | |
* @abstract: | |
* Generating bordered and stroked glyphs. | |
* | |
* @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 :: | |
* 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 | |
* 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 | |
* line join as used in PostScript and PDF. | |
* | |
* FT_STROKER_LINEJOIN_MITER_VARIABLE :: | |
* FT_STROKER_LINEJOIN_MITER :: | |
* Used to render mitered line joins, with variable bevels if | |
* 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 | |
* backwards compatibility. | |
*/ | |
typedef enum FT_Stroker_LineJoin_ | |
{ | |
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. | |
*/ | |
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. | |
*/ | |
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 :: | |
* The miter limit for the FT_STROKER_LINEJOIN_MITER_FIXED and | |
* FT_STROKER_LINEJOIN_MITER_VARIABLE line join styles, | |
* expressed as 16.16 fixed-point value. | |
* | |
* @note: | |
* The radius is expressed in the same units as the outline | |
* coordinates. | |
* | |
* 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 | |
* 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_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 | |
* 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 /* __FT_STROKE_H__ */ | |
/* END */ | |
/* Local Variables: */ | |
/* coding: utf-8 */ | |
/* End: */ |