git.sesse.net Git - casparcg/blob - SFML-1.6/extlibs/headers/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, 2002, 2003, 2005 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   /*    Walks over an outline's structure to decompose it into individual  */
  88   /*    segments and Bezier arcs.  This function is also able to emit      */
  89   /*    `move to' and `close to' operations to indicate the start and end  */
  90   /*    of new contours in the outline.                                    */
  91   /*                                                                       */
  92   /* <Input>                                                               */
  93   /*    outline        :: A pointer to the source target.                  */
  94   /*                                                                       */
  95   /*    func_interface :: A table of `emitters', i.e,. function pointers   */
  96   /*                      called during decomposition to indicate path     */
  97   /*                      operations.                                      */
  98   /*                                                                       */
  99   /* <InOut>                                                               */
 100   /*    user           :: A typeless pointer which is passed to each       */
 101   /*                      emitter during the decomposition.  It can be     */
 102   /*                      used to store the state during the               */
 103   /*                      decomposition.                                   */
 104   /*                                                                       */
 105   /* <Return>                                                              */
 106   /*    FreeType error code.  0 means sucess.                              */
 107   /*                                                                       */
 108   FT_EXPORT( FT_Error )
 109   FT_Outline_Decompose( FT_Outline*              outline,
 110                         const FT_Outline_Funcs*  func_interface,
 111                         void*                    user );
 112
 113
 114   /*************************************************************************/
 115   /*                                                                       */
 116   /* <Function>                                                            */
 117   /*    FT_Outline_New                                                     */
 118   /*                                                                       */
 119   /* <Description>                                                         */
 120   /*    Creates a new outline of a given size.                             */
 121   /*                                                                       */
 122   /* <Input>                                                               */
 123   /*    library     :: A handle to the library object from where the       */
 124   /*                   outline is allocated.  Note however that the new    */
 125   /*                   outline will NOT necessarily be FREED, when         */
 126   /*                   destroying the library, by FT_Done_FreeType().      */
 127   /*                                                                       */
 128   /*    numPoints   :: The maximal number of points within the outline.    */
 129   /*                                                                       */
 130   /*    numContours :: The maximal number of contours within the outline.  */
 131   /*                                                                       */
 132   /* <Output>                                                              */
 133   /*    anoutline   :: A handle to the new outline.  NULL in case of       */
 134   /*                   error.                                              */
 135   /*                                                                       */
 136   /* <Return>                                                              */
 137   /*    FreeType error code.  0 means success.                             */
 138   /*                                                                       */
 139   /* <Note>                                                                */
 140   /*    The reason why this function takes a `library' parameter is simply */
 141   /*    to use the library's memory allocator.                             */
 142   /*                                                                       */
 143   FT_EXPORT( FT_Error )
 144   FT_Outline_New( FT_Library   library,
 145                   FT_UInt      numPoints,
 146                   FT_Int       numContours,
 147                   FT_Outline  *anoutline );
 148
 149
 150   FT_EXPORT( FT_Error )
 151   FT_Outline_New_Internal( FT_Memory    memory,
 152                            FT_UInt      numPoints,
 153                            FT_Int       numContours,
 154                            FT_Outline  *anoutline );
 155
 156
 157   /*************************************************************************/
 158   /*                                                                       */
 159   /* <Function>                                                            */
 160   /*    FT_Outline_Done                                                    */
 161   /*                                                                       */
 162   /* <Description>                                                         */
 163   /*    Destroys an outline created with FT_Outline_New().                 */
 164   /*                                                                       */
 165   /* <Input>                                                               */
 166   /*    library :: A handle of the library object used to allocate the     */
 167   /*               outline.                                                */
 168   /*                                                                       */
 169   /*    outline :: A pointer to the outline object to be discarded.        */
 170   /*                                                                       */
 171   /* <Return>                                                              */
 172   /*    FreeType error code.  0 means success.                             */
 173   /*                                                                       */
 174   /* <Note>                                                                */
 175   /*    If the outline's `owner' field is not set, only the outline        */
 176   /*    descriptor will be released.                                       */
 177   /*                                                                       */
 178   /*    The reason why this function takes an `library' parameter is       */
 179   /*    simply to use FT_Free().                                           */
 180   /*                                                                       */
 181   FT_EXPORT( FT_Error )
 182   FT_Outline_Done( FT_Library   library,
 183                    FT_Outline*  outline );
 184
 185
 186   FT_EXPORT( FT_Error )
 187   FT_Outline_Done_Internal( FT_Memory    memory,
 188                             FT_Outline*  outline );
 189
 190
 191   /*************************************************************************/
 192   /*                                                                       */
 193   /* <Function>                                                            */
 194   /*    FT_Outline_Check                                                   */
 195   /*                                                                       */
 196   /* <Description>                                                         */
 197   /*    Check the contents of an outline descriptor.                       */
 198   /*                                                                       */
 199   /* <Input>                                                               */
 200   /*    outline :: A handle to a source outline.                           */
 201   /*                                                                       */
 202   /* <Return>                                                              */
 203   /*    FreeType error code.  0 means success.                             */
 204   /*                                                                       */
 205   FT_EXPORT( FT_Error )
 206   FT_Outline_Check( FT_Outline*  outline );
 207
 208
 209   /*************************************************************************/
 210   /*                                                                       */
 211   /* <Function>                                                            */
 212   /*    FT_Outline_Get_CBox                                                */
 213   /*                                                                       */
 214   /* <Description>                                                         */
 215   /*    Returns an outline's `control box'.  The control box encloses all  */
 216   /*    the outline's points, including Bezier control points.  Though it  */
 217   /*    coincides with the exact bounding box for most glyphs, it can be   */
 218   /*    slightly larger in some situations (like when rotating an outline  */
 219   /*    which contains Bezier outside arcs).                               */
 220   /*                                                                       */
 221   /*    Computing the control box is very fast, while getting the bounding */
 222   /*    box can take much more time as it needs to walk over all segments  */
 223   /*    and arcs in the outline.  To get the latter, you can use the       */
 224   /*    `ftbbox' component which is dedicated to this single task.         */
 225   /*                                                                       */
 226   /* <Input>                                                               */
 227   /*    outline :: A pointer to the source outline descriptor.             */
 228   /*                                                                       */
 229   /* <Output>                                                              */
 230   /*    acbox   :: The outline's control box.                              */
 231   /*                                                                       */
 232   FT_EXPORT( void )
 233   FT_Outline_Get_CBox( const FT_Outline*  outline,
 234                        FT_BBox           *acbox );
 235
 236
 237   /*************************************************************************/
 238   /*                                                                       */
 239   /* <Function>                                                            */
 240   /*    FT_Outline_Translate                                               */
 241   /*                                                                       */
 242   /* <Description>                                                         */
 243   /*    Applies a simple translation to the points of an outline.          */
 244   /*                                                                       */
 245   /* <InOut>                                                               */
 246   /*    outline :: A pointer to the target outline descriptor.             */
 247   /*                                                                       */
 248   /* <Input>                                                               */
 249   /*    xOffset :: The horizontal offset.                                  */
 250   /*                                                                       */
 251   /*    yOffset :: The vertical offset.                                    */
 252   /*                                                                       */
 253   FT_EXPORT( void )
 254   FT_Outline_Translate( const FT_Outline*  outline,
 255                         FT_Pos             xOffset,
 256                         FT_Pos             yOffset );
 257
 258
 259   /*************************************************************************/
 260   /*                                                                       */
 261   /* <Function>                                                            */
 262   /*    FT_Outline_Copy                                                    */
 263   /*                                                                       */
 264   /* <Description>                                                         */
 265   /*    Copies an outline into another one.  Both objects must have the    */
 266   /*    same sizes (number of points & number of contours) when this       */
 267   /*    function is called.                                                */
 268   /*                                                                       */
 269   /* <Input>                                                               */
 270   /*    source :: A handle to the source outline.                          */
 271   /*                                                                       */
 272   /* <Output>                                                              */
 273   /*    target :: A handle to the target outline.                          */
 274   /*                                                                       */
 275   /* <Return>                                                              */
 276   /*    FreeType error code.  0 means success.                             */
 277   /*                                                                       */
 278   FT_EXPORT( FT_Error )
 279   FT_Outline_Copy( const FT_Outline*  source,
 280                    FT_Outline        *target );
 281
 282
 283   /*************************************************************************/
 284   /*                                                                       */
 285   /* <Function>                                                            */
 286   /*    FT_Outline_Transform                                               */
 287   /*                                                                       */
 288   /* <Description>                                                         */
 289   /*    Applies a simple 2x2 matrix to all of an outline's points.  Useful */
 290   /*    for applying rotations, slanting, flipping, etc.                   */
 291   /*                                                                       */
 292   /* <InOut>                                                               */
 293   /*    outline :: A pointer to the target outline descriptor.             */
 294   /*                                                                       */
 295   /* <Input>                                                               */
 296   /*    matrix  :: A pointer to the transformation matrix.                 */
 297   /*                                                                       */
 298   /* <Note>                                                                */
 299   /*    You can use FT_Outline_Translate() if you need to translate the    */
 300   /*    outline's points.                                                  */
 301   /*                                                                       */
 302   FT_EXPORT( void )
 303   FT_Outline_Transform( const FT_Outline*  outline,
 304                         const FT_Matrix*   matrix );
 305
 306
 307   /*************************************************************************/
 308   /*                                                                       */
 309   /* <Function>                                                            */
 310   /*    FT_Outline_Embolden                                                */
 311   /*                                                                       */
 312   /* <Description>                                                         */
 313   /*    Emboldens an outline.  The new outline will be at most 4 times     */
 314   /*    `strength' pixels wider and higher.  You may think of the left and */
 315   /*    bottom borders as unchanged.                                       */
 316   /*                                                                       */
 317   /* <InOut>                                                               */
 318   /*    outline  :: A handle to the target outline.                        */
 319   /*                                                                       */
 320   /* <Input>                                                               */
 321   /*    strength :: How strong the glyph is emboldened.  Expressed in      */
 322   /*                26.6 pixel format.                                     */
 323   /*                                                                       */
 324   /* <Return>                                                              */
 325   /*    FreeType error code.  0 means success.                             */
 326   /*                                                                       */
 327   FT_EXPORT_DEF( FT_Error )
 328   FT_Outline_Embolden( FT_Outline*  outline,
 329                        FT_Pos       strength );
 330
 331
 332   /*************************************************************************/
 333   /*                                                                       */
 334   /* <Function>                                                            */
 335   /*    FT_Outline_Reverse                                                 */
 336   /*                                                                       */
 337   /* <Description>                                                         */
 338   /*    Reverses the drawing direction of an outline.  This is used to     */
 339   /*    ensure consistent fill conventions for mirrored glyphs.            */
 340   /*                                                                       */
 341   /* <InOut>                                                               */
 342   /*    outline :: A pointer to the target outline descriptor.             */
 343   /*                                                                       */
 344   /* <Note>                                                                */
 345   /*    This functions toggles the bit flag `FT_OUTLINE_REVERSE_FILL' in   */
 346   /*    the outline's `flags' field.                                       */
 347   /*                                                                       */
 348   /*    It shouldn't be used by a normal client application, unless it     */
 349   /*    knows what it is doing.                                            */
 350   /*                                                                       */
 351   FT_EXPORT( void )
 352   FT_Outline_Reverse( FT_Outline*  outline );
 353
 354
 355   /*************************************************************************/
 356   /*                                                                       */
 357   /* <Function>                                                            */
 358   /*    FT_Outline_Get_Bitmap                                              */
 359   /*                                                                       */
 360   /* <Description>                                                         */
 361   /*    Renders an outline within a bitmap.  The outline's image is simply */
 362   /*    OR-ed to the target bitmap.                                        */
 363   /*                                                                       */
 364   /* <Input>                                                               */
 365   /*    library :: A handle to a FreeType library object.                  */
 366   /*                                                                       */
 367   /*    outline :: A pointer to the source outline descriptor.             */
 368   /*                                                                       */
 369   /* <Output>                                                              */
 370   /*    abitmap :: A pointer to the target bitmap descriptor.              */
 371   /*                                                                       */
 372   /* <Return>                                                              */
 373   /*    FreeType error code.  0 means success.                             */
 374   /*                                                                       */
 375   /* <Note>                                                                */
 376   /*    This function does NOT CREATE the bitmap, it only renders an       */
 377   /*    outline image within the one you pass to it!                       */
 378   /*                                                                       */
 379   /*    It will use the raster correponding to the default glyph format.   */
 380   /*                                                                       */
 381   FT_EXPORT( FT_Error )
 382   FT_Outline_Get_Bitmap( FT_Library        library,
 383                          FT_Outline*       outline,
 384                          const FT_Bitmap  *abitmap );
 385
 386
 387   /*************************************************************************/
 388   /*                                                                       */
 389   /* <Function>                                                            */
 390   /*    FT_Outline_Render                                                  */
 391   /*                                                                       */
 392   /* <Description>                                                         */
 393   /*    Renders an outline within a bitmap using the current scan-convert. */
 394   /*    This functions uses an FT_Raster_Params structure as an argument,  */
 395   /*    allowing advanced features like direct composition, translucency,  */
 396   /*    etc.                                                               */
 397   /*                                                                       */
 398   /* <Input>                                                               */
 399   /*    library :: A handle to a FreeType library object.                  */
 400   /*                                                                       */
 401   /*    outline :: A pointer to the source outline descriptor.             */
 402   /*                                                                       */
 403   /* <InOut>                                                               */
 404   /*    params  :: A pointer to a FT_Raster_Params structure used to       */
 405   /*               describe the rendering operation.                       */
 406   /*                                                                       */
 407   /* <Return>                                                              */
 408   /*    FreeType error code.  0 means success.                             */
 409   /*                                                                       */
 410   /* <Note>                                                                */
 411   /*    You should know what you are doing and how FT_Raster_Params works  */
 412   /*    to use this function.                                              */
 413   /*                                                                       */
 414   /*    The field `params.source' will be set to `outline' before the scan */
 415   /*    converter is called, which means that the value you give to it is  */
 416   /*    actually ignored.                                                  */
 417   /*                                                                       */
 418   FT_EXPORT( FT_Error )
 419   FT_Outline_Render( FT_Library         library,
 420                      FT_Outline*        outline,
 421                      FT_Raster_Params*  params );
 422
 423
 424  /**************************************************************************
 425   *
 426   * @enum:
 427   *   FT_Orientation
 428   *
 429   * @description:
 430   *   A list of values used to describe an outline's contour orientation.
 431   *
 432   *   The TrueType and Postscript specifications use different conventions
 433   *   to determine whether outline contours should be filled or unfilled.
 434   *
 435   * @values:
 436   *   FT_ORIENTATION_TRUETYPE ::
 437   *     According to the TrueType specification, clockwise contours must
 438   *     be filled, and counter-clockwise ones must be unfilled.
 439   *
 440   *   FT_ORIENTATION_POSTSCRIPT ::
 441   *     According to the Postscript specification, counter-clockwise contours
 442   *     must be filled, and clockwise ones must be unfilled.
 443   *
 444   *   FT_ORIENTATION_FILL_RIGHT ::
 445   *     This is identical to @FT_ORIENTATION_TRUETYPE, but is used to
 446   *     remember that in TrueType, everything that is to the right of
 447   *     the drawing direction of a contour must be filled.
 448   *
 449   *   FT_ORIENTATION_FILL_LEFT ::
 450   *     This is identical to @FT_ORIENTATION_POSTSCRIPT, but is used to
 451   *     remember that in Postscript, everything that is to the left of
 452   *     the drawing direction of a contour must be filled.
 453   */
 454   typedef enum
 455   {
 456     FT_ORIENTATION_TRUETYPE   = 0,
 457     FT_ORIENTATION_POSTSCRIPT = 1,
 458     FT_ORIENTATION_FILL_RIGHT = FT_ORIENTATION_TRUETYPE,
 459     FT_ORIENTATION_FILL_LEFT  = FT_ORIENTATION_POSTSCRIPT
 460
 461   } FT_Orientation;
 462
 463
 464  /**************************************************************************
 465   *
 466   * @function:
 467   *   FT_Outline_Get_Orientation
 468   *
 469   * @description:
 470   *   This function analyzes a glyph outline and tries to compute its
 471   *   fill orientation (see @FT_Orientation).  This is done by computing
 472   *   the direction of each global horizontal and/or vertical extrema
 473   *   within the outline.
 474   *
 475   *   Note that this will return @FT_ORIENTATION_TRUETYPE for empty
 476   *   outlines.
 477   *
 478   * @input:
 479   *   outline ::
 480   *     A handle to the source outline.
 481   *
 482   * @return:
 483   *   The orientation.
 484   *
 485   */
 486   FT_EXPORT( FT_Orientation )
 487   FT_Outline_Get_Orientation( FT_Outline*  outline );
 488
 489
 490   /* */
 491
 492
 493 FT_END_HEADER
 494
 495 #endif /* __FTOUTLN_H__ */
 496
 497
 498 /* END */