| /**************************************************************************** |
| * |
| * ftoutln.h |
| * |
| * Support for the FT_Outline type used to store glyph shapes of |
| * most scalable font formats (specification). |
| * |
| * Copyright (C) 1996-2020 by |
| * David Turner, Robert Wilhelm, and Werner Lemberg. |
| * |
| * This file is part of the FreeType project, and may only be used, |
| * modified, and distributed under the terms of the FreeType project |
| * license, LICENSE.TXT. By continuing to use, modify, or distribute |
| * this file you indicate that you have read the license and |
| * understand and accept it fully. |
| * |
| */ |
| |
| |
| #ifndef FTOUTLN_H_ |
| #define FTOUTLN_H_ |
| |
| |
| #include <ft2build.h> |
| #include FT_FREETYPE_H |
| |
| #ifdef FREETYPE_H |
| #error "freetype.h of FreeType 1 has been loaded!" |
| #error "Please fix the directory search order for header files" |
| #error "so that freetype.h of FreeType 2 is found first." |
| #endif |
| |
| |
| FT_BEGIN_HEADER |
| |
| |
| /************************************************************************** |
| * |
| * @section: |
| * outline_processing |
| * |
| * @title: |
| * Outline Processing |
| * |
| * @abstract: |
| * Functions to create, transform, and render vectorial glyph images. |
| * |
| * @description: |
| * This section contains routines used to create and destroy scalable |
| * glyph images known as 'outlines'. These can also be measured, |
| * transformed, and converted into bitmaps and pixmaps. |
| * |
| * @order: |
| * FT_Outline |
| * FT_Outline_New |
| * FT_Outline_Done |
| * FT_Outline_Copy |
| * FT_Outline_Translate |
| * FT_Outline_Transform |
| * FT_Outline_Embolden |
| * FT_Outline_EmboldenXY |
| * FT_Outline_Reverse |
| * FT_Outline_Check |
| * |
| * FT_Outline_Get_CBox |
| * FT_Outline_Get_BBox |
| * |
| * FT_Outline_Get_Bitmap |
| * FT_Outline_Render |
| * FT_Outline_Decompose |
| * FT_Outline_Funcs |
| * FT_Outline_MoveToFunc |
| * FT_Outline_LineToFunc |
| * FT_Outline_ConicToFunc |
| * FT_Outline_CubicToFunc |
| * |
| * FT_Orientation |
| * FT_Outline_Get_Orientation |
| * |
| * FT_OUTLINE_XXX |
| * |
| */ |
| |
| |
| /************************************************************************** |
| * |
| * @function: |
| * FT_Outline_Decompose |
| * |
| * @description: |
| * Walk over an outline's structure to decompose it into individual |
| * segments and Bezier arcs. This function also emits 'move to' |
| * operations to indicate the start of new contours in the outline. |
| * |
| * @input: |
| * outline :: |
| * A pointer to the source target. |
| * |
| * func_interface :: |
| * A table of 'emitters', i.e., function pointers called during |
| * decomposition to indicate path operations. |
| * |
| * @inout: |
| * user :: |
| * A typeless pointer that is passed to each emitter during the |
| * decomposition. It can be used to store the state during the |
| * decomposition. |
| * |
| * @return: |
| * FreeType error code. 0~means success. |
| * |
| * @note: |
| * A contour that contains a single point only is represented by a 'move |
| * to' operation followed by 'line to' to the same point. In most cases, |
| * it is best to filter this out before using the outline for stroking |
| * purposes (otherwise it would result in a visible dot when round caps |
| * are used). |
| * |
| * Similarly, the function returns success for an empty outline also |
| * (doing nothing, this is, not calling any emitter); if necessary, you |
| * should filter this out, too. |
| */ |
| FT_EXPORT( FT_Error ) |
| FT_Outline_Decompose( FT_Outline* outline, |
| const FT_Outline_Funcs* func_interface, |
| void* user ); |
| |
| |
| /************************************************************************** |
| * |
| * @function: |
| * FT_Outline_New |
| * |
| * @description: |
| * Create a new outline of a given size. |
| * |
| * @input: |
| * library :: |
| * A handle to the library object from where the outline is allocated. |
| * Note however that the new outline will **not** necessarily be |
| * **freed**, when destroying the library, by @FT_Done_FreeType. |
| * |
| * numPoints :: |
| * The maximum number of points within the outline. Must be smaller |
| * than or equal to 0xFFFF (65535). |
| * |
| * numContours :: |
| * The maximum number of contours within the outline. This value must |
| * be in the range 0 to `numPoints`. |
| * |
| * @output: |
| * anoutline :: |
| * A handle to the new outline. |
| * |
| * @return: |
| * FreeType error code. 0~means success. |
| * |
| * @note: |
| * The reason why this function takes a `library` parameter is simply to |
| * use the library's memory allocator. |
| */ |
| FT_EXPORT( FT_Error ) |
| FT_Outline_New( FT_Library library, |
| FT_UInt numPoints, |
| FT_Int numContours, |
| FT_Outline *anoutline ); |
| |
| |
| /************************************************************************** |
| * |
| * @function: |
| * FT_Outline_Done |
| * |
| * @description: |
| * Destroy an outline created with @FT_Outline_New. |
| * |
| * @input: |
| * library :: |
| * A handle of the library object used to allocate the outline. |
| * |
| * outline :: |
| * A pointer to the outline object to be discarded. |
| * |
| * @return: |
| * FreeType error code. 0~means success. |
| * |
| * @note: |
| * If the outline's 'owner' field is not set, only the outline descriptor |
| * will be released. |
| */ |
| FT_EXPORT( FT_Error ) |
| FT_Outline_Done( FT_Library library, |
| FT_Outline* outline ); |
| |
| |
| /************************************************************************** |
| * |
| * @function: |
| * FT_Outline_Check |
| * |
| * @description: |
| * Check the contents of an outline descriptor. |
| * |
| * @input: |
| * outline :: |
| * A handle to a source outline. |
| * |
| * @return: |
| * FreeType error code. 0~means success. |
| * |
| * @note: |
| * An empty outline, or an outline with a single point only is also |
| * valid. |
| */ |
| FT_EXPORT( FT_Error ) |
| FT_Outline_Check( FT_Outline* outline ); |
| |
| |
| /************************************************************************** |
| * |
| * @function: |
| * FT_Outline_Get_CBox |
| * |
| * @description: |
| * Return an outline's 'control box'. The control box encloses all the |
| * outline's points, including Bezier control points. Though it |
| * coincides with the exact bounding box for most glyphs, it can be |
| * slightly larger in some situations (like when rotating an outline that |
| * contains Bezier outside arcs). |
| * |
| * Computing the control box is very fast, while getting the bounding box |
| * can take much more time as it needs to walk over all segments and arcs |
| * in the outline. To get the latter, you can use the 'ftbbox' |
| * component, which is dedicated to this single task. |
| * |
| * @input: |
| * outline :: |
| * A pointer to the source outline descriptor. |
| * |
| * @output: |
| * acbox :: |
| * The outline's control box. |
| * |
| * @note: |
| * See @FT_Glyph_Get_CBox for a discussion of tricky fonts. |
| */ |
| FT_EXPORT( void ) |
| FT_Outline_Get_CBox( const FT_Outline* outline, |
| FT_BBox *acbox ); |
| |
| |
| /************************************************************************** |
| * |
| * @function: |
| * FT_Outline_Translate |
| * |
| * @description: |
| * Apply a simple translation to the points of an outline. |
| * |
| * @inout: |
| * outline :: |
| * A pointer to the target outline descriptor. |
| * |
| * @input: |
| * xOffset :: |
| * The horizontal offset. |
| * |
| * yOffset :: |
| * The vertical offset. |
| */ |
| FT_EXPORT( void ) |
| FT_Outline_Translate( const FT_Outline* outline, |
| FT_Pos xOffset, |
| FT_Pos yOffset ); |
| |
| |
| /************************************************************************** |
| * |
| * @function: |
| * FT_Outline_Copy |
| * |
| * @description: |
| * Copy an outline into another one. Both objects must have the same |
| * sizes (number of points & number of contours) when this function is |
| * called. |
| * |
| * @input: |
| * source :: |
| * A handle to the source outline. |
| * |
| * @output: |
| * target :: |
| * A handle to the target outline. |
| * |
| * @return: |
| * FreeType error code. 0~means success. |
| */ |
| FT_EXPORT( FT_Error ) |
| FT_Outline_Copy( const FT_Outline* source, |
| FT_Outline *target ); |
| |
| |
| /************************************************************************** |
| * |
| * @function: |
| * FT_Outline_Transform |
| * |
| * @description: |
| * Apply a simple 2x2 matrix to all of an outline's points. Useful for |
| * applying rotations, slanting, flipping, etc. |
| * |
| * @inout: |
| * outline :: |
| * A pointer to the target outline descriptor. |
| * |
| * @input: |
| * matrix :: |
| * A pointer to the transformation matrix. |
| * |
| * @note: |
| * You can use @FT_Outline_Translate if you need to translate the |
| * outline's points. |
| */ |
| FT_EXPORT( void ) |
| FT_Outline_Transform( const FT_Outline* outline, |
| const FT_Matrix* matrix ); |
| |
| |
| /************************************************************************** |
| * |
| * @function: |
| * FT_Outline_Embolden |
| * |
| * @description: |
| * Embolden an outline. The new outline will be at most 4~times |
| * `strength` pixels wider and higher. You may think of the left and |
| * bottom borders as unchanged. |
| * |
| * Negative `strength` values to reduce the outline thickness are |
| * possible also. |
| * |
| * @inout: |
| * outline :: |
| * A handle to the target outline. |
| * |
| * @input: |
| * strength :: |
| * How strong the glyph is emboldened. Expressed in 26.6 pixel format. |
| * |
| * @return: |
| * FreeType error code. 0~means success. |
| * |
| * @note: |
| * The used algorithm to increase or decrease the thickness of the glyph |
| * doesn't change the number of points; this means that certain |
| * situations like acute angles or intersections are sometimes handled |
| * incorrectly. |
| * |
| * If you need 'better' metrics values you should call |
| * @FT_Outline_Get_CBox or @FT_Outline_Get_BBox. |
| * |
| * To get meaningful results, font scaling values must be set with |
| * functions like @FT_Set_Char_Size before calling FT_Render_Glyph. |
| * |
| * @example: |
| * ``` |
| * FT_Load_Glyph( face, index, FT_LOAD_DEFAULT ); |
| * |
| * if ( face->glyph->format == FT_GLYPH_FORMAT_OUTLINE ) |
| * FT_Outline_Embolden( &face->glyph->outline, strength ); |
| * ``` |
| * |
| */ |
| FT_EXPORT( FT_Error ) |
| FT_Outline_Embolden( FT_Outline* outline, |
| FT_Pos strength ); |
| |
| |
| /************************************************************************** |
| * |
| * @function: |
| * FT_Outline_EmboldenXY |
| * |
| * @description: |
| * Embolden an outline. The new outline will be `xstrength` pixels wider |
| * and `ystrength` pixels higher. Otherwise, it is similar to |
| * @FT_Outline_Embolden, which uses the same strength in both directions. |
| * |
| * @since: |
| * 2.4.10 |
| */ |
| FT_EXPORT( FT_Error ) |
| FT_Outline_EmboldenXY( FT_Outline* outline, |
| FT_Pos xstrength, |
| FT_Pos ystrength ); |
| |
| |
| /************************************************************************** |
| * |
| * @function: |
| * FT_Outline_Reverse |
| * |
| * @description: |
| * Reverse the drawing direction of an outline. This is used to ensure |
| * consistent fill conventions for mirrored glyphs. |
| * |
| * @inout: |
| * outline :: |
| * A pointer to the target outline descriptor. |
| * |
| * @note: |
| * This function toggles the bit flag @FT_OUTLINE_REVERSE_FILL in the |
| * outline's `flags` field. |
| * |
| * It shouldn't be used by a normal client application, unless it knows |
| * what it is doing. |
| */ |
| FT_EXPORT( void ) |
| FT_Outline_Reverse( FT_Outline* outline ); |
| |
| |
| /************************************************************************** |
| * |
| * @function: |
| * FT_Outline_Get_Bitmap |
| * |
| * @description: |
| * Render an outline within a bitmap. The outline's image is simply |
| * OR-ed to the target bitmap. |
| * |
| * @input: |
| * library :: |
| * A handle to a FreeType library object. |
| * |
| * outline :: |
| * A pointer to the source outline descriptor. |
| * |
| * @inout: |
| * abitmap :: |
| * A pointer to the target bitmap descriptor. |
| * |
| * @return: |
| * FreeType error code. 0~means success. |
| * |
| * @note: |
| * This function does **not create** the bitmap, it only renders an |
| * outline image within the one you pass to it! Consequently, the |
| * various fields in `abitmap` should be set accordingly. |
| * |
| * It will use the raster corresponding to the default glyph format. |
| * |
| * The value of the `num_grays` field in `abitmap` is ignored. If you |
| * select the gray-level rasterizer, and you want less than 256 gray |
| * levels, you have to use @FT_Outline_Render directly. |
| */ |
| FT_EXPORT( FT_Error ) |
| FT_Outline_Get_Bitmap( FT_Library library, |
| FT_Outline* outline, |
| const FT_Bitmap *abitmap ); |
| |
| |
| /************************************************************************** |
| * |
| * @function: |
| * FT_Outline_Render |
| * |
| * @description: |
| * Render an outline within a bitmap using the current scan-convert. |
| * |
| * @input: |
| * library :: |
| * A handle to a FreeType library object. |
| * |
| * outline :: |
| * A pointer to the source outline descriptor. |
| * |
| * @inout: |
| * params :: |
| * A pointer to an @FT_Raster_Params structure used to describe the |
| * rendering operation. |
| * |
| * @return: |
| * FreeType error code. 0~means success. |
| * |
| * @note: |
| * This advanced function uses @FT_Raster_Params as an argument, |
| * allowing FreeType rasterizer to be used for direct composition, |
| * translucency, etc. You should know how to set up @FT_Raster_Params |
| * for this function to work. |
| * |
| * The field `params.source` will be set to `outline` before the scan |
| * converter is called, which means that the value you give to it is |
| * actually ignored. |
| * |
| * The gray-level rasterizer always uses 256 gray levels. If you want |
| * less gray levels, you have to provide your own span callback. See the |
| * @FT_RASTER_FLAG_DIRECT value of the `flags` field in the |
| * @FT_Raster_Params structure for more details. |
| */ |
| FT_EXPORT( FT_Error ) |
| FT_Outline_Render( FT_Library library, |
| FT_Outline* outline, |
| FT_Raster_Params* params ); |
| |
| |
| /************************************************************************** |
| * |
| * @enum: |
| * FT_Orientation |
| * |
| * @description: |
| * A list of values used to describe an outline's contour orientation. |
| * |
| * The TrueType and PostScript specifications use different conventions |
| * to determine whether outline contours should be filled or unfilled. |
| * |
| * @values: |
| * FT_ORIENTATION_TRUETYPE :: |
| * According to the TrueType specification, clockwise contours must be |
| * filled, and counter-clockwise ones must be unfilled. |
| * |
| * FT_ORIENTATION_POSTSCRIPT :: |
| * According to the PostScript specification, counter-clockwise |
| * contours must be filled, and clockwise ones must be unfilled. |
| * |
| * FT_ORIENTATION_FILL_RIGHT :: |
| * This is identical to @FT_ORIENTATION_TRUETYPE, but is used to |
| * remember that in TrueType, everything that is to the right of the |
| * drawing direction of a contour must be filled. |
| * |
| * FT_ORIENTATION_FILL_LEFT :: |
| * This is identical to @FT_ORIENTATION_POSTSCRIPT, but is used to |
| * remember that in PostScript, everything that is to the left of the |
| * drawing direction of a contour must be filled. |
| * |
| * FT_ORIENTATION_NONE :: |
| * The orientation cannot be determined. That is, different parts of |
| * the glyph have different orientation. |
| * |
| */ |
| typedef enum FT_Orientation_ |
| { |
| FT_ORIENTATION_TRUETYPE = 0, |
| FT_ORIENTATION_POSTSCRIPT = 1, |
| FT_ORIENTATION_FILL_RIGHT = FT_ORIENTATION_TRUETYPE, |
| FT_ORIENTATION_FILL_LEFT = FT_ORIENTATION_POSTSCRIPT, |
| FT_ORIENTATION_NONE |
| |
| } FT_Orientation; |
| |
| |
| /************************************************************************** |
| * |
| * @function: |
| * FT_Outline_Get_Orientation |
| * |
| * @description: |
| * This function analyzes a glyph outline and tries to compute its fill |
| * orientation (see @FT_Orientation). This is done by integrating the |
| * total area covered by the outline. The positive integral corresponds |
| * to the clockwise orientation and @FT_ORIENTATION_POSTSCRIPT is |
| * returned. The negative integral corresponds to the counter-clockwise |
| * orientation and @FT_ORIENTATION_TRUETYPE is returned. |
| * |
| * Note that this will return @FT_ORIENTATION_TRUETYPE for empty |
| * outlines. |
| * |
| * @input: |
| * outline :: |
| * A handle to the source outline. |
| * |
| * @return: |
| * The orientation. |
| * |
| */ |
| FT_EXPORT( FT_Orientation ) |
| FT_Outline_Get_Orientation( FT_Outline* outline ); |
| |
| |
| /* */ |
| |
| |
| FT_END_HEADER |
| |
| #endif /* FTOUTLN_H_ */ |
| |
| |
| /* END */ |
| |
| |
| /* Local Variables: */ |
| /* coding: utf-8 */ |
| /* End: */ |
