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

(***************************************************************************)
(*                                                                         *)
(*  ftoutln.h                                                              *)
(*                                                                         *)
(*    Support for the FT_Outline type used to store glyph shapes of        *)
(*    most scalable font formats (specification).                          *)
(*                                                                         *)
(*  Copyright 1996-2001, 2002, 2003, 2005, 2006, 2007 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>                                                             *)
  (*    outline_processing                                                 *)
  (*                                                                       *)
  (* <Title>                                                               *)
  (*    Outline Processing                                                 *)
  (*                                                                       *)
  (* <Abstract>                                                            *)
  (*    Functions to create, transform, and render vectorial glyph images. *)
  (*                                                                       *)
  (* <Description>                                                         *)
  (*    This section contains routines used to create and destroy scalable *)
  (*    glyph images known as `outlines'.  These can also be measured,     *)
  (*    transformed, and converted into bitmaps and pixmaps.               *)
  (*                                                                       *)
  (* <Order>                                                               *)
  (*    FT_Outline                                                         *)
  (*    FT_OUTLINE_FLAGS                                                   *)
  (*    FT_Outline_New                                                     *)
  (*    FT_Outline_Done                                                    *)
  (*    FT_Outline_Copy                                                    *)
  (*    FT_Outline_Translate                                               *)
  (*    FT_Outline_Transform                                               *)
  (*    FT_Outline_Embolden                                                *)
  (*    FT_Outline_Reverse                                                 *)
  (*    FT_Outline_Check                                                   *)
  (*                                                                       *)
  (*    FT_Outline_Get_CBox                                                *)
  (*    FT_Outline_Get_BBox                                                *)
  (*                                                                       *)
  (*    FT_Outline_Get_Bitmap                                              *)
  (*    FT_Outline_Render                                                  *)
  (*                                                                       *)
  (*    FT_Outline_Decompose                                               *)
  (*    FT_Outline_Funcs                                                   *)
  (*    FT_Outline_MoveTo_Func                                             *)
  (*    FT_Outline_LineTo_Func                                             *)
  (*    FT_Outline_ConicTo_Func                                            *)
  (*    FT_Outline_CubicTo_Func                                            *)
  (*                                                                       *)
  (*************************************************************************)

{$IFNDEF TYPE_DECL}

  (*************************************************************************)
  (*                                                                       *)
  (* <Function>                                                            *)
  (*    FT_Outline_Decompose                                               *)
  (*                                                                       *)
  (* <Description>                                                         *)
  (*    Walks over an outline's structure to decompose it into individual  *)
  (*    segments and Bézier arcs.  This function is also able to emit      *)
  (*    `move to' and `close to' operations to indicate the start and end  *)
  (*    of new contours in the outline.                                    *)
  (*                                                                       *)
  (* <Input>                                                               *)
  (*    outline        :: A pointer to the source target.                  *)
  (*                                                                       *)
  (*    func_interface :: A table of `emitters', i.e,. function pointers   *)
  (*                      called during decomposition to indicate path     *)
  (*                      operations.                                      *)
  (*                                                                       *)
  (* <InOut>                                                               *)
  (*    user           :: A typeless pointer which is passed to each       *)
  (*                      emitter during the decomposition.  It can be     *)
  (*                      used to store the state during the               *)
  (*                      decomposition.                                   *)
  (*                                                                       *)
  (* <Return>                                                              *)
  (*    FreeType error code.  0 means success.                             *)
  (*                                                                       *)
  function FT_Outline_Decompose(
                        outline:        PFT_Outline;
                        func_interface: {const} PFT_Outline_Funcs;
                        user:           Pointer): FT_Error;
    cdecl; external ft_lib name 'FT_Outline_Decompose';

    
  (*************************************************************************)
  (*                                                                       *)
  (* <Function>                                                            *)
  (*    FT_Outline_New                                                     *)
  (*                                                                       *)
  (* <Description>                                                         *)
  (*    Creates a new outline of a given size.                             *)
  (*                                                                       *)
  (* <Input>                                                               *)
  (*    library     :: A handle to the library object from where the       *)
  (*                   outline is allocated.  Note however that the new    *)
  (*                   outline will *not* necessarily be *freed*, when     *)
  (*                   destroying the library, by @FT_Done_FreeType.       *)
  (*                                                                       *)
  (*    numPoints   :: The maximal number of points within the outline.    *)
  (*                                                                       *)
  (*    numContours :: The maximal number of contours within the outline.  *)
  (*                                                                       *)
  (* <Output>                                                              *)
  (*    anoutline   :: A handle to the new outline.  NULL in case of       *)
  (*                   error.                                              *)
  (*                                                                       *)
  (* <Return>                                                              *)
  (*    FreeType error code.  0 means success.                             *)
  (*                                                                       *)
  (* <Note>                                                                *)
  (*    The reason why this function takes a `library' parameter is simply *)
  (*    to use the library's memory allocator.                             *)
  (*                                                                       *)
  function FT_Outline_New(
                  library_:    FT_Library;
                  numPoints:   FT_UInt;
                  numContours: FT_Int;
                  anoutline:   PFT_Outline): FT_Error;
    cdecl; external ft_lib name 'FT_Outline_New';

                  
  (*************************************************************************)
  (*                                                                       *)
  (* <Function>                                                            *)
  (*    FT_Outline_Done                                                    *)
  (*                                                                       *)
  (* <Description>                                                         *)
  (*    Destroys an outline created with @FT_Outline_New.                  *)
  (*                                                                       *)
  (* <Input>                                                               *)
  (*    library :: A handle of the library object used to allocate the     *)
  (*               outline.                                                *)
  (*                                                                       *)
  (*    outline :: A pointer to the outline object to be discarded.        *)
  (*                                                                       *)
  (* <Return>                                                              *)
  (*    FreeType error code.  0 means success.                             *)
  (*                                                                       *)
  (* <Note>                                                                *)
  (*    If the outline's `owner' field is not set, only the outline        *)
  (*    descriptor will be released.                                       *)
  (*                                                                       *)
  (*    The reason why this function takes an `library' parameter is       *)
  (*    simply to use ft_mem_free().                                       *)
  (*                                                                       *)
  function FT_Outline_Done(library_: FT_Library;
                           outline:  PFT_Outline): FT_Error;
    cdecl; external ft_lib name 'FT_Outline_Done';


  (*************************************************************************)
  (*                                                                       *)
  (* <Function>                                                            *)
  (*    FT_Outline_Check                                                   *)
  (*                                                                       *)
  (* <Description>                                                         *)
  (*    Check the contents of an outline descriptor.                       *)
  (*                                                                       *)
  (* <Input>                                                               *)
  (*    outline :: A handle to a source outline.                           *)
  (*                                                                       *)
  (* <Return>                                                              *)
  (*    FreeType error code.  0 means success.                             *)
  (*                                                                       *)
  function FT_Outline_Check( outline: PFT_Outline ): FT_Error;
    cdecl; external ft_lib name 'FT_Outline_Check';


  (*************************************************************************)
  (*                                                                       *)
  (* <Function>                                                            *)
  (*    FT_Outline_Get_CBox                                                *)
  (*                                                                       *)
  (* <Description>                                                         *)
  (*    Returns an outline's `control box'.  The control box encloses all  *)
  (*    the outline's points, including Bézier control points.  Though it  *)
  (*    coincides with the exact bounding box for most glyphs, it can be   *)
  (*    slightly larger in some situations (like when rotating an outline  *)
  (*    which contains Bézier outside arcs).                               *)
  (*                                                                       *)
  (*    Computing the control box is very fast, while getting the bounding *)
  (*    box can take much more time as it needs to walk over all segments  *)
  (*    and arcs in the outline.  To get the latter, you can use the       *)
  (*    `ftbbox' component which is dedicated to this single task.         *)
  (*                                                                       *)
  (* <Input>                                                               *)
  (*    outline :: A pointer to the source outline descriptor.             *)
  (*                                                                       *)
  (* <Output>                                                              *)
  (*    acbox   :: The outline's control box.                              *)
  (*                                                                       *)
  procedure FT_Outline_Get_CBox(
                       outline: {const} PFT_Outline;
                       acbox: PFT_BBox);
    cdecl; external ft_lib name 'FT_Outline_Get_CBox';


  (*************************************************************************)
  (*                                                                       *)
  (* <Function>                                                            *)
  (*    FT_Outline_Translate                                               *)
  (*                                                                       *)
  (* <Description>                                                         *)
  (*    Applies a simple translation to the points of an outline.          *)
  (*                                                                       *)
  (* <InOut>                                                               *)
  (*    outline :: A pointer to the target outline descriptor.             *)
  (*                                                                       *)
  (* <Input>                                                               *)
  (*    xOffset :: The horizontal offset.                                  *)
  (*                                                                       *)
  (*    yOffset :: The vertical offset.                                    *)
  (*                                                                       *)
  procedure FT_Outline_Translate(
                        outline: {const} PFT_Outline;
                        xOffset: FT_Pos;
                        yOffset: FT_Pos);
    cdecl; external ft_lib name 'FT_Outline_Translate';


  (*************************************************************************)
  (*                                                                       *)
  (* <Function>                                                            *)
  (*    FT_Outline_Copy                                                    *)
  (*                                                                       *)
  (* <Description>                                                         *)
  (*    Copies an outline into another one.  Both objects must have the    *)
  (*    same sizes (number of points & number of contours) when this       *)
  (*    function is called.                                                *)
  (*                                                                       *)
  (* <Input>                                                               *)
  (*    source :: A handle to the source outline.                          *)
  (*                                                                       *)
  (* <Output>                                                              *)
  (*    target :: A handle to the target outline.                          *)
  (*                                                                       *)
  (* <Return>                                                              *)
  (*    FreeType error code.  0 means success.                             *)
  (*                                                                       *)
  function FT_Outline_Copy(
                   source: {const} PFT_Outline;
                   target: PFT_Outline): FT_Error;
    cdecl; external ft_lib name 'FT_Outline_Copy';


  (*************************************************************************)
  (*                                                                       *)
  (* <Function>                                                            *)
  (*    FT_Outline_Transform                                               *)
  (*                                                                       *)
  (* <Description>                                                         *)
  (*    Applies a simple 2x2 matrix to all of an outline's points.  Useful *)
  (*    for applying rotations, slanting, flipping, etc.                   *)
  (*                                                                       *)
  (* <InOut>                                                               *)
  (*    outline :: A pointer to the target outline descriptor.             *)
  (*                                                                       *)
  (* <Input>                                                               *)
  (*    matrix  :: A pointer to the transformation matrix.                 *)
  (*                                                                       *)
  (* <Note>                                                                *)
  (*    You can use @FT_Outline_Translate if you need to translate the     *)
  (*    outline's points.                                                  *)
  (*                                                                       *)
  procedure FT_Outline_Transform(
                        outline: {const} PFT_Outline;
                        matrix:  {const} PFT_Matrix);
    cdecl; external ft_lib name 'FT_Outline_Transform';


  (*************************************************************************)
  (*                                                                       *)
  (* <Function>                                                            *)
  (*    FT_Outline_Embolden                                                *)
  (*                                                                       *)
  (* <Description>                                                         *)
  (*    Emboldens an outline.  The new outline will be at most 4 times     *)
  (*    `strength' pixels wider and higher.  You may think of the left and *)
  (*    bottom borders as unchanged.                                       *)
  (*                                                                       *)
  (*    Negative `strength' values to reduce the outline thickness are     *)
  (*    possible also.                                                     *)
  (*                                                                       *)
  (* <InOut>                                                               *)
  (*    outline  :: A handle to the target outline.                        *)
  (*                                                                       *)
  (* <Input>                                                               *)
  (*    strength :: How strong the glyph is emboldened.  Expressed in      *)
  (*                26.6 pixel format.                                     *)
  (*                                                                       *)
  (* <Return>                                                              *)
  (*    FreeType error code.  0 means success.                             *)
  (*                                                                       *)
  (* <Note>                                                                *)
  (*    The used algorithm to increase or decrease the thickness of the    *)
  (*    glyph doesn't change the number of points; this means that certain *)
  (*    situations like acute angles or intersections are sometimes        *)
  (*    handled incorrectly.                                               *)
  (*                                                                       *)
  (*    Example call:                                                      *)
  (*                                                                       *)
  (*    {                                                                  *)
  (*      FT_Load_Glyph( face, index, FT_LOAD_DEFAULT );                   *)
  (*      if ( face->slot->format == FT_GLYPH_FORMAT_OUTLINE )             *)
  (*        FT_Outline_Embolden( &face->slot->outline, strength );         *)
  (*    }                                                                  *)
  (*                                                                       *)
  function FT_Outline_Embolden(
                       outline:  PFT_Outline;
                       strength: FT_Pos): FT_Error;
    cdecl; external ft_lib name 'FT_Outline_Embolden';


  (*************************************************************************)
  (*                                                                       *)
  (* <Function>                                                            *)
  (*    FT_Outline_Reverse                                                 *)
  (*                                                                       *)
  (* <Description>                                                         *)
  (*    Reverses the drawing direction of an outline.  This is used to     *)
  (*    ensure consistent fill conventions for mirrored glyphs.            *)
  (*                                                                       *)
  (* <InOut>                                                               *)
  (*    outline :: A pointer to the target outline descriptor.             *)
  (*                                                                       *)
  (* <Note>                                                                *)
  (*    This functions toggles the bit flag @FT_OUTLINE_REVERSE_FILL in    *)
  (*    the outline's `flags' field.                                       *)
  (*                                                                       *)
  (*    It shouldn't be used by a normal client application, unless it     *)
  (*    knows what it is doing.                                            *)
  (*                                                                       *)
  procedure FT_Outline_Reverse( outline: PFT_Outline );
    cdecl; external ft_lib name 'FT_Outline_Reverse';


  (*************************************************************************)
  (*                                                                       *)
  (* <Function>                                                            *)
  (*    FT_Outline_Get_Bitmap                                              *)
  (*                                                                       *)
  (* <Description>                                                         *)
  (*    Renders an outline within a bitmap.  The outline's image is simply *)
  (*    OR-ed to the target bitmap.                                        *)
  (*                                                                       *)
  (* <Input>                                                               *)
  (*    library :: A handle to a FreeType library object.                  *)
  (*                                                                       *)
  (*    outline :: A pointer to the source outline descriptor.             *)
  (*                                                                       *)
  (* <InOut>                                                               *)
  (*    abitmap :: A pointer to the target bitmap descriptor.              *)
  (*                                                                       *)
  (* <Return>                                                              *)
  (*    FreeType error code.  0 means success.                             *)
  (*                                                                       *)
  (* <Note>                                                                *)
  (*    This function does NOT CREATE the bitmap, it only renders an       *)
  (*    outline image within the one you pass to it!                       *)
  (*                                                                       *)
  (*    It will use the raster corresponding to the default glyph format.  *)
  (*                                                                       *)
  function FT_Outline_Get_Bitmap(
                         library_: FT_Library;
                         outline:  PFT_Outline;
                         abitmap:  {const} PFT_Bitmap): FT_Error;
    cdecl; external ft_lib name 'FT_Outline_Get_Bitmap';


  (*************************************************************************)
  (*                                                                       *)
  (* <Function>                                                            *)
  (*    FT_Outline_Render                                                  *)
  (*                                                                       *)
  (* <Description>                                                         *)
  (*    Renders an outline within a bitmap using the current scan-convert. *)
  (*    This functions uses an @FT_Raster_Params structure as an argument, *)
  (*    allowing advanced features like direct composition, translucency,  *)
  (*    etc.                                                               *)
  (*                                                                       *)
  (* <Input>                                                               *)
  (*    library :: A handle to a FreeType library object.                  *)
  (*                                                                       *)
  (*    outline :: A pointer to the source outline descriptor.             *)
  (*                                                                       *)
  (* <InOut>                                                               *)
  (*    params  :: A pointer to an @FT_Raster_Params structure used to     *)
  (*               describe the rendering operation.                       *)
  (*                                                                       *)
  (* <Return>                                                              *)
  (*    FreeType error code.  0 means success.                             *)
  (*                                                                       *)
  (* <Note>                                                                *)
  (*    You should know what you are doing and how @FT_Raster_Params works *)
  (*    to use this function.                                              *)
  (*                                                                       *)
  (*    The field `params.source' will be set to `outline' before the scan *)
  (*    converter is called, which means that the value you give to it is  *)
  (*    actually ignored.                                                  *)
  (*                                                                       *)
  function FT_Outline_Render(
                     library_: FT_Library;
                     outline: PFT_Outline;
                     params:  PFT_Raster_Params): FT_Error;
    cdecl; external ft_lib name 'FT_Outline_Render';

{$ENDIF TYPE_DECL}

 (**************************************************************************
  *
  * @enum:
  *   FT_Orientation
  *
  * @description:
  *   A list of values used to describe an outline's contour orientation.
  *
  *   The TrueType and Postscript specifications use different conventions
  *   to determine whether outline contours should be filled or unfilled.
  *
  * @values:
  *   FT_ORIENTATION_TRUETYPE ::
  *     According to the TrueType specification, clockwise contours must
  *     be filled, and counter-clockwise ones must be unfilled.
  *
  *   FT_ORIENTATION_POSTSCRIPT ::
  *     According to the Postscript specification, counter-clockwise contours
  *     must be filled, and clockwise ones must be unfilled.
  *
  *   FT_ORIENTATION_FILL_RIGHT ::
  *     This is identical to @FT_ORIENTATION_TRUETYPE, but is used to
  *     remember that in TrueType, everything that is to the right of
  *     the drawing direction of a contour must be filled.
  *
  *   FT_ORIENTATION_FILL_LEFT ::
  *     This is identical to @FT_ORIENTATION_POSTSCRIPT, but is used to
  *     remember that in Postscript, everything that is to the left of
  *     the drawing direction of a contour must be filled.
  *
  *   FT_ORIENTATION_NONE ::
  *     The orientation cannot be determined.  That is, different parts of
  *     the glyph have different orientation.
  *
  *)
{$IFDEF TYPE_DECL}
  FT_Orientation = cint;
{$ELSE TYPE_DECL}
const
  FT_ORIENTATION_TRUETYPE   = 0;
  FT_ORIENTATION_POSTSCRIPT = 1;
  FT_ORIENTATION_FILL_RIGHT = FT_ORIENTATION_TRUETYPE;
  FT_ORIENTATION_FILL_LEFT  = FT_ORIENTATION_POSTSCRIPT;
  FT_ORIENTATION_NONE       = FT_ORIENTATION_FILL_LEFT+1;

 (**************************************************************************
  *
  * @function:
  *   FT_Outline_Get_Orientation
  *
  * @description:
  *   This function analyzes a glyph outline and tries to compute its
  *   fill orientation (see @FT_Orientation).  This is done by computing
  *   the direction of each global horizontal and/or vertical extrema
  *   within the outline.
  *
  *   Note that this will return @FT_ORIENTATION_TRUETYPE for empty
  *   outlines.
  *
  * @input:
  *   outline ::
  *     A handle to the source outline.
  *
  * @return:
  *   The orientation.
  *
  *)
  function FT_Outline_Get_Orientation( outline: PFT_Outline ): FT_Orientation;
    cdecl; external ft_lib name 'FT_Outline_Get_Orientation';

{$ENDIF TYPE_DECL}