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.
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.
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.
Returns a glyph's `control box'. The control box
encloses all the outline's points, including
Bezier control points. Though it coincides with
the exact bounding box for most glyphs, it can be
slightly larger in some situations (like when
rotating an outline which contains Bezier outside
arcs).
Computing the control box is very fast, while
getting the bounding box can take much more time
as it needs to walk over all segments and arcs in
the outline. To get the latter, you can use the
`ftbbox' component which is dedicated to this
single task.
input
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.
If `bbox_mode' is set to
`ft_glyph_bbox_subpixels' the bbox coordinates
are returned in 26.6 pixels (i.e. 1/64th of
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:
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
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.
return
FreeType error code. 0 means success.
note
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.