(***************************************************************************) (* *) (* ftglyph.h *) (* *) (* FreeType convenience functions to handle glyphs (specification). *) (* *) (* Copyright 1996-2001, 2002, 2003, 2006 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. *) (* *) (***************************************************************************) (***************************************************************************) (* Pascal port by the UltraStar Deluxe Team *) (***************************************************************************) (*************************************************************************) (* *) (* 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. *) (* *) (*************************************************************************) (*************************************************************************) (* *) (*
*) (* glyph_management *) (* *) (* *) (* Glyph Management *) (* *) (* <Abstract> *) (* Generic interface to manage individual glyph data. *) (* *) (* <Description> *) (* This section contains definitions used to manage glyph data *) (* through generic FT_Glyph objects. Each of them can contain a *) (* bitmap, a vector outline, or even images in other formats. *) (* *) (*************************************************************************) {$IFDEF TYPE_DECL} (* forward declaration to a private type *) PFT_Glyph_Class = Pointer; (*************************************************************************) (* *) (* <Type> *) (* FT_Glyph *) (* *) (* <Description> *) (* Handle to an object used to model generic glyph images. It is a *) (* pointer to the @FT_GlyphRec structure and can contain a glyph *) (* bitmap or pointer. *) (* *) (* <Note> *) (* Glyph objects are not owned by the library. You must thus release *) (* them manually (through @FT_Done_Glyph) _before_ calling *) (* @FT_Done_FreeType. *) (* *) FT_Glyph = ^FT_GlyphRec; (*************************************************************************) (* *) (* <Struct> *) (* FT_GlyphRec *) (* *) (* <Description> *) (* The root glyph structure contains a given glyph image plus its *) (* advance width in 16.16 fixed float format. *) (* *) (* <Fields> *) (* 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. *) (* *) FT_GlyphRec = record library_: FT_Library; clazz: PFT_Glyph_Class; format: FT_Glyph_Format; advance: FT_Vector; end; (*************************************************************************) (* *) (* <Type> *) (* FT_BitmapGlyph *) (* *) (* <Description> *) (* A handle to an object used to model a bitmap glyph image. This is *) (* a sub-class of @FT_Glyph, and a pointer to @FT_BitmapGlyphRec. *) (* *) FT_BitmapGlyph = ^FT_BitmapGlyphRec; (*************************************************************************) (* *) (* <Struct> *) (* FT_BitmapGlyphRec *) (* *) (* <Description> *) (* A structure used for bitmap glyph images. This really is a *) (* `sub-class' of `FT_GlyphRec'. *) (* *) (* <Fields> *) (* 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. *) (* *) (* <Note> *) (* 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. *) (* *) FT_BitmapGlyphRec = record root: FT_GlyphRec; left: FT_Int; top: FT_Int; bitmap: FT_Bitmap; end; (*************************************************************************) (* *) (* <Type> *) (* FT_OutlineGlyph *) (* *) (* <Description> *) (* A handle to an object used to model an outline glyph image. This *) (* is a sub-class of @FT_Glyph, and a pointer to @FT_OutlineGlyphRec. *) (* *) FT_OutlineGlyph = ^FT_OutlineGlyphRec; (*************************************************************************) (* *) (* <Struct> *) (* FT_OutlineGlyphRec *) (* *) (* <Description> *) (* A structure used for outline (vectorial) glyph images. This *) (* really is a `sub-class' of `FT_GlyphRec'. *) (* *) (* <Fields> *) (* root :: The root FT_Glyph fields. *) (* *) (* outline :: A descriptor for the outline. *) (* *) (* <Note> *) (* 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. *) (* *) FT_OutlineGlyphRec = record root: FT_GlyphRec; outline: FT_Outline; end; {$ELSE TYPE_DECL} (*************************************************************************) (* *) (* <Function> *) (* FT_Get_Glyph *) (* *) (* <Description> *) (* A function used to extract a glyph image from a slot. *) (* *) (* <Input> *) (* slot :: A handle to the source glyph slot. *) (* *) (* <Output> *) (* aglyph :: A handle to the glyph object. *) (* *) (* <Return> *) (* FreeType error code. 0 means success. *) (* *) function FT_Get_Glyph( slot: FT_GlyphSlot; out aglyph: FT_Glyph ): FT_Error; cdecl; external ft_lib name 'FT_Get_Glyph'; (*************************************************************************) (* *) (* <Function> *) (* FT_Glyph_Copy *) (* *) (* <Description> *) (* A function used to copy a glyph image. Note that the created *) (* @FT_Glyph object must be released with @FT_Done_Glyph. *) (* *) (* <Input> *) (* source :: A handle to the source glyph object. *) (* *) (* <Output> *) (* target :: A handle to the target glyph object. 0~in case of *) (* error. *) (* *) (* <Return> *) (* FreeType error code. 0~means success. *) (* *) function FT_Glyph_Copy(source: FT_Glyph; var target: FT_Glyph ): FT_Error; cdecl; external ft_lib name 'FT_Glyph_Copy'; {$ENDIF TYPE_DECL} {$IFDEF TYPE_DECL} (*************************************************************************) (* *) (* <Enum> *) (* FT_Glyph_BBox_Mode *) (* *) (* <Description> *) (* The mode how the values of @FT_Glyph_Get_CBox are returned. *) (* *) (* <Values> *) (* FT_GLYPH_BBOX_UNSCALED :: *) (* Return unscaled font units. *) (* *) (* FT_GLYPH_BBOX_SUBPIXELS :: *) (* Return unfitted 26.6 coordinates. *) (* *) (* FT_GLYPH_BBOX_GRIDFIT :: *) (* Return grid-fitted 26.6 coordinates. *) (* *) (* FT_GLYPH_BBOX_TRUNCATE :: *) (* Return coordinates in integer pixels. *) (* *) (* FT_GLYPH_BBOX_PIXELS :: *) (* Return grid-fitted pixel coordinates. *) (* *) FT_Glyph_BBox_Mode = cint; {$ELSE TYPE_DECL} const FT_GLYPH_BBOX_UNSCALED = 0; FT_GLYPH_BBOX_SUBPIXELS = 0; FT_GLYPH_BBOX_GRIDFIT = 1; FT_GLYPH_BBOX_TRUNCATE = 2; FT_GLYPH_BBOX_PIXELS = 3; (*************************************************************************) (* *) (* <Function> *) (* FT_Glyph_Get_CBox *) (* *) (* <Description> *) (* Return a glyph's `control box'. The control box encloses all the *) (* outline's points, including Bézier 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 *) (* which contains Bézier 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> *) (* glyph :: A handle to the source glyph object. *) (* *) (* mode :: The mode which indicates how to interpret the returned *) (* bounding box values. *) (* *) (* <Output> *) (* acbox :: The glyph coordinate bounding box. Coordinates are *) (* expressed in 1/64th of pixels if it is grid-fitted. *) (* *) (* <Note> *) (* Coordinates are relative to the glyph origin, using the Y-upwards *) (* convention. *) (* *) (* If the glyph has been loaded with @FT_LOAD_NO_SCALE, `bbox_mode' *) (* must be set to @FT_GLYPH_BBOX_UNSCALED to get unscaled font *) (* units in 26.6 pixel format. The value @FT_GLYPH_BBOX_SUBPIXELS *) (* is another name for this constant. *) (* *) (* 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 `bbox_mode' is set to *) (* @FT_GLYPH_BBOX_GRIDFIT, 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); *) (* } *) (* *) (* To get the bbox in pixel coordinates, set `bbox_mode' to *) (* @FT_GLYPH_BBOX_TRUNCATE. *) (* *) (* To get the bbox in grid-fitted pixel coordinates, set `bbox_mode' *) (* to @FT_GLYPH_BBOX_PIXELS. *) (* *) procedure FT_Glyph_Get_CBox( glyph: FT_Glyph; bbox_mode: FT_UInt; out acbox: FT_BBox ); cdecl; external ft_lib name 'FT_Glyph_Get_CBox'; (*************************************************************************) (* *) (* <Function> *) (* FT_Glyph_To_Bitmap *) (* *) (* <Description> *) (* Converts a given glyph object to a bitmap glyph object. *) (* *) (* <InOut> *) (* the_glyph :: A pointer to a handle to the target glyph. *) (* *) (* <Input> *) (* render_mode :: An enumeration that describe how the data is *) (* rendered. *) (* *) (* 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. *) (* *) (* <Return> *) (* FreeType error code. 0 means success. *) (* *) (* <Note> *) (* The glyph image is translated with the `origin' vector before *) (* rendering. *) (* *) (* 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 does nothing if the glyph format isn't scalable. *) (* *) function FT_Glyph_To_Bitmap(var the_glyph: FT_Glyph; render_mode: FT_Render_Mode; origin: PFT_Vector; destroy: FT_Bool ): FT_Error; cdecl; external ft_lib name 'FT_Glyph_To_Bitmap'; (*************************************************************************) (* *) (* <Function> *) (* FT_Done_Glyph *) (* *) (* <Description> *) (* Destroys a given glyph. *) (* *) (* <Input> *) (* glyph :: A handle to the target glyph object. *) (* *) procedure FT_Done_Glyph( glyph: FT_Glyph ); cdecl; external ft_lib name 'FT_Done_Glyph'; {$ENDIF TYPE_DECL}