diff options
Diffstat (limited to 'Build/source/libs/freetype/freetype-1.5/docs/apiref.txt')
-rw-r--r-- | Build/source/libs/freetype/freetype-1.5/docs/apiref.txt | 1918 |
1 files changed, 1918 insertions, 0 deletions
diff --git a/Build/source/libs/freetype/freetype-1.5/docs/apiref.txt b/Build/source/libs/freetype/freetype-1.5/docs/apiref.txt new file mode 100644 index 00000000000..b40e66d93d1 --- /dev/null +++ b/Build/source/libs/freetype/freetype-1.5/docs/apiref.txt @@ -0,0 +1,1918 @@ + 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 + conflict of names with other packages at link time. + + The reference for extensions of the FreeType library can be found + in the file `apirefx.txt'. + + + +-------------------------------------------------------------------- +-------------------------------------------------------------------- + + + +I. Types +======== + + Here is the list of all types defined in the core FreeType API. + Their exact definition can be found in the file `freetype.h' which + should be included in every client application. + + + TT_Bool + + Can be either non-zero (true) or zero (false). + + .................................................................. + + TT_Fixed + + A signed 16.16 fixed float integer type used to specify + transform coefficients and other important data. + + .................................................................. + + TT_FWord + + A signed 16-bit type used to express a distance measured in the + font's original EM units. These are also called `FUnits' in the + TrueType specification. + + .................................................................. + + TT_UFWord + + An unsigned 16-bit type. + + .................................................................. + + TT_String + TT_Char + TT_Byte + + These types represent various 8-bit integer values (for strings, + signed, and unsigned values, respectively). + + .................................................................. + + TT_Short + TT_UShort + TT_Long + TT_ULong + + These four types are aliases for 16-bit integer (signed and + unsigned) and 32-bit integer types (signed and unsigned). + + .................................................................. + + TT_Int + + A signed type, either 16-bit or 32-bit, whichever is the most + efficient for the target platform. + + .................................................................. + + TT_F2Dot14 + + A 2.14 fixed float integer type used for unary vectors and some + scaling coefficients. Its layout is: + + s : 1 -- sign bit + m : 1 -- mantissa bit + f : 14 -- unsigned fractional value + + where `s:m' denotes a 2-bit signed integer value to which the + positive fractional part `f' should always be added. + + .................................................................. + + TT_F26Dot6 + + A 26.6 fixed float integer format used to define fractional + pixel coordinates. Here, 1 unit = 1/64 pixel. + + .................................................................. + + TT_Pos + + This type is used to store point coordinates, either in + fractional pixels (26.6 fixed floats) or in EM units (simple + integers). + + The interpretation of the value depends on the context. For + example, all distances relative to a scaled glyph are expressed + in fractional pixels (including bearings, advances, etc). + However, the same distances are measured in notional font units + when the glyph has been loaded unscaled. + + .................................................................. + + 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_BBox + + A simple type to hold a glyph's bounding box. Used by the + TT_Get_Outline_BBox() API. + + struct + { + TT_Pos xMin, yMin; + TT_Pos xMax, yMax; + } + + .................................................................. + + TT_Outline + + Outlines are represented from now on as a class in itself, with + their own API. + + This structure is used to describe a vectorial glyph + representation to the rasterizer. It consists of several fields + as described below. Note however that: + + ***** THIS STRUCTURE MAY CHANGE IN THE FUTURE. We thus + ***** encourage you to use the outlines APIs described below to + ***** process your outlines i.e., create/copy/translate/ + ***** transform them, as well as rendering bitmaps and pixmaps. + + ***** THE STRUCTURE CHANGED BETWEEN 1.0 and 1.1! + + Now that you have been warned, the fields are: + + - An array of points: + + The `n_points' field gives the number of points in the + outline, while their coordinates are found in the single + vector array called `points'. The `flags' array holds a flag + for each point indicating its type. + + Currently, only the first bit (bit 0, the least significant + bit) of each byte is meaningful to the rasterizer. If set, it + indicates that the point is _on_ the curve. If not set, the + point is said to be _off_ the curve. It is 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 end-point indices: + + The `n_contours' field gives the number of contours, while the + `contours' array holds the indices of each contour's last + point. Note that the first contour always begins at point 0. + + Hence, `contours[0]' holds the index of the last point of the + first contour. The second contour starts at point number + `contours[0]+1', and ends at point number `contours[1]'. + + ** IMPORTANT NOTE: ** + ********************* + + The last table entry _must_ always give the total number of + points used to draw the contours, i.e.: + + contours[n_contours - 1] == n_points + + If this value is greater than `n_points' when calling the + scan-line converter, the component will immediately return + an error (TT_Err_Too_Many_Points). If the value is smaller, + only the points contained in the described contours will be + used in the conversion process. + + - An owner field: + + This flag should **NEVER** be changed by the user. It + indicates whether the pointer fields own the arrays they refer + to (when the flag is set), or if they simply alias them (flag + unset). + + - A high precision flag: + + If this boolean is set (i.e. not zero), the scan-line + converter uses a higher precision to compute segment and + Bezier coordinates (more precisely, it uses 1/1024 precision, + instead of the normal 1/64). This is of course slower but can + be important for glyphs rendered at small sizes. + + - A second pass flag: + + If this boolean is set, the scan-line converter performs a + second sweep on the bitmap/pixmap to detect vertical drop-out. + Only horizontal drop-outs are detected in the first pass. + This is slower, but important for glyphs rendered at small + sizes. + + - A dropout mode: + + Used to specify which method applies 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 more recent modes 4 and 5 introduced in the newest + TrueType specification (Version 1.66) are fully supported. + + An invalid value (i.e., not 0, 1, 2, 4, or 5) is taken as no + dropout control (equivalent to mode 0). + + NOTE 1: + + The outline returned by TT_Get_Glyph_Outline() only alias the + data that is part of a glyph container (see below). However, + it is possible to create and process your own outlines with + the new API functions TT_New_Outline(), TT_Done_Outline(), + TT_Copy_Outline(), TT_Translate_Outline(), etc. + + TT_Done_Outline() will only discard an outline's array if it + owns them. + + NOTE 2: + + The outlines created by TT_New_Outline() are _not_ released by + the engine while executing TT_Done_FreeType(), they must be + explicitly discarded by the user who has created them! + + NOTE 3: + + The glyph loader sets the fields `high_precision', + `dropout_mode', and `second_pass' automatically. + + NOTE 4: + + This structure was called TT_Glyph_Outline in beta versions of + FreeType. + + .................................................................. + + TT_Glyph_Metrics + + A structure used to return simple glyph metrics, applicable for + either horizontal or vertical layout. The values are expressed + in fractional pixels (26.6 format) if scaling was active, + otherwise in FUnits. + + The main idea was to accomodate vertical text layouts by + eradicating the two explicit `leftSideBearing' and + `advanceWidth' names. + + The interpretation of the fields varies with the text layout: + + bearingX: Also known as the `left side bearing'. In + horizontal metrics, this value gives the horizontal + distance from the pen position to the glyph's bbox + xmin, otherwise it specifies the vertical distance. + + bearingY: Also known as the `top side bearing', this is the + vertical distance from the baseline to the glyph's + bbox ymax in horizontal metrics, otherwise the + horizontal distance. + + struct + { + TT_BBox bbox; /* the glyph's bbox */ + + TT_Pos bearingX; /* left-side bearing */ + TT_Pos bearingY; /* top-side bearing */ + + TT_Pos advance; /* advance width or height */ + }; + + ** IMPORTANT NOTE ** + + Because of the conventions inherent to the TrueType engine, + the outlines generated at glyph-load time are all placed so + that the pen is at position (0,0). This means that it is not + necessary to increase the pen position by `bearingX' and/or + `bearingY' before writing a glyph. Text output can be + performed with simple lines such as: + + for (glyphs in text) + { + TT_Load_Glyph( ... ); + TT_Get_Glyph_Outline( glyph, &outline ); + TT_Translate_Outline( outline, + cur_pos_x * 64, cur_pos_y * 64 ); + + TT_Get_Outline_Bitmap( outline, bitmap ); + /* blit bitmap to surface */ + + cur_pos_x += (metrics.advance + 32) / 64 + } + + For an example see the file `test/ftstring.c'. + + NOTE 2: + + This structure has changed from the beta version of FreeType. + + NOTE 3: + + FreeType only implements TT_Get_Glyph_Metrics() to return + horizontal metrics. For extracting vertical metrics you + should use TT_Get_Glyph_Big_Metrics(). + + .................................................................. + + TT_Big_Glyph_Metrics + + This structure is used to return the metrics of a glyph for both + horizontal and vertical layout. + + The `linearXXX' fields represent unhinted scaled metrics values. + They can be useful for applications which need to compute device + independent placement of glyphs. Applying these metrics to + hinted glyphs will in most cases ruin the grid fitting performed + by the bytecode interpreter. + + struct + { + TT_BBox bbox; /* the glyph's bounding box */ + + TT_Pos horiBearingX; /* horizontal left-side bearing */ + TT_Pos horiBearingY; /* horizontal top-side bearing */ + + TT_Pos vertBearingX; /* vertical left-side bearing */ + TT_Pos vertBearingY; /* vertical top-side bearing */ + + TT_Pos horiAdvance; /* horizontal advance */ + TT_Pos vertAdvance; /* vertical advance */ + + TT_Pos linearHoriBearingX; /* lin. scaled hor. lsb. */ + TT_Pos linearHoriAdvance; /* lin. scaled hor. adv. */ + + TT_Pos linearVertBearingY; /* lin. scaled vert. tsb. */ + TT_Pos linearVertAdvance; /* lin. scaled vert. adv. */ + } + + .................................................................. + + TT_Instance_Metrics + + A structure used to return instance (point size) metrics. + + struct + { + int pointSize; + /* point size in points (1 point = 1/72 inch) */ + + TT_UShort x_ppem; /* horizontal pixels per EM square */ + TT_UShort y_ppem; /* vertical pixels per EM square */ + + TT_Fixed x_scale; /* 16.16 scale for EM -> frac pixels */ + TT_Fixed y_scale; /* 16.16 scale for EM -> frac pixels */ + + TT_UShort x_resolution; /* device hor. res. in dpi */ + TT_UShort y_resolution; /* device vert. res. in dpi */ + }; + + The fields `x_scale' and `y_scale' can be used by clients to + convert notional units (in funits) in fractional pixels (in 26.6 + fixed float format), e.g.: + + TT_FUnit em_distance; + TT_F26Dot6 frac_distance; + TT_Fixed x_scale; + + frac_distance = (em_distance * x_scale) / 0x10000; + + .................................................................. + + TT_Raster_Map + + This structure is used to specify a target bitmap (or pixmap) + for 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 for + pixmaps! + + Usually, its value should be `(width+7)/8' for bitmaps, and + `(width+3) & -4' for pixmaps. + + - The `flow' field gives the map's vertical orientation. + + 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', otherwise the flow is going + `up', and the value is `TT_Flow_Up'. + + To cite 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 1: + + 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; + + NOTE 2: + + TT_Get_Outline_Bitmap() resp. TT_Get_Glyph_Bitmap() are used + to render bitmaps into a TT_Raster_Map. The convention used + is 0 for the background, and 1 for the foreground. The glyph + is simply `or-ed' to the bitmap buffer. + + NOTE 3: + + TT_Get_Outline_Pixmap() and TT_Get_Glyph_Pixmap() are used to + render pixmaps into a TT_Raster_Map. Note that pixels are + drawn in spans of 4 successive bytes, only if needed. This + means that you must ALWAYS pass a clean pixmap buffer to these + functions. Otherwise, garbage could accumulate! + + .................................................................. + + 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. + + Note that since FreeType 1.3, we support fonts without an OS/2 + table (mainly old but popular Mac fonts). In this case, the + table's `version' field will be set to 0xFFFF by the loader, and + all other fields will be zeroed. + + .................................................................. + + 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_Hdmx + + This structure is used to hold the font's horizontal device + metrics. Its layout and meaning are defined in the in the + `hdmx' section of the TrueType specification. + + .................................................................. + + 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 number of character mappings and name records within the + font. These values can still be retrieved through the APIs + TT_Get_CharMapCount() and TT_Get_Num_Names(), though these + have been _seriously_ deprecated. + + - The number of associated faces. This number is always 1 for a + normal TrueType font file. However, when the face object was + opened from a TrueType collection, it contains the total + number of embedded fonts. + + - Pointers to the face's header and horizontal header, the OS/2 + and PostScript tables, and the horizontal device metrics. + + struct + { + TT_UShort num_Glyphs; /* number of glyphs in face */ + TT_UShort max_Points; /* max. numb. of points in a glyph */ + TT_Short max_Contours; + /* maximum number of contours in a glyph */ + + TT_ULong num_Faces; + /* 1 for normal TrueType files resp. */ + /* the number of embedded faces for TT */ + /* collections */ + + TT_Header* header; /* TrueType header table */ + TT_Horizontal_Header* horizontal; + /* TrueType horizontal header */ + TT_Vertical_Header* vertical; + /* TrueType vertical header */ + TT_OS2* os2; /* TrueType OS/2 table */ + TT_Postscript* postscript; + /* TrueType PostScript table */ + TT_Hdmx* hdmx; /* TrueType hdmx table */ + + } TT_Face_Properties; + + - Note that the `vertical' field is set to NULL if the font file + does not contain any vertical metrics. + + - Note also that since version 1.3 we support font files without + an OS/2 table. See the definition of TT_OS2 for more details. + + .................................................................. + + 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 need it to support more + advanced features like sbit support. + + .................................................................. + + 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_Done_Instance(), + TT_Set_Instance_CharSizes(), TT_Set_Instance_Resolutions(), + 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 or + pixmap! + + See also: + + TT_New_Glyph(), TT_Done_Glyph(), TT_Load_Glyph(), + TT_Get_Glyph_Metrics(), TT_Get_Glyph_Big_Metrics(), + TT_Get_Glyph_Outline(), TT_Get_Glyph_Bitmap(), + TT_Get_Glyph_Pixmap() + + .................................................................. + + TT_CharMap + + This type defines a handle used to reference a charMap object. + A charMap is an object owning the tables needed to perform the + mapping from characters code to glyphs numbers. A charMap is + always created from a valid face object, and is destroyed with + it by the engine. + + See also: + + TT_Get_CharMap(), TT_Char_Index(). + + .................................................................. + + 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. + + .................................................................. + + TT_Engine + + For the sake of re-entrancy it is possible to distinguish + `engines' to separate several running instances of the library. + For example, it could be used as a DLL shared by several client + applications. + + Each client program must begin by creating its own engine, + through a call to TT_Init_FreeType(). The engine must also be + passed as the first argument of the following functions: + + TT_Open_Face() + TT_Open_Collection() + TT_Set_Raster_Gray_Palette() + TT_Get_Outline_Bitmap() + TT_Get_Outline_Pixmap() + TT_Done_FreeType() + + Note that any FreeType object pertains to one single engine + (there is no sharing). Closing an engine with + TT_Done_FreeType() will delete all the objects that have been + allocated within its instance. + + + +-------------------------------------------------------------------- +-------------------------------------------------------------------- + + + +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 other types, in which case the result type + is documented with its description. + + .................................................................. + + TT_FreeType_Version( int* major, int* minor ); + + Queries the major and minor version of the library. + + .................................................................. + + TT_Init_FreeType( TT_Engine* engine ); + + Creates and initializes a new engine. Returns a handle to the + engine in the `*engine' variable. + + This call must be performed before any other function of + FreeType is invoked. The engine handle must be passed to the + following functions: + + TT_Open_Face() + TT_Open_Collection() + TT_Set_Raster_Gray_Palette() + TT_Done_FreeType() + + .................................................................. + + TT_Done_FreeType( TT_Engine engine ); + + Finalizes and destroys an engine. This call destroys _all_ + objects that were previously created and used with the engine. + + .................................................................. + + TT_Open_Face( TT_Engine engine, + TT_Text* 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'. The object is part of the `engine' instance. + + Example: + + error = TT_Open_Face( engine, "c:\ttf\wingding.ttf", &face ); + if ( error ) + fprintf( stderr, "Could not open face.\n" ); + + NOTE 1: + + The font file can be a TrueType collection; in this case, the + engine will always open the first embedded font found in the + file. + + NOTE 2: + + `TT_Text' is usually defined as `char' by a typedef + declaration. It may be a 16-bit quantity (or even wider) for + some operating systems; see ttconfig.h for details. + + .................................................................. + + TT_Open_Collection( TT_Engine engine, + TT_Text* collectionPathName, + TT_ULong fontIndex, + TT_Face* face ); + + This call opens one of the fonts found in a TrueType collection. + The font is selected through the `fontIndex' argument. The + first font has index 0. + + Note that to know a collection's number of embedded fonts, + you will 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->num_Faces'. + + Example: + + TT_Face face; + TT_Face_Properties properties; + + + /* Open first embedded collection font */ + error = TT_Open_Face( engine, "c:\ttf\sample.ttc", &face ); + if ( error ) { ...error... } + + /* Get face properties */ + error = TT_Get_Face_Properties( face, &properties ); + if ( error ) { ...error... } + + printf( "There are %d fonts in this collection.\n", + properties->num_Faces ); + + TT_Close_Face( face ); + + /* Open second font in collection */ + error = TT_Open_Collection( engine, "c:\ttf\sample.ttc", 1, + &face ); + if ( error ) { ...error... } + + NOTE 1: + + If the file isn't a collection, `fontIndex' must be zero. + Otherwise, an error will be returned. + + NOTE 2: + + `TT_Text' is usually defined as `char' by a typedef + declaration. It may be a 16-bit quantity (or even wider) for + some operating systems; see ttconfig.h for details. + + .................................................................. + + TT_Set_Raster_Gray_Palette( TT_Engine engine, + TT_Byte* palette ); + + Sets the gray-level palette for an engine. The palette is used + to create pixmaps through the TT_Get_Glyph_Pixmap() function. + It is an array of five bytes, following the convention: + + palette[0] = background (white) + palette[1] = light + palette[2] = medium + palette[3] = dark + palette[4] = foreground (black) + + .................................................................. + + TT_Get_Face_Properties( TT_Face face, + TT_Face_Properties* properties ); + + Returns 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 for more + details. + + Note that since version 1.3, FreeType supports fonts with no + OS/2 table, like many old Mac fonts. See the definition of + TT_OS2 for more details. + + .................................................................. + + TT_Get_Face_Metrics( TT_Face face, + TT_UShort firstGlyph, + TT_UShort lastGlyph, + TT_Short* leftBearings, + TT_UShort* widths, + TT_Short* topBearings, + TT_UShort* heights ); + + This function returns the original horizontal AND vertical + metrics for a given face `face' and a given glyph range specified + by `firstGlyph' and `lastGlyph' as found in the `hmtx' and `vmtx' + tables. These are the glyphs' left-side bearings (in + `leftBearings') and horizontal advance widths (in `widths'), as + well as top-side bearings (in `topBearings') and vertical advance + heights (in `heights'). If you aren't interested in any of the + metrics fields, simply set its value to NULL. + + All are expressed in font units, a.k.a. EM units. + + The metrics arrays must be allocated by the client program. + + IMPORTANT NOTE: + + As vertical metrics are optional in a TrueType font, this + function will return an error (TT_Err_No_Vertical_Data) if this + function is called on such a face with non-NULL `topBearings' + or `heights' arguments. + + If a font has no vertical data, the `vertical' field in its + properties structure is set to NULL. + + .................................................................. + + TT_Set_Face_Pointer( TT_Face face, + void* data ); + + For convenience purposes, each face object has a `generic' + pointer which value is unused by the engine, but that can be set + freely by client applications through this function. + + Do what you want with it; it is here to give you a chance to + link a face object to your own structures and data. + + .................................................................. + + void* TT_Get_Face_Pointer( TT_Face face ); + ^^^^ + Returns a face object's generic pointer. See + TT_Set_Face_Pointer() above. + + .................................................................. + + TT_Flush_Face( TT_Face face ); + + Closes a given face object's file handler or descriptor. This + is useful to save system resources if your application opens + dozens or even hundreds of fonts. The face object is still + valid, and its file will be re-opened automatically on the next + request which requires disk access. + + .................................................................. + + TT_Close_Face( TT_Face face ); + + Closes a given `face' object. This function will also destroy + all the face's child instances. The face's glyphs will not be + destroyed, however. + + .................................................................. + + TT_New_Instance( TT_Face face, + TT_Instance* instance ); + + Creates 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_Resolutions( TT_Instance instance, + TT_UShort xResolution, + TT_UShort yResolution ); + + Sets the target device resolutions 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. Default value (before a call to + this function) is 96dpi. + + .................................................................. + + TT_Set_Instance_CharSize( TT_Instance instance, + TT_F26Dot6 charsize ); + + Sets the point size for a given instance. The size is expressed + in fractional (26.6) `points', where 1 point = 1/72 inch. The + default value is 10pt (before a call to this function). + + For example, to use a char size of 12pt, call the function with: + + TT_Set_Instance_CharSize( instance, 12 * 64 ); + + Fractional point sizes are thus possible. + + Call this function after TT_Set_Instance_Resolutions(). + + .................................................................. + + TT_Set_Instance_CharSizes( TT_Instance instance, + TT_F26Dot6 charWidth, + TT_F26Dot6 charHeight ); + + Sets an instance's glyph width and height independently in + fractional (26.6) points. Similar to Set_Instance_CharSize() + with the exception that the horizontal and vertical glyph + dimensions can differ. + + Call this function after TT_Set_Instance_Resolutions(). + + .................................................................. + + TT_Set_Instance_PixelSizes( TT_Instance instance, + TT_UShort pixelWidth, + TT_UShort pixelHeight, + TT_F26Dot6 pointSize ); + + This function can be used to specify directly the pixel sizes + and point size of a given instance, independently of device + resolutions. This is not the recommended way to do it, but can + be used for debugging or simplicity in some special cases. + + Note that you _must_ provide a point size! + + Call this function after TT_Set_Instance_Resolutions(). + + .................................................................. + + TT_Set_Instance_Transform_Flags( TT_Instance instance, + TT_Bool rotated, + TT_Bool stretched ); + + Sets 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 automatically; this must be done explicitly by the + client application. Use the function TT_Transform_Outline() + 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_Set_Instance_Pointer( TT_Instance instance, + void* data ); + + For convenience purposes, each instance object has a `generic' + pointer which value is unused by the engine, but that can be set + freely by client applications through this function. + + Do what you want with it, it is here to give you a chance to + link a face object to your own structures and data. + + .................................................................. + + void* TT_Get_Instance_Pointer( TT_Instance instance ) + ^^^^ + + This function returns an instance object's generic pointer set + through TT_Set_Instance_Pointer(). + + .................................................................. + + TT_Done_Instance( TT_Instance instance ); + + Closes 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 ); + + Creates 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: + + A glyph is destroyed with its parent face object. However, it + is possible to delete it explicitly with TT_Done_Glyph(). + + .................................................................. + + TT_Done_Glyph( TT_Glyph glyph ); + + Discards a glyph container. This is also done automatically for + all glyphs when closing its parent face object. + + .................................................................. + + TT_Load_Glyph( TT_Instance instance, + TT_Glyph glyph, + TT_UShort glyphIndex, + TT_UShort loadFlags ); + + Loads and processes (scales and/or hints) a glyph at a given + `instance' into the `glyph' container. + + Note that `glyph' and `instance' must have the _same_ parent + face object, otherwise an error message will be returned. + + `glyph_index' is the glyph's index as found in the TrueType + font. 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 (F26Dot6). + + If scaling is disabled, the coordinates returned in the + outline structure are integer font units, 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). + + When loading a hinted glyph, the metrics computed by the + loader, including the bounding box, will also be + grid-fitted. + + TTLOAD_PEDANTIC + + Starting with FreeType version 1.3, the bytecode interpreter + can ignore even more errors (like out-of-bound array + accesses). Using this flag it is possible to force TrueType + compliant interpretation of font programs. + + TTLOAD_IGNORE_GLOBAL_ADVANCE_WIDTH + + A flag to handle monospaced fonts with an incorrect global + advance width in the `hhea' table. If set, the actual + advance width value of a particular glyph will be used; if + unset, the advance widths for all glyphs are forced to be + equal to the global value. + + + 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_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_Outline in section I. + + .................................................................. + + TT_Get_Glyph_Metrics( TT_Glyph glyph, + TT_Glyph_Metrics* metrics ); + + Extracts the glyph's metrics and copies them to the `*metrics' + structure. Its format is described in section I. + + If the glyph has been loaded without scaling, the values are + expressed in FUnits (integers relative to the original font grid + called the EM Square). + + If the glyph has been loaded _with_ scaling, which is the + default, the values are expressed in fractional pixels in 26.6 + fixed point float format (F26Dot6; 1 unit = 1/64th of a pixel). + + If the glyph has been loaded with hinting, the metrics are also + grid-fitted, including the bounding box. To get the un-fitted + bbox, call TT_Get_Outline_BBox() on the glyph's outline. + + NOTE: + + BBox fitting occurs according to the following scheme: + + #define FLOOR( x ) ( (x) & -64 ) + #define CEILING( x ) ( ( (x) + 63 ) & -64 ) + + xMin = FLOOR( xMin ); + yMin = FLOOR( yMin ); + xMax = CEILING( xMax ); + yMax = CEILING( yMax ); + + This means that the outline's width and height in pixels can be + computed simply from the fitted bbox, namely + + (xMax-xMin)/64 and (yMax-yMin)/64 + + .................................................................. + + TT_Get_Glyph_Big_Metrics( TT_Glyph glyph, + TT_Big_Glyph_Metrics* metrics ); + + Extracts the glyph's big metrics and copies them to the + `*metrics' structure. Its format is described in section I. + + If the glyph has been loaded without scaling, the values are + expressed in FUnits (integers relative to the original font grid + called the EM Square). + + If the glyph has been loaded _with_ scaling, which is the + default, the values are expressed in fractional pixels in 26.6 + fixed point float format (F26Dot6; 1 unit = 1/64th of a pixel). + + If the glyph has been loaded with hinting, the metrics are also + grid-fitted, including the bounding box. To get the un-fitted + bbox, just call TT_Get_Outline_BBox() on the glyph's outline. + + NOTE 1: + + BBox fitting occurs according to the following scheme: + + #define FLOOR( x ) ( (x) & -64 ) + #define CEILING( x ) ( ( (x) + 63 ) & -64 ) + + xMin = FLOOR( xMin ); + yMin = FLOOR( yMin ); + xMax = CEILING( xMax ); + yMax = CEILING( yMax ); + + This means that the outline's width and height in pixels can be + computed simply from the fitted bounding box, namely + + (xMax-xMin)/64 and (yMax-yMin)/64 + + NOTE 2: + + The vertBearingX value in `metrics' cannot be extracted for + outline glyphs -- it is defined for embedded bitmaps only. + Instead, it is set to (xMin-xMax)/2; this will center the + bounding box on the vertical `baseline'. + + .................................................................. + + TT_Get_Glyph_Bitmap( TT_Glyph glyph, + TT_Raster_Map* bitmap, + TT_F26Dot6 xOffset, + TT_F26Dot6 yOffset ); + + 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; `xOffset' + and `yOffset' must be expressed in fractional pixels (where + 1 unit = 1/64th pixel). + + NOTE 1: + + Choosing non integer pixel offsets, i.e., values of `xOffset' + and `yOffset' that are not multiples of 64, will ruin the + hinting performed by the interpreter, and result in bad + rendering at small sizes. + + NOTE 2: + + 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! + + NOTE 3: + + FreeType always shifts the glyph horizontally so that the left + side bearing is equal to the left side of the bounding box. + + .................................................................. + + TT_Get_Glyph_Pixmap( TT_Glyph glyph, + TT_Raster_Map* pixmap, + TT_F26Dot6 xOffset, + TT_F26Dot6 yOffset ); + + 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 (`anti-aliasing' is also known as `font-smoothing'). + + The target pixmap is described by the `pixmap' pointer. Note + that its width _must_ be a multiple of 4. For the definition + and description of a pixmap see Section I. + + As with TT_Get_Glyph_Bitmap(), you can specify offsets to be + applied before the rendering (`xOffset' and `yOffset' must be + expressed in fractional pixel coordinates). + + NOTE 1: + + You don't need to supply a temporary bitmap for the + anti-aliaser. The rasterizer uses its own scheme to optimize + memory usage. + + NOTE 2: + + 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! + + NOTE 3: + + The pixmap passed to this function should always be EMPTY + (i.e., filled with zero bytes) before the call. If not, + garbage will accumulate! + + NOTE 4: + + FreeType always shifts the glyph horizontally so that the left + side bearing is equal to the left side of the bounding box. + + .................................................................. + + TT_New_Outline( TT_UShort numPoints, + TT_UShort numContours, + TT_Outline* outline ); + + Creates a new outline object. This function creates the arrays + necessary to hold `numPoints' points and `numContours' contours, + and set `outline's pointers to them. + + The new outline owns the arrays, and they will be destroyed with + it through TT_Done_Outline(). + + NOTE 1: + + Outlines created with this function are called `user' + outlines, in contrast with the outlines returned by + TT_Get_Glyph_Outline(), which fields refer to the data + contained within a glyph object (i.e., these outlines do not + own the arrays they refer to). + + NOTE 2: + + User outlines aren't tracked by the engine, which means they + are not destroyed by a TT_Done_FreeType(). You have to + explicitly discard them through TT_Done_Outline() to avoid + memory leaks. + + .................................................................. + + TT_Done_Outline( TT_Outline* outline ); + + Deletes an outline's data. Note that you need not destroy the + outlines returned by TT_Get_Glyph_Outline(), only those created + by TT_New_Outline(). + + .................................................................. + + TT_Copy_Outline( TT_Outline* source, + TT_Outline* target ); + + Copies the content of the `source' outline into the content of + the `target' outline. The two outlines must have been created + with the same dimensions (num_points and num_contours), + otherwise this function will return an error code. + + .................................................................. + + void TT_Transform_Outline( TT_Glyph_Outline* outline, + ^^^^ TT_Matrix* matrix ); + + Applies a simple transformation matrix on a given outline. This + will multiply each point coordinate vector by a 2x2 matrix, + which coefficients are given 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. + + .................................................................. + + void TT_Translate_Outline( TT_Glyph_Outline* outline, + ^^^^ TT_Pos xOffset, + TT_Pos yOffset ); + + Applies 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. + + .................................................................. + + TT_Get_Outline_Bitmap( TT_Engine engine, + TT_Outline* outline, + TT_Raster_Map* bitmap ); + + Renders an outline into a bitmap. The latter must be setup by + the user before the call (i.e., it is not created by this + function, instead it must be provided by the user). + + .................................................................. + + TT_Get_Outline_Pixmap( TT_Engine engine, + TT_Outline* outline, + TT_Raster_Map* pixmap ); + + Renders an outline into a pixmap. The latter must be setup by + the user before the call (i.e., it is not created by this + function, instead it must be provided by the user). + + NOTE: + + The pixmap passed to this function must always be EMPTY (i.e., + filled with zero bytes) before the call. Otherwise, garbage may + accumulate! + + .................................................................. + + TT_Get_Outline_BBox( TT_Outline* outline, + TT_BBox* bbox ); + + Returns an outline's bounding box in the `bbox' structure. Note + that the returned coordinates are not grid fitted! + + NOTE: + + The current release of FreeType (1.x) does compute the bounding + box for the outline's control points, and not the `exact' box + based on Bezier arcs extrema. Hence, the bbox returned by this + function may be slightly larger than necessary if the glyph + doesn't have control points at its extrema, or if it has been + rotated. + + .................................................................. + + void TT_Transform_Vector( TT_Pos* x, + ^^^^ TT_Pos* y, + TT_Matrix* matrix ); + + Applies a 2x2 matrix to a vector. + + .................................................................. + + int TT_Get_CharMapCount( TT_Face face ); + ^^^ + + Gets the number of character mappings present in the TrueType + file described by the `face' handle. Returns -1 if the handle + is invalid. + + IMPORTANT NOTE: ******** + + This function is deprecated. Get the number of character maps + from the `num_CharMaps' field in the structure returned by + TT_Get_Face_Property() instead. + + .................................................................. + + TT_Get_CharMap_ID( TT_Face face, + TT_UShort charmapIndex, + TT_UShort* platformID, + TT_UShort* encodingID ); + + Returns the platform ID and platform-specific encoding ID for + the charmap numbered `charmapIndex' in the `face' object. The + total number of character mapping tables can be found in the + `num_CharMaps' field in the structure returned by + TT_Get_Face_Property(). + + .................................................................. + + TT_Get_CharMap( TT_Face face, + TT_UShort charmapIndex, + TT_CharMap* charMap ); + + Returns 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 function. + + Charmap objects are automatically destroyed when their face + object is destroyed. + + .................................................................. + + TT_UShort TT_Char_Index( TT_CharMap charMap, + ^^^^^^^^^ TT_ULong charCode ); + + Applies a charMap to translate `charCode' into a glyph index + that can be used to load and address a glyph in the TrueType + file. In case of error, the undefined glyph (index 0) is + returned. + + Note: Since FT 1.5, the `charCode' is an unsigned long instead + of an unsigned short. + + The charmap handle can be obtained with TT_Get_CharMap(). + + .................................................................. + + int TT_Get_Name_Count( TT_Face face ); + ^^^ + + Gets the number of name strings found in a face's name table. + This function will return -1 if the face handle is invalid. + + IMPORTANT NOTE: ******** + + This function is deprecated. Get the number of name strings + from the `num_Names' field in the structure returned by + TT_Get_Face_Property() instead. + + .................................................................. + + TT_Get_Name_ID( TT_Face face, + TT_UShort nameIndex, + TT_UShort* platformID, + TT_UShort* encodingID, + TT_UShort* languageID, + TT_UShort* nameID ); + + Returns the ID of a given name string, indexed by the number + `nameIndex' in a given face. The name index ranges from 0 to + `num_names' minus one; this value can be found in the structure + returned by TT_Get_Face_Property(). + + Each string has a `platformID', `encodingID', `languageID' and + `nameID', as defined by the TrueType specification. + + The platformID is typically in the range [0,3]. Some font files + have unusual name table entries; these can be detected from + their platformID which is larger than 3. + + .................................................................. + + TT_Get_Name_String( TT_Face face, + TT_UShort nameIndex, + TT_String** stringPtr, + TT_UShort* length ); + + Returns a name string's address and length. Note that an + invalid name table entry always returns NULL for `stringPtr' and + zero for `length'. + + NOTE 1: + + The string belongs to the face object and should not be + written to or freed by the client application. + + NOTE 2: + + The library does not care about endianess here! If you are + using a little-endian machine and you have to interpret the + string bytes as 16-bit-wide characters (e.g. Unicode encoded), + you must byte-swap the data because 16-bit data is stored as + big-endian in TrueType fonts, and FreeType reads in the whole + name table bytewise. + + .................................................................. + + TT_Get_Font_Data( TT_face face, + TT_Long tag, + TT_Long offset, + void* buffer, + TT_Long* length ); + + Gets font or table data. Similar to the GetFontData() API of + the Windows world. You can use the macro MAKE_TT_TAG() to + generate TrueType table tags from character descriptions, like + + MAKE_TT_TAG( 'e', 'b', 'l', 'c' ) + + Use the value 0 instead for `tag' if you want to access the + whole font file. `offset' specifies the starting offset in the + table (or the offset in the file if tag == 0), `buffer' the + address of target buffer. + + Depending on the value of length, various actions are performed. + If `length' is NULL, the whole table will be loaded. An error + will be returned if `offset' is not 0. If `*length' is zero, + TT_Get_Font_Data() exits immediately, returning only the length + of the given table (in the variable `length'), or of the font + file, depending on the value of `tag'. Finally, if `*length' is + not zero, the next `length' bytes of the table (resp. the font) + are loaded into an array pointed to by `buffer', starting at + offset `offset'. Note that the `buffer' array must be large + enough to hold `length' bytes. + + +-------------------------------------------------------------------- +-------------------------------------------------------------------- + + + +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'. In the following table, the prefix + `TT_Err_' is omitted, e.g. `Ok' -> `TT_Err_Ok'. + + + 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 an API function. + + 0x0007 Invalid_Argument An invalid argument was passed to + an 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 + while trying to open a file which + isn't a collection. + + 0x000A Table_Missing The requested TrueType table is + missing in the font file. + + 0x000B Invalid_Horiz_Metrics The font's HMTX table is invalid. + Denotes a broken font. + + 0x000C Invalid_CharMap_Format A font's charmap entry has an + invalid format. Some other + entries may be valid though. + + 0x000D Invalid_PPem Invalid PPem values specified, + i.e., you are accessing a scaled + glyph without having called + TT_Set_Instance_CharSize() or + TT_Set_Instance_PixelSizes(). + + 0x0010 Invalid_File_Format The file isn't a TrueType font or + collection. + + 0x0011 Invalid_Vert_Metrics The font's VMTX table is invalid. + Denotes a broken font. + + 0x0020 Invalid_Engine An invalid engine handle was + passed to one of the API + functions. + + 0x0021 Too_Many_Extensions The client application is trying + to initialize too many + extensions. The default max + extensions number is 8 (this + value can be changed at compile + time). + + 0x0022 Extensions_Unsupported This build of the engine doesn't + support extensions. + + 0x0023 Invalid_Extension_Id This error indicates that the + client application is trying to + use an extension that has not + been initialized yet. + + 0x0030 No_Vertical_Data There is no vertical data, but + you are requesting it. Instead, + call TT_Get_Face_Metrics() with + NULL pointers for `topBearings' + and `heights'. + + 0x0080 Max_Profile_Missing The max profile table is missing. + => broken font file + + 0x0081 Header_Table_Missing The font header table is missing. + => broken font file + + 0x0082 Horiz_Header_Missing The horizontal header is missing. + => broken font file + + 0x0083 Locations_Missing The locations table is missing. + => broken font file + + 0x0084 Name_Table_Missing The name table is missing. + => broken font file + + 0x0085 CMap_Table_Missing The character encoding tables are + missing. + => broken font file + + 0x0086 Hmtx_Table_Missing The hmtx table is missing. + => broken font file + + 0x0087 OS2_Table_Missing The OS/2 table is missing. + Some Mac fonts don't have it. + + 0x0088 Post_Table_Missing The PostScript table is missing. + => broken font file + + 0x0089 Glyf_Table_Missing The glyph table is missing. + => broken font file + + ----------------- 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. + + 0x0410 Invalid_Displacement The program tried to use an + invalid displacement. + + 0x0411 Execution_Too_Long In order to get rid of `poison' + fonts, the interpreter produces + this error if more than one + million opcodes have been + interpreted in a single glyph + program. This detects infinite + loops softly. + + ----------------- 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 are 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()! + + +--- end of apiref.txt --- |