summaryrefslogtreecommitdiffstats
path: root/modules/freetype2/include/freetype/ftoutln.h
diff options
context:
space:
mode:
Diffstat (limited to 'modules/freetype2/include/freetype/ftoutln.h')
-rw-r--r--modules/freetype2/include/freetype/ftoutln.h588
1 files changed, 588 insertions, 0 deletions
diff --git a/modules/freetype2/include/freetype/ftoutln.h b/modules/freetype2/include/freetype/ftoutln.h
new file mode 100644
index 0000000000..54434b25f6
--- /dev/null
+++ b/modules/freetype2/include/freetype/ftoutln.h
@@ -0,0 +1,588 @@
+/****************************************************************************
+ *
+ * ftoutln.h
+ *
+ * Support for the FT_Outline type used to store glyph shapes of
+ * most scalable font formats (specification).
+ *
+ * Copyright (C) 1996-2023 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:
+ * Degenerate contours, segments, and Bezier arcs may be reported. In
+ * most cases, it is best to filter these out before using the outline
+ * for stroking or other path modification purposes (which may cause
+ * degenerate segments to become non-degenrate and visible, like when
+ * stroke caps are used or the path is otherwise outset). Some glyph
+ * outlines may contain deliberate degenerate single points for mark
+ * attachement.
+ *
+ * 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: */