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