/***************************************************************************/ | |
/* */ | |
/* ftincrem.h */ | |
/* */ | |
/* FreeType incremental loading (specification). */ | |
/* */ | |
/* Copyright 2002-2015 by */ | |
/* David Turner, Robert Wilhelm, and Werner Lemberg. */ | |
/* */ | |
/* This file is part of the FreeType project, and may only be used, */ | |
/* modified, and distributed under the terms of the FreeType project */ | |
/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ | |
/* this file you indicate that you have read the license and */ | |
/* understand and accept it fully. */ | |
/* */ | |
/***************************************************************************/ | |
#ifndef __FTINCREM_H__ | |
#define __FTINCREM_H__ | |
#include <ft2build.h> | |
#include FT_FREETYPE_H | |
#ifdef FREETYPE_H | |
#error "freetype.h of FreeType 1 has been loaded!" | |
#error "Please fix the directory search order for header files" | |
#error "so that freetype.h of FreeType 2 is found first." | |
#endif | |
FT_BEGIN_HEADER | |
/*************************************************************************** | |
* | |
* @section: | |
* incremental | |
* | |
* @title: | |
* Incremental Loading | |
* | |
* @abstract: | |
* Custom Glyph Loading. | |
* | |
* @description: | |
* This section contains various functions used to perform so-called | |
* `incremental' glyph loading. This is a mode where all glyphs loaded | |
* from a given @FT_Face are provided by the client application. | |
* | |
* Apart from that, all other tables are loaded normally from the font | |
* file. This mode is useful when FreeType is used within another | |
* engine, e.g., a PostScript Imaging Processor. | |
* | |
* To enable this mode, you must use @FT_Open_Face, passing an | |
* @FT_Parameter with the @FT_PARAM_TAG_INCREMENTAL tag and an | |
* @FT_Incremental_Interface value. See the comments for | |
* @FT_Incremental_InterfaceRec for an example. | |
* | |
*/ | |
/*************************************************************************** | |
* | |
* @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_MetricsRec | |
* | |
* @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 :: | |
* Horizontal component of glyph advance, in font units. | |
* | |
* advance_v :: | |
* Vertical component of 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_Long advance_v; /* since 2.3.12 */ | |
} FT_Incremental_MetricsRec; | |
/*************************************************************************** | |
* | |
* @struct: | |
* FT_Incremental_Metrics | |
* | |
* @description: | |
* A handle to an @FT_Incremental_MetricsRec structure. | |
* | |
*/ | |
typedef struct 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 successfully 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 :: | |
* A handle to an opaque @FT_Incremental handle provided by the client | |
* application. | |
* | |
* data :: | |
* A structure describing the glyph data bytes (which will be accessed | |
* as a read-only byte block). | |
* | |
*/ | |
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 :: | |
* A handle to an opaque @FT_Incremental handle provided by the client | |
* application. | |
* | |
* glyph_index :: | |
* Index of relevant glyph. | |
* | |
* vertical :: | |
* If true, return vertical metrics. | |
* | |
* ametrics :: | |
* This parameter is used for both input and output. | |
* The original glyph metrics, if any, in font units. If metrics are | |
* not available all the values must be set to zero. | |
* | |
* @output: | |
* ametrics :: | |
* The replacement glyph metrics in font units. | |
* | |
*/ | |
typedef FT_Error | |
(*FT_Incremental_GetGlyphMetricsFunc) | |
( FT_Incremental incremental, | |
FT_UInt glyph_index, | |
FT_Bool vertical, | |
FT_Incremental_MetricsRec *ametrics ); | |
/************************************************************************** | |
* | |
* @struct: | |
* FT_Incremental_FuncsRec | |
* | |
* @description: | |
* A table of functions for accessing fonts that load data | |
* incrementally. Used in @FT_Incremental_InterfaceRec. | |
* | |
* @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_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 font | |
* 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; | |
/*************************************************************************** | |
* | |
* @type: | |
* FT_Incremental_Interface | |
* | |
* @description: | |
* A pointer to an @FT_Incremental_InterfaceRec structure. | |
* | |
*/ | |
typedef FT_Incremental_InterfaceRec* FT_Incremental_Interface; | |
/*************************************************************************** | |
* | |
* @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 /* __FTINCREM_H__ */ | |
/* END */ |