0,0 → 1,716 |
/***************************************************************************/ |
/* */ |
/* ftstroke.h */ |
/* */ |
/* FreeType path stroker (specification). */ |
/* */ |
/* Copyright 2002, 2003, 2004, 2005, 2006, 2008, 2009 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. |
*/ |
|
|
/************************************************************** |
* |
* @type: |
* FT_Stroker |
* |
* @description: |
* Opaque handler 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; i.e., the two joining lines |
* are extended until they intersect. |
* |
* FT_STROKER_LINEJOIN_MITER :: |
* Same as beveled rendering, except that an additional line |
* break is added if the angle between the two joining lines |
* is too closed (this is useful to avoid unpleasant spikes |
* in beveled rendering). |
*/ |
typedef enum FT_Stroker_LineJoin_ |
{ |
FT_STROKER_LINEJOIN_ROUND = 0, |
FT_STROKER_LINEJOIN_BEVEL, |
FT_STROKER_LINEJOIN_MITER |
|
} 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 style, |
* expressed as 16.16 fixed point value. |
* |
* @note: |
* The radius is expressed in the same units as the outline |
* coordinates. |
*/ |
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. |
*/ |
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. |
*/ |
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: */ |