include/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-2003, 2005-2014 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_New                                                     */
  56   /*    FT_Outline_Done                                                    */
  57   /*    FT_Outline_Copy                                                    */
  58   /*    FT_Outline_Translate                                               */
  59   /*    FT_Outline_Transform                                               */
  60   /*    FT_Outline_Embolden                                                */
  61   /*    FT_Outline_EmboldenXY                                              */
  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   /*    FT_Outline_Decompose                                               */
  71   /*    FT_Outline_Funcs                                                   */
  72   /*    FT_Outline_MoveToFunc                                              */
  73   /*    FT_Outline_LineToFunc                                              */
  74   /*    FT_Outline_ConicToFunc                                             */
  75   /*    FT_Outline_CubicToFunc                                             */
  76   /*                                                                       */
  77   /*    FT_Orientation                                                     */
  78   /*    FT_Outline_Get_Orientation                                         */
  79   /*                                                                       */
  80   /*    FT_OUTLINE_XXX                                                     */
  81   /*                                                                       */
  82   /*************************************************************************/
  83
  84
  85   /*************************************************************************/
  86   /*                                                                       */
  87   /* <Function>                                                            */
  88   /*    FT_Outline_Decompose                                               */
  89   /*                                                                       */
  90   /* <Description>                                                         */
  91   /*    Walk over an outline's structure to decompose it into individual   */
  92   /*    segments and Bézier arcs.  This function also emits `move to'      */
  93   /*    operations to indicate the start of new contours in the outline.   */
  94   /*                                                                       */
  95   /* <Input>                                                               */
  96   /*    outline        :: A pointer to the source target.                  */
  97   /*                                                                       */
  98   /*    func_interface :: A table of `emitters', i.e., function pointers   */
  99   /*                      called during decomposition to indicate path     */
 100   /*                      operations.                                      */
 101   /*                                                                       */
 102   /* <InOut>                                                               */
 103   /*    user           :: A typeless pointer that is passed to each        */
 104   /*                      emitter during the decomposition.  It can be     */
 105   /*                      used to store the state during the               */
 106   /*                      decomposition.                                   */
 107   /*                                                                       */
 108   /* <Return>                                                              */
 109   /*    FreeType error code.  0~means success.                             */
 110   /*                                                                       */
 111   /* <Note>                                                                */
 112   /*    A contour that contains a single point only is represented by a    */
 113   /*    `move to' operation followed by `line to' to the same point.  In   */
 114   /*    most cases, it is best to filter this out before using the         */
 115   /*    outline for stroking purposes (otherwise it would result in a      */
 116   /*    visible dot when round caps are used).                             */
 117   /*                                                                       */
 118   FT_EXPORT( FT_Error )
 119   FT_Outline_Decompose( FT_Outline*              outline,
 120                         const FT_Outline_Funcs*  func_interface,
 121                         void*                    user );
 122
 123
 124   /*************************************************************************/
 125   /*                                                                       */
 126   /* <Function>                                                            */
 127   /*    FT_Outline_New                                                     */
 128   /*                                                                       */
 129   /* <Description>                                                         */
 130   /*    Create a new outline of a given size.                              */
 131   /*                                                                       */
 132   /* <Input>                                                               */
 133   /*    library     :: A handle to the library object from where the       */
 134   /*                   outline is allocated.  Note however that the new    */
 135   /*                   outline will *not* necessarily be *freed*, when     */
 136   /*                   destroying the library, by @FT_Done_FreeType.       */
 137   /*                                                                       */
 138   /*    numPoints   :: The maximum number of points within the outline.    */
 139   /*                   Must be smaller than or equal to 0xFFFF (65535).    */
 140   /*                                                                       */
 141   /*    numContours :: The maximum number of contours within the outline.  */
 142   /*                   This value must be in the range 0 to `numPoints'.   */
 143   /*                                                                       */
 144   /* <Output>                                                              */
 145   /*    anoutline   :: A handle to the new outline.                        */
 146   /*                                                                       */
 147   /* <Return>                                                              */
 148   /*    FreeType error code.  0~means success.                             */
 149   /*                                                                       */
 150   /* <Note>                                                                */
 151   /*    The reason why this function takes a `library' parameter is simply */
 152   /*    to use the library's memory allocator.                             */
 153   /*                                                                       */
 154   FT_EXPORT( FT_Error )
 155   FT_Outline_New( FT_Library   library,
 156                   FT_UInt      numPoints,
 157                   FT_Int       numContours,
 158                   FT_Outline  *anoutline );
 159
 160
 161   FT_EXPORT( FT_Error )
 162   FT_Outline_New_Internal( FT_Memory    memory,
 163                            FT_UInt      numPoints,
 164                            FT_Int       numContours,
 165                            FT_Outline  *anoutline );
 166
 167
 168   /*************************************************************************/
 169   /*                                                                       */
 170   /* <Function>                                                            */
 171   /*    FT_Outline_Done                                                    */
 172   /*                                                                       */
 173   /* <Description>                                                         */
 174   /*    Destroy an outline created with @FT_Outline_New.                   */
 175   /*                                                                       */
 176   /* <Input>                                                               */
 177   /*    library :: A handle of the library object used to allocate the     */
 178   /*               outline.                                                */
 179   /*                                                                       */
 180   /*    outline :: A pointer to the outline object to be discarded.        */
 181   /*                                                                       */
 182   /* <Return>                                                              */
 183   /*    FreeType error code.  0~means success.                             */
 184   /*                                                                       */
 185   /* <Note>                                                                */
 186   /*    If the outline's `owner' field is not set, only the outline        */
 187   /*    descriptor will be released.                                       */
 188   /*                                                                       */
 189   /*    The reason why this function takes an `library' parameter is       */
 190   /*    simply to use ft_mem_free().                                       */
 191   /*                                                                       */
 192   FT_EXPORT( FT_Error )
 193   FT_Outline_Done( FT_Library   library,
 194                    FT_Outline*  outline );
 195
 196
 197   FT_EXPORT( FT_Error )
 198   FT_Outline_Done_Internal( FT_Memory    memory,
 199                             FT_Outline*  outline );
 200
 201
 202   /*************************************************************************/
 203   /*                                                                       */
 204   /* <Function>                                                            */
 205   /*    FT_Outline_Check                                                   */
 206   /*                                                                       */
 207   /* <Description>                                                         */
 208   /*    Check the contents of an outline descriptor.                       */
 209   /*                                                                       */
 210   /* <Input>                                                               */
 211   /*    outline :: A handle to a source outline.                           */
 212   /*                                                                       */
 213   /* <Return>                                                              */
 214   /*    FreeType error code.  0~means success.                             */
 215   /*                                                                       */
 216   FT_EXPORT( FT_Error )
 217   FT_Outline_Check( FT_Outline*  outline );
 218
 219
 220   /*************************************************************************/
 221   /*                                                                       */
 222   /* <Function>                                                            */
 223   /*    FT_Outline_Get_CBox                                                */
 224   /*                                                                       */
 225   /* <Description>                                                         */
 226   /*    Return an outline's `control box'.  The control box encloses all   */
 227   /*    the outline's points, including Bézier control points.  Though it  */
 228   /*    coincides with the exact bounding box for most glyphs, it can be   */
 229   /*    slightly larger in some situations (like when rotating an outline  */
 230   /*    that contains Bézier outside arcs).                                */
 231   /*                                                                       */
 232   /*    Computing the control box is very fast, while getting the bounding */
 233   /*    box can take much more time as it needs to walk over all segments  */
 234   /*    and arcs in the outline.  To get the latter, you can use the       */
 235   /*    `ftbbox' component, which is dedicated to this single task.        */
 236   /*                                                                       */
 237   /* <Input>                                                               */
 238   /*    outline :: A pointer to the source outline descriptor.             */
 239   /*                                                                       */
 240   /* <Output>                                                              */
 241   /*    acbox   :: The outline's control box.                              */
 242   /*                                                                       */
 243   /* <Note>                                                                */
 244   /*    See @FT_Glyph_Get_CBox for a discussion of tricky fonts.           */
 245   /*                                                                       */
 246   FT_EXPORT( void )
 247   FT_Outline_Get_CBox( const FT_Outline*  outline,
 248                        FT_BBox           *acbox );
 249
 250
 251   /*************************************************************************/
 252   /*                                                                       */
 253   /* <Function>                                                            */
 254   /*    FT_Outline_Translate                                               */
 255   /*                                                                       */
 256   /* <Description>                                                         */
 257   /*    Apply a simple translation to the points of an outline.            */
 258   /*                                                                       */
 259   /* <InOut>                                                               */
 260   /*    outline :: A pointer to the target outline descriptor.             */
 261   /*                                                                       */
 262   /* <Input>                                                               */
 263   /*    xOffset :: The horizontal offset.                                  */
 264   /*                                                                       */
 265   /*    yOffset :: The vertical offset.                                    */
 266   /*                                                                       */
 267   FT_EXPORT( void )
 268   FT_Outline_Translate( const FT_Outline*  outline,
 269                         FT_Pos             xOffset,
 270                         FT_Pos             yOffset );
 271
 272
 273   /*************************************************************************/
 274   /*                                                                       */
 275   /* <Function>                                                            */
 276   /*    FT_Outline_Copy                                                    */
 277   /*                                                                       */
 278   /* <Description>                                                         */
 279   /*    Copy an outline into another one.  Both objects must have the      */
 280   /*    same sizes (number of points & number of contours) when this       */
 281   /*    function is called.                                                */
 282   /*                                                                       */
 283   /* <Input>                                                               */
 284   /*    source :: A handle to the source outline.                          */
 285   /*                                                                       */
 286   /* <Output>                                                              */
 287   /*    target :: A handle to the target outline.                          */
 288   /*                                                                       */
 289   /* <Return>                                                              */
 290   /*    FreeType error code.  0~means success.                             */
 291   /*                                                                       */
 292   FT_EXPORT( FT_Error )
 293   FT_Outline_Copy( const FT_Outline*  source,
 294                    FT_Outline        *target );
 295
 296
 297   /*************************************************************************/
 298   /*                                                                       */
 299   /* <Function>                                                            */
 300   /*    FT_Outline_Transform                                               */
 301   /*                                                                       */
 302   /* <Description>                                                         */
 303   /*    Apply a simple 2x2 matrix to all of an outline's points.  Useful   */
 304   /*    for applying rotations, slanting, flipping, etc.                   */
 305   /*                                                                       */
 306   /* <InOut>                                                               */
 307   /*    outline :: A pointer to the target outline descriptor.             */
 308   /*                                                                       */
 309   /* <Input>                                                               */
 310   /*    matrix  :: A pointer to the transformation matrix.                 */
 311   /*                                                                       */
 312   /* <Note>                                                                */
 313   /*    You can use @FT_Outline_Translate if you need to translate the     */
 314   /*    outline's points.                                                  */
 315   /*                                                                       */
 316   FT_EXPORT( void )
 317   FT_Outline_Transform( const FT_Outline*  outline,
 318                         const FT_Matrix*   matrix );
 319
 320
 321   /*************************************************************************/
 322   /*                                                                       */
 323   /* <Function>                                                            */
 324   /*    FT_Outline_Embolden                                                */
 325   /*                                                                       */
 326   /* <Description>                                                         */
 327   /*    Embolden an outline.  The new outline will be at most 4~times      */
 328   /*    `strength' pixels wider and higher.  You may think of the left and */
 329   /*    bottom borders as unchanged.                                       */
 330   /*                                                                       */
 331   /*    Negative `strength' values to reduce the outline thickness are     */
 332   /*    possible also.                                                     */
 333   /*                                                                       */
 334   /* <InOut>                                                               */
 335   /*    outline  :: A handle to the target outline.                        */
 336   /*                                                                       */
 337   /* <Input>                                                               */
 338   /*    strength :: How strong the glyph is emboldened.  Expressed in      */
 339   /*                26.6 pixel format.                                     */
 340   /*                                                                       */
 341   /* <Return>                                                              */
 342   /*    FreeType error code.  0~means success.                             */
 343   /*                                                                       */
 344   /* <Note>                                                                */
 345   /*    The used algorithm to increase or decrease the thickness of the    */
 346   /*    glyph doesn't change the number of points; this means that certain */
 347   /*    situations like acute angles or intersections are sometimes        */
 348   /*    handled incorrectly.                                               */
 349   /*                                                                       */
 350   /*    If you need `better' metrics values you should call                */
 351   /*    @FT_Outline_Get_CBox or @FT_Outline_Get_BBox.                      */
 352   /*                                                                       */
 353   /*    Example call:                                                      */
 354   /*                                                                       */
 355   /*    {                                                                  */
 356   /*      FT_Load_Glyph( face, index, FT_LOAD_DEFAULT );                   */
 357   /*      if ( face->slot->format == FT_GLYPH_FORMAT_OUTLINE )             */
 358   /*        FT_Outline_Embolden( &face->slot->outline, strength );         */
 359   /*    }                                                                  */
 360   /*                                                                       */
 361   /*    To get meaningful results, font scaling values must be set with    */
 362   /*    functions like @FT_Set_Char_Size before calling FT_Render_Glyph.   */
 363   /*                                                                       */
 364   FT_EXPORT( FT_Error )
 365   FT_Outline_Embolden( FT_Outline*  outline,
 366                        FT_Pos       strength );
 367
 368
 369   /*************************************************************************/
 370   /*                                                                       */
 371   /* <Function>                                                            */
 372   /*    FT_Outline_EmboldenXY                                              */
 373   /*                                                                       */
 374   /* <Description>                                                         */
 375   /*    Embolden an outline.  The new outline will be `xstrength' pixels   */
 376   /*    wider and `ystrength' pixels higher.  Otherwise, it is similar to  */
 377   /*    @FT_Outline_Embolden, which uses the same strength in both         */
 378   /*    directions.                                                        */
 379   /*                                                                       */
 380   FT_EXPORT( FT_Error )
 381   FT_Outline_EmboldenXY( FT_Outline*  outline,
 382                          FT_Pos       xstrength,
 383                          FT_Pos       ystrength );
 384
 385
 386   /*************************************************************************/
 387   /*                                                                       */
 388   /* <Function>                                                            */
 389   /*    FT_Outline_Reverse                                                 */
 390   /*                                                                       */
 391   /* <Description>                                                         */
 392   /*    Reverse the drawing direction of an outline.  This is used to      */
 393   /*    ensure consistent fill conventions for mirrored glyphs.            */
 394   /*                                                                       */
 395   /* <InOut>                                                               */
 396   /*    outline :: A pointer to the target outline descriptor.             */
 397   /*                                                                       */
 398   /* <Note>                                                                */
 399   /*    This function toggles the bit flag @FT_OUTLINE_REVERSE_FILL in     */
 400   /*    the outline's `flags' field.                                       */
 401   /*                                                                       */
 402   /*    It shouldn't be used by a normal client application, unless it     */
 403   /*    knows what it is doing.                                            */
 404   /*                                                                       */
 405   FT_EXPORT( void )
 406   FT_Outline_Reverse( FT_Outline*  outline );
 407
 408
 409   /*************************************************************************/
 410   /*                                                                       */
 411   /* <Function>                                                            */
 412   /*    FT_Outline_Get_Bitmap                                              */
 413   /*                                                                       */
 414   /* <Description>                                                         */
 415   /*    Render an outline within a bitmap.  The outline's image is simply  */
 416   /*    OR-ed to the target bitmap.                                        */
 417   /*                                                                       */
 418   /* <Input>                                                               */
 419   /*    library :: A handle to a FreeType library object.                  */
 420   /*                                                                       */
 421   /*    outline :: A pointer to the source outline descriptor.             */
 422   /*                                                                       */
 423   /* <InOut>                                                               */
 424   /*    abitmap :: A pointer to the target bitmap descriptor.              */
 425   /*                                                                       */
 426   /* <Return>                                                              */
 427   /*    FreeType error code.  0~means success.                             */
 428   /*                                                                       */
 429   /* <Note>                                                                */
 430   /*    This function does NOT CREATE the bitmap, it only renders an       */
 431   /*    outline image within the one you pass to it!  Consequently, the    */
 432   /*    various fields in `abitmap' should be set accordingly.             */
 433   /*                                                                       */
 434   /*    It will use the raster corresponding to the default glyph format.  */
 435   /*                                                                       */
 436   /*    The value of the `num_grays' field in `abitmap' is ignored.  If    */
 437   /*    you select the gray-level rasterizer, and you want less than 256   */
 438   /*    gray levels, you have to use @FT_Outline_Render directly.          */
 439   /*                                                                       */
 440   FT_EXPORT( FT_Error )
 441   FT_Outline_Get_Bitmap( FT_Library        library,
 442                          FT_Outline*       outline,
 443                          const FT_Bitmap  *abitmap );
 444
 445
 446   /*************************************************************************/
 447   /*                                                                       */
 448   /* <Function>                                                            */
 449   /*    FT_Outline_Render                                                  */
 450   /*                                                                       */
 451   /* <Description>                                                         */
 452   /*    Render an outline within a bitmap using the current scan-convert.  */
 453   /*    This function uses an @FT_Raster_Params structure as an argument,  */
 454   /*    allowing advanced features like direct composition, translucency,  */
 455   /*    etc.                                                               */
 456   /*                                                                       */
 457   /* <Input>                                                               */
 458   /*    library :: A handle to a FreeType library object.                  */
 459   /*                                                                       */
 460   /*    outline :: A pointer to the source outline descriptor.             */
 461   /*                                                                       */
 462   /* <InOut>                                                               */
 463   /*    params  :: A pointer to an @FT_Raster_Params structure used to     */
 464   /*               describe the rendering operation.                       */
 465   /*                                                                       */
 466   /* <Return>                                                              */
 467   /*    FreeType error code.  0~means success.                             */
 468   /*                                                                       */
 469   /* <Note>                                                                */
 470   /*    You should know what you are doing and how @FT_Raster_Params works */
 471   /*    to use this function.                                              */
 472   /*                                                                       */
 473   /*    The field `params.source' will be set to `outline' before the scan */
 474   /*    converter is called, which means that the value you give to it is  */
 475   /*    actually ignored.                                                  */
 476   /*                                                                       */
 477   /*    The gray-level rasterizer always uses 256 gray levels.  If you     */
 478   /*    want less gray levels, you have to provide your own span callback. */
 479   /*    See the @FT_RASTER_FLAG_DIRECT value of the `flags' field in the   */
 480   /*    @FT_Raster_Params structure for more details.                      */
 481   /*                                                                       */
 482   FT_EXPORT( FT_Error )
 483   FT_Outline_Render( FT_Library         library,
 484                      FT_Outline*        outline,
 485                      FT_Raster_Params*  params );
 486
 487
 488  /**************************************************************************
 489   *
 490   * @enum:
 491   *   FT_Orientation
 492   *
 493   * @description:
 494   *   A list of values used to describe an outline's contour orientation.
 495   *
 496   *   The TrueType and PostScript specifications use different conventions
 497   *   to determine whether outline contours should be filled or unfilled.
 498   *
 499   * @values:
 500   *   FT_ORIENTATION_TRUETYPE ::
 501   *     According to the TrueType specification, clockwise contours must
 502   *     be filled, and counter-clockwise ones must be unfilled.
 503   *
 504   *   FT_ORIENTATION_POSTSCRIPT ::
 505   *     According to the PostScript specification, counter-clockwise contours
 506   *     must be filled, and clockwise ones must be unfilled.
 507   *
 508   *   FT_ORIENTATION_FILL_RIGHT ::
 509   *     This is identical to @FT_ORIENTATION_TRUETYPE, but is used to
 510   *     remember that in TrueType, everything that is to the right of
 511   *     the drawing direction of a contour must be filled.
 512   *
 513   *   FT_ORIENTATION_FILL_LEFT ::
 514   *     This is identical to @FT_ORIENTATION_POSTSCRIPT, but is used to
 515   *     remember that in PostScript, everything that is to the left of
 516   *     the drawing direction of a contour must be filled.
 517   *
 518   *   FT_ORIENTATION_NONE ::
 519   *     The orientation cannot be determined.  That is, different parts of
 520   *     the glyph have different orientation.
 521   *
 522   */
 523   typedef enum  FT_Orientation_
 524   {
 525     FT_ORIENTATION_TRUETYPE   = 0,
 526     FT_ORIENTATION_POSTSCRIPT = 1,
 527     FT_ORIENTATION_FILL_RIGHT = FT_ORIENTATION_TRUETYPE,
 528     FT_ORIENTATION_FILL_LEFT  = FT_ORIENTATION_POSTSCRIPT,
 529     FT_ORIENTATION_NONE
 530
 531   } FT_Orientation;
 532
 533
 534  /**************************************************************************
 535   *
 536   * @function:
 537   *   FT_Outline_Get_Orientation
 538   *
 539   * @description:
 540   *   This function analyzes a glyph outline and tries to compute its
 541   *   fill orientation (see @FT_Orientation).  This is done by integrating
 542   *   the total area covered by the outline. The positive integral
 543   *   corresponds to the clockwise orientation and @FT_ORIENTATION_POSTSCRIPT
 544   *   is returned. The negative integral corresponds to the counter-clockwise
 545   *   orientation and @FT_ORIENTATION_TRUETYPE is returned.
 546   *
 547   *   Note that this will return @FT_ORIENTATION_TRUETYPE for empty
 548   *   outlines.
 549   *
 550   * @input:
 551   *   outline ::
 552   *     A handle to the source outline.
 553   *
 554   * @return:
 555   *   The orientation.
 556   *
 557   */
 558   FT_EXPORT( FT_Orientation )
 559   FT_Outline_Get_Orientation( FT_Outline*  outline );
 560
 561   /* */
 562
 563
 564 FT_END_HEADER
 565
 566 #endif /* __FTOUTLN_H__ */
 567
 568
 569 /* END */
 570
 571
 572 /* Local Variables: */
 573 /* coding: utf-8    */
 574 /* End:             */