libraries/freetype-2.0.5/include/freetype/ftoutln.h

   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-2001 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
  28 FT_BEGIN_HEADER
  29
  30
  31   /*************************************************************************/
  32   /*                                                                       */
  33   /* <Section>                                                             */
  34   /*    outline_processing                                                 */
  35   /*                                                                       */
  36   /* <Title>                                                               */
  37   /*    Outline Processing                                                 */
  38   /*                                                                       */
  39   /* <Abstract>                                                            */
  40   /*    Functions to create, transform, and render vectorial glyph images. */
  41   /*                                                                       */
  42   /* <Description>                                                         */
  43   /*    This section contains routines used to create and destroy scalable */
  44   /*    glyph images known as `outlines'.  These can also be measured,     */
  45   /*    transformed, and converted into bitmaps and pixmaps.               */
  46   /*                                                                       */
  47   /* <Order>                                                               */
  48   /*    FT_Outline                                                         */
  49   /*    FT_Outline_Flags                                                   */
  50   /*    FT_Outline_New                                                     */
  51   /*    FT_Outline_Done                                                    */
  52   /*    FT_Outline_Copy                                                    */
  53   /*    FT_Outline_Translate                                               */
  54   /*    FT_Outline_Transform                                               */
  55   /*    FT_Outline_Reverse                                                 */
  56   /*                                                                       */
  57   /*    FT_Outline_Get_CBox                                                */
  58   /*    FT_Outline_Get_BBox                                                */
  59   /*                                                                       */
  60   /*    FT_Outline_Get_Bitmap                                              */
  61   /*    FT_Outline_Render                                                  */
  62   /*                                                                       */
  63   /*    FT_Outline_Decompose                                               */
  64   /*    FT_Outline_Funcs                                                   */
  65   /*    FT_Outline_MoveTo_Func                                             */
  66   /*    FT_Outline_LineTo_Func                                             */
  67   /*    FT_Outline_ConicTo_Func                                            */
  68   /*    FT_Outline_CubicTo_Func                                            */
  69   /*                                                                       */
  70   /*************************************************************************/
  71
  72
  73   /*************************************************************************/
  74   /*                                                                       */
  75   /* <Function>                                                            */
  76   /*    FT_Outline_Decompose                                               */
  77   /*                                                                       */
  78   /* <Description>                                                         */
  79   /*    Walks over an outline's structure to decompose it into individual  */
  80   /*    segments and Bezier arcs.  This function is also able to emit      */
  81   /*    `move to' and `close to' operations to indicate the start and end  */
  82   /*    of new contours in the outline.                                    */
  83   /*                                                                       */
  84   /* <Input>                                                               */
  85   /*    outline   :: A pointer to the source target.                       */
  86   /*                                                                       */
  87   /*    interface :: A table of `emitters', i.e,. function pointers called */
  88   /*                 during decomposition to indicate path operations.     */
  89   /*                                                                       */
  90   /* <InOut>                                                               */
  91   /*    user      :: A typeless pointer which is passed to each emitter    */
  92   /*                 during the decomposition.  It can be used to store    */
  93   /*                 the state during the decomposition.                   */
  94   /*                                                                       */
  95   /* <Return>                                                              */
  96   /*    FreeType error code.  0 means sucess.                              */
  97   /*                                                                       */
  98   FT_EXPORT( FT_Error )
  99   FT_Outline_Decompose( FT_Outline*              outline,
 100                         const FT_Outline_Funcs*  interface,
 101                         void*                    user );
 102
 103
 104   /*************************************************************************/
 105   /*                                                                       */
 106   /* <Function>                                                            */
 107   /*    FT_Outline_New                                                     */
 108   /*                                                                       */
 109   /* <Description>                                                         */
 110   /*    Creates a new outline of a given size.                             */
 111   /*                                                                       */
 112   /* <Input>                                                               */
 113   /*    library     :: A handle to the library object from where the       */
 114   /*                   outline is allocated.  Note however that the new    */
 115   /*                   outline will NOT necessarily be FREED, when         */
 116   /*                   destroying the library, by FT_Done_FreeType().      */
 117   /*                                                                       */
 118   /*    numPoints   :: The maximal number of points within the outline.    */
 119   /*                                                                       */
 120   /*    numContours :: The maximal number of contours within the outline.  */
 121   /*                                                                       */
 122   /* <Output>                                                              */
 123   /*    anoutline   :: A handle to the new outline.  NULL in case of       */
 124   /*                   error.                                              */
 125   /*                                                                       */
 126   /* <Return>                                                              */
 127   /*    FreeType error code.  0 means success.                             */
 128   /*                                                                       */
 129   /* <Note>                                                                */
 130   /*    The reason why this function takes a `library' parameter is simply */
 131   /*    to use the library's memory allocator.                             */
 132   /*                                                                       */
 133   FT_EXPORT( FT_Error )
 134   FT_Outline_New( FT_Library   library,
 135                   FT_UInt      numPoints,
 136                   FT_Int       numContours,
 137                   FT_Outline  *anoutline );
 138
 139
 140   FT_EXPORT( FT_Error )
 141   FT_Outline_New_Internal( FT_Memory    memory,
 142                            FT_UInt      numPoints,
 143                            FT_Int       numContours,
 144                            FT_Outline  *anoutline );
 145
 146
 147   /*************************************************************************/
 148   /*                                                                       */
 149   /* <Function>                                                            */
 150   /*    FT_Outline_Done                                                    */
 151   /*                                                                       */
 152   /* <Description>                                                         */
 153   /*    Destroys an outline created with FT_Outline_New().                 */
 154   /*                                                                       */
 155   /* <Input>                                                               */
 156   /*    library :: A handle of the library object used to allocate the     */
 157   /*               outline.                                                */
 158   /*                                                                       */
 159   /*    outline :: A pointer to the outline object to be discarded.        */
 160   /*                                                                       */
 161   /* <Return>                                                              */
 162   /*    FreeType error code.  0 means success.                             */
 163   /*                                                                       */
 164   /* <Note>                                                                */
 165   /*    If the outline's `owner' field is not set, only the outline        */
 166   /*    descriptor will be released.                                       */
 167   /*                                                                       */
 168   /*    The reason why this function takes an `library' parameter is       */
 169   /*    simply to use FT_Free().                                           */
 170   /*                                                                       */
 171   FT_EXPORT( FT_Error )
 172   FT_Outline_Done( FT_Library   library,
 173                    FT_Outline*  outline );
 174
 175
 176   FT_EXPORT( FT_Error )
 177   FT_Outline_Done_Internal( FT_Memory    memory,
 178                             FT_Outline*  outline );
 179
 180
 181   /*************************************************************************/
 182   /*                                                                       */
 183   /* <Function>                                                            */
 184   /*    FT_Outline_Get_CBox                                                */
 185   /*                                                                       */
 186   /* <Description>                                                         */
 187   /*    Returns an outline's `control box'.  The control box encloses all  */
 188   /*    the outline's points, including Bezier control points.  Though it  */
 189   /*    coincides with the exact bounding box for most glyphs, it can be   */
 190   /*    slightly larger in some situations (like when rotating an outline  */
 191   /*    which contains Bezier outside arcs).                               */
 192   /*                                                                       */
 193   /*    Computing the control box is very fast, while getting the bounding */
 194   /*    box can take much more time as it needs to walk over all segments  */
 195   /*    and arcs in the outline.  To get the latter, you can use the       */
 196   /*    `ftbbox' component which is dedicated to this single task.         */
 197   /*                                                                       */
 198   /* <Input>                                                               */
 199   /*    outline :: A pointer to the source outline descriptor.             */
 200   /*                                                                       */
 201   /* <Output>                                                              */
 202   /*    acbox   :: The outline's control box.                              */
 203   /*                                                                       */
 204   FT_EXPORT( void )
 205   FT_Outline_Get_CBox( FT_Outline*  outline,
 206                        FT_BBox     *acbox );
 207
 208
 209   /*************************************************************************/
 210   /*                                                                       */
 211   /* <Function>                                                            */
 212   /*    FT_Outline_Translate                                               */
 213   /*                                                                       */
 214   /* <Description>                                                         */
 215   /*    Applies a simple translation to the points of an outline.          */
 216   /*                                                                       */
 217   /* <InOut>                                                               */
 218   /*    outline :: A pointer to the target outline descriptor.             */
 219   /*                                                                       */
 220   /* <Input>                                                               */
 221   /*    xOffset :: The horizontal offset.                                  */
 222   /*                                                                       */
 223   /*    yOffset :: The vertical offset.                                    */
 224   /*                                                                       */
 225   FT_EXPORT( void )
 226   FT_Outline_Translate( FT_Outline*  outline,
 227                         FT_Pos       xOffset,
 228                         FT_Pos       yOffset );
 229
 230
 231   /*************************************************************************/
 232   /*                                                                       */
 233   /* <Function>                                                            */
 234   /*    FT_Outline_Copy                                                    */
 235   /*                                                                       */
 236   /* <Description>                                                         */
 237   /*    Copies an outline into another one.  Both objects must have the    */
 238   /*    same sizes (number of points & number of contours) when this       */
 239   /*    function is called.                                                */
 240   /*                                                                       */
 241   /* <Input>                                                               */
 242   /*    source :: A handle to the source outline.                          */
 243   /*                                                                       */
 244   /* <Output>                                                              */
 245   /*    target :: A handle to the target outline.                          */
 246   /*                                                                       */
 247   /* <Return>                                                              */
 248   /*    FreeType error code.  0 means success.                             */
 249   /*                                                                       */
 250   FT_EXPORT( FT_Error )
 251   FT_Outline_Copy( FT_Outline*  source,
 252                    FT_Outline  *target );
 253
 254
 255   /*************************************************************************/
 256   /*                                                                       */
 257   /* <Function>                                                            */
 258   /*    FT_Outline_Transform                                               */
 259   /*                                                                       */
 260   /* <Description>                                                         */
 261   /*    Applies a simple 2x2 matrix to all of an outline's points.  Useful */
 262   /*    for applying rotations, slanting, flipping, etc.                   */
 263   /*                                                                       */
 264   /* <InOut>                                                               */
 265   /*    outline :: A pointer to the target outline descriptor.             */
 266   /*                                                                       */
 267   /* <Input>                                                               */
 268   /*    matrix  :: A pointer to the transformation matrix.                 */
 269   /*                                                                       */
 270   /* <Note>                                                                */
 271   /*    You can use FT_Outline_Translate() if you need to translate the    */
 272   /*    outline's points.                                                  */
 273   /*                                                                       */
 274   FT_EXPORT( void )
 275   FT_Outline_Transform( FT_Outline*  outline,
 276                         FT_Matrix*   matrix );
 277
 278
 279   /*************************************************************************/
 280   /*                                                                       */
 281   /* <Function>                                                            */
 282   /*    FT_Outline_Reverse                                                 */
 283   /*                                                                       */
 284   /* <Description>                                                         */
 285   /*    Reverses the drawing direction of an outline.  This is used to     */
 286   /*    ensure consistent fill conventions for mirrored glyphs.            */
 287   /*                                                                       */
 288   /* <InOut>                                                               */
 289   /*    outline :: A pointer to the target outline descriptor.             */
 290   /*                                                                       */
 291   /* <Note>                                                                */
 292   /*    This functions toggles the bit flag `ft_outline_reverse_fill' in   */
 293   /*    the outline's `flags' field.                                       */
 294   /*                                                                       */
 295   /*    It shouldn't be used by a normal client application, unless it     */
 296   /*    knows what it is doing.                                            */
 297   /*                                                                       */
 298   FT_EXPORT( void )
 299   FT_Outline_Reverse( FT_Outline*  outline );
 300
 301
 302   /*************************************************************************/
 303   /*                                                                       */
 304   /* <Function>                                                            */
 305   /*    FT_Outline_Get_Bitmap                                              */
 306   /*                                                                       */
 307   /* <Description>                                                         */
 308   /*    Renders an outline within a bitmap.  The outline's image is simply */
 309   /*    OR-ed to the target bitmap.                                        */
 310   /*                                                                       */
 311   /* <Input>                                                               */
 312   /*    library :: A handle to a FreeType library object.                  */
 313   /*                                                                       */
 314   /*    outline :: A pointer to the source outline descriptor.             */
 315   /*                                                                       */
 316   /* <Output>                                                              */
 317   /*    abitmap :: A pointer to the target bitmap descriptor.              */
 318   /*                                                                       */
 319   /* <Return>                                                              */
 320   /*    FreeType error code.  0 means success.                             */
 321   /*                                                                       */
 322   /* <Note>                                                                */
 323   /*    This function does NOT CREATE the bitmap, it only renders an       */
 324   /*    outline image within the one you pass to it!                       */
 325   /*                                                                       */
 326   /*    It will use the raster correponding to the default glyph format.   */
 327   /*                                                                       */
 328   FT_EXPORT( FT_Error )
 329   FT_Outline_Get_Bitmap( FT_Library   library,
 330                          FT_Outline*  outline,
 331                          FT_Bitmap   *abitmap );
 332
 333
 334   /*************************************************************************/
 335   /*                                                                       */
 336   /* <Function>                                                            */
 337   /*    FT_Outline_Render                                                  */
 338   /*                                                                       */
 339   /* <Description>                                                         */
 340   /*    Renders an outline within a bitmap using the current scan-convert. */
 341   /*    This functions uses an FT_Raster_Params structure as an argument,  */
 342   /*    allowing advanced features like direct composition, translucency,  */
 343   /*    etc.                                                               */
 344   /*                                                                       */
 345   /* <Input>                                                               */
 346   /*    library :: A handle to a FreeType library object.                  */
 347   /*                                                                       */
 348   /*    outline :: A pointer to the source outline descriptor.             */
 349   /*                                                                       */
 350   /* <InOut>                                                               */
 351   /*    params  :: A pointer to a FT_Raster_Params structure used to       */
 352   /*               describe the rendering operation.                       */
 353   /*                                                                       */
 354   /* <Return>                                                              */
 355   /*    FreeType error code.  0 means success.                             */
 356   /*                                                                       */
 357   /* <Note>                                                                */
 358   /*    You should know what you are doing and how FT_Raster_Params works  */
 359   /*    to use this function.                                              */
 360   /*                                                                       */
 361   /*    The field `params.source' will be set to `outline' before the scan */
 362   /*    converter is called, which means that the value you give to it is  */
 363   /*    actually ignored.                                                  */
 364   /*                                                                       */
 365   FT_EXPORT( FT_Error )
 366   FT_Outline_Render( FT_Library         library,
 367                      FT_Outline*        outline,
 368                      FT_Raster_Params*  params );
 369
 370
 371   /* */
 372
 373
 374 FT_END_HEADER
 375
 376 #endif /* __FTOUTLN_H__ */
 377
 378
 379 /* END */