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