home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: SysTools
/
SysTools.zip
/
ft-beta.zip
/
freetype
/
docs
/
apiref.txt
next >
Wrap
Text File
|
1997-10-06
|
45KB
|
1,184 lines
The FreeType Engine
Core Library Reference
-----------------------------------
Table of Contents:
Introduction
I. Types
II. Functions
III. Error codes
--------------------
Introduction:
This reference presents the types, functions and error codes
defined in the high-level API header file "freetype.h". Note that
all symbols defined in this file are prefixed by "TT_", to avoid
name conflicts with other packages at link time.
Some of its parts are also dedicated to the extension that comes
by default with this distribution of the library, which is kerning
support.
----------------------------------------------------------------------------
I. Types:
Here is the list of all the types defined in the core FreeType
API. Their exact definition can be found in the file "freetype.h"
which should be included by every client application.
TT_Fixed
A signed 16.16 fixed float value used to specify transform
coefficients and other important data.
..................................................................
TT_FWord
A signed 16 bits value used to express a distance measured in
the font's original EM units. These are also called 'FUnits' in
the TrueType specification.
..................................................................
TT_UFWord
Unsigned FWord.
..................................................................
TT_Short
TT_UShort
TT_Long
TT_ULong
These four types are aliases for 16 bits integer (signed and
unsigned) and 32 bits one (signed and unsigned).
..................................................................
TT_F2Dot14
A 2.14 fixed float integer used for unary vectors and some
scaling coefficients. Their layout is:
s : 1 -- sign bit
m : 1 -- mantissa bit
f : 14 -- unsigned fractional value
where 's:m' is the 2-bit signed integer value to which the
always-positive fractional part 'f' should be added.
..................................................................
TT_F26Dot6
The 26.6 fixed float format used to define fractional pixel
coordinates. Here, 1 unit = 1/64 pixel.
..................................................................
TT_UnitVector
A simple structure used to store a unit vector. The vector's
coordinates are expressed in fixed float format (2.14).
struct
{
TT_F2Dot14 x;
TT_F2Dot14 y;
}
..................................................................
TT_Vector
A simple structure used to store a single vector. Its
coordinates are expressed in fixed float format (26.6).
struct
{
TT_F26Dot6 x;
TT_F26Dot6 y;
}
..................................................................
TT_Matrix
A simple structure used to store a single 2x2 matrix. Its
coefficients are expressed in 16.16 fixed float format. This
matrix is used to perform linear transformations on the glyph
outline, such as slanting or rotation.
struct
{
TT_Fixed xx, xy;
TT_Fixed yx, yy;
};
The computation performed is:
x' = xx * x + xy * y
y' = yx * x + yy * y
..................................................................
TT_Glyph_Outline
This structure is used to describe a vectorial glyph
representation to the rasterizer. It is made of:
- an array of points:
The 'points' field gives the number of points in the
outline, while their coordinates are found in the parallel
arrays 'xCoord' and 'yCoord'. The 'flag' array holds for
each point a flag indicating its type.
Currently, only the first bit (bit 0, the least significant
bit) of each byte is meaningful to the rasterizer. When
set, it indicates that the point is _on_ the curve. When
not set, the point is said to be _off_ the curve. It's then
a Bezier control point.
For more information about point states, read the TrueType
specification or the scan-line documentation "raster.txt".
- an array of contours' start-point indexes:
The 'contours' field gives the number of contours, while the
'conStarts' array holds the indexes of each contour's first
point. Note that the first contour always starts at 0 and
has no entry in this table.
Hence, conStarts[0] holds the index of the point starting
the _second_ contour. The first one being defined by the
closure of the path 0..conStarts[0]-1.
** IMPORTANT NOTE: **
*********************
The last table entry _must_ always give the total number of
points used to draw the contours, i.e.:
conStarts[contours-1] == points
If this value is bigger than 'points' when calling the
scan-line converter, the component will immediately return
an error. If the value is smaller, only the points
contained in the described contours will be used in the
conversion process.
- a dropout mode:
Used to specify the method to apply for drop-out control
(also called 'continuity testing' in other environments).
The mode value must be one of the values defined by the
TrueType specification.
The recent modes 4 and 5 introduced in the newest spec (1.6)
are fully supported.
An invalid value (i.e., other than 0, 1, 2, 4, or 5) is
taken as no dropout control (equivalent to mode 0).
NOTE1:
A typical user would only modify the point coordinates accessed
through the 'xCoord' and 'yCoord' fields. Changing the number
of points, the contours arrays or even the flags array is a
delicate process that should be taken seriously.
NOTE2:
A glyph outline only contains pointers to the tables it
describes, but it doesn't own them!
Typically, the tables are defined and owned by a glyph
container object (see below). They are accessed through a call
to TT_Get_Glyph_Outline() which returns a TT_Glyph_Outline
structure whose pointers relate to the container's data.
These outline's tables should never be freed directly by the
client application; they will be destroyed with the glyph
container when the latter is discarded.
struct
{
unsigned int contours; /* number of contours in glyph */
unsigned short* conStarts; /* points to an array of each
contour's start point index */
unsigned int points; /* number of points in the glyph */
long* xCoord; /* table of x coordinates */
long* yCoord; /* table of y coordinates */
unsigned char* flag; /* table of flags */
char dropout_mode; /* dropout mode */
}
..................................................................
TT_Glyph_Metrics
A structure used to return simple glyph metrics. These values
are expressed in fractional pixels (26.6 format) if scaling was
active, and in FUnits otherwise.
struct
{
TT_F26Dot6 leftSideBearing;
TT_F26Dot6 advanceWidth;
TT_F26Dot6 xMin, yMin, xMax, yMax;
};
..................................................................
TT_Instance_Metrics
A structure used to return instance (point size) metrics.
struct
{
int pointSize;
/* point size in points (1 point = 1/72 inch) */
int x_ppem; /* horizontal pixels per EM square */
int y_ppem; /* vertical pixels per EM square */
int x_resolution; /* device horizontal resolution in dpi */
int y_resolution; /* device vertical resolution in dpi */
};
..................................................................
TT_Raster_Map
This structure is used to describe a target bitmap (or pixmap)
to the scan-line converter. It must be set up by the client
application.
- the 'rows' field contains the total number of rows in the
bitmap
- the 'width' field gives the number of pixels per row (a bit or
a byte, depending on the map's nature).
- the 'cols' field gives the number of columns, i.e. bytes,
taken by each row in the map buffer.
** IMPORTANT **: the 'cols' field must be a multiple of 4!
Typically, its value should be '(width+7)/8' for bitmaps, and
'(width+3) & -4' for pixmaps.
- the 'flow' field gives the map's vertical orientation.
For example, if the first bytes of the bitmap buffer pertain
to its upper row, the flow is said to be going 'down', and the
field should take the value 'TT_Flow_Down'. If these bytes
pertain to its lowest row, the flow is going 'up', and the
value is 'TT_Flow_Up'.
As an example, the PC video modes use a 'down' flow, where the
first VRAM byte corresponds to the upper and leftmost corner
of the screen.
- the 'bitmap' field is a typeless pointer to the map's buffer.
- the 'size' field contains the buffer's size in bytes. It is
usually computed as follows:
size = rows * cols;
NOTE:
For bitmaps, the leftmost-pixel is related to the highest
(i.e. most significant) bit of its byte. There is currently
no support for the opposite convention found in some systems.
(It can be easily added if you really need it, just ask the
development team)
struct
{
int rows; /* number of rows */
int cols; /* number of columns (bytes) per row */
int width; /* number of pixels per line */
int flow; /* bitmap orientation */
void* bitmap; /* bit/pixmap buffer */
long size; /* bit/pixmap size in bytes */
} TT_Raster_Map;
..................................................................
TT_Header
This structure is used to hold the font's header. Its layout
and meaning are defined in the TrueType specification, in the
'head' section.
..................................................................
TT_Horizontal_Header
This structure is used to hold the font's horizontal header.
Its layout and meaning are defined in the TrueType
specification, in the 'hhead' section.
..................................................................
TT_OS2
This structure is used to hold the font's OS/2 table. Its
layout and meaning are defined in the TrueType specification, in
the 'OS/2' section.
..................................................................
TT_Postscript
This structure is used to hold the font's Postscript table. Its
layout and meaning are defined in the TrueType specification, in
the 'post' section.
..................................................................
TT_Face_Properties
This structure is used to return an opened face's properties.
These are:
- The total number of glyphs in the font, given by the field
'num_Glyphs'.
- The maximum number of points for the font's glyphs. This
value is used to allocate the points tables of a glyph
container's outline. It can be fairly large (like 256 points
for Roman fonts).
- The maximum number of contours for the font's glyphs. This
value is used to allocate the contours tables of a glyph
container's outline. It can be fairly large (over 16, even in
Roman fonts).
- The maximum number of associated faces. This number is always
0 for a normal TrueType font file. However, when the face
object was opened from a TrueType collection, it contains the
maximum embedded font index used within this font collection.
- pointers to the face's header, horizontal header, OS/2, and
Postscript tables.
struct
{
int num_Glyphs; /* number of glyphs in face */
int max_Points; /* maximum number of points in a glyph */
int max_Contours;
/* maximum number of contours in a glyph */
int max_Faces; /* 0 for normal TrueType files, and the */
/* number of embedded faces minus 1 for */
/* TrueType collections */
TT_Header* header; /* TrueType header table */
TT_Horizontal_Header* horizontal;
/* TrueType horizontal header */
TT_OS2* os2; /* TrueType OS/2 table */
TT_Postscript* postscript;
/* TrueType Postscript table */
} TT_Face_Properties;
..................................................................
TT_Stream
This handle type defines a stream used to access a font file's
data. A client application should never deal with streams
directly, but some engine extensions may later need it to
support more advanced features like font embedding.
..................................................................
TT_Face
This type defines a handle used to reference a face object.
The objects are never accessed directly by a client
application; it can only obtain handles to new objects, and use
them to query specific information or processes.
See also:
TT_Open_Face(), TT_Open_Collection(), TT_Close_Face(),
TT_Get_Face_Properties(), etc.
..................................................................
TT_Instance
This type defines a handle used to reference an instance object
(also called a 'pointsize' in other type engines). An instance
is always created from a valid face object, and is destroyed
with it by the engine.
See also:
TT_New_Instance(), TT_Close_Instance(),
TT_Set_Instance_Pointsize(), TT_Set_Instance_Resolution(),
etc.
..................................................................
TT_Glyph
This type defines a handle used to reference a glyph container
object. A glyph container is an object owning tables sized to
the font's maximum profile to hold any glyph of a given font
file.
It contains an outline, some metrics, as well as some data
related to the way it should be processed by the scan-line
converter.
Note that a glyph container doesn't contain any bitmap nor
pixmap!
See also:
TT_New_Glyph(), TT_Close_Glyph(), TT_Get_Glyph_Metrics(),
TT_Get_Glyph_Outline(), TT_Get_Glyph_Bitmap(),
TT_Get_Glyph_Pixmap()
..................................................................
TT_Error
This is the type of all error codes returned by the API. Nearly
all functions return an error code, set to 0 in case of success.
A list of all error codes is given in section III.
..................................................................
This distribution comes with an extension used to support access
to a font's kerning information. The extension's types and API
are defined in the file "ftxkern.h"
----------------------------------------------------------------------------
II. Functions:
Here is a list of the core library's API.
NOTE: A function's default result is an error code of type
TT_Error; a list of error codes is given in section III
below.
Some functions return integers or other types, in which case
the result type is written with its description.
..................................................................
TT_Init_FreeType();
Initialize the engine. This call must be performed before any
other function of FreeType is invoked.
..................................................................
TT_Done_FreeType();
Finalize the engine. This calls destroys _all_ objects that
were previously created and used with the engine
..................................................................
TT_Open_Face( char* fontpathname,
TT_face* face );
This call opens a font file, located by 'fontpathname', and
returns a handle to the newly corresponding face object in the
handle '*face'.
Example:
error = TT_Open_Face( "c:\ttf\wingding.ttf", &face );
if ( error )
fprintf( stderr, "could not open face\n" );
Note:
The font file can be a TrueType collection; in this case, the
engine will always open the first embedded font found in the
file.
..................................................................
TT_Open_Collection( char* collectionpathname,
int fontIndex,
TT_Face* face );
This call opens one of the font files found in a TrueType
collection. The file is selected through the 'fontIndex'
argument.
Note that to know a collection's number of embedded fonts,
you'll have to:
1 - open the first collection font with TT_Open_Face().
2 - query the face's properties through
TT_Get_Face_Properties().
The number of embedded faces is then
'properties->max_Faces + 1'.
Example:
TT_Face face;
TT_Face_Properties properties;
error = TT_Open_Face( "c:\ttf\sample.ttc", &face );
if ( error ) { ...error .. }
/* Open first embedded collection font */
error = TT_Get_Face_Properties( face, &properties );
if ( error ) { ...error .. }
/* Get face metrics */
printf( "There are %d fonts in this collection",
properties->max_Faces + 1 );
TT_Close_Face( face );
error = TT_Open_Collection( "c:\ttf\sample.ttc", 1,
&face );
if ( error ) { ...error .. }
/* Open second font in collection */
Note: If the file isn't a collection, 'fontIndex' must be zero.
Otherwise, an error will be produced.
..................................................................
TT_Get_Face_Properties( TT_Face face,
TT_Face_Properties* properties );
Return the 'face' object's '*properties'. This structure
contains various data, like the total number of glyphs and
pointers to some mandatory TrueType tables.
(See the definition of TT_Face_Properties in section I.)
..................................................................
TT_Close_Face( TT_Face face );
Close a given 'face' object. This function will also destroy
all the face's child instances. The face's glyphs won't be
destroyed, however.
..................................................................
TT_New_Instance( TT_Face face,
TT_Instance* instance );
Create a new instance object related to the 'face' object. A
handle to the newly created instance is returned in 'instance'.
The default instance resolution is 96dpi in both vertical and
horizontal direction; the default point size is 10pt.
..................................................................
TT_Set_Instance_Resolution( TT_Instance instance,
int x_resolution,
int y_resolution );
Set the target device resolution for a given instance. The
values are expressed in dots per inch (dpi). A value of 96dpi
is typical for an SVGA display, 72dpi for a Macintosh one, and
300 to 6000dpi for printers.
..................................................................
TT_Set_Instance_PointSize( TT_Instance instance,
int pointsize );
Sets the point size for a given instance. The size is
expressed in 'points', where 1 point = 1/72 inch. The default
value is 10pt.
..................................................................
TT_Set_Instance_Transform_Flags( TT_Instance instance,
int rotated,
int stretched );
Set the transform flags for a given instance. These flags are
passed to the interpreter each time a glyph is loaded within
the instance. Their role is to notify the glyph hinting
mechanism that the resulting glyph will be transformed in a
special way. Setting one of these flags to true usually
disables hinting, though this behaviour varies with each font
file.
NOTE:
The glyph loader doesn't perform the rotation or the stretching
itself; this must be done explicitly by the client application.
Use the function TT_Apply_Outline_Matrix() for that purpose.
..................................................................
TT_Get_Instance_Metrics( TT_Instance instance,
TT_Instance_Metrics* imetrics );
This call returns a given instance's current metrics. They are
returned in the 'imetrics' structure, which contains, among
other things, the current point size, ppem, and device
resolution (horizontal and vertical).
..................................................................
TT_Done_Instance( TT_Instance instance );
Close a given instance object, destroying its associated data.
Note that this is performed automatically when a face is closed
on all its child instances. However, explicit deallocation can
help in freeing the memory used by the application earlier.
..................................................................
TT_New_Glyph( TT_Face face,
TT_Glyph* glyph );
Create a new glyph container for the glyphs of the font
described by the 'face' handle. A pointer to the container is
returned in 'glyph'. The face is said to be the glyph's
parent.
Note that a glyph isn't destroyed when the face object is
destroyed. You have to discard it manually through a call to
TT_Done_Glyph(), or automatically when closing the engine
through TT_Done_FreeType().
..................................................................
TT_Done_Glyph( TT_Glyph glyph );
Discard a glyph container. This is also done automatically for
all glyphs when closing the engine.
..................................................................
TT_Load_Glyph( TT_Instance instance,
TT_Glyph glyph,
int glyph_index,
int load_flags );
Load and process (scale and/or hint) a glyph at a given
'instance' into the 'glyph' container.
Note that 'glyph' and 'instance' must have the _same_ parent
face object, or an error message will be returned.
'glyph_index' is the glyph's index as found in the TrueType
file. It is _not_ a character code (see the charmap functions
below).
'load_flags' is an integer that specifies which operations are
to be performed on the loaded glyph. The following values/bits
are used:
TTLOAD_SCALE_GLYPH
Indicates that the glyph must be scaled to the
instance's resolution. The pixel coordinates returned
in the glyph outline structure (see below) are then
expressed in fractional pixels represented in the 26.6
fixed point floating format defined by Apple as
'F26Dot6'.
If scaling is disabled, the coordinates returned in the
outline structure are integers, also called 'FUnits' by
the TrueType specification.
TTLOAD_HINT_GLYPH
This flag is only valid when scaling is on. It informs
the loader that the glyph must be hinted (i.e.
grid-fitted for optimal display). Note that hinting
will occur only if the instance's transformations and
metrics allow it (for example, most font programs
disable hinting automatically in case of rotation or
stretching).
NOTE:
You can also use the constant TTLOAD_DEFAULT, which is simply
the union of TTLOAD_SCALE_GLYPH and TTLOAD_HINT_GLYPH for
most 'typical' loads.
..................................................................
TT_Get_Glyph_Outline( TT_Glyph glyph,
TT_Glyph_Outline* outline );
This call returns the glyph's 'outline'. This is a simple
structure which contains pointers to the data used to describe
an outline to the rasterizer. See the definition of
TT_Glyph_Outline() in section I.
..................................................................
TT_Get_Glyph_Metrics( TT_Glyph glyph,
TT_Glyph_Metrics* metrics );
Extract the glyph's metrics and copy them to the '*metrics'
structure. Its format is described in section I.
When the glyph has been loaded without scaling, the values are
expressed in FUnits (integers relative to the original font
grid called the EM Square).
When the glyph has been loaded _with_ scaling, which is the
default, the values are expressed in fractional pixels in the
26.6 fixed point float format called F26Dot6 (where 1 unit =
1/64th of a pixel).
..................................................................
TT_Get_Glyph_Bitmap( TT_Glyph glyph,
TT_Raster_Map* bitmap,
TT_F26Dot6 x_offset,
TT_F26Dot6 y_offset );
This call converts the vectorial glyph representation contained
in the object handled by 'glyph' into a bitmap.
The target bitmap is described by the 'bitmap' pointer.
Clipping will be done if necessary. You can also specify an
offset to be applied before the scan-line conversion;
'x_offset' and 'y_offset' must be expressed in fractional
pixels (where 1 unit = 1/64th pixel).
NOTE1:
Choosing non integer pixel offsets, i.e., values of
'x_offset' and 'y_offset' that are not multiples of 64, will
ruin the hinting performed by the interpreter, and result in
bad rendering at small sizes.
NOTE2:
The glyph's point coordinates must be scaled before calling
this function. Never call this function with a glyph that
were loaded with no scaling!
..................................................................
TT_Get_Glyph_Pixmap( TT_Glyph glyph,
TT_Raster_Map* pixmap,
TT_F26Dot6 x_offset,
TT_F26Dot6 y_offset );
This call converts the vectorial glyph representation contained
in the object handled by 'glyph' into a pixmap (i.e., an
8-bit/pixel map). The result is an anti-aliased version of the
glyph (a.k.a. font-smoothing).
The target pixmap is described by the 'pixmap' pointer. Note
that its width _must_ be a multiple of 4. For a pixmap
definition and description, see Section I.
As with TT_Get_Glyph_Bitmap(), you can specify offsets to be
applied before the rendering ('x_offset' and 'y_offset' must be
expressed in fractional pixel coordinates).
NOTE1:
You don't need to supply a temporary bitmap for the
anti-aliaser. The rasterizer uses its own scheme to optimize
memory uses.
NOTE2:
The glyph's point coordinates must be scaled before calling
this function. This means that you should never call it with
a glyph which has been loaded without scaling!
..................................................................
TT_Apply_Outline_Matrix( TT_Glyph_Outline* outline,
TT_Matrix* matrix );
Apply a simple transformation matrix on a given outline. This
will multiply each point coordinate vector by a 2x2 matrix,
which coefficients are written in the 16.16 fixed float format.
Rotation can be performed with this function.
NOTE:
This function takes an outline, and not a glyph handle, as a
parameter. This 'feature' lets you apply transformations on
your own copies of glyphs.
..................................................................
TT_Apply_Outline_Translation( TT_Glyph_Outline* outline,
TT_F26Dot6 x_offset,
TT_F26Dot6 y_offset );
Apply a simple translation on a given outline.
NOTE:
This function takes an outline, and not a glyph handle, as a
parameter. This 'feature' lets you apply translation to your
own copies of glyphs.
..................................................................
int TT_Get_CharMap_Count( TT_Face face );
^^^
Return the number of character mappings present in the TrueType
file described by the 'face' handle. Returns zero if there are
no mappings, and -1 when the handle is invalid.
..................................................................
TT_Get_CharMap_ID( TT_Face face,
int charmapIndex,
short* platformID,
short* encodingID );
Return the platform ID and platform-specific encoding ID for
the charmap numbered 'charmapIndex' in the 'face' object. The
total number of character mapping tables is returned by the
TT_Get_CharMap_Count() function described above.
..................................................................
TT_Get_CharMap( TT_Face face,
int charmapIndex,
TT_CharMap* charMap );
Return a handle for the character map number 'charmapIndex' of
'face'. The handle is placed in '*charMap' and can be used
later for fast lookup with the TT_Char_Index() API.
Charmap objects are automatically destroyed when their face
object is destroyed.
..................................................................
int TT_Char_Index( TT_CharMap charMap,
^^^ int charCode );
Apply a charMap to translate a charCode into a glyph index that
can be used to load and address a glyph in the TrueType file.
The charmap handle can be obtained with TT_Get_CharMap().
..................................................................
int TT_Get_Name_Count( TT_Face face );
^^^
Returns the number of name strings found in a face's name
table. This function will return zero when there are no name
strings in the font file, and -1 if the face handle is invalid.
..................................................................
TT_Get_Name_ID( TT_Face face,
int nameIndex,
short* platformID,
short* encodingID,
short* languageID,
short* nameID );
Return the ID of a given name string, indexed by the number
'nameIndex' in a given face. The name index ranges from 0 to
the value returned by TT_Get_Name_Count() minus one.
Each string has a platformID, encodingID, languageID and
nameID, as defined by the TT specification.
The platformID is typically in the 0..3 range. Some font files
have invalid name table entries; these can be detected from
their platformID which is over 3.
..................................................................
TT_Get_Name_String( TT_Face face,
int nameIndex,
char** stringPtr,
int* length );
Return a name string's address and length. Note that an
invalid name table entry, detected by a platformID > 3, always
returns NULL for 'stringPtr' and a zero length.
Note: the string belongs to the face object, and should not be
written to or freed by the client application.
..................................................................
TT_Get_Kerning_Directory( TT_Face face,
TT_Kerning* directory );
Queries the kerning directory found in a face object. If no
kerning table is found in the TrueType file, the error
TT_Err_Table_Is_Missing will be returned.
You can access the subtables through the pointers of the
directory. However, by default, the directory is only loaded
when a face object is created. You must load the subtables
that interest you with a call to TT_Load_Kerning_Table().
The layout of all kerning structures is defined in the file
"lib/extend/apikern.h". Both formats (0 and 2) are exposed by
this API.
..................................................................
TT_Load_Kerning_Table( TT_Face face,
int kern_index );
Load the kerning subtable number 'kern_index' into memory. The
subtable can be accessed through the pointers provided by the
kerning directory, obtained from a call to
TT_Get_Kerning_Directory().
Note that the interpretation of the kerning data is left to the
client application. Read the TrueType specification for more
information on kerning encoding.
III. Error Messages:
Most functions return an error code, typed to TT_Error. A return
value of zero indicates no error. The error values are defined in
the file 'freetype.h'.
Error Unprefixed Error
Code Macro Name Description
------------------------------------------------------------------
0x0000 Ok Successful function call.
Always 0!
----------------- high-level API error codes ---------------------
The following error codes are returned by the high-level API to
indicate an invalid client request.
0x0001 Invalid_Face_Handle An invalid face object handle was
passed to an API function.
0x0002 Invalid_Instance_Handle An invalid instance object handle
was passed to an API function.
0x0003 Invalid_Glyph_Handle An invalid glyph container handle
was passed to an API function.
0x0004 Invalid_CharMap_Handle An invalid charmap handle was
passed to an API function.
0x0005 Invalid_Result_Address An output parameter (a result)
was given a NULL address in an
API call.
0x0006 Invalid_Glyph_Index An invalid glyph index was passed
to one API function
0x0007 Invalid_Argument An invalid argument was passed to
one API function. Usually, this
means a simple out-of-bounds
error.
0x0008 Could_Not_Open_File The pathname passed doesn't point
to an existing or accessible
file.
0x0009 File_Is_Not_Collection Returned by TT_Open_Collection
when trying to open a file which
isn't a collection.
0x000A Table_Missing A mandatory TrueType table is
missing from the font file.
Denotes a broken font file.
0x000B Invalid_Horiz_Metrics The font's HMTX table is broken.
Denotes a broken font.
0x000C Invalid_CharMap_Format A font's charmap entry has an
invalid format. Some other
entries may be valid though.
0x0010 Invalid_File_Format The file isn't a TrueType font or
collection
----------------- memory component error codes -------------------
0x0100 Out_Of_Memory An operation couldn't be
performed due to memory
exhaustion.
----------------- file component error codes ---------------------
0x0200 Invalid_File_Offset Trying to seek to an invalid
portion of the font file.
Denotes a broken file.
0x0201 Invalid_File_Read Trying to read an invalid portion
of the font file. Denotes a
broken file.
0x0202 Invalid_Frame_Access Trying to frame an invalid
portion of the font file.
Denotes a broken file.
----------------- glyph loader error codes -----------------------
These errors are produced by the glyph loader. They denote an
invalid glyph record within the font file.
0x0300 Too_Many_Points The glyph has too many points to
be valid for its font file.
0x0301 Too_Many_Contours The glyph has too many contours
to be valid for its font file.
0x0302 Invalid_Composite_Glyph A composite glyph's description
is broken.
0x0303 Too_Many_Ins The glyph has too many
instructions to be valid for its
font file.
----------------- byte-code interpreter error codes --------------
These error codes are produced by the TrueType byte-code
interpreter. They usually indicate a broken font file or a broken
glyph within a font.
0x0400 Invalid_Opcode Found an invalid opcode in a
TrueType byte-code stream.
0x0401 Too_Few_Arguments An opcode was invoked with too few
arguments on the stack.
0x0402 Stack_Overflow The interpreter's stack has been
filled up and operations can't
continue.
0x0403 Code_Overflow The byte-code stream runs out of
its valid bounds.
0x0404 Bad_Argument A function received an invalid
argument.
0x0405 Divide_By_Zero A division by 0 operation was
queried by the interpreter program.
0x0406 Storage_Overflow The program tried to access data
outside of its storage area.
0x0407 Cvt_Overflow The program tried to access data
outside of its control value table.
0x0408 Invalid_Reference The program tried to reference an
invalid point, zone or contour.
0x0409 Invalid_Distance The program tried to use an invalid
distance.
0x040A Interpolate_Twilight The program tried to interpolate
twilight points.
0x040B Debug_Opcode The now invalid 'debug' opcode was
found in the byte-code stream.
0x040C ENDF_In_Exec_Stream A misplaced ENDF was encountered in
the byte-code stream.
0x040D Out_Of_CodeRanges The program tried to allocate too
much code ranges (this is really an
engine internal error that should
never happen).
0x040E Nested_DEFS Nested function definitions
encountered.
0x040F Invalid_CodeRange The program tried to access an
invalid code range.
----------------- internal failure error codes -------------------
These error codes are produced if an incoherent library state has
been detected. All of these reflect a severe bug in the engine
(or a severe memory corruption due to massive overwrites by your
application into the library's data)!
If you do encounter a font that makes one of the test programs
produce such an error, please report it!
0x0500 Nested_Frame_Access
0x0501 Invalid_Cache_List
0x0502 Could_Not_Find_Context
0x0503 Unlisted_Object
----------------- scan-line converter error codes ----------------
These error codes are produced by the raster component. They
indicate that an outline structure was incoherently set up, or
that you're trying to render a horribly complex glyph.
They should be _extremely_ rare, however.
0x0600 Raster_Pool_Overflow Render pool overflow. This should
never happen in this release.
0x0601 Raster_Negative_Height
A negative height was produced.
0x0602 Raster_Invalid_Value The outline data wasn't set
properly. Check that:
points >= endContours[contours]
0x0603 Raster_Not_Initialized
You did not call TT_Init_FreeType!
----------------- engine extensions error codes ------------------
The engine's extensions also provide their own error codes, within
their own group:
0x0A00 Invalid_Kerning_Table_Format
A kerning subtable format was found
invalid in this font.
--- end of apiref.txt ---