587 lines
17 KiB
C
587 lines
17 KiB
C
/****************************************************************************
|
|
*
|
|
* 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 <freetype/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.
|
|
* 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. Either `params.target` must point to preallocated
|
|
* bitmap, or @FT_RASTER_FLAG_DIRECT must be set in `params.flags`
|
|
* allowing FreeType rasterizer to be used for direct composition,
|
|
* translucency, etc. See @FT_Raster_Params 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: */
|