@ -876,17 +876,36 @@ FT_BEGIN_HEADER
/* font formats can have multiple faces in */
/* a font file. */
/* */
/* face_index :: The index of the face in the font file. It */
/* is set to~0 if there is only one face in */
/* face_index :: This field holds two different values. */
/* Bits 0-15 are the index of the face in the */
/* font file (starting with value~0). They */
/* are set to~0 if there is only one face in */
/* the font file. */
/* */
/* Bits 16-30 are relevant to GX variation */
/* fonts only, holding the named instance */
/* index for the current face index (starting */
/* with value~1; value~0 indicates font access */
/* without GX variation data). For non-GX */
/* fonts, bits 16-30 are ignored. If we have */
/* the third named instance of face~4, say, */
/* `face_index' is set to 0x00030004. */
/* */
/* Bit 31 is always zero (this is, */
/* `face_index' is always a positive value). */
/* */
/* face_flags :: A set of bit flags that give important */
/* information about the face; see */
/* @FT_FACE_FLAG_XXX for the details. */
/* */
/* style_flags :: A set of bit flags indicating the style of */
/* the face; see @FT_STYLE_FLAG_XXX for the */
/* details. */
/* style_flags :: The lower 16~bits contain a set of bit */
/* flags indicating the style of the face; see */
/* @FT_STYLE_FLAG_XXX for the details. Bits */
/* 16-30 hold the number of named instances */
/* available for the current face if we have a */
/* GX variation (sub)font. Bit 31 is always */
/* zero (this is, `style_flags' is always a */
/* positive value). */
/* */
/* num_glyphs :: The number of glyphs in the face. If the */
/* face is scalable and has sbits (see */
@ -1392,7 +1411,7 @@ FT_BEGIN_HEADER
/* FT_STYLE_FLAG_XXX */
/* */
/* <Description> */
/* A list of bit- flags used to indicate the style of a given face. */
/* A list of bit flags used to indicate the style of a given face. */
/* These are used in the `style_flags' field of @FT_FaceRec. */
/* */
/* <Values> */
@ -1824,7 +1843,7 @@ FT_BEGIN_HEADER
/* FT_OPEN_XXX */
/* */
/* <Description> */
/* A list of bit- field constants used within the `flags' field of the */
/* A list of bit field constants used within the `flags' field of the */
/* @FT_Open_Args structure. */
/* */
/* <Values> */
@ -1971,13 +1990,12 @@ FT_BEGIN_HEADER
/* <Input> */
/* pathname :: A path to the font file. */
/* */
/* face_index :: The index of the face within the font. The first */
/* face has index~0. */
/* face_index :: See @FT_Open_Face for a detailed description of this */
/* parameter. */
/* */
/* <Output> */
/* aface :: A handle to a new face object. If `face_index' is */
/* greater than or equal to zero, it must be non-NULL. */
/* See @FT_Open_Face for more details. */
/* */
/* <Return> */
/* FreeType error code. 0~means success. */
@ -2010,13 +2028,12 @@ FT_BEGIN_HEADER
/* */
/* file_size :: The size of the memory chunk used by the font data. */
/* */
/* face_index :: The index of the face within the font. The first */
/* face has index~0. */
/* face_index :: See @FT_Open_Face for a detailed description of this */
/* parameter. */
/* */
/* <Output> */
/* aface :: A handle to a new face object. If `face_index' is */
/* greater than or equal to zero, it must be non-NULL. */
/* See @FT_Open_Face for more details. */
/* */
/* <Return> */
/* FreeType error code. 0~means success. */
@ -2048,13 +2065,43 @@ FT_BEGIN_HEADER
/* args :: A pointer to an `FT_Open_Args' structure that must */
/* be filled by the caller. */
/* */
/* face_index :: The index of the face within the font. The first */
/* face has index~0. */
/* face_index :: This field holds two different values. Bits 0-15 */
/* are the index of the face in the font file (starting */
/* with value~0). Set it to~0 if there is only one */
/* face in the font file. */
/* */
/* Bits 16-30 are relevant to GX variation fonts only, */
/* specifying the named instance index for the current */
/* face index (starting with value~1; value~0 makes */
/* FreeType ignore named instances). For non-GX fonts, */
/* bits 16-30 are ignored. Assuming that you want to */
/* access the third named instance in face~4, */
/* `face_index' should be set to 0x00030004. If you */
/* want to access face~4 without GX variation handling, */
/* simply set `face_index' to value~4. */
/* */
/* FT_Open_Face and its siblings can be used to quickly */
/* check whether the font format of a given font */
/* resource is supported by FreeType. In general, if */
/* the `face_index' argument is negative, the */
/* function's return value is~0 if the font format is */
/* recognized, or non-zero otherwise. The function */
/* allocates a more or less empty face handle in */
/* `*aface' (if `aface' isn't NULL); the only two */
/* useful fields in this special case are */
/* `face->num_faces' and `face->style_flags'. For any */
/* negative value of `face_index', `face->num_faces' */
/* gives the number of faces within the font file. For */
/* the negative value `-(N+1)' (with `N' a 16-bit */
/* value), bits 16-30 in `face->style_flags' give the */
/* number of named instances in face `N' if we have a */
/* GX variation font (or zero otherwise). After */
/* examination, the returned @FT_Face structure should */
/* be deallocated with a call to @FT_Done_Face. */
/* */
/* <Output> */
/* aface :: A handle to a new face object. If `face_index' is */
/* greater than or equal to zero, it must be non-NULL. */
/* See note below. */
/* */
/* <Return> */
/* FreeType error code. 0~means success. */
@ -2064,16 +2111,6 @@ FT_BEGIN_HEADER
/* slot for the face object that can be accessed directly through */
/* `face->glyph'. */
/* */
/* FT_Open_Face can be used to quickly check whether the font */
/* format of a given font resource is supported by FreeType. If the */
/* `face_index' field is negative, the function's return value is~0 */
/* if the font format is recognized, or non-zero otherwise; */
/* the function returns a more or less empty face handle in `*aface' */
/* (if `aface' isn't NULL). The only useful field in this special */
/* case is `face->num_faces' that gives the number of faces within */
/* the font file. After examination, the returned @FT_Face structure */
/* should be deallocated with a call to @FT_Done_Face. */
/* */
/* Each new face object created with this function also owns a */
/* default @FT_Size object, accessible as `face->size'. */
/* */
@ -2084,6 +2121,74 @@ FT_BEGIN_HEADER
/* See the discussion of reference counters in the description of */
/* @FT_Reference_Face. */
/* */
/* To loop over all faces, use code similar to the following snippet */
/* (omitting the error handling). */
/* */
/* { */
/* ... */
/* FT_Face face; */
/* FT_Long i, num_faces; */
/* */
/* */
/* error = FT_Open_Face( library, args, -1, &face ); */
/* if ( error ) { ... } */
/* */
/* num_faces = face->num_faces; */
/* FT_Done_Face( face ); */
/* */
/* for ( i = 0; i < num_faces; i++ ) */
/* { */
/* ... */
/* error = FT_Open_Face( library, args, i, &face ); */
/* ... */
/* FT_Done_Face( face ); */
/* ... */
/* } */
/* } */
/* */
/* To loop over all valid values for `face_index', use something */
/* similar to the following snippet, again without error handling. */
/* The code accesses all faces immediately (thus only a single call */
/* of `FT_Open_Face' within the do-loop), with and without named */
/* instances. */
/* */
/* { */
/* ... */
/* FT_Face face; */
/* */
/* FT_Long num_faces = 0; */
/* FT_Long num_instances = 0; */
/* */
/* FT_Long face_idx = 0; */
/* FT_Long instance_idx = 0; */
/* */
/* */
/* do */
/* { */
/* FT_Long id = ( instance_idx << 16 ) + face_idx; */
/* */
/* */
/* error = FT_Open_Face( library, args, id, &face ); */
/* if ( error ) { ... } */
/* */
/* num_faces = face->num_faces; */
/* num_instances = face->style_flags >> 16; */
/* */
/* ... */
/* */
/* FT_Done_Face( face ); */
/* */
/* if ( instance_idx < num_instances ) */
/* instance_idx++; */
/* else */
/* { */
/* face_idx++; */
/* instance_idx = 0; */
/* } */
/* */
/* } while ( face_idx < num_faces ) */
/* } */
/* */
FT_EXPORT ( FT_Error )
FT_Open_Face ( FT_Library library ,
const FT_Open_Args * args ,
@ -2521,7 +2626,7 @@ FT_BEGIN_HEADER
* FT_LOAD_XXX
*
* @ description :
* A list of bit - field constants used with @ FT_Load_Glyph to indicate
* A list of bit field constants used with @ FT_Load_Glyph to indicate
* what kind of operations to perform during glyph loading .
*
* @ values :