From 670caab8554dd0458ac2e59687223544e09ce15d Mon Sep 17 00:00:00 2001 From: Werner Lemberg Date: Mon, 10 Jul 2000 14:24:26 +0000 Subject: [PATCH] Formatting. --- include/freetype/freetype.h | 12 +- include/freetype/ftglyph.h | 4 +- include/freetype/ftimage.h | 1059 ++++++++++++++++++----------------- 3 files changed, 553 insertions(+), 522 deletions(-) diff --git a/include/freetype/freetype.h b/include/freetype/freetype.h index b992b0073..e5f4bd29d 100644 --- a/include/freetype/freetype.h +++ b/include/freetype/freetype.h @@ -968,7 +968,7 @@ /* */ typedef struct FT_GlyphLoader_ FT_GlyphLoader; - + /*************************************************************************/ /* */ /* FreeType Glyph Slot base class */ @@ -1113,11 +1113,11 @@ FT_Vector advance; FT_Glyph_Format format; - + FT_Bitmap bitmap; FT_Int bitmap_left; FT_Int bitmap_top; - + FT_Outline outline; FT_UInt num_subglyphs; @@ -1939,10 +1939,10 @@ { ft_render_mode_normal = 0, ft_render_mode_mono = 1 - + } FT_Render_Mode; - + /*************************************************************************/ /* */ /* */ @@ -1992,7 +1992,7 @@ ft_kerning_default = 0, ft_kerning_unfitted, ft_kerning_unscaled - + } FT_Kerning_Mode; diff --git a/include/freetype/ftglyph.h b/include/freetype/ftglyph.h index 4772d8c04..8b374a89d 100644 --- a/include/freetype/ftglyph.h +++ b/include/freetype/ftglyph.h @@ -215,7 +215,7 @@ FT_Matrix* matrix, FT_Vector* delta ); - + enum { ft_glyph_bbox_pixels = 0, @@ -348,7 +348,7 @@ FT_ULong render_mode, FT_Vector* origin, FT_Bool destroy ); - + /*************************************************************************/ /* */ diff --git a/include/freetype/ftimage.h b/include/freetype/ftimage.h index a1b15c950..e61443c3b 100644 --- a/include/freetype/ftimage.h +++ b/include/freetype/ftimage.h @@ -2,23 +2,27 @@ /* */ /* ftimage.h */ /* */ -/* This file defines the glyph image formats recognized by FreeType, as */ -/* well as the default raster interface. */ -/* */ -/* Note: a "raster" is simply a scan-line converter, used to render */ -/* FT_Outlines into FT_Bitmaps */ +/* FreeType glyph image formats and default raster interface. */ /* */ /* 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. */ /* */ /***************************************************************************/ + /*************************************************************************/ + /* */ + /* Note: A `raster' is simply a scan-line converter, used to render */ + /* FT_Outlines into FT_Bitmaps. */ + /* */ + /*************************************************************************/ + + #ifndef FTIMAGE_H #define FTIMAGE_H @@ -48,7 +52,7 @@ /* FT_Vector */ /* */ /* */ - /* A simple structure used to store a 2d vector; coordinates are of */ + /* A simple structure used to store a 2D vector; coordinates are of */ /* the FT_Pos type. */ /* */ /* */ @@ -63,53 +67,51 @@ } FT_Vector; - /************************************************************************* - * - * - * FT_Pixel_Mode - * - * - * An enumeration type used to describe the format of pixels - * in a given bitmap. Note that additional formats may be added - * in the future. - * - * - * ft_pixel_mode_mono :: a monochrome bitmap (1 bit/pixel) - * - * ft_pixel_mode_grays :: an 8-bit gray-levels bitmap. Note that - * the total number of gray levels is given - * in the `num_grays' field of the FT_Bitmap - * structure. - * - * ft_pixel_mode_pal2 :: a 2-bit paletted bitmap. - * currently unused by FreeType. - * - * ft_pixel_mode_pal4 :: a 4-bit paletted bitmap. - * currently unused by FreeType. - * - * ft_pixel_mode_pal8 :: an 8-bit paletted bitmap. - * currently unused by FreeType. - * - * ft_pixel_mode_rgb15 :: a 15-bit RGB bitmap. Uses 5:5:5 encoding - * currently unused by FreeType. - * - * ft_pixel_mode_rgb16 :: a 16-bit RGB bitmap. Uses 5:6:5 encoding - * currently unused by FreeType. - * - * ft_pixel_mode_rgb24 :: a 24-bit RGB bitmap. - * currently unused by FreeType. - * - * ft_pixel_mode_rgb32 :: a 32-bit RGB bitmap. - * currently unused by FreeType. - * - * - * Some anti-aliased bitmaps might be embedded in TrueType fonts - * using formats pal2 or pal4, though no fonts presenting those - * have been found to date.. - * - *************************************************************************/ - - typedef enum FT_Pixel_Mode_ + /*************************************************************************/ + /* */ + /* */ + /* FT_Pixel_Mode */ + /* */ + /* */ + /* An enumeration type used to describe the format of pixels in a */ + /* given bitmap. Note that additional formats may be added in the */ + /* future. */ + /* */ + /* */ + /* ft_pixel_mode_mono :: A monochrome bitmap (1 bit/pixel). */ + /* */ + /* ft_pixel_mode_grays :: An 8-bit gray-levels bitmap. Note that the */ + /* total number of gray levels is given in the */ + /* `num_grays' field of the FT_Bitmap */ + /* structure. */ + /* */ + /* ft_pixel_mode_pal2 :: A 2-bit paletted bitmap. */ + /* Currently unused by FreeType. */ + /* */ + /* ft_pixel_mode_pal4 :: A 4-bit paletted bitmap. */ + /* Currently unused by FreeType. */ + /* */ + /* ft_pixel_mode_pal8 :: An 8-bit paletted bitmap. */ + /* Currently unused by FreeType. */ + /* */ + /* ft_pixel_mode_rgb15 :: A 15-bit RGB bitmap. Uses 5:5:5 encoding. */ + /* Currently unused by FreeType. */ + /* */ + /* ft_pixel_mode_rgb16 :: A 16-bit RGB bitmap. Uses 5:6:5 encoding. */ + /* Currently unused by FreeType. */ + /* */ + /* ft_pixel_mode_rgb24 :: A 24-bit RGB bitmap. */ + /* Currently unused by FreeType. */ + /* */ + /* ft_pixel_mode_rgb32 :: A 32-bit RGB bitmap. */ + /* Currently unused by FreeType. */ + /* */ + /* */ + /* Some anti-aliased bitmaps might be embedded in TrueType fonts */ + /* using formats pal2 or pal4, though no fonts presenting those have */ + /* been found to date. */ + /* */ + typedef enum FT_Pixel_Mode_ { ft_pixel_mode_none = 0, ft_pixel_mode_mono, @@ -127,28 +129,27 @@ } FT_Pixel_Mode; - - /************************************************************************* - * - * - * FT_Palette_Mode - * - * - * An enumeration type used to describe the format of a bitmap - * palette, used with ft_pixel_mode_pal4 and ft_pixel_mode_pal8 - * - * - * ft_palette_mode_rgb :: the palette is an array of 3-bytes RGB records - * - * ft_palette_mode_rgba :: the palette is an array of 4-bytes RGBA records - * - * - * As ft_pixel_mode_pal2, pal4 and pal8 are currently unused by - * FreeType, these types are not handled by the library itself. - * - *************************************************************************/ - - typedef enum FT_Palette_Mode_ + /*************************************************************************/ + /* */ + /* */ + /* FT_Palette_Mode */ + /* */ + /* */ + /* An enumeration type used to describe the format of a bitmap */ + /* palette, used with ft_pixel_mode_pal4 and ft_pixel_mode_pal8. */ + /* */ + /* */ + /* ft_palette_mode_rgb :: The palette is an array of 3-bytes RGB */ + /* records. */ + /* */ + /* ft_palette_mode_rgba :: The palette is an array of 4-bytes RGBA */ + /* records. */ + /* */ + /* */ + /* As ft_pixel_mode_pal2, pal4 and pal8 are currently unused by */ + /* FreeType, these types are not handled by the library itself. */ + /* */ + typedef enum FT_Palette_Mode_ { ft_palette_mode_rgb = 0, ft_palette_mode_rgba, @@ -158,59 +159,58 @@ } FT_Palette_Mode; - /************************************************************************* - * - * - * FT_Bitmap - * - * - * A structure used to describe a bitmap or pixmap to the raster. - * Note that we now manage pixmaps of various depths through the - * `pixel_mode' field. - * - * - * rows :: The number of bitmap rows. - * - * width :: The number of pixels in bitmap row. - * - * pitch :: The pitch's absolute value is the number of bytes - * taken by one bitmap row, including padding. However, - * the pitch is positive when the bitmap has a `down' - * flow, and negative when it has an `up' flow. In all - * cases, the pitch is an offset to add to a bitmap - * pointer in order to go down one row. - * - * buffer :: A typeless pointer to the bitmap buffer. This value - * should be aligned on 32-bit boundaries in most cases. - * - * num_grays :: this field is only used with ft_pixel_mode_grays, - * it gives the number of gray levels used in the - * bitmap. - * - * pixel_mode :: the pixel_mode, i.e. how pixel bits are stored - * - * palette_mode :: this field is only used with paletted pixel modes, - * it indicates how the palette is stored - * - * palette :: a typeless pointer to the bitmap palette. only used - * for paletted pixel modes. - * - * - * For now, the only pixel mode supported by FreeType are mono and grays. - * However, drivers might be added in the future to support more "colorful" - * options.. - * - * When using pixel modes pal2, pal4 and pal8 with a void `palette' - * field, a gray pixmap with respectively 4, 16 and 256 levels of gray - * is assumed. This, in order to be compatible with some embedded bitmap - * formats defined in the TrueType spec. - * - * Note that no font was found presenting such embedded bitmaps, so this - * is currently completely unhandled by the library. - * - *************************************************************************/ - - typedef struct FT_Bitmap_ + /*************************************************************************/ + /* */ + /* */ + /* FT_Bitmap */ + /* */ + /* */ + /* A structure used to describe a bitmap or pixmap to the raster. */ + /* Note that we now manage pixmaps of various depths through the */ + /* `pixel_mode' field. */ + /* */ + /* */ + /* rows :: The number of bitmap rows. */ + /* */ + /* width :: The number of pixels in bitmap row. */ + /* */ + /* pitch :: The pitch's absolute value is the number of bytes */ + /* taken by one bitmap row, including padding. */ + /* However, the pitch is positive when the bitmap has */ + /* a `down' flow, and negative when it has an `up' */ + /* flow. In all cases, the pitch is an offset to add */ + /* to a bitmap pointer in order to go down one row. */ + /* */ + /* buffer :: A typeless pointer to the bitmap buffer. This */ + /* value should be aligned on 32-bit boundaries in */ + /* most cases. */ + /* */ + /* num_grays :: This field is only used with */ + /* `ft_pixel_mode_grays'; it gives the number of gray */ + /* levels used in the bitmap. */ + /* */ + /* pixel_mode :: The pixel_mode, i.e., how pixel bits are stored. */ + /* */ + /* palette_mode :: This field is only used with paletted pixel modes; */ + /* it indicates how the palette is stored. */ + /* */ + /* palette :: A typeless pointer to the bitmap palette; only */ + /* used for paletted pixel modes. */ + /* */ + /* */ + /* For now, the only pixel mode supported by FreeType are mono and */ + /* grays. However, drivers might be added in the future to support */ + /* more `colorful' options. */ + /* */ + /* When using pixel modes pal2, pal4 and pal8 with a void `palette' */ + /* field, a gray pixmap with respectively 4, 16, and 256 levels of */ + /* gray is assumed. This, in order to be compatible with some */ + /* embedded bitmap formats defined in the TrueType specification. */ + /* */ + /* Note that no font was found presenting such embedded bitmaps, so */ + /* this is currently completely unhandled by the library. */ + /* */ + typedef struct FT_Bitmap_ { int rows; int width; @@ -224,7 +224,6 @@ } FT_Bitmap; - /*************************************************************************/ /* */ /* */ @@ -240,31 +239,26 @@ /* n_points :: The number of points in the outline. */ /* */ /* points :: A pointer to an array of `n_points' FT_Vector */ - /* elements, giving the outline's point */ - /* coordinates. */ + /* elements, giving the outline's point coordinates. */ /* */ - /* tags :: A pointer to an array of `n_points' chars, */ + /* tags :: A pointer to an array of `n_points' chars, giving */ /* giving each outline point's type. If bit 0 is */ - /* unset, the point is 'off' the curve, i.e. a */ - /* Bezier control point, while it is `on' when */ - /* unset. */ + /* unset, the point is 'off' the curve, i.e. a Bezier */ + /* control point, while it is `on' when unset. */ /* */ - /* Bit 1 is meaningful for `off' points only. If */ - /* set, it indicates a third-order Bezier arc */ - /* control point; and a second-order control point */ - /* if unset. */ + /* Bit 1 is meaningful for `off' points only. If set, */ + /* it indicates a third-order Bezier arc control point; */ + /* and a second-order control point if unset. */ /* */ /* contours :: An array of `n_contours' shorts, giving the end */ /* point of each contour within the outline. For */ - /* example, the first contour is defined by the */ - /* points `0' to `contours[0]', the second one is */ - /* defined by the points `contours[0]+1' to */ - /* `contours[1]', etc. */ + /* example, the first contour is defined by the points */ + /* `0' to `contours[0]', the second one is defined by */ + /* the points `contours[0]+1' to `contours[1]', etc. */ /* */ - /* flags :: a set of bit flags used to characterize the */ - /* outline and give hints to the scan-converter */ - /* and hinter on how to convert/grid-fit it.. */ - /* see FT_Outline_Flags.. */ + /* flags :: A set of bit flags used to characterize the outline */ + /* and give hints to the scan-converter and hinter on */ + /* how to convert/grid-fit it. See FT_Outline_Flags. */ /* */ typedef struct FT_Outline_ { @@ -286,49 +280,59 @@ /* FT_Outline_Flags */ /* */ /* */ - /* A simple type used to enumerates the flags in an outline's */ - /* "outline_flags" field. */ + /* A simple type used to enumerates the flags in an outline's */ + /* `outline_flags' field. */ /* */ /* */ - /* ft_outline_owner :: */ - /* when set, this flag indicates that the outline's field arrays */ - /* (i.e. "points", "flags" & "contours") are "owned" by the */ - /* outline object, and should thus be freed when it is destroyed. */ + /* ft_outline_owner :: If set, this flag indicates that the */ + /* outline's field arrays (i.e. */ + /* `points', `flags' & `contours') are */ + /* `owned' by the outline object, and */ + /* should thus be freed when it is */ + /* destroyed. */ /* */ - /* ft_outline_even_odd_fill :: */ - /* by default, outlines are filled using the non-zero winding */ - /* rule. When set to 1, the outline will be filled using the */ - /* even-odd fill rule.. (only works with the smooth raster) */ + /* ft_outline_even_odd_fill :: By default, outlines are filled using */ + /* the non-zero winding rule. If set to */ + /* 1, the outline will be filled using */ + /* the even-odd fill rule (only works */ + /* with the smooth raster). */ /* */ - /* ft_outline_reverse_fill :: */ - /* By default, outside contours of an outline are oriented in */ - /* clock-wise direction, as defined in the TrueType specification. */ - /* This flag is set when the outline uses the opposite direction, */ - /* (typically for Type 1 fonts). This flag is ignored by the */ - /* scan-converter. However, it is very important for the */ - /* auto-hinter.. */ + /* ft_outline_reverse_fill :: By default, outside contours of an */ + /* outline are oriented in clock-wise */ + /* direction, as defined in the TrueType */ + /* specification. This flag is set if */ + /* the outline uses the opposite */ + /* direction (typically for Type 1 */ + /* fonts). This flag is ignored by the */ + /* scan-converter. However, it is very */ + /* important for the auto-hinter. */ /* */ - /* ft_outline_ignore_dropouts :: */ - /* By default, the scan converter will try to detect drop-outs */ - /* in an outline and correct the glyph bitmap to ensure consistent */ - /* shape continuity. When set, this flag hints the scan-line */ - /* converter to ignore such cases. */ + /* ft_outline_ignore_dropouts :: By default, the scan converter will */ + /* try to detect drop-outs in an outline */ + /* and correct the glyph bitmap to */ + /* ensure consistent shape continuity. */ + /* If set, this flag hints the scan-line */ + /* converter to ignore such cases. */ /* */ - /* ft_outline_high_precision :: */ - /* this flag indicates that the scan-line converter should try */ - /* to convert this outline to bitmaps with the highest possible */ - /* quality. It is typically set for small character sizes. Note */ - /* that this is only a hint, that might be completely ignored */ - /* by a given scan-converter. */ + /* ft_outline_high_precision :: This flag indicates that the */ + /* scan-line converter should try to */ + /* convert this outline to bitmaps with */ + /* the highest possible quality. It is */ + /* typically set for small character */ + /* sizes. Note that this is only a */ + /* hint, that might be completely */ + /* ignored by a given scan-converter. */ /* */ - /* ft_outline_single_pass :: */ - /* this flag is set to force a given scan-converter to only */ - /* use a single pass over the outline to render a bitmap glyph */ - /* image. Normally, it is set for very large character sizes. */ - /* It is only a hint, that might be completely ignored by a */ - /* given scan-converter. */ + /* ft_outline_single_pass :: This flag is set to force a given */ + /* scan-converter to only use a single */ + /* pass over the outline to render a */ + /* bitmap glyph image. Normally, it is */ + /* set for very large character sizes. */ + /* It is only a hint, that might be */ + /* completely ignored by a given */ + /* scan-converter. */ /* */ - typedef enum FT_Outline_Flags_ + typedef enum FT_Outline_Flags_ { ft_outline_none = 0, ft_outline_owner = 1, @@ -341,18 +345,18 @@ } FT_Outline_Flags; +#define FT_CURVE_TAG( flag ) ( flag & 3 ) -#define FT_CURVE_TAG( flag ) (flag & 3) +#define FT_Curve_Tag_On 1 +#define FT_Curve_Tag_Conic 0 +#define FT_Curve_Tag_Cubic 2 -#define FT_Curve_Tag_On 1 -#define FT_Curve_Tag_Conic 0 -#define FT_Curve_Tag_Cubic 2 - -#define FT_Curve_Tag_Touch_X 8 /* reserved for the TrueType hinter */ -#define FT_Curve_Tag_Touch_Y 16 /* reserved for the TrueType hinter */ +#define FT_Curve_Tag_Touch_X 8 /* reserved for the TrueType hinter */ +#define FT_Curve_Tag_Touch_Y 16 /* reserved for the TrueType hinter */ #define FT_Curve_Tag_Touch_Both ( FT_Curve_Tag_Touch_X | \ - FT_Curve_Tag_Touch_Y) + FT_Curve_Tag_Touch_Y ) + /*************************************************************************/ /* */ @@ -367,6 +371,7 @@ /* */ /* */ /* to :: A pointer to the target point of the `move to'. */ + /* */ /* user :: A typeless pointer which is passed from the caller of the */ /* decomposition function. */ /* */ @@ -390,6 +395,7 @@ /* */ /* */ /* to :: A pointer to the target point of the `line to'. */ + /* */ /* user :: A typeless pointer which is passed from the caller of the */ /* decomposition function. */ /* */ @@ -442,8 +448,11 @@ /* */ /* */ /* control1 :: A pointer to the first Bezier control point. */ + /* */ /* control2 :: A pointer to the second Bezier control point. */ + /* */ /* to :: A pointer to the target end point. */ + /* */ /* user :: A typeless pointer which is passed from the caller of */ /* the decomposition function. */ /* */ @@ -468,26 +477,29 @@ /* */ /* */ /* move_to :: The `move to' emitter. */ + /* */ /* line_to :: The segment emitter. */ + /* */ /* conic_to :: The second-order Bezier arc emitter. */ + /* */ /* cubic_to :: The third-order Bezier arc emitter. */ /* */ - /* shift :: the shift that is applied to coordinates before */ - /* they're sent to the emmiter */ + /* shift :: The shift that is applied to coordinates before they */ + /* are sent to the emitter. */ /* */ - /* delta :: the delta that is applied to coordinates before */ - /* they're sent to the emitter, but after the shift */ + /* delta :: The delta that is applied to coordinates before they */ + /* are sent to the emitter, but after the shift. */ /* */ /* */ /* The point coordinates sent to the emitters are the transformed */ /* version of the original coordinates (this is important for high */ - /* accuracy during scan-conversion). The transform is simply: */ + /* accuracy during scan-conversion). The transformation is simple: */ /* */ - /* x' = (x << shift) - delta */ - /* y' = (x << shift) - delta */ + /* x' = (x << shift) - delta */ + /* y' = (x << shift) - delta */ /* */ - /* Set the value of 'shift' and 'delta' to 0 to get the original */ - /* point coordinates.. */ + /* Set the value of `shift' and `delta' to 0 to get the original */ + /* point coordinates. */ /* */ typedef struct FT_Outline_Funcs_ { @@ -508,55 +520,56 @@ /* FT_IMAGE_TAG */ /* */ /* */ - /* This macro converts four letter tags into unsigned longs.. */ + /* This macro converts four letter tags into an unsigned long. */ /* */ #define FT_IMAGE_TAG( _x1, _x2, _x3, _x4 ) \ - (((unsigned long)_x1 << 24) | \ - ((unsigned long)_x2 << 16) | \ - ((unsigned long)_x3 << 8) | \ - (unsigned long)_x4) + ( ( (unsigned long)_x1 << 24 ) | \ + ( (unsigned long)_x2 << 16 ) | \ + ( (unsigned long)_x3 << 8 ) | \ + (unsigned long)_x4 ) - /*********************************************************************** - * - * - * FT_Glyph_Format - * - * - * An enumeration type used to describe the format of a given glyph - * image. Note that this version of FreeType only supports two image - * formats, even though future font drivers will be able to register - * their own format. - * - * - * ft_glyph_format_composite :: the glyph image is a composite of several - * other images. This glyph format is _only_ - * used with the FT_LOAD_FLAG_NO_RECURSE flag - * (XXX: Which is currently iunimplemented) - * - * ft_glyph_format_bitmap :: the glyph image is a bitmap, and can - * be described as a FT_Bitmap - * - * ft_glyph_format_outline :: the glyph image is a vectorial image - * made of bezier control points, and can - * be described as a FT_Outline - * - * ft_glyph_format_plotter :: the glyph image is a vectorial image - * made of plotter lines (some T1 fonts like - * Hershey contain glyph in this format). - * - ***********************************************************************/ - - typedef enum FT_Glyph_Format_ + /*************************************************************************/ + /* */ + /* */ + /* FT_Glyph_Format */ + /* */ + /* */ + /* An enumeration type used to describe the format of a given glyph */ + /* image. Note that this version of FreeType only supports two image */ + /* formats, even though future font drivers will be able to register */ + /* their own format. */ + /* */ + /* */ + /* ft_glyph_format_composite :: The glyph image is a composite of */ + /* several other images. This glyph */ + /* format is _only_ used with the */ + /* FT_LOAD_FLAG_NO_RECURSE flag (XXX: */ + /* Which is currently unimplemented). */ + /* */ + /* ft_glyph_format_bitmap :: The glyph image is a bitmap, and can */ + /* be described as a FT_Bitmap. */ + /* */ + /* ft_glyph_format_outline :: The glyph image is a vectorial image */ + /* made of bezier control points, and */ + /* can be described as a FT_Outline. */ + /* */ + /* ft_glyph_format_plotter :: The glyph image is a vectorial image */ + /* made of plotter lines (some T1 fonts */ + /* like Hershey contain glyph in this */ + /* format). */ + /* */ + typedef enum FT_Glyph_Format_ { ft_glyph_format_none = 0, - ft_glyph_format_composite = FT_IMAGE_TAG('c','o','m','p'), - ft_glyph_format_bitmap = FT_IMAGE_TAG('b','i','t','s'), - ft_glyph_format_outline = FT_IMAGE_TAG('o','u','t','l'), - ft_glyph_format_plotter = FT_IMAGE_TAG('p','l','o','t') + ft_glyph_format_composite = FT_IMAGE_TAG( 'c', 'o', 'm', 'p' ), + ft_glyph_format_bitmap = FT_IMAGE_TAG( 'b', 'i', 't', 's' ), + ft_glyph_format_outline = FT_IMAGE_TAG( 'o', 'u', 't', 'l' ), + ft_glyph_format_plotter = FT_IMAGE_TAG( 'p', 'l', 'o', 't' ) } FT_Glyph_Format; + /*************************************************************************/ /*************************************************************************/ /*************************************************************************/ @@ -567,16 +580,18 @@ /*************************************************************************/ /*************************************************************************/ - /************************************************************************** - * - * A raster is a scan converter, in charge of rendering an outline into a - * a bitmap. This section contains the public API for rasters. - * - * Note that in FreeType 2, all rasters are now encapsulated within - * specific modules called "renderers". See - * for more details on renderers.. - * - **************************************************************************/ + + /*************************************************************************/ + /* */ + /* A raster is a scan converter, in charge of rendering an outline into */ + /* a a bitmap. This section contains the public API for rasters. */ + /* */ + /* Note that in FreeType 2, all rasters are now encapsulated within */ + /* specific modules called "renderers". See */ + /* for more details on renderers. */ + /* */ + /*************************************************************************/ + /*************************************************************************/ /* */ @@ -597,24 +612,26 @@ /* */ /* */ /* A structure used to model a single span of gray (or black) pixels */ - /* when rendering a monocrhome or anti-aliased bitmap. */ + /* when rendering a monochrome or anti-aliased bitmap. */ /* */ /* */ - /* x :: the span's horizontal start position */ - /* len :: the span's length in pixels */ - /* coverage :: the span color/coverage, ranging from 0 (background) */ - /* to 255 (foreground). Only used for anti-aliased */ - /* rendering.. */ + /* x :: The span's horizontal start position. */ + /* */ + /* len :: The span's length in pixels. */ + /* */ + /* coverage :: The span color/coverage, ranging from 0 (background) */ + /* to 255 (foreground). Only used for anti-aliased */ + /* rendering. */ /* */ /* */ - /* This structure is used by the span drawing callback type */ - /* named FT_Raster_Span_Func, which takes the y coordinate of the */ - /* span as a paremeter.. */ + /* This structure is used by the span drawing callback type named */ + /* FT_Raster_Span_Func(), which takes the y-coordinate of the span as */ + /* a parameter. */ /* */ - /* The coverage value is always between 0 and 255, even if the */ - /* number of gray levels have been set through FT_Set_Gray_Levels() */ + /* The coverage value is always between 0 and 255, even if the number */ + /* of gray levels have been set through FT_Set_Gray_Levels(). */ /* */ - typedef struct FT_Span_ + typedef struct FT_Span_ { short x; unsigned short len; @@ -634,33 +651,36 @@ /* spans on each scan line. */ /* */ /* */ - /* y :: the scanline's y coordinate */ - /* count :: the number of spans to draw on this scanline */ - /* spans :: a table of 'count' spans to draw on the scanline */ - /* user :: user-supplied data that is passed to the callback */ + /* y :: The scanline's y-coordinate. */ + /* */ + /* count :: The number of spans to draw on this scanline. */ + /* */ + /* spans :: A table of `count' spans to draw on the scanline. */ + /* */ + /* user :: User-supplied data that is passed to the callback. */ /* */ /* */ - /* This callback allows client applications to directly render the */ - /* gray spans of the anti-aliased bitmap to any kind of surfaces. */ + /* This callback allows client applications to directly render the */ + /* gray spans of the anti-aliased bitmap to any kind of surfaces. */ /* */ - /* This can be used to write anti-aliased outlines directly to a */ - /* given background bitmap, and even perform translucency.. */ + /* This can be used to write anti-aliased outlines directly to a */ + /* given background bitmap, and even perform translucency. */ /* */ - /* Note that the "count" field cannot be greater than a fixed value */ - /* defined by the FT_MAX_GRAY_SPANS configuration macro in ftoption.h */ + /* Note that the `count' field cannot be greater than a fixed value */ + /* defined by the FT_MAX_GRAY_SPANS configuration macro in */ + /* ftoption.h. By default, this value is set to 32, which means that */ + /* if there are more than 32 spans on a given scanline, the callback */ + /* will be called several times with the same `y' parameter in order */ + /* to draw all callbacks. */ /* */ - /* By default, this value is set to 32, which means that if there are */ - /* more than 32 spans on a given scanline, the callback will be called */ - /* several times with the same "y" parameter in order to draw all */ - /* callbacks.. */ + /* Otherwise, the callback is only called once per scan-line, and */ + /* only for those scanlines that do have `gray' pixels on them. */ /* */ - /* Otherwise, the callback is only called once per scan-line, and */ - /* only for those scanlines that do have "gray" pixels on them.. */ - /* */ - typedef void (*FT_Raster_Span_Func)( int y, - int count, - FT_Span* spans, - void* user ); + typedef void (*FT_Raster_Span_Func)( int y, + int count, + FT_Span* spans, + void* user ); + /*************************************************************************/ /* */ @@ -669,21 +689,24 @@ /* */ /* */ /* A function used as a call-back by the monochrome scan-converter */ - /* to test wether a given target pixel is already set to the drawing */ - /* "color". These tests are crucial to implement drop-out control */ - /* per-se the TrueType spec.. */ + /* to test whether a given target pixel is already set to the drawing */ + /* `color'. These tests are crucial to implement drop-out control */ + /* per-se the TrueType spec. */ /* */ /* */ - /* y :: the pixel's y coordinate */ - /* x :: the pixel's x coordinate */ - /* user :: user-supplied data that is passed to the callback */ + /* y :: The pixel's y-coordinate. */ + /* */ + /* x :: The pixel's x-coordinate. */ + /* */ + /* user :: User-supplied data that is passed to the callback. */ /* */ /* */ - /* 1 if the pixel is "set", 0 otherwise */ + /* 1 if the pixel is `set', 0 otherwise. */ /* */ - typedef int (*FT_Raster_BitTest_Func)( int y, - int x, - void* user ); + typedef int (*FT_Raster_BitTest_Func)( int y, + int x, + void* user ); + /*************************************************************************/ /* */ @@ -692,94 +715,103 @@ /* */ /* */ /* A function used as a call-back by the monochrome scan-converter */ - /* used to set an individual target pixel. This is crucial to */ - /* implement drop-out control per-se the TrueType spec.. */ + /* to set an individual target pixel. This is crucial to implement */ + /* drop-out control according to the TrueType specification. */ /* */ /* */ - /* y :: the pixel's y coordinate */ - /* x :: the pixel's x coordinate */ - /* user :: user-supplied data that is passed to the callback */ + /* y :: The pixel's y-coordinate. */ + /* */ + /* x :: The pixel's x-coordinate. */ + /* */ + /* user :: User-supplied data that is passed to the callback. */ /* */ /* */ - /* 1 if the pixel is "set", 0 otherwise */ + /* 1 if the pixel is `set', 0 otherwise. */ /* */ - typedef void (*FT_Raster_BitSet_Func)( int y, - int x, - void* user ); + typedef void (*FT_Raster_BitSet_Func)( int y, + int x, + void* user ); - /************************************************************************** - * - * - * FT_Raster_Flag - * - * - * An enumeration used to list the bit flags used in the "flags" - * field of a FT_Raster_Params function. - * - * - * ft_raster_flag_default :: this value is 0 - * - * ft_raster_flag_aa :: resquests the rendering of an anti-aliased - * glyph bitmap. If unset, a monchrome bitmap - * will be rendered. - * - * ft_raster_flag_direct :: requests direct rendering over the target - * bitmap. Direct rendering uses user-provided - * callbacks in order to perform direct - * drawing or composition over an existing - * bitmap. If this bit is unset, the content - * of the target bitmap **must be zeroed** ! - * - **************************************************************************/ - typedef enum { - + /*************************************************************************/ + /* */ + /* */ + /* FT_Raster_Flag */ + /* */ + /* */ + /* An enumeration to list the bit flags as used in the `flags' field */ + /* of a FT_Raster_Params structure. */ + /* */ + /* */ + /* ft_raster_flag_default :: This value is 0. */ + /* */ + /* ft_raster_flag_aa :: Requests the rendering of an */ + /* anti-aliased glyph bitmap. If unset, a */ + /* monchrome bitmap will be rendered. */ + /* */ + /* ft_raster_flag_direct :: Requests direct rendering over the */ + /* target bitmap. Direct rendering uses */ + /* user-provided callbacks in order to */ + /* perform direct drawing or composition */ + /* over an existing bitmap. If this bit is */ + /* unset, the content of the target bitmap */ + /* *must be zeroed*! */ + /* */ + typedef enum + { ft_raster_flag_default = 0, ft_raster_flag_aa = 1, ft_raster_flag_direct = 2 } FT_Raster_Flag; - /************************************************************************** - * - * - * FT_Raster_Params - * - * - * A structure used to hold the arguments used by a raster's render - * function. - * - * - * target :: the target bitmap - * source :: pointer to the source glyph image (e.g. a FT_Outline) - * flags :: rendering flags - * gray_spans :: gray span drawing callback - * black_spans :: black span drawing callback - * bit_test :: bit test callback - * bit_set :: bit set callback - * user :: user-supplied data that is passed to each drawing - * callback.. - * - * - * An anti-aliased glyph bitmap is drawn if the ft_raster_flag_aa bit - * flag is set in the "flags" field, otherwise a monochrome bitmap will - * be generated. - * - * When the ft_raster_flag_direct bit flag is set in "flags", the raster - * will call the "gray_spans" callback to drawn gray pixel spans, in the - * case of an aa glyph bitmap, or "black_spans", "bit_test" and "bit_set" - * in the case of a monochrome bitmap. - * - * This allows direct composition over a pre-existing bitmap through - * user-provided callbacks to perform the span drawing/composition. - * - * Note that the "bit_test" and "bit_set" callbacks are required when - * rendering a monochrome bitmap, as they are crucial to implement correct - * drop-out control per-se the TrueType specification.. - * - **************************************************************************/ - typedef struct FT_Raster_Params_ + /*************************************************************************/ + /* */ + /* */ + /* FT_Raster_Params */ + /* */ + /* */ + /* A structure to hold the arguments used by a raster's render */ + /* function. */ + /* */ + /* */ + /* target :: The target bitmap. */ + /* */ + /* source :: A pointer to the source glyph image (e.g. an */ + /* FT_Outline). */ + /* */ + /* flags :: The rendering flags. */ + /* */ + /* gray_spans :: The gray span drawing callback. */ + /* */ + /* black_spans :: The black span drawing callback. */ + /* */ + /* bit_test :: The bit test callback. */ + /* */ + /* bit_set :: The bit set callback. */ + /* */ + /* user :: User-supplied data that is passed to each drawing */ + /* callback. */ + /* */ + /* */ + /* An anti-aliased glyph bitmap is drawn if the ft_raster_flag_aa bit */ + /* flag is set in the `flags' field, otherwise a monochrome bitmap */ + /* will be generated. */ + /* */ + /* If the ft_raster_flag_direct bit flag is set in `flags', the */ + /* raster will call the `gray_spans' callback to draw gray pixel */ + /* spans, in the case of an aa glyph bitmap, it will call */ + /* `black_spans', and `bit_test' and `bit_set' in the case of a */ + /* monochrome bitmap. This allows direct composition over a */ + /* pre-existing bitmap through user-provided callbacks to perform the */ + /* span drawing/composition. */ + /* */ + /* Note that the `bit_test' and `bit_set' callbacks are required when */ + /* rendering a monochrome bitmap, as they are crucial to implement */ + /* correct drop-out control as defined in the TrueType specification. */ + /* */ + typedef struct FT_Raster_Params_ { FT_Bitmap* target; void* source; @@ -793,164 +825,161 @@ } FT_Raster_Params; - - /************************************************************************** - * - * FT_Raster_New_Func - * - * - * A function used to create a new raster object. - * - * - * memory :: handle to memory allocator. - * - * - * raster :: handle to new raster object - * - * - * Error code. 0 means success - * - * - * the "memory" parameter is a typeless pointer in order to avoid - * un-wanted dependencies on the rest of the FreeType code. - * - * in practice, it is a FT_Memory, i.e. a handle to the standard - * FreeType memory allocator. However, this field can be completely - * ignored by a given raster implementation.. - * - **************************************************************************/ - - typedef int (*FT_Raster_New_Func)( void* memory, - FT_Raster *raster ); + /*************************************************************************/ + /* */ + /* */ + /* FT_Raster_New_Func */ + /* */ + /* */ + /* A function used to create a new raster object. */ + /* */ + /* */ + /* memory :: A handle to the memory allocator. */ + /* */ + /* */ + /* raster :: A handle to the new raster object. */ + /* */ + /* */ + /* Error code. 0 means success. */ + /* */ + /* */ + /* The `memory' parameter is a typeless pointer in order to avoid */ + /* un-wanted dependencies on the rest of the FreeType code. In */ + /* practice, it is a FT_Memory, i.e., a handle to the standard */ + /* FreeType memory allocator. However, this field can be completely */ + /* ignored by a given raster implementation. */ + /* */ + typedef int (*FT_Raster_New_Func)( void* memory, + FT_Raster* raster ); - /************************************************************************** - * - * FT_Raster_Done_Func - * - * - * A function used to destroy a given raster object. - * - * - * raster :: handle to new raster object - * - **************************************************************************/ - - typedef void (*FT_Raster_Done_Func)( FT_Raster raster ); + /*************************************************************************/ + /* */ + /* */ + /* FT_Raster_Done_Func */ + /* */ + /* */ + /* A function used to destroy a given raster object. */ + /* */ + /* */ + /* raster :: A handle to the raster object. */ + /* */ + typedef void (*FT_Raster_Done_Func)( FT_Raster raster ); - - /************************************************************************** - * - * - * FT_Raster_Reset_Func - * - * - * FreeType provides an area of memory called the "render pool", - * available to all registered rasters. This pool can be freely - * used during a given scan-conversion but is shared by all rasters. - * Its content is thus transient. - * - * This function is called each time the render pool changes, or - * just after a new raster object is created. - * - * - * raster :: handle to new raster object - * pool_base :: address in memory of render pool - * pool_size :: size in bytes of render pool - * - * - * Rasters can ignore the render pool and rely on dynamic memory - * allocation if they want to (a handle to the memory allocator is - * passed to the raster constructor). However, this is not recommended - * for efficiency purposes.. - * - **************************************************************************/ - - typedef void (*FT_Raster_Reset_Func)( FT_Raster raster, - unsigned char* pool_base, - unsigned long pool_size ); + /*************************************************************************/ + /* */ + /* */ + /* FT_Raster_Reset_Func */ + /* */ + /* */ + /* FreeType provides an area of memory called the `render pool', */ + /* available to all registered rasters. This pool can be freely used */ + /* during a given scan-conversion but is shared by all rasters. Its */ + /* content is thus transient. */ + /* */ + /* This function is called each time the render pool changes, or just */ + /* after a new raster object is created. */ + /* */ + /* */ + /* raster :: A handle to the new raster object. */ + /* */ + /* pool_base :: The address in memory of the render pool. */ + /* */ + /* pool_size :: The size in bytes of the render pool. */ + /* */ + /* */ + /* Rasters can ignore the render pool and rely on dynamic memory */ + /* allocation if they want to (a handle to the memory allocator is */ + /* passed to the raster constructor). However, this is not */ + /* recommended for efficiency purposes. */ + /* */ + typedef void (*FT_Raster_Reset_Func)( FT_Raster raster, + unsigned char* pool_base, + unsigned long pool_size ); - /************************************************************************** - * - * - * FT_Raster_Set_Mode_Func - * - * - * This function is a generic facility to change modes or attributes - * in a given raster. This can be used for debugging purposes, or - * simply to allow implementation-specific "features" in a given - * raster module. - * - * - * raster :: handle to new raster object - * mode :: a 4-byte tag used to name the mode or property - * args :: a pointer to the new mode/property to use - * - **************************************************************************/ + /*************************************************************************/ + /* */ + /* */ + /* FT_Raster_Set_Mode_Func */ + /* */ + /* */ + /* This function is a generic facility to change modes or attributes */ + /* in a given raster. This can be used for debugging purposes, or */ + /* simply to allow implementation-specific `features' in a given */ + /* raster module. */ + /* */ + /* */ + /* raster :: A handle to the new raster object. */ + /* */ + /* mode :: A 4-byte tag used to name the mode or property. */ + /* */ + /* args :: A pointer to the new mode/property to use. */ + /* */ + typedef int (*FT_Raster_Set_Mode_Func)( FT_Raster raster, + unsigned long mode, + void* args ); - typedef int (*FT_Raster_Set_Mode_Func)( FT_Raster raster, - unsigned long mode, - void* args ); - - /************************************************************************** - * - * - * FT_Raster_Render_Func - * - * - * Invokes a given raster to scan-convert a given glyph image into - * a target bitmap. - * - * - * raster :: handle to raster object - * params :: pointer to a FT_Raster_Params structure used to store - * the rendering parameters. - * - * - * Error code. 0 means success - * - * - * The exact format of the source image depends on the raster's - * glyph format defined in its FT_Raster_Funcs structure. It can be - * an FT_Outline or anything else in order to support a large array - * of glyph formats. - * - * Note also that the render function can fail and return a - * FT_Err_Unimplemented_Feature error code when the raster used does - * not support direct composition. - * - * XXX: For now, the standard raster doesn't support direct composition - * but this should change for the final release (see the files - * demos/src/ftgrays.c and demos/src/ftgrays2.c for examples of - * distinct implementations which support direct composition). - * - **************************************************************************/ + /*************************************************************************/ + /* */ + /* */ + /* FT_Raster_Render_Func */ + /* */ + /* */ + /* Invokes a given raster to scan-convert a given glyph image into a */ + /* target bitmap. */ + /* */ + /* */ + /* raster :: A handle to the raster object. */ + /* */ + /* params :: A pointer to a FT_Raster_Params structure used to store */ + /* the rendering parameters. */ + /* */ + /* */ + /* Error code. 0 means success. */ + /* */ + /* */ + /* The exact format of the source image depends on the raster's glyph */ + /* format defined in its FT_Raster_Funcs structure. It can be an */ + /* FT_Outline or anything else in order to support a large array of */ + /* glyph formats. */ + /* */ + /* Note also that the render function can fail and return a */ + /* FT_Err_Unimplemented_Feature error code if the raster used does */ + /* not support direct composition. */ + /* */ + /* XXX: For now, the standard raster doesn't support direct */ + /* composition but this should change for the final release (see */ + /* the files demos/src/ftgrays.c and demos/src/ftgrays2.c for */ + /* examples of distinct implementations which support direct */ + /* composition). */ + /* */ typedef int (*FT_Raster_Render_Func)( FT_Raster raster, FT_Raster_Params* params ); - /************************************************************************** - * - * - * FT_Raster_Funcs - * - * - * A structure used to describe a given raster class to the library. - * - * - * glyph_format :: the supported glyph format for this raster - * raster_new :: the raster constructor - * raster_reset :: used to reset the render pool within the raster - * raster_render :: renders a glyph into a given bitmap - * raster_done :: the raster destructor - * - **************************************************************************/ - - - typedef struct FT_Raster_Funcs_ + /*************************************************************************/ + /* */ + /* */ + /* FT_Raster_Funcs */ + /* */ + /* */ + /* A structure used to describe a given raster class to the library. */ + /* */ + /* */ + /* glyph_format :: The supported glyph format for this raster. */ + /* */ + /* raster_new :: The raster constructor. */ + /* */ + /* raster_reset :: Used to reset the render pool within the raster. */ + /* */ + /* raster_render :: A function to render a glyph into a given bitmap. */ + /* */ + /* raster_done :: The raster destructor. */ + /* */ + typedef struct FT_Raster_Funcs_ { FT_Glyph_Format glyph_format; FT_Raster_New_Func raster_new; @@ -969,3 +998,5 @@ #endif /* FTIMAGE_H */ + +/* END */