FreeType-2.1.10 API Reference

Glyph Stroker

Synopsis

FT_StrokerFT_Stroker_EndSubPath
FT_Stroker_LineJoinFT_Stroker_LineTo
FT_Stroker_LineCapFT_Stroker_ConicTo
FT_StrokerBorderFT_Stroker_CubicTo
FT_Outline_GetInsideBorderFT_Stroker_GetBorderCounts
FT_Outline_GetOutsideBorderFT_Stroker_ExportBorder
FT_Stroker_NewFT_Stroker_GetCounts
FT_Stroker_SetFT_Stroker_Export
FT_Stroker_RewindFT_Stroker_Done
FT_Stroker_ParseOutlineFT_Glyph_Stroke
FT_Stroker_BeginSubPathFT_Glyph_StrokeBorder


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.


FT_Stroker


  typedef struct FT_StrokerRec_*  FT_Stroker;


Opaque handler to a path stroker object.



FT_Stroker_LineJoin


  typedef enum
  {
    FT_STROKER_LINEJOIN_ROUND = 0,
    FT_STROKER_LINEJOIN_BEVEL,
    FT_STROKER_LINEJOIN_MITER

  } FT_Stroker_LineJoin;


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).


FT_Stroker_LineCap


  typedef enum
  {
    FT_STROKER_LINECAP_BUTT = 0,
    FT_STROKER_LINECAP_ROUND,
    FT_STROKER_LINECAP_SQUARE

  } FT_Stroker_LineCap;


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.


FT_StrokerBorder


  typedef enum
  {
    FT_STROKER_BORDER_LEFT = 0,
    FT_STROKER_BORDER_RIGHT

  } FT_StrokerBorder;


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' / `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.


FT_Outline_GetInsideBorder


  FT_EXPORT( FT_StrokerBorder )
  FT_Outline_GetInsideBorder( FT_Outline*  outline );


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_LEFT for empty or invalid outlines.


FT_Outline_GetOutsideBorder


  FT_EXPORT( FT_StrokerBorder )
  FT_Outline_GetOutsideBorder( FT_Outline*  outline );


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_Stroker_New


  FT_EXPORT( FT_Error )
  FT_Stroker_New( FT_Memory    memory,
                  FT_Stroker  *astroker );


Create a new stroker object.


input
memory

The memory manager handle.

output

A new stroker object handle. NULL in case of error.

return

FreeType error code. 0 means success.


FT_Stroker_Set


  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 );


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 that the outline coordinates.


FT_Stroker_Rewind


  FT_EXPORT( void )
  FT_Stroker_Rewind( FT_Stroker  stroker );


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_Stroker_ParseOutline


  FT_EXPORT( FT_Error )
  FT_Stroker_ParseOutline( FT_Stroker   stroker,
                           FT_Outline*  outline,
                           FT_Bool      opened );


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 TRUE, 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 will generate two distinct `border' outlines.

If `opened' is 1, the outline is processed as an open path, and the stroker will generate a single `stroke' outline.

This function calls FT_Stroker_Rewind automatically.


FT_Stroker_BeginSubPath


  FT_EXPORT( FT_Error )
  FT_Stroker_BeginSubPath( FT_Stroker  stroker,
                           FT_Vector*  to,
                           FT_Bool     open );


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 TRUE, 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 a FT_Outline object.


FT_Stroker_EndSubPath


  FT_EXPORT( FT_Error )
  FT_Stroker_EndSubPath( FT_Stroker  stroker );


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 will `draw' a single line segment to the start position when needed.


FT_Stroker_LineTo


  FT_EXPORT( FT_Error )
  FT_Stroker_LineTo( FT_Stroker  stroker,
                     FT_Vector*  to );


`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_Stroker_ConicTo


  FT_EXPORT( FT_Error )
  FT_Stroker_ConicTo( FT_Stroker  stroker,
                      FT_Vector*  control,
                      FT_Vector*  to );


`Draw; a single quadratic bezier 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_Stroker_CubicTo


  FT_EXPORT( FT_Error )
  FT_Stroker_CubicTo( FT_Stroker  stroker,
                      FT_Vector*  control1,
                      FT_Vector*  control2,
                      FT_Vector*  to );


`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_Stroker_GetBorderCounts


  FT_EXPORT( FT_Error )
  FT_Stroker_GetBorderCounts( FT_Stroker        stroker,
                              FT_StrokerBorder  border,
                              FT_UInt          *anum_points,
                              FT_UInt          *anum_contours );


Vall this function once you have finished parsing your paths with the stroker. It will return 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_Stroker_ExportBorder


  FT_EXPORT( void )
  FT_Stroker_ExportBorder( FT_Stroker        stroker,
                           FT_StrokerBorder  border,
                           FT_Outline*       outline );


Call this function after FT_Stroker_GetBorderCounts to export the corresponding border to your own FT_Outline structure.

Note that this function will append the border points and contours to your outline, but will 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_Stroker_GetCounts


  FT_EXPORT( FT_Error )
  FT_Stroker_GetCounts( FT_Stroker  stroker,
                        FT_UInt    *anum_points,
                        FT_UInt    *anum_contours );


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_Stroker_Export


  FT_EXPORT( void )
  FT_Stroker_Export( FT_Stroker   stroker,
                     FT_Outline*  outline );


Call this function after FT_Stroker_GetBorderCounts to export the all borders to your own FT_Outline structure.

Note that this function will append the border points and contours to your outline, but will not try to resize its arrays.


input
stroker

The target stroker handle.

outline

The target outline handle.


FT_Stroker_Done


  FT_EXPORT( void )
  FT_Stroker_Done( FT_Stroker  stroker );


Destroy a stroker object.


input
stroker

A stroker handle. Can be NULL.


FT_Glyph_Stroke


  FT_EXPORT( FT_Error )
  FT_Glyph_Stroke( FT_Glyph    *pglyph,
                   FT_Stroker   stroker,
                   FT_Bool      destroy );


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 TRUE, 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_Glyph_StrokeBorder


  FT_EXPORT( FT_Error )
  FT_Glyph_StrokeBorder( FT_Glyph    *pglyph,
                         FT_Stroker   stroker,
                         FT_Bool      inside,
                         FT_Bool      destroy );


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 TRUE, return the inside border, otherwise the outside border.

destroy

A Boolean. If TRUE, 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.