summaryrefslogtreecommitdiff
path: root/Build/source/libs/freetype/freetype-1.5/docs/apiref.txt
diff options
context:
space:
mode:
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.txt1918
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 ---