# FreeType-2.1.8 API Reference

# SFNT Names

## Synopsis

| FT_SfntName |  | FT_Stroker_EndSubPath
| FT_Get_Sfnt_Name_Count |  | FT_Stroker_LineTo
| FT_Get_Sfnt_Name |  | FT_Stroker_ConicTo
| FT_StrokerBorder |  | FT_Stroker_CubicTo
| FT_Outline_GetInsideBorder |  | FT_Stroker_GetBorderCounts
| FT_Outline_GetOutsideBorder |  | FT_Stroker_ExportBorder
| FT_Stroker_New |  | FT_Stroker_GetCounts
| FT_Stroker_Set |  | FT_Stroker_Export
| FT_Stroker_Rewind |  | FT_Stroker_Done
| FT_Stroker_ParseOutline |  | FT_Glyph_Stroke
| FT_Stroker_BeginSubPath |  | FT_Glyph_StrokeBorder

The TrueType and OpenType specification allow the inclusion of a special `names table' in font files. This table contains textual (and internationalized) information regarding the font, like family name, copyright, version, etc. The definitions below are used to access them if available. Note that this has nothing to do with glyph names!

#### FT_SfntName

      typedef struct  FT_SfntName_
      {
        FT_UShort  platform_id;
        FT_UShort  encoding_id;
        FT_UShort  language_id;
        FT_UShort  name_id;

        FT_Byte*   string;      /* this string is *not* null-terminated! */
        FT_UInt    string_len;  /* in bytes */

      } FT_SfntName;

A structure used to model an SFNT `name' table entry.

fields

platform_id | The platform ID for `string'.
encoding_id | The encoding ID for `string'.
language_id | The language ID for `string'.
name_id | An identifier for `string'.
string | The `name' string. Note that its format differs depending on the (platform,encoding) pair. It can be a Pascal String, a UTF-16 one, etc.. Generally speaking, the string is not zero-terminated. Please refer to the TrueType specification for details..
string_len | The length of `string' in bytes.

note
Possible values for `platform_id', `encoding_id', `language_id', and `name_id' are given in the file `ttnameid.h'. For details please refer to the TrueType or OpenType specification.

#### FT_Get_Sfnt_Name_Count

      FT_EXPORT( FT_UInt )
      FT_Get_Sfnt_Name_Count( FT_Face  face );

Retrieves the number of name strings in the SFNT `name' table.

input

face | A handle to the source face.

return
The number of strings in the `name' table.

#### FT_Get_Sfnt_Name

      FT_EXPORT( FT_Error )
      FT_Get_Sfnt_Name( FT_Face       face,
                        FT_UInt       idx,
                        FT_SfntName  *aname );

Retrieves a string of the SFNT `name' table for a given index.

input

face | A handle to the source face.
idx | The index of the `name' string.

output

aname | The indexed FT_SfntName structure.

return
FreeType error code. 0 means success.

note
The `string' array returned in the `aname' structure is not null-terminated. Use FT_Get_Sfnt_Name_Count() to get the total number of available `name' table entries, then do a loop until you get the right platform, encoding, and name ID.

#### 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. /