865 lines
33 KiB
Plaintext
865 lines
33 KiB
Plaintext
The FreeType Engine
|
|
|
|
Extension Library Reference
|
|
|
|
|
|
-----------------------------------
|
|
|
|
|
|
Table of Contents:
|
|
|
|
I. Engine extensions
|
|
1. kerning (ftxkern)
|
|
2. PostScript names (ftxpost)
|
|
3. TrueType Open (ftxopen)
|
|
a. The `BASE' table (baseline data)
|
|
b. The `GDEF' table (glyph definitions)
|
|
c. The `GPOS' table (glyph positions)
|
|
d. The `GSUB' table (glyph substitions)
|
|
e. The `JSTF' table (justification data)
|
|
f. auxiliary functions
|
|
4. embedded bitmaps (ftxsbit)
|
|
|
|
II. API extensions
|
|
1. cmap iteration (ftxcmap)
|
|
2. internationalized error messages (ftxerr18)
|
|
3. access to the `gasp' table (ftxgasp)
|
|
4. fast retrieval of glyph widths and heights (ftxwidth)
|
|
|
|
III. Error codes
|
|
|
|
|
|
--------------------
|
|
|
|
|
|
Please read the file `user.txt' for an introduction into FreeType's
|
|
extension mechanism and the difference between engine and API
|
|
extensions.
|
|
|
|
|
|
I. Engine extensions
|
|
====================
|
|
|
|
To use engine extensions you have to compile the library with the
|
|
macro TT_CONFIG_OPTION_EXTEND_ENGINE. By default, this macro is set
|
|
and all engine extensions are linked to the FreeType library.
|
|
|
|
|
|
1. kerning (ftxkern)
|
|
--------------------
|
|
|
|
TT_Init_Kerning_Extension( TT_Engine engine )
|
|
|
|
Initializes the kerning extension for a given engine. This must
|
|
be called just after the engine creation, and before any face
|
|
object allocation. Example:
|
|
|
|
TT_Init_FreeType( &engine );
|
|
TT_Init_Kerning_Extension( engine );
|
|
|
|
..................................................................
|
|
|
|
TT_Get_Kerning_Directory( TT_Face face,
|
|
TT_Kerning* directory )
|
|
|
|
Queries the kerning directory found in a face object. If no
|
|
kerning table is found in the TrueType file, the error
|
|
TT_Err_Table_Is_Missing will be returned.
|
|
|
|
You can access the subtables through the pointers of the
|
|
directory. However, by default, the directory is only loaded if
|
|
a face object is created. You must load the subtables that
|
|
interest you with a call to TT_Load_Kerning_Table().
|
|
|
|
The layout of all kerning structures is defined in the file
|
|
`lib/extend/ftxkern.h'. Formats 0 and 2 (as defined in the
|
|
Microsoft TrueType specification) are exposed by this API.
|
|
|
|
NOTE:
|
|
|
|
This function must be called after the kerning extension has
|
|
been initialized.
|
|
|
|
..................................................................
|
|
|
|
TT_Load_Kerning_Table( TT_Face face,
|
|
TT_UShort kernIndex )
|
|
|
|
Loads the kerning subtable number `kern_index' into memory. The
|
|
subtable can be accessed through the pointers provided by the
|
|
kerning directory, obtained from a call to the function
|
|
TT_Get_Kerning_Directory().
|
|
|
|
Note that the interpretation of the kerning data is left to the
|
|
client application. Read the TrueType specification for more
|
|
information on kerning encoding.
|
|
|
|
NOTE 1:
|
|
|
|
This function must be called after the kerning extension were
|
|
initialized.
|
|
|
|
NOTE 2:
|
|
|
|
An example can be found in the file `test/ftstrtto.c'.
|
|
|
|
|
|
====================================================================
|
|
|
|
|
|
2. PostScript names (ftxpost)
|
|
-----------------------------
|
|
|
|
TT_Init_Post_Extension( TT_Engine engine )
|
|
|
|
Initializes the PostScript name extension to load the PostScript
|
|
glyph names given in the `post' table. This must be called just
|
|
after creation of the engine, and before any face object
|
|
allocation. See description of TT_Get_PS_Name() for an example.
|
|
|
|
..................................................................
|
|
|
|
TT_Load_PS_Names( TT_Face face,
|
|
TT_Post* post )
|
|
|
|
Loads the PostScript glyph names into memory. This must be done
|
|
before TT_Get_PS_Name() is called. In case of error, either
|
|
TT_Err_Invalid_Post_Table or TT_Err_Invalid_Post_Table_Format is
|
|
returned. See description of TT_Get_PS_Name() for an example.
|
|
|
|
..................................................................
|
|
|
|
TT_Get_PS_Name( TT_Face face,
|
|
TT_UShort index,
|
|
TT_String** PSname )
|
|
|
|
Get the PostScript glyph name for a given glyph index. A
|
|
pointer to the name is returned in `PSname'. Example:
|
|
|
|
...
|
|
TT_Post post;
|
|
char* PSname;
|
|
|
|
...
|
|
TT_Init_Post_Extension( engine );
|
|
TT_Load_PS_Names( face, &post );
|
|
|
|
...
|
|
TT_Get_PS_Name( face, index, &PSname );
|
|
|
|
|
|
NOTE:
|
|
|
|
You must not alter the PostScript glyph name string returned
|
|
in `PSname'.
|
|
|
|
|
|
====================================================================
|
|
|
|
|
|
3. TrueType Open (ftxopen)
|
|
--------------------------
|
|
|
|
Please note that TrueType Open specific error codes have the
|
|
prefix `TTO_Err_' instead of `TT_Err_'.
|
|
|
|
a. The `BASE' table (baseline data)
|
|
|
|
Not yet supported.
|
|
|
|
b. The `GDEF' table (glyph definitions)
|
|
|
|
TT_Init_GDEF_Extension( TT_Engine engine )
|
|
|
|
Initializes the GDEF extension to load the glyph definition
|
|
data given in the `GDEF' table. This must be called just
|
|
after creation of the engine, and before any face object
|
|
allocation. See the file `ftstrtto.c' for an example.
|
|
|
|
................................................................
|
|
|
|
TT_Load_GDEF_Table( TT_Face face,
|
|
TTO_GDEFHeader* gdef )
|
|
|
|
Loads the GDEF table into `gdef' for a given face `face'.
|
|
This must be done before any queries about glyph properties
|
|
with TT_GSUB_Get_Property(). Returns TT_Err_Table_Missing if
|
|
there is no GDEF table in the font.
|
|
|
|
................................................................
|
|
|
|
TT_GDEF_Get_Glyph_Property( TTO_GDEFHeader* gdef,
|
|
TT_UShort glyphID,
|
|
TT_UShort* property )
|
|
|
|
Use this function to get glyph properties in the variable
|
|
`property' for the glyph with index `glyphID' stored in the
|
|
`gdef' table. This data is essential for many fonts to
|
|
correctly apply contextual substitution (both GSUB and GPOS).
|
|
As a special case, zero is assigned to `property' if `gdef' is
|
|
NULL or the glyph has no special glyph property assigned to
|
|
it. The other return values of `property' are TTO_BASE,
|
|
TTO_LIGATURE, TTO_MARK, and TTO_COMPONENT; you can directly
|
|
apply the `LookupFlag' mask to check for certain properties:
|
|
|
|
TTO_GDEFHeader* gdef;
|
|
TTO_Lookup* lo;
|
|
TT_UShort glyph_ID;
|
|
TT_UShort p;
|
|
|
|
|
|
TT_GDEF_Get_Property( gdef, glyph_ID, &p );
|
|
|
|
if ( p & lo->LookupFlag )
|
|
return TTO_Err_Not_Covered;
|
|
|
|
Usually, you don't need to take care of glyph properties by
|
|
yourself since TT_GSUB_Apply_String() will do this for you by
|
|
calling TT_GDEF_Get_Property().
|
|
|
|
Some fonts need GDEF-like data even if no GDEF table is
|
|
provided (for example, the Arabic script needs information
|
|
which glyphs are base glyphs and which are mark glyphs). In
|
|
such cases, you should use TT_GDEF_Build_ClassDefinition() to
|
|
build the necessary structures so that TT_GDEF_Get_Property()
|
|
returns meaningful values.
|
|
|
|
See also TT_Load_GSUB_Table() and TT_Load_GPOS_Table().
|
|
|
|
................................................................
|
|
|
|
TT_GDEF_Build_ClassDefinition( TTO_GDEFHeader* gdef,
|
|
TT_UShort num_glyphs,
|
|
TT_UShort glyph_count,
|
|
TT_UShort* glyph_array,
|
|
TT_UShort* class_array )
|
|
|
|
Fills a `gdef' structure with data to make
|
|
TT_GDEF_Get_Property() work in case no GDEF table is
|
|
available. `num_glyphs' is the number of glyphs in the font.
|
|
|
|
`glyph_count' is the number of glyphs resp. class values (as
|
|
specified in the GDEF specification) given in the arrays
|
|
`glyph_array' and `class_array', respectively. The glyph
|
|
indices in `glyph_array' must be all different and sorted in
|
|
ascending order; the function expects that glyph index
|
|
`glyph_array[n]' has its class value in `class_array[n]'.
|
|
|
|
Note that mark attach classes as defined in OpenType 1.2 are
|
|
not supported for constructed GDEF tables.
|
|
|
|
See `arabic.c' for an example.
|
|
|
|
|
|
c. The `GPOS' table (glyph positions)
|
|
|
|
Not yet supported.
|
|
|
|
|
|
d. The `GSUB' table (glyph substitions)
|
|
|
|
For glyph substitution, a string object of type TTO_GSUB_String
|
|
is used. The field `length' holds the length of the string,
|
|
`pos' points to the actual position in the glyph string `string'
|
|
(for input strings) resp. the position where the substituted
|
|
glyphs should be placed at (for output strings).
|
|
|
|
Within the `properties' array (which must always have the same
|
|
length as `string' if set), you can define properties for glyphs
|
|
-- `string[n]' is associated with `properties[n]'. The idea is
|
|
that some features apply to specific glyphs only. As an
|
|
example, the `fina' feature for Arabic applies only to glyphs
|
|
which appear at the end of a word (strictly speaking, this
|
|
feature is used only for glyphs which have a `final' property;
|
|
such glyphs can occur in the middle of a word also under certain
|
|
circumstances which is dependent on Arabic script rules). The
|
|
relationship between properties and features can be set up with
|
|
the function TT_GSUB_Add_Feature(). If `properties' is set to
|
|
NULL, all selected features apply to all glyphs in the given
|
|
string object. If `properties' is non-NULL, the elements of the
|
|
array are treated as bit fields. A set flag means that the
|
|
corresponding feature (as set with the TT_GSUB_Add_Feature()
|
|
function) should not be applied to the particular glyph. As a
|
|
consequence, a zero value for these 16 bits means that all
|
|
features should be applied, and a value of 0xFFFF implies that
|
|
no feature at all should be used for the glyph.
|
|
|
|
The field `allocated' is for internal use only and must not be
|
|
modified. If its value is larger than zero, you should use
|
|
free() to deallocate the memory used by `string' (and
|
|
`properties' if set) in case you want to destroy a
|
|
TTO_GSUB_String object (memory for `string' and `properties' is
|
|
allocated automatically e.g. by TT_GSUB_Apply_String() for
|
|
output string objects).
|
|
|
|
struct TTO_GSUB_String_
|
|
{
|
|
TT_ULong length;
|
|
TT_ULong pos;
|
|
TT_ULong allocated;
|
|
TT_UShort* string;
|
|
TT_UShort* properties;
|
|
};
|
|
|
|
typedef struct TTO_GSUB_String_ TTO_GSUB_String;
|
|
|
|
Note that the `string' field must contain glyph indices, not
|
|
character codes.
|
|
|
|
For initializing an input string object, you should set the
|
|
`length', `string', and `properties' fields (the last one only
|
|
if necessary) to appropriate values. `pos' has to be set to the
|
|
position where the substitution lookups should start (usually
|
|
zero). The `allocated' field will be ignored.
|
|
|
|
For initializing an output string object, all fields (except
|
|
`length' which will be ignored) must be set to zero. If you
|
|
want to reuse the object, set `pos' to the position where the
|
|
substituted glyphs should be placed at (usually zero), but don't
|
|
touch the `allocated', `string', and `properties' fields.
|
|
|
|
................................................................
|
|
|
|
TT_Init_GSUB_Extension( TT_Engine engine )
|
|
|
|
Initializes the GSUB extension to load the glyph substitution
|
|
data given in the `GSUB' table. This must be called just
|
|
after creation of the engine, and before any face object
|
|
allocation. See the files `ftstrtto.c' and `ftdump.c' for
|
|
detailed examples.
|
|
|
|
................................................................
|
|
|
|
TT_Load_GSUB_Table( TT_Face face,
|
|
TTO_GSUBHeader* gsub,
|
|
TTO_GDEFHeader* gdef )
|
|
|
|
Loads the GSUB table into `gsub' for a given face `face'.
|
|
This must be done before any queries about or selection of
|
|
scripts, languages, and features. Returns
|
|
TT_Err_Table_Missing if there is no GSUB table in the font.
|
|
|
|
`gdef' should contain a pointer to an associated GDEF table,
|
|
either a native one loaded with TT_Load_GDEF_Table() or
|
|
emulated with TT_GDEF_Build_ClassDefinition(). If `gdef' is
|
|
set to NULL, no GDEF data will be used.
|
|
|
|
................................................................
|
|
|
|
TT_GSUB_Select_Script( TTO_GSUBHeader* gsub,
|
|
TT_ULong script_tag,
|
|
TT_UShort* script_index )
|
|
|
|
This function sets the script index of a given script tag
|
|
`script_tag' in the variable `script_index' for the GSUB table
|
|
`gsub'. Returns TTO_Err_Not_Covered if the script tag cannot
|
|
be found. The available script tags can be queried with the
|
|
function TT_GSUB_Query_Scripts().
|
|
|
|
................................................................
|
|
|
|
TT_GSUB_Select_Language( TTO_GSUBHeader* gsub,
|
|
TT_ULong language_tag,
|
|
TT_UShort script_index,
|
|
TT_UShort* language_index,
|
|
TT_UShort* req_feature_index )
|
|
|
|
This function sets the language index of a given language tag
|
|
`language_tag' and script index `script_index' in the variable
|
|
`language_index' for the GSUB table `gsub'. Returns
|
|
TTO_Err_Not_Covered if the language tag cannot be found. The
|
|
available language tags can be queried with the function
|
|
TT_GSUB_Query_Languages().
|
|
|
|
Additionally, the index of the required feature for this
|
|
language system is returned in `req_feature_index'; it must be
|
|
later registered for use with TT_GSUB_Add_Feature().
|
|
|
|
................................................................
|
|
|
|
TT_GSUB_Select_Feature( TTO_GSUBHeader* gsub,
|
|
TT_ULong feature_tag,
|
|
TT_UShort script_index,
|
|
TT_UShort language_index,
|
|
TT_UShort* feature_index )
|
|
|
|
This function sets the feature index of a feature tag
|
|
`feature_tag', script index `script_index', and language index
|
|
`language_index' in the variable `feature_index' for the GSUB
|
|
table `gsub'. Returns TTO_Err_Not_Covered if the feature tag
|
|
cannot be found. The available feature tags can be queried
|
|
with the function TT_GSUB_Query_Features(). Setting
|
|
language_index to 0xFFFF selects the default language system.
|
|
|
|
................................................................
|
|
|
|
TT_GSUB_Query_Scripts( TTO_GSUBHeader* gsub,
|
|
TT_ULong** script_tag_list )
|
|
|
|
Returns the available script tags for a given GSUB table
|
|
`gsub' in the array `script_tag_list'. The array can be later
|
|
deallocated with free().
|
|
|
|
................................................................
|
|
|
|
TT_GSUB_Query_Languages( TTO_GSUBHeader* gsub,
|
|
TT_UShort script_index,
|
|
TT_ULong** language_tag_list )
|
|
|
|
Returns the available language tags for a given GSUB table
|
|
`gsub' and script index `script_index' in the array
|
|
`language_tag_list'. The array can be later deallocated with
|
|
free().
|
|
|
|
................................................................
|
|
|
|
TT_GSUB_Query_Features( TTO_GSUBHeader* gsub,
|
|
TT_UShort script_index,
|
|
TT_UShort language_index,
|
|
TT_ULong** feature_tag_list )
|
|
|
|
Returns the available feature tags for a given GSUB table
|
|
`gsub', script index `script_index', and language index
|
|
`language_index' in the array `feature_tag_list'. If language
|
|
index is set to 0xFFFF, the values for the default language
|
|
system are returned. The array can be later deallocated with
|
|
free().
|
|
|
|
................................................................
|
|
|
|
TT_GSUB_Add_Feature( TTO_GSUBHeader* gsub,
|
|
TT_UShort feature_index,
|
|
TT_UShort property )
|
|
|
|
To prepare a call to TT_GSUB_Apply_String() which should
|
|
process a given feature with index `feature_index' and the
|
|
property `property', you must use this function. Its task is
|
|
to mark the lookup tables used by the feature for further
|
|
processing.
|
|
|
|
`property' defines a relationship between the input string
|
|
object and the specific feature. The client must handle this
|
|
variable as a bit field, i.e., up to 16 user properties can be
|
|
defined. If `property' is set to ALL_GLYPHS (0xFFFF, the only
|
|
predefined value), or if the input string object has no set
|
|
bits in the `properties' field, the feature applies to all
|
|
glyphs. If bit `x' is set in `property', the feature applies
|
|
only to glyphs which have bit `x' not set in glyph's
|
|
`properties' field in the input string object. See
|
|
TT_GSUB_Apply_String() for an example.
|
|
|
|
Returns TT_Err_Invalid_Argument in case of error.
|
|
|
|
................................................................
|
|
|
|
TT_GSUB_Clear_Features( TTO_GSUBHeader* gsub )
|
|
|
|
Clears the list of used features and properties. No lookup
|
|
tables will be processed.
|
|
|
|
................................................................
|
|
|
|
TT_GSUB_Register_Alternate_Function( TTO_GSUBHeader* gsub,
|
|
TTO_AltFunction alt,
|
|
void* data )
|
|
|
|
Installs a callback function to handle alternate
|
|
substitutions. `data' is a generic pointer to a user-defined
|
|
structure which will be completely ignored by the ftxopen
|
|
extension. `alt' is a function pointer defined as
|
|
|
|
typedef TT_UShort
|
|
(*TTO_AltFunction)(TT_ULong pos,
|
|
TT_UShort glyphID,
|
|
TT_UShort num_alternates,
|
|
TT_UShort* alternates,
|
|
void* data );
|
|
|
|
If TT_GSUB_Apply_String() encounters an alternate lookup while
|
|
processing the input string, it will call the function `alt'
|
|
to find out which alternate glyph it should use. `pos' gives
|
|
the position in the string, `glyphID' the glyph ID of the
|
|
glyph to be replaced with an alternate glyph, and
|
|
`num_alternates' the number of alternate glyphs in the
|
|
`alternates' array. A pointer to the user-defined `data'
|
|
structure is also available. `alt' must return an index into
|
|
`alternates'.
|
|
|
|
If `alt' is NULL or if this function isn't called at all,
|
|
TT_GSUB_Apply_String() will always use the first alternate
|
|
glyph.
|
|
|
|
Please note that theoretically an alternate lookup can happen
|
|
during any other lookup! For example, a lookup chain like
|
|
|
|
single subst -> alternate subst -> ligature subst
|
|
|
|
*is* possible (albeit rather unlikely). Thus be warned that
|
|
`pos' does not necessarily reflect the position of a glyph to
|
|
be displayed at all, nor does `glyphID' specifies a glyph
|
|
which will be in the final output string.
|
|
|
|
................................................................
|
|
|
|
TT_GSUB_Apply_String( TTO_GSUBHeader* gsub,
|
|
TTO_GSUB_String* in,
|
|
TTO_GSUB_String* out )
|
|
|
|
This is the very function which handles glyph substitution
|
|
according to the features set up with TT_GSUB_Add_Feature(),
|
|
using both GSUB and GDEF data (if defined). Two
|
|
TTO_GSUB_String objects `in' and `out' (as described above)
|
|
are taken for input and output; after successful excecution,
|
|
the converted glyph string can been found in `out', and
|
|
`out.length' gives the actual length of the output string
|
|
(counted from the begin of the array).
|
|
|
|
Example:
|
|
|
|
/* We assume that the feature `xxxx' has index 5, and */
|
|
/* feature `yyyy' has index 8, applying only to glyphs */
|
|
/* with the property `FINAL_GLYPHS' set (0x1000 is an */
|
|
/* ad-hoc value just for this example). */
|
|
|
|
/* The order of calls to TT_GSUB_Add_Feature() is not */
|
|
/* significant. */
|
|
|
|
#define FINAL_GLYPHS 0x1000
|
|
|
|
TT_GSUB_Clear_Features( &gsub );
|
|
TT_GSUB_Add_Feature( &gsub, 8, FINAL_GLYPHS );
|
|
TT_GSUB_Add_Feature( &gsub, 5, ALL_GLYPHS );
|
|
|
|
TT_GSUB_Apply_String( &gsub, &in, &out );
|
|
|
|
You must initialize both `in' and `out' structures; allocation
|
|
necessary for the `out' object will be handled automatically.
|
|
|
|
In case you don't register a function to handle alternate
|
|
substitutions (GSUB lookup 3), always the first alternate
|
|
glyph will be used. See TT_GSUB_Register_Alternate_Function()
|
|
above for more details.
|
|
|
|
|
|
e. The `JSTF' table (justification data)
|
|
|
|
Not yet supported.
|
|
|
|
|
|
f. auxiliary functions
|
|
|
|
TT_GSUB_Add_String( TTO_GSUB_String* in,
|
|
TT_UShort num_in,
|
|
TTO_GSUB_String* out,
|
|
TT_UShort num_out,
|
|
TT_UShort* data )
|
|
|
|
This function copies `num_out' elements from `data' to `out',
|
|
advancing the array pointer `in.pos' by `num_in' elements and
|
|
`out.pos' by `num_out' elements. If the string (resp. the
|
|
properties) array in `out' is empty or too small, it allocates
|
|
resp. reallocates the string (and properties) array.
|
|
Finally, it sets `out.length' equal to `out.pos'.
|
|
|
|
The properties for all replaced glyphs are taken from the
|
|
glyph at position `in->pos'.
|
|
|
|
TT_GSUB_Add_String() is normally used in
|
|
TT_GSUB_Apply_String(); you will need it for the special case
|
|
to skip some glyphs (i.e., copy glyphs directly from the `in'
|
|
to the `out' object), bypassing a possible GSUB substitution.
|
|
|
|
Here an example which copies one glyph:
|
|
|
|
TT_GSUB_Add_String( in, 1,
|
|
out, 1,
|
|
&in->string[in->pos] );
|
|
|
|
|
|
====================================================================
|
|
|
|
|
|
4. embedded bitmaps (ftxsbit)
|
|
-----------------------------
|
|
|
|
TT_Init_SBit_Extension( TT_Engine engine )
|
|
|
|
Initializes the embedded bitmap extension to load the bitmap
|
|
glyphs given in the various sbit tables: `EBLC', `bloc', `EBDT',
|
|
and `bdat' (`bloc' and `bdat' tables are only in Apple fonts;
|
|
the former is equivalent to `EBLC', the latter equivalent to
|
|
`EBDT'). This must be called just after creation of the engine,
|
|
and before any face object allocation. See description of
|
|
TT_Load_Glyph_Bitmap() for an example.
|
|
|
|
..................................................................
|
|
|
|
TT_Get_Face_Bitmaps( TT_Face face,
|
|
TT_EBLC* eblc_table )
|
|
|
|
Loads the `EBLC' (resp. `bloc') table from a font file into the
|
|
`eblc_table' structure. Use this function for testing whether
|
|
embedded bitmaps are available or not.
|
|
|
|
This function returns TT_Err_Table_Missing if the font contains
|
|
no embedded bitmaps. All fields in `eblc_table' will then be
|
|
set to 0.
|
|
|
|
..................................................................
|
|
|
|
TT_New_SBit_Image( TT_SBit_Image** image )
|
|
|
|
Allocates a new embedded bitmap container, pointed to by
|
|
`image'.
|
|
|
|
..................................................................
|
|
|
|
void TT_Done_SBit_Image( TT_SBit_Image* image )
|
|
^^^^
|
|
|
|
Releases the embedded bitmap container `image'.
|
|
|
|
..................................................................
|
|
|
|
TT_Get_SBit_Strike( TT_Face face,
|
|
TT_Instance instance,
|
|
TT_SBit_Strike* strike )
|
|
|
|
Loads a suitable strike (i.e. bitmap sizetable) for the given
|
|
instance. Will return TT_Err_Invalid_PPem if there is no strike
|
|
for the current x_ppem and y_ppem values.
|
|
|
|
..................................................................
|
|
|
|
TT_Load_Glyph_Bitmap( TT_Face face,
|
|
TT_Instance instance,
|
|
TT_UShort glyph_index,
|
|
TT_SBit_Image* bitmap );
|
|
|
|
Loads a glyph bitmap for a given glyph index `glyph_index' (in
|
|
face `face' and instance `instance') into `bitmap'. It calls
|
|
TT_Get_SBit_Strike() internally for checking the current x_ppem
|
|
and y_ppem values.
|
|
|
|
This function returns an error if there is no embedded bitmap
|
|
for the glyph at the given instance.
|
|
|
|
Example (omitting the error handling):
|
|
|
|
...
|
|
TT_SBit_Image* bitmap;
|
|
|
|
...
|
|
TT_Init_SBit_Extension( engine );
|
|
TT_New_SBit_Image( &bitmap );
|
|
...
|
|
TT_Load_Glyph_Bitmap( face, instance, glyph_index, bitmap );
|
|
|
|
|
|
|
|
--------------------------------------------------------------------
|
|
--------------------------------------------------------------------
|
|
|
|
|
|
|
|
II. API extensions
|
|
==================
|
|
|
|
To use API extensions, simply compile the specific extension file
|
|
and link it to the library or your program. By default, all
|
|
extensions described below are linked to the library.
|
|
|
|
|
|
1. cmap iteration (ftxcmap)
|
|
---------------------------
|
|
|
|
TT_Long TT_CharMap_First( TT_CharMap charMap,
|
|
^^^^^^^ TT_UShort* glyph_index )
|
|
|
|
|
|
Returns the first valid character code in a given character map
|
|
`charMap'. Also returns the corresponding glyph index (in the
|
|
parameter `*glyph_index'). In case of failure, -1 is returned,
|
|
and `*glyph_index' is undefined.
|
|
|
|
..................................................................
|
|
|
|
TT_Long TT_CharMap_Next( TT_CharMap charMap,
|
|
^^^^^^^ TT_UShort last_char,
|
|
TT_UShort* glyph_index )
|
|
|
|
Returns the next valid character code in a given character map
|
|
`charMap' which follows `last_char'. Also returns the
|
|
corresponding glyph index (in the parameter `*glyph_index'). In
|
|
case of failure, -1 is returned, and `glyph_index' is undefined.
|
|
|
|
..................................................................
|
|
|
|
TT_Long TT_CharMap_Last( TT_CharMap charMap,
|
|
^^^^^^^ TT_UShort* glyph_index )
|
|
|
|
|
|
Returns the last valid character code in a given character map
|
|
`charMap'. Also returns the corresponding glyph index (in the
|
|
parameter `*glyph_index'). In case of failure, -1 is returned,
|
|
and `*glyph_index' is undefined.
|
|
|
|
|
|
====================================================================
|
|
|
|
|
|
2. internationalized error messages (ftxerr18)
|
|
----------------------------------------------
|
|
|
|
This extension provides internationalized error strings from the
|
|
various error messages. It uses the `gettext' package if
|
|
available or returns English/American message strings if not.
|
|
Currently, the gettext package is only available on UNIX-like
|
|
systems like Linux; this means that for other platforms only
|
|
English error strings are returned.
|
|
|
|
If the gettext package is found on your system, the configure
|
|
script automatically includes it by default. In case you don't
|
|
want to use it, or if you encounter some problems compiling this
|
|
file, try to disable nls support by configuring FreeType with
|
|
`./configure --disable-nls'.
|
|
|
|
Please read the gettext info files for more information how to set
|
|
up your system for internationalized messages. A short
|
|
introduction is also given in the file `i18n.txt'.
|
|
|
|
|
|
TT_String* TT_ErrToString18( TT_Error i )
|
|
^^^^^^^^^^
|
|
|
|
This function returns an error string for a given error code
|
|
`i'. The type `TT_String' usually defaults to `char'; see
|
|
apiref.txt for more details.
|
|
|
|
An example how to use this function (in connection with the
|
|
gettext interface) is given e.g. in test/ftdump.c.
|
|
|
|
|
|
====================================================================
|
|
|
|
|
|
3. access to the `gasp' table (ftxgasp)
|
|
---------------------------------------
|
|
|
|
The `gasp' table is currently loaded by the core engine, but the
|
|
standard API doesn't give access to it.
|
|
|
|
|
|
TT_Get_Face_Gasp_Flags( TT_Face face,
|
|
TT_UShort point_size,
|
|
TT_Bool* grid_fit,
|
|
TT_Bool* smooth_font )
|
|
|
|
This function returns for a given `point_size' the values of the
|
|
gasp flags `grid_fit' and `smooth_font'. The returned values
|
|
are booleans (where 0 = NO, and 1 = YES).
|
|
|
|
Note that this function will return TT_Err_Table_Missing if the
|
|
font file doesn't contain any gasp table.
|
|
|
|
|
|
====================================================================
|
|
|
|
|
|
4. fast retrieval of glyph widths and heights (ftxwidth)
|
|
--------------------------------------------------------
|
|
|
|
This extension is used to parse the `glyf' table of a TrueType
|
|
file in order to extract the bounding box of a given range of
|
|
glyphs.
|
|
|
|
The bounding box is then used to build font unit widths and
|
|
heights that are returned in two parallel arrays.
|
|
|
|
This extension is needed by the FreeType/2 OS/2 Font Driver.
|
|
|
|
|
|
TT_Get_Face_Widths( TT_Face face,
|
|
TT_UShort first_glyph,
|
|
TT_UShort last_glyph,
|
|
TT_UShort* widths,
|
|
TT_UShort* heights )
|
|
|
|
Returns the widths (in array `widths') and heights (in array
|
|
`heights') of a glyph range which starts at `first_glyph' and
|
|
ends at `last_glyph'. All returned values are returned in font
|
|
units. If either `widths' or `heights' is set to a NULL
|
|
pointer, no data will be returned for that particular array.
|
|
|
|
Note: TT_Get_Face_Widths() does *not* allocate the two arrays!
|
|
|
|
|
|
|
|
--------------------------------------------------------------------
|
|
--------------------------------------------------------------------
|
|
|
|
|
|
|
|
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 various extension header files (e.g. ftxkern.h). In the
|
|
following table, the prefix `TT_Err_' is omitted, e.g. `Ok' ->
|
|
`TT_Err_Ok'.
|
|
|
|
|
|
Error Unprefixed Error
|
|
Code Macro Name Description
|
|
------------------------------------------------------------------
|
|
|
|
0x0A00 Invalid_Kerning_Table_Format
|
|
An invalid kerning subtable
|
|
format was found in this font.
|
|
|
|
0x0A01 Invalid_Kerning_Table A kerning table contains illegal
|
|
glyph indices.
|
|
|
|
0x0B00 Invalid_Post_Table_Format
|
|
The post table format specified
|
|
in the font is invalid.
|
|
|
|
0x0B01 Invalid_Post_Table The post table contains illegal
|
|
entries.
|
|
|
|
|
|
Here the TrueType Open error codes. In the following table, the
|
|
prefix `TTO_Err_' is omitted.
|
|
|
|
|
|
Error Unprefixed Error
|
|
Code Macro Name Description
|
|
------------------------------------------------------------------
|
|
0x1000 Invalid_SubTable_Format The TrueType Open subtable format
|
|
specified in the font is invalid.
|
|
|
|
0x1001 Invalid_SubTable A TrueType Open subtable contains
|
|
illegal entries.
|
|
|
|
0x1002 Not_Covered The requested feature, glyph,
|
|
etc. isn't covered by the actual
|
|
function.
|
|
|
|
0x1010 Invalid_GSUB_SubTable_Format
|
|
The GSUB subtable format
|
|
specified in the font is invalid.
|
|
|
|
0x1011 Invalid_GSUB_SubTable The GSUB subtable contains
|
|
illegal entries.
|
|
|
|
0x1020 Invalid_GPOS_SubTable_Format
|
|
The GPOS subtable format
|
|
specified in the font is invalid.
|
|
|
|
0x1021 Invalid_GPOS_SubTable The GPOS subtable contains
|
|
illegal entries.
|
|
|
|
|
|
--- end of apirefx.txt ---
|