/***************************************************************************/

/*                                                                         */

/*  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, 2008, 2009, 2010 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_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                                            */

  /*                                                                       */

  /*************************************************************************/





  /*************************************************************************/

  /*                                                                       */

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

  /*                                                                       */

  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 maximal number of points within the outline.    */

  /*                                                                       */

  /*    numContours :: The maximal number of contours within the outline.  */

  /*                                                                       */

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

  /*                                                                       */

  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  */

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

  /*                                                                       */

  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 ot @FT_Outline_Get_BBox.                      */

  /*                                                                       */

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

  /*    }                                                                  */

  /*                                                                       */

  FT_EXPORT( FT_Error )

  FT_Outline_Embolden( FT_Outline*  outline,

                       FT_Pos       strength );





  /*************************************************************************/

  /*                                                                       */

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

  *

  */

  FT_EXPORT( FT_Orientation )

  FT_Outline_Get_Orientation( FT_Outline*  outline );





  /* */





FT_END_HEADER



#endif /* __FTOUTLN_H__ */





/* END */





/* Local Variables: */

/* coding: utf-8    */

/* End:             */

