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