freetype2/freetype/ftoutln.h

0001 /****************************************************************************
0002  *
0003  * ftoutln.h
0004  *
0005  *   Support for the FT_Outline type used to store glyph shapes of
0006  *   most scalable font formats (specification).
0007  *
0008  * Copyright (C) 1996-2023 by
0009  * David Turner, Robert Wilhelm, and Werner Lemberg.
0010  *
0011  * This file is part of the FreeType project, and may only be used,
0012  * modified, and distributed under the terms of the FreeType project
0013  * license, LICENSE.TXT.  By continuing to use, modify, or distribute
0014  * this file you indicate that you have read the license and
0015  * understand and accept it fully.
0016  *
0017  */
0018
0019
0020 #ifndef FTOUTLN_H_
0021 #define FTOUTLN_H_
0022
0023
0024 #include <freetype/freetype.h>
0025
0026 #ifdef FREETYPE_H
0027 #error "freetype.h of FreeType 1 has been loaded!"
0028 #error "Please fix the directory search order for header files"
0029 #error "so that freetype.h of FreeType 2 is found first."
0030 #endif
0031
0032
0033 FT_BEGIN_HEADER
0034
0035
0036   /**************************************************************************
0037    *
0038    * @section:
0039    *   outline_processing
0040    *
0041    * @title:
0042    *   Outline Processing
0043    *
0044    * @abstract:
0045    *   Functions to create, transform, and render vectorial glyph images.
0046    *
0047    * @description:
0048    *   This section contains routines used to create and destroy scalable
0049    *   glyph images known as 'outlines'.  These can also be measured,
0050    *   transformed, and converted into bitmaps and pixmaps.
0051    *
0052    * @order:
0053    *   FT_Outline
0054    *   FT_Outline_New
0055    *   FT_Outline_Done
0056    *   FT_Outline_Copy
0057    *   FT_Outline_Translate
0058    *   FT_Outline_Transform
0059    *   FT_Outline_Embolden
0060    *   FT_Outline_EmboldenXY
0061    *   FT_Outline_Reverse
0062    *   FT_Outline_Check
0063    *
0064    *   FT_Outline_Get_CBox
0065    *   FT_Outline_Get_BBox
0066    *
0067    *   FT_Outline_Get_Bitmap
0068    *   FT_Outline_Render
0069    *   FT_Outline_Decompose
0070    *   FT_Outline_Funcs
0071    *   FT_Outline_MoveToFunc
0072    *   FT_Outline_LineToFunc
0073    *   FT_Outline_ConicToFunc
0074    *   FT_Outline_CubicToFunc
0075    *
0076    *   FT_Orientation
0077    *   FT_Outline_Get_Orientation
0078    *
0079    *   FT_OUTLINE_XXX
0080    *
0081    */
0082
0083
0084   /**************************************************************************
0085    *
0086    * @function:
0087    *   FT_Outline_Decompose
0088    *
0089    * @description:
0090    *   Walk over an outline's structure to decompose it into individual
0091    *   segments and Bezier arcs.  This function also emits 'move to'
0092    *   operations to indicate the start of new contours in the outline.
0093    *
0094    * @input:
0095    *   outline ::
0096    *     A pointer to the source target.
0097    *
0098    *   func_interface ::
0099    *     A table of 'emitters', i.e., function pointers called during
0100    *     decomposition to indicate path operations.
0101    *
0102    * @inout:
0103    *   user ::
0104    *     A typeless pointer that is passed to each emitter during the
0105    *     decomposition.  It can be used to store the state during the
0106    *     decomposition.
0107    *
0108    * @return:
0109    *   FreeType error code.  0~means success.
0110    *
0111    * @note:
0112    *   Degenerate contours, segments, and Bezier arcs may be reported.  In
0113    *   most cases, it is best to filter these out before using the outline
0114    *   for stroking or other path modification purposes (which may cause
0115    *   degenerate segments to become non-degenrate and visible, like when
0116    *   stroke caps are used or the path is otherwise outset).  Some glyph
0117    *   outlines may contain deliberate degenerate single points for mark
0118    *   attachement.
0119    *
0120    *   Similarly, the function returns success for an empty outline also
0121    *   (doing nothing, that is, not calling any emitter); if necessary, you
0122    *   should filter this out, too.
0123    */
0124   FT_EXPORT( FT_Error )
0125   FT_Outline_Decompose( FT_Outline*              outline,
0126                         const FT_Outline_Funcs*  func_interface,
0127                         void*                    user );
0128
0129
0130   /**************************************************************************
0131    *
0132    * @function:
0133    *   FT_Outline_New
0134    *
0135    * @description:
0136    *   Create a new outline of a given size.
0137    *
0138    * @input:
0139    *   library ::
0140    *     A handle to the library object from where the outline is allocated.
0141    *     Note however that the new outline will **not** necessarily be
0142    *     **freed**, when destroying the library, by @FT_Done_FreeType.
0143    *
0144    *   numPoints ::
0145    *     The maximum number of points within the outline.  Must be smaller
0146    *     than or equal to 0xFFFF (65535).
0147    *
0148    *   numContours ::
0149    *     The maximum number of contours within the outline.  This value must
0150    *     be in the range 0 to `numPoints`.
0151    *
0152    * @output:
0153    *   anoutline ::
0154    *     A handle to the new outline.
0155    *
0156    * @return:
0157    *   FreeType error code.  0~means success.
0158    *
0159    * @note:
0160    *   The reason why this function takes a `library` parameter is simply to
0161    *   use the library's memory allocator.
0162    */
0163   FT_EXPORT( FT_Error )
0164   FT_Outline_New( FT_Library   library,
0165                   FT_UInt      numPoints,
0166                   FT_Int       numContours,
0167                   FT_Outline  *anoutline );
0168
0169
0170   /**************************************************************************
0171    *
0172    * @function:
0173    *   FT_Outline_Done
0174    *
0175    * @description:
0176    *   Destroy an outline created with @FT_Outline_New.
0177    *
0178    * @input:
0179    *   library ::
0180    *     A handle of the library object used to allocate the outline.
0181    *
0182    *   outline ::
0183    *     A pointer to the outline object to be discarded.
0184    *
0185    * @return:
0186    *   FreeType error code.  0~means success.
0187    *
0188    * @note:
0189    *   If the outline's 'owner' field is not set, only the outline descriptor
0190    *   will be released.
0191    */
0192   FT_EXPORT( FT_Error )
0193   FT_Outline_Done( FT_Library   library,
0194                    FT_Outline*  outline );
0195
0196
0197   /**************************************************************************
0198    *
0199    * @function:
0200    *   FT_Outline_Check
0201    *
0202    * @description:
0203    *   Check the contents of an outline descriptor.
0204    *
0205    * @input:
0206    *   outline ::
0207    *     A handle to a source outline.
0208    *
0209    * @return:
0210    *   FreeType error code.  0~means success.
0211    *
0212    * @note:
0213    *   An empty outline, or an outline with a single point only is also
0214    *   valid.
0215    */
0216   FT_EXPORT( FT_Error )
0217   FT_Outline_Check( FT_Outline*  outline );
0218
0219
0220   /**************************************************************************
0221    *
0222    * @function:
0223    *   FT_Outline_Get_CBox
0224    *
0225    * @description:
0226    *   Return an outline's 'control box'.  The control box encloses all the
0227    *   outline's points, including Bezier control points.  Though it
0228    *   coincides with the exact bounding box for most glyphs, it can be
0229    *   slightly larger in some situations (like when rotating an outline that
0230    *   contains Bezier outside arcs).
0231    *
0232    *   Computing the control box is very fast, while getting the bounding box
0233    *   can take much more time as it needs to walk over all segments and arcs
0234    *   in the outline.  To get the latter, you can use the 'ftbbox'
0235    *   component, which is dedicated to this single task.
0236    *
0237    * @input:
0238    *   outline ::
0239    *     A pointer to the source outline descriptor.
0240    *
0241    * @output:
0242    *   acbox ::
0243    *     The outline's control box.
0244    *
0245    * @note:
0246    *   See @FT_Glyph_Get_CBox for a discussion of tricky fonts.
0247    */
0248   FT_EXPORT( void )
0249   FT_Outline_Get_CBox( const FT_Outline*  outline,
0250                        FT_BBox           *acbox );
0251
0252
0253   /**************************************************************************
0254    *
0255    * @function:
0256    *   FT_Outline_Translate
0257    *
0258    * @description:
0259    *   Apply a simple translation to the points of an outline.
0260    *
0261    * @inout:
0262    *   outline ::
0263    *     A pointer to the target outline descriptor.
0264    *
0265    * @input:
0266    *   xOffset ::
0267    *     The horizontal offset.
0268    *
0269    *   yOffset ::
0270    *     The vertical offset.
0271    */
0272   FT_EXPORT( void )
0273   FT_Outline_Translate( const FT_Outline*  outline,
0274                         FT_Pos             xOffset,
0275                         FT_Pos             yOffset );
0276
0277
0278   /**************************************************************************
0279    *
0280    * @function:
0281    *   FT_Outline_Copy
0282    *
0283    * @description:
0284    *   Copy an outline into another one.  Both objects must have the same
0285    *   sizes (number of points & number of contours) when this function is
0286    *   called.
0287    *
0288    * @input:
0289    *   source ::
0290    *     A handle to the source outline.
0291    *
0292    * @output:
0293    *   target ::
0294    *     A handle to the target outline.
0295    *
0296    * @return:
0297    *   FreeType error code.  0~means success.
0298    */
0299   FT_EXPORT( FT_Error )
0300   FT_Outline_Copy( const FT_Outline*  source,
0301                    FT_Outline        *target );
0302
0303
0304   /**************************************************************************
0305    *
0306    * @function:
0307    *   FT_Outline_Transform
0308    *
0309    * @description:
0310    *   Apply a simple 2x2 matrix to all of an outline's points.  Useful for
0311    *   applying rotations, slanting, flipping, etc.
0312    *
0313    * @inout:
0314    *   outline ::
0315    *     A pointer to the target outline descriptor.
0316    *
0317    * @input:
0318    *   matrix ::
0319    *     A pointer to the transformation matrix.
0320    *
0321    * @note:
0322    *   You can use @FT_Outline_Translate if you need to translate the
0323    *   outline's points.
0324    */
0325   FT_EXPORT( void )
0326   FT_Outline_Transform( const FT_Outline*  outline,
0327                         const FT_Matrix*   matrix );
0328
0329
0330   /**************************************************************************
0331    *
0332    * @function:
0333    *   FT_Outline_Embolden
0334    *
0335    * @description:
0336    *   Embolden an outline.  The new outline will be at most 4~times
0337    *   `strength` pixels wider and higher.  You may think of the left and
0338    *   bottom borders as unchanged.
0339    *
0340    *   Negative `strength` values to reduce the outline thickness are
0341    *   possible also.
0342    *
0343    * @inout:
0344    *   outline ::
0345    *     A handle to the target outline.
0346    *
0347    * @input:
0348    *   strength ::
0349    *     How strong the glyph is emboldened.  Expressed in 26.6 pixel format.
0350    *
0351    * @return:
0352    *   FreeType error code.  0~means success.
0353    *
0354    * @note:
0355    *   The used algorithm to increase or decrease the thickness of the glyph
0356    *   doesn't change the number of points; this means that certain
0357    *   situations like acute angles or intersections are sometimes handled
0358    *   incorrectly.
0359    *
0360    *   If you need 'better' metrics values you should call
0361    *   @FT_Outline_Get_CBox or @FT_Outline_Get_BBox.
0362    *
0363    *   To get meaningful results, font scaling values must be set with
0364    *   functions like @FT_Set_Char_Size before calling FT_Render_Glyph.
0365    *
0366    * @example:
0367    *   ```
0368    *     FT_Load_Glyph( face, index, FT_LOAD_DEFAULT );
0369    *
0370    *     if ( face->glyph->format == FT_GLYPH_FORMAT_OUTLINE )
0371    *       FT_Outline_Embolden( &face->glyph->outline, strength );
0372    *   ```
0373    *
0374    */
0375   FT_EXPORT( FT_Error )
0376   FT_Outline_Embolden( FT_Outline*  outline,
0377                        FT_Pos       strength );
0378
0379
0380   /**************************************************************************
0381    *
0382    * @function:
0383    *   FT_Outline_EmboldenXY
0384    *
0385    * @description:
0386    *   Embolden an outline.  The new outline will be `xstrength` pixels wider
0387    *   and `ystrength` pixels higher.  Otherwise, it is similar to
0388    *   @FT_Outline_Embolden, which uses the same strength in both directions.
0389    *
0390    * @since:
0391    *   2.4.10
0392    */
0393   FT_EXPORT( FT_Error )
0394   FT_Outline_EmboldenXY( FT_Outline*  outline,
0395                          FT_Pos       xstrength,
0396                          FT_Pos       ystrength );
0397
0398
0399   /**************************************************************************
0400    *
0401    * @function:
0402    *   FT_Outline_Reverse
0403    *
0404    * @description:
0405    *   Reverse the drawing direction of an outline.  This is used to ensure
0406    *   consistent fill conventions for mirrored glyphs.
0407    *
0408    * @inout:
0409    *   outline ::
0410    *     A pointer to the target outline descriptor.
0411    *
0412    * @note:
0413    *   This function toggles the bit flag @FT_OUTLINE_REVERSE_FILL in the
0414    *   outline's `flags` field.
0415    *
0416    *   It shouldn't be used by a normal client application, unless it knows
0417    *   what it is doing.
0418    */
0419   FT_EXPORT( void )
0420   FT_Outline_Reverse( FT_Outline*  outline );
0421
0422
0423   /**************************************************************************
0424    *
0425    * @function:
0426    *   FT_Outline_Get_Bitmap
0427    *
0428    * @description:
0429    *   Render an outline within a bitmap.  The outline's image is simply
0430    *   OR-ed to the target bitmap.
0431    *
0432    * @input:
0433    *   library ::
0434    *     A handle to a FreeType library object.
0435    *
0436    *   outline ::
0437    *     A pointer to the source outline descriptor.
0438    *
0439    * @inout:
0440    *   abitmap ::
0441    *     A pointer to the target bitmap descriptor.
0442    *
0443    * @return:
0444    *   FreeType error code.  0~means success.
0445    *
0446    * @note:
0447    *   This function does **not create** the bitmap, it only renders an
0448    *   outline image within the one you pass to it!  Consequently, the
0449    *   various fields in `abitmap` should be set accordingly.
0450    *
0451    *   It will use the raster corresponding to the default glyph format.
0452    *
0453    *   The value of the `num_grays` field in `abitmap` is ignored.  If you
0454    *   select the gray-level rasterizer, and you want less than 256 gray
0455    *   levels, you have to use @FT_Outline_Render directly.
0456    */
0457   FT_EXPORT( FT_Error )
0458   FT_Outline_Get_Bitmap( FT_Library        library,
0459                          FT_Outline*       outline,
0460                          const FT_Bitmap  *abitmap );
0461
0462
0463   /**************************************************************************
0464    *
0465    * @function:
0466    *   FT_Outline_Render
0467    *
0468    * @description:
0469    *   Render an outline within a bitmap using the current scan-convert.
0470    *
0471    * @input:
0472    *   library ::
0473    *     A handle to a FreeType library object.
0474    *
0475    *   outline ::
0476    *     A pointer to the source outline descriptor.
0477    *
0478    * @inout:
0479    *   params ::
0480    *     A pointer to an @FT_Raster_Params structure used to describe the
0481    *     rendering operation.
0482    *
0483    * @return:
0484    *   FreeType error code.  0~means success.
0485    *
0486    * @note:
0487    *   This advanced function uses @FT_Raster_Params as an argument.
0488    *   The field `params.source` will be set to `outline` before the scan
0489    *   converter is called, which means that the value you give to it is
0490    *   actually ignored.  Either `params.target` must point to preallocated
0491    *   bitmap, or @FT_RASTER_FLAG_DIRECT must be set in `params.flags`
0492    *   allowing FreeType rasterizer to be used for direct composition,
0493    *   translucency, etc.  See @FT_Raster_Params for more details.
0494    */
0495   FT_EXPORT( FT_Error )
0496   FT_Outline_Render( FT_Library         library,
0497                      FT_Outline*        outline,
0498                      FT_Raster_Params*  params );
0499
0500
0501   /**************************************************************************
0502    *
0503    * @enum:
0504    *   FT_Orientation
0505    *
0506    * @description:
0507    *   A list of values used to describe an outline's contour orientation.
0508    *
0509    *   The TrueType and PostScript specifications use different conventions
0510    *   to determine whether outline contours should be filled or unfilled.
0511    *
0512    * @values:
0513    *   FT_ORIENTATION_TRUETYPE ::
0514    *     According to the TrueType specification, clockwise contours must be
0515    *     filled, and counter-clockwise ones must be unfilled.
0516    *
0517    *   FT_ORIENTATION_POSTSCRIPT ::
0518    *     According to the PostScript specification, counter-clockwise
0519    *     contours must be filled, and clockwise ones must be unfilled.
0520    *
0521    *   FT_ORIENTATION_FILL_RIGHT ::
0522    *     This is identical to @FT_ORIENTATION_TRUETYPE, but is used to
0523    *     remember that in TrueType, everything that is to the right of the
0524    *     drawing direction of a contour must be filled.
0525    *
0526    *   FT_ORIENTATION_FILL_LEFT ::
0527    *     This is identical to @FT_ORIENTATION_POSTSCRIPT, but is used to
0528    *     remember that in PostScript, everything that is to the left of the
0529    *     drawing direction of a contour must be filled.
0530    *
0531    *   FT_ORIENTATION_NONE ::
0532    *     The orientation cannot be determined.  That is, different parts of
0533    *     the glyph have different orientation.
0534    *
0535    */
0536   typedef enum  FT_Orientation_
0537   {
0538     FT_ORIENTATION_TRUETYPE   = 0,
0539     FT_ORIENTATION_POSTSCRIPT = 1,
0540     FT_ORIENTATION_FILL_RIGHT = FT_ORIENTATION_TRUETYPE,
0541     FT_ORIENTATION_FILL_LEFT  = FT_ORIENTATION_POSTSCRIPT,
0542     FT_ORIENTATION_NONE
0543
0544   } FT_Orientation;
0545
0546
0547   /**************************************************************************
0548    *
0549    * @function:
0550    *   FT_Outline_Get_Orientation
0551    *
0552    * @description:
0553    *   This function analyzes a glyph outline and tries to compute its fill
0554    *   orientation (see @FT_Orientation).  This is done by integrating the
0555    *   total area covered by the outline. The positive integral corresponds
0556    *   to the clockwise orientation and @FT_ORIENTATION_POSTSCRIPT is
0557    *   returned. The negative integral corresponds to the counter-clockwise
0558    *   orientation and @FT_ORIENTATION_TRUETYPE is returned.
0559    *
0560    *   Note that this will return @FT_ORIENTATION_TRUETYPE for empty
0561    *   outlines.
0562    *
0563    * @input:
0564    *   outline ::
0565    *     A handle to the source outline.
0566    *
0567    * @return:
0568    *   The orientation.
0569    *
0570    */
0571   FT_EXPORT( FT_Orientation )
0572   FT_Outline_Get_Orientation( FT_Outline*  outline );
0573
0574
0575   /* */
0576
0577
0578 FT_END_HEADER
0579
0580 #endif /* FTOUTLN_H_ */
0581
0582
0583 /* END */
0584
0585
0586 /* Local Variables: */
0587 /* coding: utf-8    */
0588 /* End:             */