Home | History | Annotate | Download | only in freetype
      1 /***************************************************************************/
      2 /*                                                                         */
      3 /*  ftoutln.h                                                              */
      4 /*                                                                         */
      5 /*    Support for the FT_Outline type used to store glyph shapes of        */
      6 /*    most scalable font formats (specification).                          */
      7 /*                                                                         */
      8 /*  Copyright 1996-2003, 2005-2011 by                                      */
      9 /*  David Turner, Robert Wilhelm, and Werner Lemberg.                      */
     10 /*                                                                         */
     11 /*  This file is part of the FreeType project, and may only be used,       */
     12 /*  modified, and distributed under the terms of the FreeType project      */
     13 /*  license, LICENSE.TXT.  By continuing to use, modify, or distribute     */
     14 /*  this file you indicate that you have read the license and              */
     15 /*  understand and accept it fully.                                        */
     16 /*                                                                         */
     17 /***************************************************************************/
     18 
     19 
     20 #ifndef __FTOUTLN_H__
     21 #define __FTOUTLN_H__
     22 
     23 
     24 #include <ft2build.h>
     25 #include FT_FREETYPE_H
     26 
     27 #ifdef FREETYPE_H
     28 #error "freetype.h of FreeType 1 has been loaded!"
     29 #error "Please fix the directory search order for header files"
     30 #error "so that freetype.h of FreeType 2 is found first."
     31 #endif
     32 
     33 
     34 FT_BEGIN_HEADER
     35 
     36 
     37   /*************************************************************************/
     38   /*                                                                       */
     39   /* <Section>                                                             */
     40   /*    outline_processing                                                 */
     41   /*                                                                       */
     42   /* <Title>                                                               */
     43   /*    Outline Processing                                                 */
     44   /*                                                                       */
     45   /* <Abstract>                                                            */
     46   /*    Functions to create, transform, and render vectorial glyph images. */
     47   /*                                                                       */
     48   /* <Description>                                                         */
     49   /*    This section contains routines used to create and destroy scalable */
     50   /*    glyph images known as `outlines'.  These can also be measured,     */
     51   /*    transformed, and converted into bitmaps and pixmaps.               */
     52   /*                                                                       */
     53   /* <Order>                                                               */
     54   /*    FT_Outline                                                         */
     55   /*    FT_OUTLINE_FLAGS                                                   */
     56   /*    FT_Outline_New                                                     */
     57   /*    FT_Outline_Done                                                    */
     58   /*    FT_Outline_Copy                                                    */
     59   /*    FT_Outline_Translate                                               */
     60   /*    FT_Outline_Transform                                               */
     61   /*    FT_Outline_Embolden                                                */
     62   /*    FT_Outline_Reverse                                                 */
     63   /*    FT_Outline_Check                                                   */
     64   /*                                                                       */
     65   /*    FT_Outline_Get_CBox                                                */
     66   /*    FT_Outline_Get_BBox                                                */
     67   /*                                                                       */
     68   /*    FT_Outline_Get_Bitmap                                              */
     69   /*    FT_Outline_Render                                                  */
     70   /*                                                                       */
     71   /*    FT_Outline_Decompose                                               */
     72   /*    FT_Outline_Funcs                                                   */
     73   /*    FT_Outline_MoveTo_Func                                             */
     74   /*    FT_Outline_LineTo_Func                                             */
     75   /*    FT_Outline_ConicTo_Func                                            */
     76   /*    FT_Outline_CubicTo_Func                                            */
     77   /*                                                                       */
     78   /*************************************************************************/
     79 
     80 
     81   /*************************************************************************/
     82   /*                                                                       */
     83   /* <Function>                                                            */
     84   /*    FT_Outline_Decompose                                               */
     85   /*                                                                       */
     86   /* <Description>                                                         */
     87   /*    Walk over an outline's structure to decompose it into individual   */
     88   /*    segments and Bzier arcs.  This function also emits `move to'      */
     89   /*    operations to indicate the start of new contours in the outline.   */
     90   /*                                                                       */
     91   /* <Input>                                                               */
     92   /*    outline        :: A pointer to the source target.                  */
     93   /*                                                                       */
     94   /*    func_interface :: A table of `emitters', i.e., function pointers   */
     95   /*                      called during decomposition to indicate path     */
     96   /*                      operations.                                      */
     97   /*                                                                       */
     98   /* <InOut>                                                               */
     99   /*    user           :: A typeless pointer which is passed to each       */
    100   /*                      emitter during the decomposition.  It can be     */
    101   /*                      used to store the state during the               */
    102   /*                      decomposition.                                   */
    103   /*                                                                       */
    104   /* <Return>                                                              */
    105   /*    FreeType error code.  0~means success.                             */
    106   /*                                                                       */
    107   FT_EXPORT( FT_Error )
    108   FT_Outline_Decompose( FT_Outline*              outline,
    109                         const FT_Outline_Funcs*  func_interface,
    110                         void*                    user );
    111 
    112 
    113   /*************************************************************************/
    114   /*                                                                       */
    115   /* <Function>                                                            */
    116   /*    FT_Outline_New                                                     */
    117   /*                                                                       */
    118   /* <Description>                                                         */
    119   /*    Create a new outline of a given size.                              */
    120   /*                                                                       */
    121   /* <Input>                                                               */
    122   /*    library     :: A handle to the library object from where the       */
    123   /*                   outline is allocated.  Note however that the new    */
    124   /*                   outline will *not* necessarily be *freed*, when     */
    125   /*                   destroying the library, by @FT_Done_FreeType.       */
    126   /*                                                                       */
    127   /*    numPoints   :: The maximal number of points within the outline.    */
    128   /*                                                                       */
    129   /*    numContours :: The maximal number of contours within the outline.  */
    130   /*                                                                       */
    131   /* <Output>                                                              */
    132   /*    anoutline   :: A handle to the new outline.                        */
    133   /*                                                                       */
    134   /* <Return>                                                              */
    135   /*    FreeType error code.  0~means success.                             */
    136   /*                                                                       */
    137   /* <Note>                                                                */
    138   /*    The reason why this function takes a `library' parameter is simply */
    139   /*    to use the library's memory allocator.                             */
    140   /*                                                                       */
    141   FT_EXPORT( FT_Error )
    142   FT_Outline_New( FT_Library   library,
    143                   FT_UInt      numPoints,
    144                   FT_Int       numContours,
    145                   FT_Outline  *anoutline );
    146 
    147 
    148   FT_EXPORT( FT_Error )
    149   FT_Outline_New_Internal( FT_Memory    memory,
    150                            FT_UInt      numPoints,
    151                            FT_Int       numContours,
    152                            FT_Outline  *anoutline );
    153 
    154 
    155   /*************************************************************************/
    156   /*                                                                       */
    157   /* <Function>                                                            */
    158   /*    FT_Outline_Done                                                    */
    159   /*                                                                       */
    160   /* <Description>                                                         */
    161   /*    Destroy an outline created with @FT_Outline_New.                   */
    162   /*                                                                       */
    163   /* <Input>                                                               */
    164   /*    library :: A handle of the library object used to allocate the     */
    165   /*               outline.                                                */
    166   /*                                                                       */
    167   /*    outline :: A pointer to the outline object to be discarded.        */
    168   /*                                                                       */
    169   /* <Return>                                                              */
    170   /*    FreeType error code.  0~means success.                             */
    171   /*                                                                       */
    172   /* <Note>                                                                */
    173   /*    If the outline's `owner' field is not set, only the outline        */
    174   /*    descriptor will be released.                                       */
    175   /*                                                                       */
    176   /*    The reason why this function takes an `library' parameter is       */
    177   /*    simply to use ft_mem_free().                                       */
    178   /*                                                                       */
    179   FT_EXPORT( FT_Error )
    180   FT_Outline_Done( FT_Library   library,
    181                    FT_Outline*  outline );
    182 
    183 
    184   FT_EXPORT( FT_Error )
    185   FT_Outline_Done_Internal( FT_Memory    memory,
    186                             FT_Outline*  outline );
    187 
    188 
    189   /*************************************************************************/
    190   /*                                                                       */
    191   /* <Function>                                                            */
    192   /*    FT_Outline_Check                                                   */
    193   /*                                                                       */
    194   /* <Description>                                                         */
    195   /*    Check the contents of an outline descriptor.                       */
    196   /*                                                                       */
    197   /* <Input>                                                               */
    198   /*    outline :: A handle to a source outline.                           */
    199   /*                                                                       */
    200   /* <Return>                                                              */
    201   /*    FreeType error code.  0~means success.                             */
    202   /*                                                                       */
    203   FT_EXPORT( FT_Error )
    204   FT_Outline_Check( FT_Outline*  outline );
    205 
    206 
    207   /*************************************************************************/
    208   /*                                                                       */
    209   /* <Function>                                                            */
    210   /*    FT_Outline_Get_CBox                                                */
    211   /*                                                                       */
    212   /* <Description>                                                         */
    213   /*    Return an outline's `control box'.  The control box encloses all   */
    214   /*    the outline's points, including Bzier control points.  Though it  */
    215   /*    coincides with the exact bounding box for most glyphs, it can be   */
    216   /*    slightly larger in some situations (like when rotating an outline  */
    217   /*    which contains Bzier outside arcs).                               */
    218   /*                                                                       */
    219   /*    Computing the control box is very fast, while getting the bounding */
    220   /*    box can take much more time as it needs to walk over all segments  */
    221   /*    and arcs in the outline.  To get the latter, you can use the       */
    222   /*    `ftbbox' component which is dedicated to this single task.         */
    223   /*                                                                       */
    224   /* <Input>                                                               */
    225   /*    outline :: A pointer to the source outline descriptor.             */
    226   /*                                                                       */
    227   /* <Output>                                                              */
    228   /*    acbox   :: The outline's control box.                              */
    229   /*                                                                       */
    230   /* <Note>                                                                */
    231   /*    See @FT_Glyph_Get_CBox for a discussion of tricky fonts.           */
    232   /*                                                                       */
    233   FT_EXPORT( void )
    234   FT_Outline_Get_CBox( const FT_Outline*  outline,
    235                        FT_BBox           *acbox );
    236 
    237 
    238   /*************************************************************************/
    239   /*                                                                       */
    240   /* <Function>                                                            */
    241   /*    FT_Outline_Translate                                               */
    242   /*                                                                       */
    243   /* <Description>                                                         */
    244   /*    Apply a simple translation to the points of an outline.            */
    245   /*                                                                       */
    246   /* <InOut>                                                               */
    247   /*    outline :: A pointer to the target outline descriptor.             */
    248   /*                                                                       */
    249   /* <Input>                                                               */
    250   /*    xOffset :: The horizontal offset.                                  */
    251   /*                                                                       */
    252   /*    yOffset :: The vertical offset.                                    */
    253   /*                                                                       */
    254   FT_EXPORT( void )
    255   FT_Outline_Translate( const FT_Outline*  outline,
    256                         FT_Pos             xOffset,
    257                         FT_Pos             yOffset );
    258 
    259 
    260   /*************************************************************************/
    261   /*                                                                       */
    262   /* <Function>                                                            */
    263   /*    FT_Outline_Copy                                                    */
    264   /*                                                                       */
    265   /* <Description>                                                         */
    266   /*    Copy an outline into another one.  Both objects must have the      */
    267   /*    same sizes (number of points & number of contours) when this       */
    268   /*    function is called.                                                */
    269   /*                                                                       */
    270   /* <Input>                                                               */
    271   /*    source :: A handle to the source outline.                          */
    272   /*                                                                       */
    273   /* <Output>                                                              */
    274   /*    target :: A handle to the target outline.                          */
    275   /*                                                                       */
    276   /* <Return>                                                              */
    277   /*    FreeType error code.  0~means success.                             */
    278   /*                                                                       */
    279   FT_EXPORT( FT_Error )
    280   FT_Outline_Copy( const FT_Outline*  source,
    281                    FT_Outline        *target );
    282 
    283 
    284   /*************************************************************************/
    285   /*                                                                       */
    286   /* <Function>                                                            */
    287   /*    FT_Outline_Transform                                               */
    288   /*                                                                       */
    289   /* <Description>                                                         */
    290   /*    Apply a simple 2x2 matrix to all of an outline's points.  Useful   */
    291   /*    for applying rotations, slanting, flipping, etc.                   */
    292   /*                                                                       */
    293   /* <InOut>                                                               */
    294   /*    outline :: A pointer to the target outline descriptor.             */
    295   /*                                                                       */
    296   /* <Input>                                                               */
    297   /*    matrix  :: A pointer to the transformation matrix.                 */
    298   /*                                                                       */
    299   /* <Note>                                                                */
    300   /*    You can use @FT_Outline_Translate if you need to translate the     */
    301   /*    outline's points.                                                  */
    302   /*                                                                       */
    303   FT_EXPORT( void )
    304   FT_Outline_Transform( const FT_Outline*  outline,
    305                         const FT_Matrix*   matrix );
    306 
    307 
    308   /*************************************************************************/
    309   /*                                                                       */
    310   /* <Function>                                                            */
    311   /*    FT_Outline_Embolden                                                */
    312   /*                                                                       */
    313   /* <Description>                                                         */
    314   /*    Embolden an outline.  The new outline will be at most 4~times      */
    315   /*    `strength' pixels wider and higher.  You may think of the left and */
    316   /*    bottom borders as unchanged.                                       */
    317   /*                                                                       */
    318   /*    Negative `strength' values to reduce the outline thickness are     */
    319   /*    possible also.                                                     */
    320   /*                                                                       */
    321   /* <InOut>                                                               */
    322   /*    outline  :: A handle to the target outline.                        */
    323   /*                                                                       */
    324   /* <Input>                                                               */
    325   /*    strength :: How strong the glyph is emboldened.  Expressed in      */
    326   /*                26.6 pixel format.                                     */
    327   /*                                                                       */
    328   /* <Return>                                                              */
    329   /*    FreeType error code.  0~means success.                             */
    330   /*                                                                       */
    331   /* <Note>                                                                */
    332   /*    The used algorithm to increase or decrease the thickness of the    */
    333   /*    glyph doesn't change the number of points; this means that certain */
    334   /*    situations like acute angles or intersections are sometimes        */
    335   /*    handled incorrectly.                                               */
    336   /*                                                                       */
    337   /*    If you need `better' metrics values you should call                */
    338   /*    @FT_Outline_Get_CBox or @FT_Outline_Get_BBox.                      */
    339   /*                                                                       */
    340   /*    Example call:                                                      */
    341   /*                                                                       */
    342   /*    {                                                                  */
    343   /*      FT_Load_Glyph( face, index, FT_LOAD_DEFAULT );                   */
    344   /*      if ( face->slot->format == FT_GLYPH_FORMAT_OUTLINE )             */
    345   /*        FT_Outline_Embolden( &face->slot->outline, strength );         */
    346   /*    }                                                                  */
    347   /*                                                                       */
    348   FT_EXPORT( FT_Error )
    349   FT_Outline_Embolden( FT_Outline*  outline,
    350                        FT_Pos       strength );
    351 
    352 
    353   /*************************************************************************/
    354   /*                                                                       */
    355   /* <Function>                                                            */
    356   /*    FT_Outline_Reverse                                                 */
    357   /*                                                                       */
    358   /* <Description>                                                         */
    359   /*    Reverse the drawing direction of an outline.  This is used to      */
    360   /*    ensure consistent fill conventions for mirrored glyphs.            */
    361   /*                                                                       */
    362   /* <InOut>                                                               */
    363   /*    outline :: A pointer to the target outline descriptor.             */
    364   /*                                                                       */
    365   /* <Note>                                                                */
    366   /*    This function toggles the bit flag @FT_OUTLINE_REVERSE_FILL in     */
    367   /*    the outline's `flags' field.                                       */
    368   /*                                                                       */
    369   /*    It shouldn't be used by a normal client application, unless it     */
    370   /*    knows what it is doing.                                            */
    371   /*                                                                       */
    372   FT_EXPORT( void )
    373   FT_Outline_Reverse( FT_Outline*  outline );
    374 
    375 
    376   /*************************************************************************/
    377   /*                                                                       */
    378   /* <Function>                                                            */
    379   /*    FT_Outline_Get_Bitmap                                              */
    380   /*                                                                       */
    381   /* <Description>                                                         */
    382   /*    Render an outline within a bitmap.  The outline's image is simply  */
    383   /*    OR-ed to the target bitmap.                                        */
    384   /*                                                                       */
    385   /* <Input>                                                               */
    386   /*    library :: A handle to a FreeType library object.                  */
    387   /*                                                                       */
    388   /*    outline :: A pointer to the source outline descriptor.             */
    389   /*                                                                       */
    390   /* <InOut>                                                               */
    391   /*    abitmap :: A pointer to the target bitmap descriptor.              */
    392   /*                                                                       */
    393   /* <Return>                                                              */
    394   /*    FreeType error code.  0~means success.                             */
    395   /*                                                                       */
    396   /* <Note>                                                                */
    397   /*    This function does NOT CREATE the bitmap, it only renders an       */
    398   /*    outline image within the one you pass to it!  Consequently, the    */
    399   /*    various fields in `abitmap' should be set accordingly.             */
    400   /*                                                                       */
    401   /*    It will use the raster corresponding to the default glyph format.  */
    402   /*                                                                       */
    403   /*    The value of the `num_grays' field in `abitmap' is ignored.  If    */
    404   /*    you select the gray-level rasterizer, and you want less than 256   */
    405   /*    gray levels, you have to use @FT_Outline_Render directly.          */
    406   /*                                                                       */
    407   FT_EXPORT( FT_Error )
    408   FT_Outline_Get_Bitmap( FT_Library        library,
    409                          FT_Outline*       outline,
    410                          const FT_Bitmap  *abitmap );
    411 
    412 
    413   /*************************************************************************/
    414   /*                                                                       */
    415   /* <Function>                                                            */
    416   /*    FT_Outline_Render                                                  */
    417   /*                                                                       */
    418   /* <Description>                                                         */
    419   /*    Render an outline within a bitmap using the current scan-convert.  */
    420   /*    This function uses an @FT_Raster_Params structure as an argument,  */
    421   /*    allowing advanced features like direct composition, translucency,  */
    422   /*    etc.                                                               */
    423   /*                                                                       */
    424   /* <Input>                                                               */
    425   /*    library :: A handle to a FreeType library object.                  */
    426   /*                                                                       */
    427   /*    outline :: A pointer to the source outline descriptor.             */
    428   /*                                                                       */
    429   /* <InOut>                                                               */
    430   /*    params  :: A pointer to an @FT_Raster_Params structure used to     */
    431   /*               describe the rendering operation.                       */
    432   /*                                                                       */
    433   /* <Return>                                                              */
    434   /*    FreeType error code.  0~means success.                             */
    435   /*                                                                       */
    436   /* <Note>                                                                */
    437   /*    You should know what you are doing and how @FT_Raster_Params works */
    438   /*    to use this function.                                              */
    439   /*                                                                       */
    440   /*    The field `params.source' will be set to `outline' before the scan */
    441   /*    converter is called, which means that the value you give to it is  */
    442   /*    actually ignored.                                                  */
    443   /*                                                                       */
    444   /*    The gray-level rasterizer always uses 256 gray levels.  If you     */
    445   /*    want less gray levels, you have to provide your own span callback. */
    446   /*    See the @FT_RASTER_FLAG_DIRECT value of the `flags' field in the   */
    447   /*    @FT_Raster_Params structure for more details.                      */
    448   /*                                                                       */
    449   FT_EXPORT( FT_Error )
    450   FT_Outline_Render( FT_Library         library,
    451                      FT_Outline*        outline,
    452                      FT_Raster_Params*  params );
    453 
    454 
    455  /**************************************************************************
    456   *
    457   * @enum:
    458   *   FT_Orientation
    459   *
    460   * @description:
    461   *   A list of values used to describe an outline's contour orientation.
    462   *
    463   *   The TrueType and PostScript specifications use different conventions
    464   *   to determine whether outline contours should be filled or unfilled.
    465   *
    466   * @values:
    467   *   FT_ORIENTATION_TRUETYPE ::
    468   *     According to the TrueType specification, clockwise contours must
    469   *     be filled, and counter-clockwise ones must be unfilled.
    470   *
    471   *   FT_ORIENTATION_POSTSCRIPT ::
    472   *     According to the PostScript specification, counter-clockwise contours
    473   *     must be filled, and clockwise ones must be unfilled.
    474   *
    475   *   FT_ORIENTATION_FILL_RIGHT ::
    476   *     This is identical to @FT_ORIENTATION_TRUETYPE, but is used to
    477   *     remember that in TrueType, everything that is to the right of
    478   *     the drawing direction of a contour must be filled.
    479   *
    480   *   FT_ORIENTATION_FILL_LEFT ::
    481   *     This is identical to @FT_ORIENTATION_POSTSCRIPT, but is used to
    482   *     remember that in PostScript, everything that is to the left of
    483   *     the drawing direction of a contour must be filled.
    484   *
    485   *   FT_ORIENTATION_NONE ::
    486   *     The orientation cannot be determined.  That is, different parts of
    487   *     the glyph have different orientation.
    488   *
    489   */
    490   typedef enum  FT_Orientation_
    491   {
    492     FT_ORIENTATION_TRUETYPE   = 0,
    493     FT_ORIENTATION_POSTSCRIPT = 1,
    494     FT_ORIENTATION_FILL_RIGHT = FT_ORIENTATION_TRUETYPE,
    495     FT_ORIENTATION_FILL_LEFT  = FT_ORIENTATION_POSTSCRIPT,
    496     FT_ORIENTATION_NONE
    497 
    498   } FT_Orientation;
    499 
    500 
    501  /**************************************************************************
    502   *
    503   * @function:
    504   *   FT_Outline_Get_Orientation
    505   *
    506   * @description:
    507   *   This function analyzes a glyph outline and tries to compute its
    508   *   fill orientation (see @FT_Orientation).  This is done by computing
    509   *   the direction of each global horizontal and/or vertical extrema
    510   *   within the outline.
    511   *
    512   *   Note that this will return @FT_ORIENTATION_TRUETYPE for empty
    513   *   outlines.
    514   *
    515   * @input:
    516   *   outline ::
    517   *     A handle to the source outline.
    518   *
    519   * @return:
    520   *   The orientation.
    521   *
    522   */
    523   FT_EXPORT( FT_Orientation )
    524   FT_Outline_Get_Orientation( FT_Outline*  outline );
    525 
    526 
    527   /* */
    528 
    529 
    530 FT_END_HEADER
    531 
    532 #endif /* __FTOUTLN_H__ */
    533 
    534 
    535 /* END */
    536 
    537 
    538 /* Local Variables: */
    539 /* coding: utf-8    */
    540 /* End:             */
    541