A handle to a FreeType library instance. Each
`library' is completely independent from the
others; it is the `root' of a set of objects like
fonts, faces, sizes, etc.
It also embeds a memory manager (see
FT_Memory
), as well as a scan-line converter object (see
FT_Raster
).
A handle to a given size object. Such an object
models the data that depends on the current
_resolution_ and _character_ _size_ in a given
FT_Face
.
note
Each face object owns one or more sizes. There is
however a single _active_ size for the face at
any time that will be used by functions like
FT_Load_Glyph
,
FT_Get_Kerning
, etc...
you can use the
FT_Activate_Size
API to change the current active size of any
given face
A handle to a given `glyph slot'. A slot is a
container where it is possible to load any one of
the glyphs contained in its parent face.
In other words, each time you call
FT_Load_Glyph
or
FT_Load_Char
, the slot's content is erased by the new glyph
data, i.e. the glyph's metrics, its image (bitmap
or outline), and other control information
A handle to a given character map. A charmap is
used to translate character codes in a given
encoding into glyph indexes for its parent's
face. Some font formats may provide several
charmaps per font.
Each face object owns zero or more charmaps, but
only one of them can be "active" and used by
FT_Get_Char_Index
or
FT_Load_Char
The list of available charmaps in a face is
available through the "face->num_charmaps" and
"face->charmaps" fields of
FT_FaceRec
the currently active charmap is available as
"face->charmap". You should call
FT_Set_Charmap
to change it
note
when a new face is created (either through
FT_New_Face
or
FT_Open_Face
), the library looks for a Unicode charmap within
the list and automatically activates it
FreeType root face class structure. A face object
models the resolution and point-size independent
data found in a font file.
fields
num_faces
In the case where the face is located in a
collection (i.e., a file which embed several
faces), this is the total number of faces found
in the resource. 1 by default.
face_index
The index of the face in its font file. Usually,
this is 0 for all normal font formats. It can be
more in the case of collections (which embed
several fonts in a single resource/file).
face_flags
A set of bit flags that give important
information about the face; see the
FT_FACE_FLAG_XXX constants for details.
style_flags
A set of bit flags indicating the style of the
face (i.e., italic, bold, underline, etc).
num_glyphs
The total number of glyphs in the face.
family_name
The face's family name. This is an ASCII string,
usually in English, which describes the
typeface's family (like `Times New Roman',
`Bodoni', `Garamond', etc). This is a least
common denominator used to list fonts. Some
formats (TrueType & OpenType) provide localized
and Unicode versions of this string. Applications
should use the format specific interface to
access them.
style_name
The face's style name. This is an ASCII string,
usually in English, which describes the
typeface's style (like `Italic', `Bold',
`Condensed', etc). Not all font formats provide a
style name, so this field is optional, and can be
set to NULL. As for `family_name', some formats
provide localized/Unicode versions of this
string. Applications should use the format
specific interface to access them.
num_fixed_sizes
The number of fixed sizes available in this face.
This should be set to 0 for scalable fonts,
unless its face includes a complete set of glyphs
(called a `strike') for the specified sizes.
available_sizes
An array of sizes specifying the available
bitmap/graymap sizes that are contained in in the
font face. Should be set to NULL if the field
`num_fixed_sizes' is set to 0.
num_charmaps
The total number of character maps in the face.
charmaps
A table of pointers to the face's charmaps. Used
to scan the list of available charmaps -- this
table might change after a call to
FT_Attach_File
or
FT_Attach_Stream
(e.g. when used to hook an additional encoding or
CMap to the face object).
generic
A field reserved for client uses. See the
FT_Generic
type description.
bbox
The font bounding box. Coordinates are expressed
in font units (see units_per_EM). The box is
large enough to contain any glyph from the font.
Thus, bbox.yMax can be seen as the `maximal
ascender', bbox.yMin as the `minimal descender',
and the maximal glyph width is given by
`bbox.xMax-bbox.xMin' (not to be confused with
the maximal _advance_width_). Only relevant for
scalable formats.
units_per_EM
The number of font units per EM square for this
face. This is typically 2048 for TrueType fonts,
1000 for Type1 fonts, and should be set to the
(unrealistic) value 1 for fixed-sizes fonts. Only
relevant for scalable formats.
ascender
The face's ascender is the vertical distance from
the baseline to the topmost point of any glyph in
the face. This field's value is positive,
expressed in font units. Some font designs use a
value different from `bbox.yMax'. Only relevant
for scalable formats.
descender
The face's descender is the vertical distance
from the baseline to the bottommost point of any
glyph in the face. This field's value is
positive, expressed in font units. Some font
designs use a value different from `-bbox.yMin'.
Only relevant for scalable formats.
height
The face's height is the vertical distance from
one baseline to the next when writing several
lines of text. Its value is always positive,
expressed in font units. The value can be
computed as `ascender+descender+line_gap' where
the value of `line_gap' is also called `external
leading'. Only relevant for scalable formats.
max_advance_width
The maximal advance width, in font units, for all
glyphs in this face. This can be used to make
word wrapping computations faster. Only relevant
for scalable formats.
max_advance_height
The maximal advance height, in font units, for
all glyphs in this face. This is only relevant
for vertical layouts, and should be set to the
`height' for fonts that do not provide vertical
metrics. Only relevant for scalable formats.
underline_position
The position, in font units, of the underline
line for this face. It's the center of the
underlining stem. Only relevant for scalable
formats.
underline_thickness
The thickness, in font units, of the underline
for this face. Only relevant for scalable
formats.
glyph
The face's associated glyph slot(s). This object
is created automatically with a new face object.
However, certain kinds of applications (mainly
tools like converters) can need more than one
slot to ease their task.
A bit-field constant, used to indicate that a
given face provides vectorial outlines (i.e.,
TrueType or Type1). This doesn't prevent
embedding of bitmap strikes though, i.e., a given
face can have both this bit set, and a
`num_fixed_sizes' property > 0.
A bit-field constant, used to indicate that a
given face contains `fixed sizes', i.e., bitmap
strikes for some given pixel sizes. See the
`num_fixed_sizes' and `available_sizes' face
properties for more information.
A bit-field constant, used to indicate that a
given face contains vertical glyph metrics. If
not set, the glyph loader will synthetize
vertical metrics itself to help display vertical
text correctly.
A bit-field constant, used to indicate that a
given face contains kerning information. When
set, this information can be retrieved through
the function
FT_Get_Kerning
(). Note that when unset, this function will
always return the kerning vector (0,0).
A bit-field constant, used to indicate that the
font contains multiple masters and is capable of
interpolating between them. See the
multiple-masters specific API for more details
This bit field is used internally by FreeType to
indicate that a face's stream was provided by the
client application and should not be destroyed by
FT_Done_Face
().
A bit-field constant, used to indicate that the
glyphs in a given font can be retrieved very
quickly, and that a glyph cache is thus not
necessary for any of its child size objects.
This flag should really be set for fixed-size
formats like FNT, where each glyph bitmap is
available directly in binary form without any
kind of compression.
note
This bit flag is deprecated, because even if the
bitmaps are available directly in the font file,
the glyph sub-system is very likely to be faster
anyway...
FreeType root size class structure. A size object
models the resolution and pointsize dependent
data of a given face.
fields
face
Handle to the parent face object.
generic
A typeless pointer, which is unused by the
FreeType library or any of its drivers. It can be
used by client applications to link their own
data to each size object.
metrics
Metrics for this size object. This field is
read-only.
typedef struct FT_Size_Metrics_
{
FT_UShort x_ppem; /* horizontal pixels per EM */
FT_UShort y_ppem; /* vertical pixels per EM */
FT_Fixed x_scale; /* two scales used to convert font units */
FT_Fixed y_scale; /* to 26.6 frac. pixel coordinates.. */
FT_Pos ascender; /* ascender in 26.6 frac. pixels */
FT_Pos descender; /* descender in 26.6 frac. pixels */
FT_Pos height; /* text height in 26.6 frac. pixels */
FT_Pos max_advance; /* max horizontal advance, in 26.6 pixels */
} FT_Size_Metrics;
The size metrics structure returned scaled
important distances for a given size object.
fields
x_ppem
The character width, expressed in integer pixels.
This is the width of the EM square expressed in
pixels, hence the term `ppem' (pixels per EM).
y_ppem
The character height, expressed in integer
pixels. This is the height of the EM square
expressed in pixels, hence the term `ppem'
(pixels per EM).
x_scale
A simple 16.16 fixed point format coefficient
used to scale horizontal distances expressed in
font units to fractional (26.6) pixel
coordinates.
y_scale
A simple 16.16 fixed point format coefficient
used to scale vertical distances expressed in
font units to fractional (26.6) pixel
coordinates.
ascender
The ascender, expressed in 26.6 fixed point
pixels. Always positive.
descender
The descender, expressed in 26.6 fixed point
pixels. Always positive.
height
The text height, expressed in 26.6 fixed point
pixels. Always positive.
max_advance
Maximum horizontal advance, expressed in 26.6
fixed point pixels. Always positive.
note
The values of `ascender', `descender', and
`height' are only the scaled versions of
`face->ascender', `face->descender', and
`face->height'.
Unfortunately, due to glyph hinting, these values
might not be exact for certain fonts, they thus
must be treated as unreliable with an error
margin of at least one pixel!
Indeed, the only way to get the exact pixel
ascender and descender is to render _all_ glyphs.
As this would be a definite performance hit, it
is up to client applications to perform such
computations.
FreeType root glyph slot class structure. A glyph
slot is a container where individual glyphs can
be loaded, be they vectorial or bitmap/graymaps.
fields
library
A handle to the FreeType library instance this
slot belongs to.
face
A handle to the parent face object.
next
In some cases (like some font tools), several
glyph slots per face object can be a good thing.
As this is rare, the glyph slots are listed
through a direct, single-linked list using its
`next' field.
generic
A typeless pointer which is unused by the
FreeType library or any of its drivers. It can be
used by client applications to link their own
data to each glyph slot object.
metrics
The metrics of the last loaded glyph in the slot.
The returned values depend on the last load flags
(see the FT_Load_Glyph() API function) and can be
expressed either in 26.6 fractional pixels or
font units.
Note that even when the glyph image is
transformed, the metrics are not.
linearHoriAdvance
For scalable formats only, this field holds the
linearly scaled horizontal advance width for the
glyph (i.e. the scaled and unhinted value of the
hori advance). This can be important to perform
correct WYSIWYG layout.
Note that this value is expressed by default in
16.16 pixels. However, when the glyph is loaded
with the FT_LOAD_LINEAR_DESIGN flag, this field
contains simply the value of the advance in
original font units.
linearVertAdvance
For scalable formats only, this field holds the
linearly scaled vertical advance height for the
glyph. See linearHoriAdvance for comments.
advance
This is the transformed advance width for the
glyph.
format
This field indicates the format of the image
contained in the glyph slot. Typically
ft_glyph_format_bitmap, ft_glyph_format_outline,
and ft_glyph_format_composite, but others are
possible.
bitmap
This field is used as a bitmap descriptor when
the slot format is ft_glyph_format_bitmap. Note
that the address and content of the bitmap buffer
can change between calls of
FT_Load_Glyph
() and a few other functions.
bitmap_left
This is the bitmap's left bearing expressed in
integer pixels. Of course, this is only valid if
the format is ft_glyph_format_bitmap.
bitmap_top
This is the bitmap's top bearing expressed in
integer pixels. Remember that this is the
distance from the baseline to the top-most glyph
scanline, upwards y-coordinates being *positive*.
outline
The outline descriptor for the current glyph
image if its format is ft_glyph_bitmap_outline.
num_subglyphs
The number of subglyphs in a composite glyph.
This format is only valid for the composite glyph
format, that should normally only be loaded with
the FT_LOAD_NO_RECURSE flag.
subglyphs
An array of subglyph descriptors for composite
glyphs. There are `num_subglyphs' elements in
there.
control_data
Certain font drivers can also return the control
data for a given glyph image (e.g. TrueType
bytecode, Type 1 charstrings, etc.). This field
is a pointer to such data.
control_len
This is the length in bytes of the control data.
other
Really wicked formats can use this pointer to
present their own glyph image to client apps.
Note that the app will need to know about the
image format.
note
If
FT_Load_Glyph
() is called with default flags (see
FT_LOAD_DEFAULT
) the glyph image is loaded in the glyph slot in
its native format (e.g. a vectorial outline for
TrueType and Type 1 formats).
This image can later be converted into a bitmap
by calling FT_Render_Glyph(). This function finds
the current renderer for the native image's
format then invokes it.
The renderer is in charge of transforming the
native image through the slot's face
transformation fields, then convert it into a
bitmap that is returned in `slot->bitmap'.
Note that `slot->bitmap_left' and
`slot->bitmap_top' are also used to specify the
position of the bitmap relative to the current
pen position (e.g. coordinates [0,0] on the
baseline). Of course, `slot->format' is also
changed to `ft_glyph_format_bitmap' .
typedef struct FT_Glyph_Metrics_
{
FT_Pos width; /* glyph width */
FT_Pos height; /* glyph height */
FT_Pos horiBearingX; /* left side bearing in horizontal layouts */
FT_Pos horiBearingY; /* top side bearing in horizontal layouts */
FT_Pos horiAdvance; /* advance width for horizontal layout */
FT_Pos vertBearingX; /* left side bearing in vertical layouts */
FT_Pos vertBearingY; /* top side bearing in vertical layouts */
FT_Pos vertAdvance; /* advance height for vertical layout */
} FT_Glyph_Metrics;
A structure used to model the metrics of a single
glyph. Note that values are expressed in 26.6
fractional pixel format or in font units,
depending on context.
An extremely simple structure used to model the
size of a bitmap strike (i.e., a bitmap instance
of the font for a given resolution) in a
fixed-size font face. This is used for the
`available_sizes' field of the FT_Face_Properties
structure.
Return the version of the FreeType library being
used. This is useful when dynamically linking to
the library, since one cannot use the macros
FT_FREETYPE_MAJOR, FT_FREETYPE_MINOR, and
FT_FREETYPE_PATCH.
input
library
A source library handle.
output
amajor
The major version number.
aminor
The minor version number.
apatch
The patch version number.
note
The reason why this function takes a 'library'
argument is because certain programs implement
library initialization in a custom way that
doesn't use `FT_Init_FreeType'.
In such cases, the library version might not be
available before the library object has been
created.
Creates a new face object from a given resource
and typeface index using a pathname to the font
file.
inout
library
A handle to the library resource.
input
pathname
A path to the font file.
face_index
The index of the face within the resource. The
first face has index 0.
output
aface
A handle to a new face object.
return
FreeType error code. 0 means success.
note
Unlike FreeType 1.x, this function automatically
creates a glyph slot for the face object which
can be accessed directly through `face->glyph'.
FT_New_Face() can be used to determine and/or
check the font format of a given font resource.
If the `face_index' field is negative, the
function will _not_ return any face handle in
`aface'. Its return value should be 0 if the font
format is recognized, or non-zero otherwise.
Each new face object created with this function
also owns a default
FT_Size
object, accessible as `face->size'
Creates a new face object from a given resource
and typeface index using a font file already
loaded into memory.
inout
library
A handle to the library resource.
input
file_base
A pointer to the beginning of the font data.
file_size
The size of the memory chunk used by the font
data.
face_index
The index of the face within the resource. The
first face has index 0.
output
aface
A handle to a new face object.
return
FreeType error code. 0 means success.
note
The font data bytes are used _directly_ by the
FT_Face
object. This means that they are not copied, and
that the client is responsible for
releasing/destroying them _after_ the
corresponding call to
FT_Done_Face
.
Unlike FreeType 1.x, this function automatically
creates a glyph slot for the face object which
can be accessed directly through `face->glyph'.
FT_New_Memory_Face() can be used to determine
and/or check the font format of a given font
resource. If the `face_index' field is negative,
the function will _not_ return any face handle in
`aface'. Its return value should be 0 if the font
format is recognized, or non-zero otherwise.
Opens a face object from a given resource and
typeface index using an `FT_Open_Args' structure.
If the face object doesn't exist, it will be
created.
inout
library
A handle to the library resource.
input
args
A pointer to an `FT_Open_Args' structure which
must be filled by the caller.
face_index
The index of the face within the resource. The
first face has index 0.
output
aface
A handle to a new face object.
return
FreeType error code. 0 means success.
note
Unlike FreeType 1.x, this function automatically
creates a glyph slot for the face object which
can be accessed directly through `face->glyph'.
FT_Open_Face() can be used to determine and/or
check the font format of a given font resource.
If the `face_index' field is negative, the
function will _not_ return any face handle in
`*face'. Its return value should be 0 if the font
format is recognized, or non-zero otherwise.
A structure used to indicate how to open a new
font file/stream. A pointer to such a structure
can be used as a parameter for the functions
FT_Open_Face
() &
FT_Attach_Stream
().
fields
flags
A set of bit flags indicating how to use the
structure.
memory_base
The first byte of the file in memory.
memory_size
The size in bytes of the file in memory.
pathname
A pointer to an 8-bit file pathname.
stream
A handle to a source stream object.
driver
This field is exclusively used by FT_Open_Face();
it simply specifies the font driver to use to
open the face. If set to 0, FreeType will try to
load the face with each one of the drivers in its
list.
num_params
The number of extra parameters.
params
Extra parameters passed to the font driver when
opening a new face.
note
The stream type is determined by the contents of
`flags' which are tested in the following order
by
FT_Open_Face
:
If the `ft_open_memory' bit is set, assume that
this is a memory file of `memory_size'
bytes,located at `memory_address'.
Otherwise, if the `ft_open_stream' bit is set,
assume that a custom input stream `stream' is
used.
Otherwise, if the `ft_open_pathname' bit is set,
assume that this is a normal file and use
`pathname' to open it.
If the `ft_open_driver' bit is set,
FT_Open_Face
() will only try to open the file with the driver
whose handler is in `driver'.
If the `ft_open_params' bit is set, the
parameters given by `num_params' and `params'
will be used. They are ignored otherwise.
`Attaches' a given font file to an existing face.
This is usually to read additional information
for a single face object. For example, it is used
to read the AFM files that come with Type 1 fonts
in order to add kerning data and other metrics.
inout
face
The target face object.
input
filepathname
An 8-bit pathname naming the `metrics' file.
return
FreeType error code. 0 means success.
note
If your font file is in memory, or if you want to
provide your own input stream object, use
FT_Attach_Stream().
The meaning of the `attach' action (i.e., what
really happens when the new file is read) is not
fixed by FreeType itself. It really depends on
the font format (and thus the font driver).
Client applications are expected to know what
they are doing when invoking this function. Most
drivers simply do not implement file attachments.
This function is similar to FT_Attach_File() with
the exception that it reads the attachment from
an arbitrary stream.
inout
face
The target face object.
input
parameters
A pointer to an FT_Open_Args structure used to
describe the input stream to FreeType.
return
FreeType error code. 0 means success.
note
The meaning of the `attach' (i.e. what really
happens when the new file is read) is not fixed
by FreeType itself. It really depends on the font
format (and thus the font driver).
Client applications are expected to know what
they are doing when invoking this function. Most
drivers simply do not implement file attachments.
Sets the character dimensions of a given face
object. The `char_width' and `char_height' values
are used for the width and height, respectively,
expressed in 26.6 fractional points.
If the horizontal or vertical resolution values
are zero, a default value of 72dpi is used.
Similarly, if one of the character dimensions is
zero, its value is set equal to the other.
inout
size
A handle to a target size object.
input
char_width
The character width, in 26.6 fractional points.
char_height
The character height, in 26.6 fractional points.
horz_resolution
The horizontal resolution.
vert_resolution
The vertical resolution.
return
FreeType error code. 0 means success.
note
When dealing with fixed-size faces (i.e.,
non-scalable formats), use the function
FT_Set_Pixel_Sizes().
Sets the character dimensions of a given face
object. The width and height are expressed in
integer pixels.
If one of the character dimensions is zero, its
value is set equal to the other.
inout
face
A handle to the target face object.
input
pixel_width
The character width, in integer pixels.
pixel_height
The character height, in integer pixels.
return
FreeType error code. 0 means success.
note
The values of `pixel_width' and `pixel_height'
correspond to the pixel values of the
_typographic_ character size, which are NOT
necessarily the same as the dimensions of the
glyph `bitmap cells'.
The `character size' is really the size of an
abstract square called the `EM', used to design
the font. However, depending on the font design,
glyphs will be smaller or greater than the EM.
This means that setting the pixel size to, say,
8x8 doesn't guarantee in any way that you will
get glyph bitmaps that all fit within an 8x8 cell
(sometimes even far from it).
A function used to set the transformation that is
applied to glyph images just before they are
converted to bitmaps in a glyph slot when
FT_Render_Glyph() is called.
inout
face
A handle to the source face object.
input
matrix
A pointer to the transformation's 2x2 matrix. Use
0 for the identity matrix.
delta
A pointer to the translation vector. Use 0 for
the null vector.
note
The transformation is only applied to scalable
image formats after the glyph has been loaded. It
means that hinting is unaltered by the
transformation and is performed on the character
size given in the last call to
FT_Set_Char_Sizes() or FT_Set_Pixel_Sizes().
A function used to load a single glyph within a
given glyph slot, for a given size.
inout
face
A handle to the target face object where the
glyph will be loaded.
input
glyph_index
The index of the glyph in the font file.
load_flags
A flag indicating what to load for this glyph.
The FT_LOAD_XXX constants can be used to control
the glyph loading process (e.g., whether the
outline should be scaled, whether to load bitmaps
or not, whether to hint the outline, etc).
return
FreeType error code. 0 means success.
note
If the glyph image is not a bitmap, and if the
bit flag FT_LOAD_IGNORE_TRANSFORM is unset, the
glyph image will be transformed with the
information passed to a previous call to
FT_Set_Transform().
Note that this also transforms the
`face.glyph.advance' field, but *not* the values
in `face.glyph.metrics'.
Returns the glyph index of a given character
code. This function uses a charmap object to do
the translation.
input
face
A handle to the source face object.
charcode
The character code.
return
The glyph index. 0 means `undefined character
code'.
note
FreeType computes its own glyph indices which are
not necessarily the same as used in the font in
case the font is based on glyph indices. Reason
for this behaviour is to assure that index 0 is
never used, representing the missing glyph.
A function used to load a single glyph within a
given glyph slot, for a given size, according to
its character code.
inout
face
A handle to a target face object where the glyph
will be loaded.
input
char_code
The glyph's character code, according to the
current charmap used in the face.
load_flags
A flag indicating what to load for this glyph.
The FT_LOAD_XXX constants can be used to control
the glyph loading process (e.g., whether the
outline should be scaled, whether to load bitmaps
or not, whether to hint the outline, etc).
return
FreeType error code. 0 means success.
note
If the face has no current charmap, or if the
character code is not defined in the charmap,
this function will return an error.
If the glyph image is not a bitmap, and if the
bit flag FT_LOAD_IGNORE_TRANSFORM is unset, the
glyph image will be transformed with the
information passed to a previous call to
FT_Set_Transform().
Note that this also transforms the
`face.glyph.advance' field, but *not* the values
in `face.glyph.metrics'.
A bit-field constant, used with FT_Load_Glyph()
to indicate that the function should try to load
the glyph normally, i.e., embedded bitmaps are
favored over outlines, vectors are always scaled
and grid-fitted.
A bit-field constant, used with FT_Load_Glyph()
to indicate that the function should load the
glyph and immediately convert it into a bitmap,
if necessary, by calling FT_Render_Glyph().
Note that by default, FT_Load_Glyph() loads the
glyph image in its native format.
Only used with FT_LOAD_RENDER set, it indicates
that the returned glyph image should be 1-bit
monochrome. This really tells the glyph loader to
use `ft_render_mode_mono' when calling
FT_Render_Glyph().
A bit-field constant, used with FT_Load_Glyph()
to indicate that the function should return the
linearly scaled metrics expressed in original
font units, instead of the default 16.16 pixel
values.
A bit field constant, used with FT_Load_Glyph()
to indicate that the vector outline being loaded
should not be scaled to 26.6 fractional pixels,
but kept in notional units.
A bit-field constant, used with FT_Load_Glyph()
to indicate that the vector outline being loaded
should not be fitted to the pixel grid but simply
scaled to 26.6 fractional pixels.
A bit-field constant, used with FT_Load_Glyph()
to indicate that the function should not load the
bitmap or pixmap of a given glyph. This is useful
when you do not want to load the embedded bitmaps
of scalable formats, as the native glyph image
will be loaded, and can then be rendered through
FT_Render_Glyph().
A bit-field constant, used with FT_Load_Glyph()
to indicate that the font driver should try to
crop the bitmap (i.e. remove all space around its
black bits) when loading it. For now, this really
only works with embedded bitmaps in TrueType
fonts.
A bit-field constant, used with FT_Load_Glyph()
to indicate that the glyph image should be
prepared for vertical layout. This basically
means that `face.glyph.advance' will correspond
to the vertical advance height (instead of the
default horizontal advance width), and that the
glyph image will translated to match the vertical
bearings positions.
A bit-field constant, used with FT_Load_Glyph()
to indicate that the glyph loader should ignore
the global advance width defined in the font. As
far as we know, this is only used by the
X-TrueType font server, in order to deal
correctly with the incorrect metrics contained in
DynaLab's TrueType CJK fonts.
A bit-field constant, used with FT_Load_Glyph()
to indicate that the function should try to
auto-hint the glyphs, even if a driver specific
hinter is available.
A bit-field constant, used with FT_Load_Glyph()
to indicate that the glyph loader should not load
composite glyph recursively. Rather, when a
composite glyph is encountered, it should set the
values of `num_subglyphs' and `subglyphs', as
well as set `face->glyph.format' to
ft_glyph_format_composite.
This is for use by the auto-hinter and possibly
other tools. For nearly all applications, this
flags should be left unset when invoking
FT_Load_Glyph().
Note that the flag forces the load of unscaled
glyphs.
A bit-field constant, used with FT_Load_Glyph()
to indicate that the glyph loader should perform
a pedantic bytecode interpretation. Many popular
fonts come with broken glyph programs. When this
flag is set, loading them will return an error.
Otherwise, errors are ignored by the loader,
sometimes resulting in ugly glyphs.
An enumeration type that lists the render modes
supported by the FreeType 2 renderer(s). A
renderer is in charge of converting a glyph image
into a bitmap.
fields
ft_render_mode_normal
This is the default render mode; it corresponds
to 8-bit anti-aliased bitmaps, using 256 levels
of gray.
ft_render_mode_mono
This render mode is used to produce 1-bit
monochrome bitmaps.
note
There is no render mode to produce 8-bit
`monochrome' bitmaps -- you have to make the
conversion yourself if you need such things
(besides, FreeType is not a graphics library).
More modes might appear later for specific
display modes (e.g. TV, LCDs, etc.). They will be
supported through the simple addition of a
renderer module, with no changes to the rest of
the engine.
Returns the kerning vector between two glyphs of
a same face.
input
face
A handle to a source face object.
left_glyph
The index of the left glyph in the kern pair.
right_glyph
The index of the right glyph in the kern pair.
kern_mode
See FT_Kerning_Mode() for more information.
Determines the scale/dimension of the returned
kerning vector.
output
akerning
The kerning vector. This is in font units for
scalable formats, and in pixels for fixed-sizes
formats.
return
FreeType error code. 0 means success.
note
Only horizontal layouts (left-to-right &
right-to-left) are supported by this method.
Other layouts, or more sophisticated kernings,
are out of the scope of this API function -- they
can be implemented through format-specific
interfaces.
Retrieves the ASCII name of a given glyph in a
face. This only works for those faces where
FT_HAS_GLYPH_NAME(face) returns true.
input
face
A handle to a source face object.
glyph_index
The glyph index.
buffer_max
The maximal number of bytes available in the
buffer.
output
buffer
A pointer to a target buffer where the name will
be copied to.
return
FreeType error code. 0 means success.
note
An error is returned if the face doesn't provide
glyph names or if the glyph index is invalid. In
all cases of failure, the first byte of `buffer'
will be set to 0 to indicate an empty name.
The glyph name is truncated to fit within the
buffer if it is too long. The returned string is
always zero-terminated.
This function is not compiled within the library
if the config macro
FT_CONFIG_OPTION_NO_GLYPH_NAMES is defined in
`include/freetype/config/ftoptions.h'
An ID number describing the platform for the
following encoding ID. This comes directly from
the TrueType specification and should be emulated
for other formats.
encoding_id
A platform specific encoding number. This also
comes from the TrueType specification and should
be emulated similarly.
A handle to a given FreeType renderer. A renderer
is a special module in charge of converting a
glyph image to a bitmap, when necessary. Each
renderer supports a given glyph image format, and
one or more target surface depths.
#define FT_IS_SFNT( face ) \
( face->face_flags & FT_FACE_FLAG_SFNT )
A macro that returns true whenever a face object
contains a font whose format is based on the SFNT
storage scheme. This usually means: TrueType
fonts, OpenType fonts, as well as SFNT-based
embedded bitmap fonts.
#define FT_HAS_MULTIPLE_MASTERS( face ) \
( face->face_flags & FT_FACE_FLAG_MULTIPLE_MASTERS )
A macro that returns true whenever a face object
contains some multiple masters. The functions
provided by
FT_MULTIPLE_MASTERS_H
are then available to choose the exact design you
want.
This function is used to return the first
character code in the current charmap of a given
face. It will also return the corresponding glyph
index.
input
face
A handle to the source face object.
output
agindex
Glyph index of first character code. 0 if charmap
is empty.
return
The charmap's first character code.
note
You should use this function with
FT_Get_Next_Char
to be able to parse all character codes available
in a given charmap. The code should look like
this:
Note that `*agindex' will be set to 0 if the
charmap is empty. The result itself can be 0 in
two cases: if the charmap is empty or when the
value 0 is the first valid character code.
This function is used to return the next
character code in the current charmap of a given
face following the value 'char_code', as well as
the corresponding glyph index.
input
face
A handle to the source face object.
char_code
The starting character code.
output
agindex
Glyph index of first character code. 0 if charmap
is empty.
return
The charmap's next character code.
note
You should use this function with
FT_Get_First_Char
to walk through all character codes available in
a given charmap. See the note for this function
for a simple code example.
Note that `*agindex' will be set to 0 when there
are no more codes in the charmap.