path: root/src/lib/freetype/ftstroke.inc

{***************************************************************************}
{*                                                                         *}
{*  ftstroke.h                                                             *}
{*                                                                         *}
{*    FreeType path stroker (specification).                               *}
{*                                                                         *}
{*  Copyright 2002, 2003, 2004, 2005, 2006 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.                                        *}
{*                                                                         *}
{***************************************************************************}
(***************************************************************************)
(* Pascal port by the UltraStar Deluxe Team                                *)
(***************************************************************************)

 {************************************************************************
  *
  * @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.
  *}

{$IFDEF TYPE_DECL}

 {**************************************************************
  *
  * @type:
  *   FT_Stroker
  *
  * @description:
  *   Opaque handler to a path stroker object.
  *}
   FT_Stroker = Pointer;


  {**************************************************************
   *
   * @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).
   *}
    FT_Stroker_LineJoin = cint;
{$ELSE TYPE_DECL}
const
    FT_STROKER_LINEJOIN_ROUND = 0;
    FT_STROKER_LINEJOIN_BEVEL = 1;
    FT_STROKER_LINEJOIN_MITER = 2;

{$ENDIF TYPE_DECL}
{$IFDEF TYPE_DECL}

  {**************************************************************
   *
   * @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.
   *}
    FT_Stroker_LineCap = cint;
{$ELSE TYPE_DECL}
const
    FT_STROKER_LINECAP_BUTT   = 0;
    FT_STROKER_LINECAP_ROUND  = 1;
    FT_STROKER_LINECAP_SQUARE = 2;

{$ENDIF TYPE_DECL}
{$IFDEF TYPE_DECL}

  {**************************************************************
   *
   * @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.
   *}
    FT_StrokerBorder = cint;
{$ELSE TYPE_DECL}
const
    FT_STROKER_BORDER_LEFT  = 0;
    FT_STROKER_BORDER_RIGHT = 1;


  {**************************************************************
   *
   * @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_LEFT for empty or invalid
   *   outlines.
   *}
  function FT_Outline_GetInsideBorder( outline: PFT_Outline ): FT_StrokerBorder;
    cdecl; external ft_lib name 'FT_Outline_GetInsideBorder';


  {**************************************************************
   *
   * @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.
   *}
  function FT_Outline_GetOutsideBorder( outline: PFT_Outline ): FT_StrokerBorder;
    cdecl; external ft_lib name 'FT_Outline_GetOutsideBorder';


  {**************************************************************
   *
   * @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.
   *}
  function FT_Stroker_New(
                  library_: FT_Library;
                  out astroker: FT_Stroker ): FT_Error;
    cdecl; external ft_lib name 'FT_Stroker_New';


  {**************************************************************
   *
   * @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 that the outline
   *   coordinates.
   *}
  procedure FT_Stroker_Set(
                  stroker:     FT_Stroker;
                  radius:      FT_Fixed;
                  line_cap:    FT_Stroker_LineCap;
                  line_join:   FT_Stroker_LineJoin;
                  miter_limit: FT_Fixed );
    cdecl; external ft_lib name 'FT_Stroker_Set';


  {**************************************************************
   *
   * @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.
   *}
  procedure FT_Stroker_Rewind( stroker: FT_Stroker );
    cdecl; external ft_lib name 'FT_Stroker_Rewind';


  {**************************************************************
   *
   * @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 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.
   *}
  function FT_Stroker_ParseOutline(
                           stroker: FT_Stroker;
                           outline: PFT_Outline;
                           opened:  FT_Bool): FT_Error;
    cdecl; external ft_lib name 'FT_Stroker_ParseOutline';


  {**************************************************************
   *
   * @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.
   *}
  function FT_Stroker_BeginSubPath(
                           stroker: FT_Stroker;
                           to_:     PFT_Vector;
                           open:    FT_Bool ): FT_Error;
    cdecl; external ft_lib name 'FT_Stroker_BeginSubPath';


  {**************************************************************
   *
   * @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 will `draw' a
   *   single line segment to the start position when needed.
   *}
  function FT_Stroker_EndSubPath( stroker: FT_Stroker ): FT_Error;
    cdecl; external ft_lib name 'FT_Stroker_EndSubPath';


  {**************************************************************
   *
   * @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.
   *}
  function FT_Stroker_LineTo(
                     stroker: FT_Stroker;
                     to_:     PFT_Vector ): FT_Error;
    cdecl; external ft_lib name 'FT_Stroker_LineTo';


  {**************************************************************
   *
   * @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.
   *}
  function FT_Stroker_ConicTo(
                      stroker: FT_Stroker;
                      control: PFT_Vector;
                      to_:     PFT_Vector ): FT_Error;
    cdecl; external ft_lib name 'FT_Stroker_ConicTo';


  {**************************************************************
   *
   * @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.
   *}
  function FT_Stroker_CubicTo(
                      stroker:  FT_Stroker;
                      control1: PFT_Vector;
                      control2: PFT_Vector;
                      to_:      PFT_Vector ): FT_Error;
    cdecl; external ft_lib name 'FT_Stroker_CubicTo';


  {**************************************************************
   *
   * @function:
   *   FT_Stroker_GetBorderCounts
   *
   * @description:
   *   Call 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.
   *}
  function FT_Stroker_GetBorderCounts(
                              stroker:           FT_Stroker;
                              border:            FT_StrokerBorder;
                              out anum_points:   FT_UInt;
                              out anum_contours: FT_UInt ): FT_Error;
    cdecl; external ft_lib name 'FT_Stroker_GetBorderCounts';


  {**************************************************************
   *
   * @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 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.
   *}
  procedure FT_Stroker_ExportBorder(
                           stroker: FT_Stroker;
                           border:  FT_StrokerBorder;
                           outline: PFT_Outline );
    cdecl; external ft_lib name 'FT_Stroker_ExportBorder';


  {**************************************************************
   *
   * @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.
   *}
  function FT_Stroker_GetCounts(
                        stroker:           FT_Stroker;
                        out anum_points:   FT_UInt;
                        out anum_contours: FT_UInt ): FT_Error;
     cdecl; external ft_lib name 'FT_Stroker_GetCounts';


  {**************************************************************
   *
   * @function:
   *   FT_Stroker_Export
   *
   * @description:
   *   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.
   *}
  procedure FT_Stroker_Export(
                     stroker: FT_Stroker;
                     outline: PFT_Outline );
     cdecl; external ft_lib name 'FT_Stroker_Export';


  {**************************************************************
   *
   * @function:
   *   FT_Stroker_Done
   *
   * @description:
   *   Destroy a stroker object.
   *
   * @input:
   *   stroker ::
   *     A stroker handle.  Can be NULL.
   *}
  procedure FT_Stroker_Done( stroker: FT_Stroker );
     cdecl; external ft_lib name 'FT_Stroker_Done';


  {**************************************************************
   *
   * @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.
   *}
  function FT_Glyph_Stroke(
                   var glyph: FT_Glyph;
                   stroker: FT_Stroker;
                   destroy: FT_Bool ): FT_Error;
     cdecl; external ft_lib name 'FT_Glyph_Stroke';


  {**************************************************************
   *
   * @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.
   *}
  function FT_Glyph_StrokeBorder(
                         var glyph: FT_Glyph;
                         stroker:   FT_Stroker;
                         inside:    FT_Bool;
                         destroy:   FT_Bool ): FT_Error;
     cdecl; external ft_lib name 'FT_Glyph_StrokeBorder';

{$ENDIF TYPE_DECL}