diff --git a/include/freetype/freetype.h b/include/freetype/freetype.h index 6b86a9ca4..b992b0073 100644 --- a/include/freetype/freetype.h +++ b/include/freetype/freetype.h @@ -1977,7 +1977,7 @@ /* An enumeration used to specify which kerning values to return in */ /* FT_Get_Kerning(). */ /* */ - /* */ + /* */ /* ft_kerning_default :: Return scaled and grid-fitted kerning */ /* distances (value is 0). */ /* */ diff --git a/include/freetype/ftglyph.h b/include/freetype/ftglyph.h index 51cb1cc19..4772d8c04 100644 --- a/include/freetype/ftglyph.h +++ b/include/freetype/ftglyph.h @@ -7,22 +7,28 @@ /* Copyright 1996-2000 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 */ +/* 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. */ /* */ -/* This file contains the definition of several convenience functions */ -/* that can be used by client applications to easily retrieve glyph */ -/* bitmaps and outlines from a given face. */ -/* */ -/* These functions should be optional if you're writing a font server */ -/* or text layout engine on top of FreeType. However, they are pretty */ -/* handy for many other simple uses of the library.. */ -/* */ /***************************************************************************/ + + /*************************************************************************/ + /* */ + /* This file contains the definition of several convenience functions */ + /* that can be used by client applications to easily retrieve glyph */ + /* bitmaps and outlines from a given face. */ + /* */ + /* These functions should be optional if you are writing a font server */ + /* or text layout engine on top of FreeType. However, they are pretty */ + /* handy for many other simple uses of the library. */ + /* */ + /*************************************************************************/ + + #ifndef FTGLYPH_H #define FTGLYPH_H @@ -35,24 +41,26 @@ /* forward declaration to a private type */ typedef struct FT_Glyph_Class_ FT_Glyph_Class; - /*********************************************************************** - * - * - * FT_GlyphRec - * - * - * The root glyph structure contains a given glyph image plus its - * advance width in 16.16 fixed float format.. - * - * - * library :: a handle to the FreeType library object. - * clazz :: a pointer to the glyph's class. Private. - * format :: the format of the glyph's image - * advance :: a 16.16 vector that gives the glyph's advance width - * - ***********************************************************************/ - typedef struct FT_GlyphRec_ + /*************************************************************************/ + /* */ + /* */ + /* FT_GlyphRec */ + /* */ + /* */ + /* The root glyph structure contains a given glyph image plus its */ + /* advance width in 16.16 fixed float format. */ + /* */ + /* */ + /* library :: A handle to the FreeType library object. */ + /* */ + /* clazz :: A pointer to the glyph's class. Private. */ + /* */ + /* format :: The format of the glyph's image. */ + /* */ + /* advance :: A 16.16 vector that gives the glyph's advance width. */ + /* */ + typedef struct FT_GlyphRec_ { FT_Library library; const FT_Glyph_Class* clazz; @@ -62,36 +70,37 @@ } FT_GlyphRec, *FT_Glyph; - /*********************************************************************** - * - * - * FT_BitmapGlyphRec - * - * - * A structure used for bitmap glyph images.. This really is - * a "sub-class" of "FT_GlyphRec". - * - * - * root :: the root FT_Glyph fields - * left :: left-side bearing, i.e. the horizontal distance from - * the current pen position to the left border of the glyph - * bitmap. - * top :: top-side bearing, i.e. the vertical distance from the - * current pen position to the top border of the glyph bitmap - * this distance is positive for upwards-y !! - * bitmap :: a descriptor for the bitmap. - * - * - * You can typecast a FT_Glyph to FT_BitmapGlyph when you have - * glyph->format == ft_glyph_format_bitmap. This lets you access - * the bitmap's content easily.. - * - * the corresponding pixel buffer is always owned by the BitmapGlyph - * and is thus created and destroyed with it.. - * - ***********************************************************************/ - - typedef struct FT_BitmapGlyphRec_ + /*************************************************************************/ + /* */ + /* */ + /* FT_BitmapGlyphRec */ + /* */ + /* */ + /* A structure used for bitmap glyph images. This really is a */ + /* `sub-class' of `FT_GlyphRec'. */ + /* */ + /* */ + /* root :: The root FT_Glyph fields. */ + /* */ + /* left :: The left-side bearing, i.e., the horizontal distance */ + /* from the current pen position to the left border of the */ + /* glyph bitmap. */ + /* */ + /* top :: The top-side bearing, i.e., the vertical distance from */ + /* the current pen position to the top border of the glyph */ + /* bitmap. This distance is positive for upwards-y! */ + /* */ + /* bitmap :: A descriptor for the bitmap. */ + /* */ + /* */ + /* You can typecast FT_Glyph to FT_BitmapGlyph if you have */ + /* glyph->format == ft_glyph_format_bitmap. This lets you access */ + /* the bitmap's contents easily. */ + /* */ + /* The corresponding pixel buffer is always owned by the BitmapGlyph */ + /* and is thus created and destroyed with it. */ + /* */ + typedef struct FT_BitmapGlyphRec_ { FT_GlyphRec root; FT_Int left; @@ -101,34 +110,33 @@ } FT_BitmapGlyphRec, *FT_BitmapGlyph; - /*********************************************************************** - * - * - * FT_OutlineGlyphRec - * - * - * A structure used for outline (vectorial) glyph images.. - * This really is a "sub-class" of FT_GlyphRec. - * - * - * root :: the root FT_Glyph fields. - * outline :: a descriptor for the outline - * - * - * You can typecast a FT_Glyph to FT_OutlineGlyph when you have - * glyph->format == ft_glyph_format_outline. This lets you access - * the outline's content easily.. - * - * As the outline is extracted from a glyph slot, its coordinates - * are expressed normally in 26.6 pixels, unless the flag - * FT_LOAD_NO_SCALE was used in FT_Load_Glyph / FT_Load_Char.. - * - * the outline's tables are always owned by the object and are - * destroyed with it.. - * - ***********************************************************************/ - - typedef struct FT_OutlineGlyphRec_ + /*************************************************************************/ + /* */ + /* */ + /* FT_OutlineGlyphRec */ + /* */ + /* */ + /* A structure used for outline (vectorial) glyph images. This */ + /* really is a `sub-class' of `FT_GlyphRec'. */ + /* */ + /* */ + /* root :: The root FT_Glyph fields. */ + /* */ + /* outline :: A descriptor for the outline. */ + /* */ + /* */ + /* You can typecast FT_Glyph to FT_OutlineGlyph if you have */ + /* glyph->format == ft_glyph_format_outline. This lets you access */ + /* the outline's content easily. */ + /* */ + /* As the outline is extracted from a glyph slot, its coordinates are */ + /* expressed normally in 26.6 pixels, unless the flag */ + /* FT_LOAD_NO_SCALE was used in FT_Load_Glyph() or FT_Load_Char(). */ + /* */ + /* The outline's tables are always owned by the object and are */ + /* destroyed with it. */ + /* */ + typedef struct FT_OutlineGlyphRec_ { FT_GlyphRec root; FT_Outline outline; @@ -136,128 +144,78 @@ } FT_OutlineGlyphRec, *FT_OutlineGlyph; - - /*********************************************************************** - * - * - * FT_Get_Glyph - * - * - * A function used to extract one glyph image from a slot.. - * - * - * slot :: handle to source glyph slot. - * - * - * aglyph :: handle to the glyph object. - * - * - * Error code. 0 means success. - * - * - * - * - ***********************************************************************/ - - FT_EXPORT_DEF(FT_Error) FT_Get_Glyph( FT_GlyphSlot slot, - FT_Glyph *aglyph ); - - /*********************************************************************** - * - * - * FT_Glyph_Copy - * - * - * A function used to copy one glyph image. - * - * - * source :: handle to source glyph object - * - * - * target :: handle to target glyph object. 0 in case of error - * - * - * Error code. 0 means success. - * - ***********************************************************************/ - - FT_EXPORT_DEF(FT_Error) FT_Glyph_Copy( FT_Glyph source, - FT_Glyph *target ); + /*************************************************************************/ + /* */ + /* */ + /* FT_Get_Glyph */ + /* */ + /* */ + /* A function used to extract a glyph image from a slot. */ + /* */ + /* */ + /* slot :: A handle to the source glyph slot. */ + /* */ + /* */ + /* aglyph :: A handle to the glyph object. */ + /* */ + /* */ + /* FreeType error code. 0 means success. */ + /* */ + FT_EXPORT_DEF( FT_Error ) FT_Get_Glyph( FT_GlyphSlot slot, + FT_Glyph* aglyph ); - /*********************************************************************** - * - * - * FT_Glyph_Transform - * - * - * Transforms a glyph image, when it's format is scalable - * - * - * glyph :: handle to target glyph object - * - * matrix :: pointer to 2x2 matrix to apply - * - * delta :: pointer to a 2d vector to apply. coordinates are - * expressed in 1/64th of a pixel.. - * - * - * error code (is not 0, the glyph format is not scalable). - * - * - * the 2x2 transform matrix is also applied to the glyph's - * advance vector - * - ***********************************************************************/ + /*************************************************************************/ + /* */ + /* */ + /* FT_Glyph_Copy */ + /* */ + /* */ + /* A function used to copy a glyph image. */ + /* */ + /* */ + /* source :: A handle to the source glyph object. */ + /* */ + /* */ + /* target :: A handle to the target glyph object. 0 in case of */ + /* error. */ + /* */ + /* */ + /* FreeType error code. 0 means success. */ + /* */ + FT_EXPORT_DEF( FT_Error ) FT_Glyph_Copy( FT_Glyph source, + FT_Glyph* target ); + + + /*************************************************************************/ + /* */ + /* */ + /* FT_Glyph_Transform */ + /* */ + /* */ + /* Transforms a glyph image if its format is scalable. */ + /* */ + /* */ + /* glyph :: A handle to the target glyph object. */ + /* */ + /* matrix :: A pointer to a 2x2 matrix to apply. */ + /* */ + /* delta :: A pointer to a 2d vector to apply. Coordinates are */ + /* expressed in 1/64th of a pixel. */ + /* */ + /* */ + /* FreeType error code (the glyph format is not scalable if it is */ + /* not zero). */ + /* */ + /* */ + /* The 2x2 transformation matrix is also applied to the glyph's */ + /* advance vector. */ + /* */ + FT_EXPORT_DEF( FT_Error ) FT_Glyph_Transform( FT_Glyph glyph, + FT_Matrix* matrix, + FT_Vector* delta ); - FT_EXPORT_DEF(FT_Error) FT_Glyph_Transform( FT_Glyph glyph, - FT_Matrix* matrix, - FT_Vector* delta ); - /*********************************************************************** - * - * - * FT_Glyph_Get_CBox - * - * - * Returns the glyph image's bounding box. - * - * - * glyph :: handle to source glyph object - * mode :: a set of bit flags that indicate how to interpret - * the meaning of the box's coordinates - * - * - * box :: the glyph bounding box. Coordinates are expressed in - * 1/64th of pixels, it is grid-fitted.. - * - * - * Coordinates are relative to the glyph origin, using the Y-upwards - * convention.. - * - * if 'ft_glyph_bbox_subpixels' is set in "mode", the bbox coordinates - * are returned in 26.6 pixels (i.e. 1/64th of pixels). - * - * otherwise, coordinates are in integer pixels. - * - * note that the maximum coordinates are exclusive, which means that - * once can compute the width and height of the glyph image (be it - * in integer or 26.6 pixels) as: - * - * width = bbox.xMax - bbox.xMin; - * height = bbox.yMax - bbox.yMin; - * - * Note also that for 26.6 coordinates, if the 'ft_glyph_bbox_gridfit' - * flag is set in "mode", the coordinates will also be grid-fitted, - * which corresponds to: - * - * bbox.xMin = FLOOR(bbox.xMin); - * bbox.yMin = FLOOR(bbox.yMin); - * bbox.xMax = CEILING(bbox.xMax); - * bbox.yMax = CEILING(bbox.yMax); - * - ***********************************************************************/ - enum { ft_glyph_bbox_pixels = 0, @@ -265,98 +223,150 @@ ft_glyph_bbox_gridfit = 2 }; - FT_EXPORT_DEF(void) FT_Glyph_Get_CBox( FT_Glyph glyph, - FT_UInt bbox_mode, - FT_BBox *cbox ); + + /*************************************************************************/ + /* */ + /* */ + /* FT_Glyph_Get_CBox */ + /* */ + /* */ + /* Returns the glyph image's bounding box. */ + /* */ + /* */ + /* glyph :: A handle to the source glyph object. */ + /* */ + /* mode :: A set of bit flags that indicate how to interpret the */ + /* returned bounding box values. */ + /* */ + /* */ + /* box :: The glyph bounding box. Coordinates are expressed in */ + /* 1/64th of pixels if it is grid-fitted. */ + /* */ + /* */ + /* Coordinates are relative to the glyph origin, using the Y-upwards */ + /* convention. */ + /* */ + /* If `ft_glyph_bbox_subpixels' is set in `mode', the bbox */ + /* coordinates are returned in 26.6 pixels (i.e. 1/64th of pixels). */ + /* Otherwise, coordinates are expressed in integer pixels. */ + /* */ + /* Note that the maximum coordinates are exclusive, which means that */ + /* one can compute the width and height of the glyph image (be it in */ + /* integer or 26.6 pixels) as: */ + /* */ + /* width = bbox.xMax - bbox.xMin; */ + /* height = bbox.yMax - bbox.yMin; */ + /* */ + /* Note also that for 26.6 coordinates, if the */ + /* `ft_glyph_bbox_gridfit' flag is set in `mode;, the coordinates */ + /* will also be grid-fitted, which corresponds to: */ + /* */ + /* bbox.xMin = FLOOR(bbox.xMin); */ + /* bbox.yMin = FLOOR(bbox.yMin); */ + /* bbox.xMax = CEILING(bbox.xMax); */ + /* bbox.yMax = CEILING(bbox.yMax); */ + /* */ + /* The default value (0) for `bbox_mode' is `ft_glyph_bbox_pixels'. */ + /* */ + FT_EXPORT_DEF( void ) FT_Glyph_Get_CBox( FT_Glyph glyph, + FT_UInt bbox_mode, + FT_BBox* cbox ); - /*********************************************************************** - * - * - * FT_Glyph_To_Bitmap - * - * - * converts a given glyph object to a bitmap glyph object - * - * - * glyph :: pointer to a handle to the target glyph - * - * - * render_mode :: a set of bit flags that describe how - * - * origin :: pointer to a vector used to translate the glyph image - * before rendering. Can be 0 (for no translation). The - * origin is expressed in 26.6 pixels.. - * - * destroy :: a boolean that indicates that the original glyph image - * should be destroyed by this function. The glyph is - * never destroyed in case of error.. - * - * - * Error code. 0 means success - * - * - * the glyph image is translated with the "origin" vector before - * rendering.. In case of error, it it translated back to its original - * position and the glyph is untouched.. - * - * The first parameter is a pointer to a FT_Glyph handle, that - * will be replaced by this function. Typically, you would use: - * - * { - * FT_Glyph glyph; - * FT_BitmapGlyph glyph_bitmap; - * - * // load glyph - * error = FT_Load_Char( face, glyph_index, FT_LOAD_DEFAUT ); - * - * // extract glyph image - * error = FT_Get_Glyph( face->glyph, &glyph ); - * - * // convert to a bitmap (default render mode + destroy old) - * if (glyph->format != ft_glyph_format_bitmap) - * { - * error = FT_Glyph_To_Bitmap( &glyph, ft_render_mode_default, 0, 1 ); - * if (error) // glyph unchanged.. - * } - * - * // access bitmap content by typecasting - * glyph_bitmap = (FT_BitmapGlyph)glyph; - * - * // do funny stuff with it, like blitting/drawing - * .... - * - * // discard glyph image (bitmap or not) - * FT_Done_Glyph( glyph ); - * - * - * This function will always fail if the glyph's format isn't scalable - * - ***********************************************************************/ - - FT_EXPORT_DEF(FT_Error) FT_Glyph_To_Bitmap( FT_Glyph *the_glyph, - FT_ULong render_mode, - FT_Vector* origin, - FT_Bool destroy ); + /*************************************************************************/ + /* */ + /* */ + /* FT_Glyph_To_Bitmap */ + /* */ + /* */ + /* Converts a given glyph object to a bitmap glyph object. */ + /* */ + /* */ + /* glyph :: A pointer to a handle to the target glyph. */ + /* */ + /* */ + /* render_mode :: A set of bit flags that describe how the data is */ + /* */ + /* */ + /* origin :: A pointer to a vector used to translate the glyph */ + /* image before rendering. Can be 0 (if no */ + /* translation). The origin is expressed in */ + /* 26.6 pixels. */ + /* */ + /* destroy :: A boolean that indicates that the original glyph */ + /* image should be destroyed by this function. It is */ + /* never destroyed in case of error. */ + /* */ + /* */ + /* FreeType error code. 0 means success. */ + /* */ + /* */ + /* The glyph image is translated with the `origin' vector before */ + /* rendering. In case of error, it it translated back to its */ + /* original position and the glyph is left untouched. */ + /* */ + /* The first parameter is a pointer to a FT_Glyph handle, that will */ + /* be replaced by this function. Typically, you would use (omitting */ + /* error handling): */ + /* */ + /* */ + /* { */ + /* FT_Glyph glyph; */ + /* FT_BitmapGlyph glyph_bitmap; */ + /* */ + /* */ + /* // load glyph */ + /* error = FT_Load_Char( face, glyph_index, FT_LOAD_DEFAUT ); */ + /* */ + /* // extract glyph image */ + /* error = FT_Get_Glyph( face->glyph, &glyph ); */ + /* */ + /* // convert to a bitmap (default render mode + destroy old) */ + /* if ( glyph->format != ft_glyph_format_bitmap ) */ + /* { */ + /* error = FT_Glyph_To_Bitmap( &glyph, ft_render_mode_default, */ + /* 0, 1 ); */ + /* if ( error ) // glyph unchanged */ + /* ... */ + /* } */ + /* */ + /* // access bitmap content by typecasting */ + /* glyph_bitmap = (FT_BitmapGlyph)glyph; */ + /* */ + /* // do funny stuff with it, like blitting/drawing */ + /* ... */ + /* */ + /* // discard glyph image (bitmap or not) */ + /* FT_Done_Glyph( glyph ); */ + /* } */ + /* */ + /* */ + /* This function will always fail if the glyph's format isn't */ + /* scalable. */ + /* */ + FT_EXPORT_DEF( FT_Error ) FT_Glyph_To_Bitmap( FT_Glyph* the_glyph, + FT_ULong render_mode, + FT_Vector* origin, + FT_Bool destroy ); - /*********************************************************************** - * - * - * FT_Done_Glyph - * - * - * Destroys a given glyph.. - * - * - * glyph :: handle to target glyph object - * - ***********************************************************************/ - FT_EXPORT_DEF(void) FT_Done_Glyph( FT_Glyph glyph ); + /*************************************************************************/ + /* */ + /* */ + /* FT_Done_Glyph */ + /* */ + /* */ + /* Destroys a given glyph. */ + /* */ + /* */ + /* glyph :: A handle to the target glyph object. */ + /* */ + FT_EXPORT_DEF( void ) FT_Done_Glyph( FT_Glyph glyph ); /* other helpful functions */ + /*************************************************************************/ /* */ /* */ @@ -374,8 +384,11 @@ /* */ /* Yes. */ /* */ - FT_EXPORT_DEF(void) FT_Matrix_Multiply( FT_Matrix* a, - FT_Matrix* b ); + /* */ + /* The result is undefined if either `a' or `b' is zero. */ + /* */ + FT_EXPORT_DEF( void ) FT_Matrix_Multiply( FT_Matrix* a, + FT_Matrix* b ); /*************************************************************************/ @@ -396,7 +409,7 @@ /* */ /* Yes. */ /* */ - FT_EXPORT_DEF(FT_Error) FT_Matrix_Invert( FT_Matrix* matrix ); + FT_EXPORT_DEF( FT_Error ) FT_Matrix_Invert( FT_Matrix* matrix ); #ifdef __cplusplus @@ -404,3 +417,6 @@ #endif #endif /* FTGLYPH_H */ + + +/* END */ diff --git a/include/freetype/internal/psnames.h b/include/freetype/internal/psnames.h index 282a2b0a9..bb3e6582e 100644 --- a/include/freetype/internal/psnames.h +++ b/include/freetype/internal/psnames.h @@ -163,7 +163,7 @@ * this structure holds pointers to the functions used to load and * free the basic tables that are required in a `sfnt' font file. * - * + * * unicode_value :: a function used to convert a glyph name into * a Unicode character code * diff --git a/src/base/ftglyph.c b/src/base/ftglyph.c index 3bbc73aa9..4052e6e4f 100644 --- a/src/base/ftglyph.c +++ b/src/base/ftglyph.c @@ -633,6 +633,8 @@ /* bbox.xMax = CEILING(bbox.xMax); */ /* bbox.yMax = CEILING(bbox.yMax); */ /* */ + /* The default value (0) for `bbox_mode' is `ft_glyph_bbox_pixels'. */ + /* */ FT_EXPORT_FUNC( void ) FT_Glyph_Get_CBox( FT_Glyph glyph, FT_UInt bbox_mode, FT_BBox* cbox )