text: /***************************************************************************/
  /*                                                                         */
  /*  ftoutln.h                                                              */
  /*                                                                         */
  /*    Support for the FT_Outline type used to store glyph shapes of        */
  /*    most scalable font formats (specification).                          */
  /*                                                                         */
  /*  Copyright 1996-2017 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 FTOUTLN_H_
  #define FTOUTLN_H_
  
  
  #include <ft2build.h>
  #include FT_FREETYPE_H
  
  #ifdef FREETYPE_H
  #error "freetype.h of FreeType 1 has been loaded!"
  #error "Please fix the directory search order for header files"
  #error "so that freetype.h of FreeType 2 is found first."
  #endif
  
  
  FT_BEGIN_HEADER
  
  
    /*************************************************************************/
    /*                                                                       */
    /* <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_New                                                     */
    /*    FT_Outline_Done                                                    */
    /*    FT_Outline_Copy                                                    */
    /*    FT_Outline_Translate                                               */
    /*    FT_Outline_Transform                                               */
    /*    FT_Outline_Embolden                                                */
    /*    FT_Outline_EmboldenXY                                              */
    /*    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_MoveToFunc                                              */
    /*    FT_Outline_LineToFunc                                              */
    /*    FT_Outline_ConicToFunc                                             */
    /*    FT_Outline_CubicToFunc                                             */
    /*                                                                       */
    /*    FT_Orientation                                                     */
    /*    FT_Outline_Get_Orientation                                         */
    /*                                                                       */
    /*    FT_OUTLINE_XXX                                                     */
    /*                                                                       */
    /*************************************************************************/
  
  
    /*************************************************************************/
    /*                                                                       */
    /* <Function>                                                            */
    /*    FT_Outline_Decompose                                               */
    /*                                                                       */
    /* <Description>                                                         */
    /*    Walk over an outline's structure to decompose it into individual   */
    /*    segments and Bézier arcs.  This function also emits `move to'      */
    /*    operations to indicate the start 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 that 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.                             */
    /*                                                                       */
    /* <Note>                                                                */
    /*    A contour that contains a single point only is represented by a    */
    /*    `move to' operation followed by `line to' to the same point.  In   */
    /*    most cases, it is best to filter this out before using the         */
    /*    outline for stroking purposes (otherwise it would result in a      */
    /*    visible dot when round caps are used).                             */
    /*                                                                       */
    /*    Similarly, the function returns success for an empty outline also  */
    /*    (doing nothing, this is, not calling any emitter); if necessary,   */
    /*    you should filter this out, too.                                   */
    /*                                                                       */
    FT_EXPORT( FT_Error )
    FT_Outline_Decompose( FT_Outline*              outline,
                          const FT_Outline_Funcs*  func_interface,
                          void*                    user );
  
  
    /*************************************************************************/
    /*                                                                       */
    /* <Function>                                                            */
    /*    FT_Outline_New                                                     */
    /*                                                                       */
    /* <Description>                                                         */
    /*    Create 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 maximum number of points within the outline.    */
    /*                   Must be smaller than or equal to 0xFFFF (65535).    */
    /*                                                                       */
    /*    numContours :: The maximum number of contours within the outline.  */
    /*                   This value must be in the range 0 to `numPoints'.   */
    /*                                                                       */
    /* <Output>                                                              */
    /*    anoutline   :: A handle to the new outline.                        */
    /*                                                                       */
    /* <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.                             */
    /*                                                                       */
    FT_EXPORT( FT_Error )
    FT_Outline_New( FT_Library   library,
                    FT_UInt      numPoints,
                    FT_Int       numContours,
                    FT_Outline  *anoutline );
  
  
    FT_EXPORT( FT_Error )
    FT_Outline_New_Internal( FT_Memory    memory,
                             FT_UInt      numPoints,
                             FT_Int       numContours,
                             FT_Outline  *anoutline );
  
  
    /*************************************************************************/
    /*                                                                       */
    /* <Function>                                                            */
    /*    FT_Outline_Done                                                    */
    /*                                                                       */
    /* <Description>                                                         */
    /*    Destroy 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().                                       */
    /*                                                                       */
    FT_EXPORT( FT_Error )
    FT_Outline_Done( FT_Library   library,
                     FT_Outline*  outline );
  
  
    FT_EXPORT( FT_Error )
    FT_Outline_Done_Internal( FT_Memory    memory,
                              FT_Outline*  outline );
  
  
    /*************************************************************************/
    /*                                                                       */
    /* <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.                             */
    /*                                                                       */
    /* <Note>                                                                */
    /*    An empty outline, or an outline with a single point only is also   */
    /*    valid.                                                             */
    /*                                                                       */
    FT_EXPORT( FT_Error )
    FT_Outline_Check( FT_Outline*  outline );
  
  
    /*************************************************************************/
    /*                                                                       */
    /* <Function>                                                            */
    /*    FT_Outline_Get_CBox                                                */
    /*                                                                       */
    /* <Description>                                                         */
    /*    Return 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  */
    /*    that 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.                              */
    /*                                                                       */
    /* <Note>                                                                */
    /*    See @FT_Glyph_Get_CBox for a discussion of tricky fonts.           */
    /*                                                                       */
    FT_EXPORT( void )
    FT_Outline_Get_CBox( const FT_Outline*  outline,
                         FT_BBox           *acbox );
  
  
    /*************************************************************************/
    /*                                                                       */
    /* <Function>                                                            */
    /*    FT_Outline_Translate                                               */
    /*                                                                       */
    /* <Description>                                                         */
    /*    Apply 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.                                    */
    /*                                                                       */
    FT_EXPORT( void )
    FT_Outline_Translate( const FT_Outline*  outline,
                          FT_Pos             xOffset,
                          FT_Pos             yOffset );
  
  
    /*************************************************************************/
    /*                                                                       */
    /* <Function>                                                            */
    /*    FT_Outline_Copy                                                    */
    /*                                                                       */
    /* <Description>                                                         */
    /*    Copy 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.                             */
    /*                                                                       */
    FT_EXPORT( FT_Error )
    FT_Outline_Copy( const FT_Outline*  source,
                     FT_Outline        *target );
  
  
    /*************************************************************************/
    /*                                                                       */
    /* <Function>                                                            */
    /*    FT_Outline_Transform                                               */
    /*                                                                       */
    /* <Description>                                                         */
    /*    Apply 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.                                                  */
    /*                                                                       */
    FT_EXPORT( void )
    FT_Outline_Transform( const FT_Outline*  outline,
                          const FT_Matrix*   matrix );
  
  
    /*************************************************************************/
    /*                                                                       */
    /* <Function>                                                            */
    /*    FT_Outline_Embolden                                                */
    /*                                                                       */
    /* <Description>                                                         */
    /*    Embolden 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.                                               */
    /*                                                                       */
    /*    If you need `better' metrics values you should call                */
    /*    @FT_Outline_Get_CBox or @FT_Outline_Get_BBox.                      */
    /*                                                                       */
    /*    Example call:                                                      */
    /*                                                                       */
    /*    {                                                                  */
    /*      FT_Load_Glyph( face, index, FT_LOAD_DEFAULT );                   */
    /*      if ( face->glyph->format == FT_GLYPH_FORMAT_OUTLINE )            */
    /*        FT_Outline_Embolden( &face->glyph->outline, strength );        */
    /*    }                                                                  */
    /*                                                                       */
    /*    To get meaningful results, font scaling values must be set with    */
    /*    functions like @FT_Set_Char_Size before calling FT_Render_Glyph.   */
    /*                                                                       */
    FT_EXPORT( FT_Error )
    FT_Outline_Embolden( FT_Outline*  outline,
                         FT_Pos       strength );
  
  
    /*************************************************************************/
    /*                                                                       */
    /* <Function>                                                            */
    /*    FT_Outline_EmboldenXY                                              */
    /*                                                                       */
    /* <Description>                                                         */
    /*    Embolden an outline.  The new outline will be `xstrength' pixels   */
    /*    wider and `ystrength' pixels higher.  Otherwise, it is similar to  */
    /*    @FT_Outline_Embolden, which uses the same strength in both         */
    /*    directions.                                                        */
    /*                                                                       */
    FT_EXPORT( FT_Error )
    FT_Outline_EmboldenXY( FT_Outline*  outline,
                           FT_Pos       xstrength,
                           FT_Pos       ystrength );
  
  
    /*************************************************************************/
    /*                                                                       */
    /* <Function>                                                            */
    /*    FT_Outline_Reverse                                                 */
    /*                                                                       */
    /* <Description>                                                         */
    /*    Reverse 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 function 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.                                            */
    /*                                                                       */
    FT_EXPORT( void )
    FT_Outline_Reverse( FT_Outline*  outline );
  
  
    /*************************************************************************/
    /*                                                                       */
    /* <Function>                                                            */
    /*    FT_Outline_Get_Bitmap                                              */
    /*                                                                       */
    /* <Description>                                                         */
    /*    Render 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!  Consequently, the    */
    /*    various fields in `abitmap' should be set accordingly.             */
    /*                                                                       */
    /*    It will use the raster corresponding to the default glyph format.  */
    /*                                                                       */
    /*    The value of the `num_grays' field in `abitmap' is ignored.  If    */
    /*    you select the gray-level rasterizer, and you want less than 256   */
    /*    gray levels, you have to use @FT_Outline_Render directly.          */
    /*                                                                       */
    FT_EXPORT( FT_Error )
    FT_Outline_Get_Bitmap( FT_Library        library,
                           FT_Outline*       outline,
                           const FT_Bitmap  *abitmap );
  
  
    /*************************************************************************/
    /*                                                                       */
    /* <Function>                                                            */
    /*    FT_Outline_Render                                                  */
    /*                                                                       */
    /* <Description>                                                         */
    /*    Render an outline within a bitmap using the current scan-convert.  */
    /*    This function 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.                                                  */
    /*                                                                       */
    /*    The gray-level rasterizer always uses 256 gray levels.  If you     */
    /*    want less gray levels, you have to provide your own span callback. */
    /*    See the @FT_RASTER_FLAG_DIRECT value of the `flags' field in the   */
    /*    @FT_Raster_Params structure for more details.                      */
    /*                                                                       */
    FT_EXPORT( FT_Error )
    FT_Outline_Render( FT_Library         library,
                       FT_Outline*        outline,
                       FT_Raster_Params*  params );
  
  
   /**************************************************************************
    *
    * @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.
    *
    */
    typedef enum  FT_Orientation_
    {
      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;
  
  
   /**************************************************************************
    *
    * @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 integrating
    *   the total area covered by the outline. The positive integral
    *   corresponds to the clockwise orientation and @FT_ORIENTATION_POSTSCRIPT
    *   is returned. The negative integral corresponds to the counter-clockwise
    *   orientation and @FT_ORIENTATION_TRUETYPE is returned.
    *
    *   Note that this will return @FT_ORIENTATION_TRUETYPE for empty
    *   outlines.
    *
    * @input:
    *   outline ::
    *     A handle to the source outline.
    *
    * @return:
    *   The orientation.
    *
    */
    FT_EXPORT( FT_Orientation )
    FT_Outline_Get_Orientation( FT_Outline*  outline );
  
    /* */
  
  
  FT_END_HEADER
  
  #endif /* FTOUTLN_H_ */
  
  
  /* END */
  
  
  /* Local Variables: */
  /* coding: utf-8    */
  /* End:             */
  