ref: ce12182cfc612a5de6b073197f3f3fa60ca98fa8
dir: /include/freetype/ftincrem.h/
#ifndef __FT_INCREMENTAL_H__
#define __FT_INCREMENTAL_H__
#include <ft2build.h>
#include FT_FREETYPE_H
FT_BEGIN_HEADER
/*************************************************************************
*
* @type: FT_Incremental
*
* @description:
* An opaque type describing a user-provided object used to implement
* "incremental" glyph loading within FreeType. This is used to support
* embedded fonts in certain environments (e.g. Postscript interpreters),
* where the glyph data isn't in the font file, or must be overridden by
* different values.
*
* @note:
* It is up to client applications to create and implement @FT_Incremental
* objects, as long as they provide implementations for the methods
* @FT_Incremental_GetGlyphDataFunc, @FT_Incremental_FreeGlyphDataFunc
* and @FT_Incremental_GetGlyphMetricsFunc
*
* see the description of @FT_Incremental_InterfaceRec to understand how
* to use incremental objects with FreeType.
*/
typedef struct FT_IncrementalRec_* FT_Incremental;
/*************************************************************************
*
* @struct: FT_Incremental_Metrics
*
* @description:
* A small structure used to contain the basic glyph metrics returned
* by the @FT_Incremental_GetGlyphMetricsFunc method
*
* @fields:
* bearing_x :: left bearing, in font units.
* bearing_y :: top bearing, in font units.
* advance :: glyph advance, in font units
*
* @note:
* These correspond to horizontal or vertical metrics depending on the
* value of the 'vertical' argument to the function
* @FT_Incremental_GetGlyphMetricsFunc
*/
typedef struct FT_Incremental_MetricsRec_
{
FT_Long bearing_x;
FT_Long bearing_y;
FT_Long advance;
} FT_Incremental_MetricsRec, *FT_Incremental_Metrics;
/**************************************************************************
*
* @type: FT_Incremental_GetGlyphDataFunc
*
* @description:
* A function called by FreeType to access a given glyph's data bytes
* during @FT_Load_Glyph or @FT_Load_Char if incremental loading is
* enabled.
*
* Note that the format of the glyph's data bytes depends on the font
* file format. For TrueType, it must correspond to the raw bytes within
* the 'glyf' table. For Postscript formats, it must correspond to the
* *unencrypted* charstring bytes, without any 'lenIV' header. It is
* undefined for any other format.
*
* @input:
* incremental :: handle to an opaque @FT_Incremental handle provided
* by the client application
*
* glyph_index :: index of relevant glyph
*
* @output:
* adata :: a structure describing the returned glyph data bytes
* (which will be accessed as a read-only byte block)
*
* @return:
* FreeType error code. 0 means success
*
* @note:
* If this function returns succesfully the method
* @FT_Incremental_FreeGlyphDataFunc will be called later to release
* the data bytes.
*
* Nested calls to @FT_Incremental_GetGlyphDataFunc can happen for
* compound glyphs.
*/
typedef FT_Error (*FT_Incremental_GetGlyphDataFunc)
( FT_Incremental incremental,
FT_UInt glyph_index,
FT_Data* adata );
/**************************************************************************
*
* @type: FT_Incremental_FreeGlyphDataFunc
*
* @description:
* A function used to release the glyph data bytes returned by a
* successful call to @FT_Incremental_GetGlyphDataFunc.
*
* @input:
* incremental :: handle to an opaque @FT_Incremental handle provided
* by the client application
*
* data :: glyph_index :: index of relevant glyph
*/
typedef void (*FT_Incremental_FreeGlyphDataFunc)
( FT_Incremental incremental,
FT_Data* data );
/**************************************************************************
*
* @type: FT_Incremental_GetGlyphMetricsFunc
*
* @description:
* A function used to retrieve the basic metrics of a given glyph index
* before accessing its data. This is necessary because, in certain formats
* like TrueType, the metrics are stored in a different place from the
* glyph images proper.
*
* @input:
* incremental :: handle to an opaque @FT_Incremental handle provided
* by the client application
*
*/
typedef FT_Error (*FT_Incremental_GetGlyphMetricsFunc)
( FT_Incremental incremental,
FT_UInt glyph_index,
FT_Bool vertical,
FT_Incremental_MetricsRec *ametrics,
FT_Bool *afound );
/*************************************************************************
*
* @struct: FT_Incremental_FuncsRec
*
* @description:
* A table of functions for accessing fonts that load data
* incrementally. Used in @FT_Incremental_Interface.
*
* @fields:
* get_glyph_data :: The function to get glyph data. Must not be
* null.
*
* free_glyph_data :: The function to release glyph data. Must not
* be null.
*
* get_glyph_metrics :: The function to get glyph metrics. May be
* null if the font does not provide
* overriding glyph metrics.
*/
typedef struct FT_Incremental_FuncsRec_
{
FT_Incremental_GetGlyphDataFunc get_glyph_data;
FT_Incremental_FreeGlyphDataFunc free_glyph_data;
FT_Incremental_GetGlyphMetricsFunc get_glyph_metrics;
} FT_Incremental_FuncsRec;
/**************************************************************************
*
* @struct: FT_Incremental_InterfaceRec
*
* @description:
* A structure to be used with @FT_Open_Face to indicate that the user
* wants to support incremental glyph loading. You should use it with
* @FT_PARAM_TAG_INCREMENTAL as in the following example:
*
* {
* FT_Incremental_InterfaceRec inc_int;
* FT_Parameter parameter;
* FT_Open_Args open_args;
*
* // set up incremental descriptor
* inc_int.funcs = my_funcs;
* inc_int.object = my_object;
*
* // set up optional parameter
* parameter.tag = FT_PARAM_TAG_INCREMENTAL;
* parameter.data = &inc_int;
*
* // set up FT_Open_Args structure
* open_args.flags = (FT_Open_Flags)(ft_open_pathname | ft_open_params);
* open_args.pathname = my_font_pathname;
* open_args.num_params = 1;
* open_args.params = ¶meter; // we use one optional argument
*
* // open the
* error = FT_Open_Face( library, &open_args, index, &face );
* ....
* }
*/
typedef struct FT_Incremental_InterfaceRec_
{
const FT_Incremental_FuncsRec* funcs;
FT_Incremental object;
} FT_Incremental_InterfaceRec;
/**************************************************************************
*
* @constant: FT_PARAM_TAG_INCREMENTAL
*
* @description:
* A constant used as the tag of @FT_Parameter structures to indicate
* an incremental loading object to be used by FreeType.
*
*/
#define FT_PARAM_TAG_INCREMENTAL FT_MAKE_TAG('i','n','c','r')
/* */
FT_END_HEADER
#endif /* __FT_INCREMENTAL_H__ */