• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /****************************************************************************
2  *
3  * ftincrem.h
4  *
5  *   FreeType incremental loading (specification).
6  *
7  * Copyright 2002-2018 by
8  * David Turner, Robert Wilhelm, and Werner Lemberg.
9  *
10  * This file is part of the FreeType project, and may only be used,
11  * modified, and distributed under the terms of the FreeType project
12  * license, LICENSE.TXT.  By continuing to use, modify, or distribute
13  * this file you indicate that you have read the license and
14  * understand and accept it fully.
15  *
16  */
17 
18 
19 #ifndef FTINCREM_H_
20 #define FTINCREM_H_
21 
22 #include <ft2build.h>
23 #include FT_FREETYPE_H
24 #include FT_PARAMETER_TAGS_H
25 
26 #ifdef FREETYPE_H
27 #error "freetype.h of FreeType 1 has been loaded!"
28 #error "Please fix the directory search order for header files"
29 #error "so that freetype.h of FreeType 2 is found first."
30 #endif
31 
32 
33 FT_BEGIN_HEADER
34 
35   /***************************************************************************
36    *
37    * @section:
38    *    incremental
39    *
40    * @title:
41    *    Incremental Loading
42    *
43    * @abstract:
44    *    Custom Glyph Loading.
45    *
46    * @description:
47    *   This section contains various functions used to perform so-called
48    *   `incremental' glyph loading.  This is a mode where all glyphs loaded
49    *   from a given @FT_Face are provided by the client application.
50    *
51    *   Apart from that, all other tables are loaded normally from the font
52    *   file.  This mode is useful when FreeType is used within another
53    *   engine, e.g., a PostScript Imaging Processor.
54    *
55    *   To enable this mode, you must use @FT_Open_Face, passing an
56    *   @FT_Parameter with the @FT_PARAM_TAG_INCREMENTAL tag and an
57    *   @FT_Incremental_Interface value.  See the comments for
58    *   @FT_Incremental_InterfaceRec for an example.
59    *
60    */
61 
62 
63   /***************************************************************************
64    *
65    * @type:
66    *   FT_Incremental
67    *
68    * @description:
69    *   An opaque type describing a user-provided object used to implement
70    *   `incremental' glyph loading within FreeType.  This is used to support
71    *   embedded fonts in certain environments (e.g., PostScript interpreters),
72    *   where the glyph data isn't in the font file, or must be overridden by
73    *   different values.
74    *
75    * @note:
76    *   It is up to client applications to create and implement @FT_Incremental
77    *   objects, as long as they provide implementations for the methods
78    *   @FT_Incremental_GetGlyphDataFunc, @FT_Incremental_FreeGlyphDataFunc
79    *   and @FT_Incremental_GetGlyphMetricsFunc.
80    *
81    *   See the description of @FT_Incremental_InterfaceRec to understand how
82    *   to use incremental objects with FreeType.
83    *
84    */
85   typedef struct FT_IncrementalRec_*  FT_Incremental;
86 
87 
88   /***************************************************************************
89    *
90    * @struct:
91    *   FT_Incremental_MetricsRec
92    *
93    * @description:
94    *   A small structure used to contain the basic glyph metrics returned
95    *   by the @FT_Incremental_GetGlyphMetricsFunc method.
96    *
97    * @fields:
98    *   bearing_x ::
99    *     Left bearing, in font units.
100    *
101    *   bearing_y ::
102    *     Top bearing, in font units.
103    *
104    *   advance ::
105    *     Horizontal component of glyph advance, in font units.
106    *
107    *   advance_v ::
108    *     Vertical component of glyph advance, in font units.
109    *
110    * @note:
111    *   These correspond to horizontal or vertical metrics depending on the
112    *   value of the `vertical' argument to the function
113    *   @FT_Incremental_GetGlyphMetricsFunc.
114    *
115    */
116   typedef struct  FT_Incremental_MetricsRec_
117   {
118     FT_Long  bearing_x;
119     FT_Long  bearing_y;
120     FT_Long  advance;
121     FT_Long  advance_v;     /* since 2.3.12 */
122 
123   } FT_Incremental_MetricsRec;
124 
125 
126   /***************************************************************************
127    *
128    * @struct:
129    *   FT_Incremental_Metrics
130    *
131    * @description:
132    *   A handle to an @FT_Incremental_MetricsRec structure.
133    *
134    */
135    typedef struct FT_Incremental_MetricsRec_*  FT_Incremental_Metrics;
136 
137 
138   /***************************************************************************
139    *
140    * @type:
141    *   FT_Incremental_GetGlyphDataFunc
142    *
143    * @description:
144    *   A function called by FreeType to access a given glyph's data bytes
145    *   during @FT_Load_Glyph or @FT_Load_Char if incremental loading is
146    *   enabled.
147    *
148    *   Note that the format of the glyph's data bytes depends on the font
149    *   file format.  For TrueType, it must correspond to the raw bytes within
150    *   the `glyf' table.  For PostScript formats, it must correspond to the
151    *   *unencrypted* charstring bytes, without any `lenIV' header.  It is
152    *   undefined for any other format.
153    *
154    * @input:
155    *   incremental ::
156    *     Handle to an opaque @FT_Incremental handle provided by the client
157    *     application.
158    *
159    *   glyph_index ::
160    *     Index of relevant glyph.
161    *
162    * @output:
163    *   adata ::
164    *     A structure describing the returned glyph data bytes (which will be
165    *     accessed as a read-only byte block).
166    *
167    * @return:
168    *   FreeType error code.  0~means success.
169    *
170    * @note:
171    *   If this function returns successfully the method
172    *   @FT_Incremental_FreeGlyphDataFunc will be called later to release
173    *   the data bytes.
174    *
175    *   Nested calls to @FT_Incremental_GetGlyphDataFunc can happen for
176    *   compound glyphs.
177    *
178    */
179   typedef FT_Error
180   (*FT_Incremental_GetGlyphDataFunc)( FT_Incremental  incremental,
181                                       FT_UInt         glyph_index,
182                                       FT_Data*        adata );
183 
184 
185   /***************************************************************************
186    *
187    * @type:
188    *   FT_Incremental_FreeGlyphDataFunc
189    *
190    * @description:
191    *   A function used to release the glyph data bytes returned by a
192    *   successful call to @FT_Incremental_GetGlyphDataFunc.
193    *
194    * @input:
195    *   incremental ::
196    *     A handle to an opaque @FT_Incremental handle provided by the client
197    *     application.
198    *
199    *   data ::
200    *     A structure describing the glyph data bytes (which will be accessed
201    *     as a read-only byte block).
202    *
203    */
204   typedef void
205   (*FT_Incremental_FreeGlyphDataFunc)( FT_Incremental  incremental,
206                                        FT_Data*        data );
207 
208 
209   /***************************************************************************
210    *
211    * @type:
212    *   FT_Incremental_GetGlyphMetricsFunc
213    *
214    * @description:
215    *   A function used to retrieve the basic metrics of a given glyph index
216    *   before accessing its data.  This is necessary because, in certain
217    *   formats like TrueType, the metrics are stored in a different place from
218    *   the glyph images proper.
219    *
220    * @input:
221    *   incremental ::
222    *     A handle to an opaque @FT_Incremental handle provided by the client
223    *     application.
224    *
225    *   glyph_index ::
226    *     Index of relevant glyph.
227    *
228    *   vertical ::
229    *     If true, return vertical metrics.
230    *
231    *   ametrics ::
232    *     This parameter is used for both input and output.
233    *     The original glyph metrics, if any, in font units.  If metrics are
234    *     not available all the values must be set to zero.
235    *
236    * @output:
237    *   ametrics ::
238    *     The replacement glyph metrics in font units.
239    *
240    */
241   typedef FT_Error
242   (*FT_Incremental_GetGlyphMetricsFunc)
243                       ( FT_Incremental              incremental,
244                         FT_UInt                     glyph_index,
245                         FT_Bool                     vertical,
246                         FT_Incremental_MetricsRec  *ametrics );
247 
248 
249   /**************************************************************************
250    *
251    * @struct:
252    *   FT_Incremental_FuncsRec
253    *
254    * @description:
255    *   A table of functions for accessing fonts that load data
256    *   incrementally.  Used in @FT_Incremental_InterfaceRec.
257    *
258    * @fields:
259    *   get_glyph_data ::
260    *     The function to get glyph data.  Must not be null.
261    *
262    *   free_glyph_data ::
263    *     The function to release glyph data.  Must not be null.
264    *
265    *   get_glyph_metrics ::
266    *     The function to get glyph metrics.  May be null if the font does
267    *     not provide overriding glyph metrics.
268    *
269    */
270   typedef struct  FT_Incremental_FuncsRec_
271   {
272     FT_Incremental_GetGlyphDataFunc     get_glyph_data;
273     FT_Incremental_FreeGlyphDataFunc    free_glyph_data;
274     FT_Incremental_GetGlyphMetricsFunc  get_glyph_metrics;
275 
276   } FT_Incremental_FuncsRec;
277 
278 
279   /***************************************************************************
280    *
281    * @struct:
282    *   FT_Incremental_InterfaceRec
283    *
284    * @description:
285    *   A structure to be used with @FT_Open_Face to indicate that the user
286    *   wants to support incremental glyph loading.  You should use it with
287    *   @FT_PARAM_TAG_INCREMENTAL as in the following example:
288    *
289    *   {
290    *     FT_Incremental_InterfaceRec  inc_int;
291    *     FT_Parameter                 parameter;
292    *     FT_Open_Args                 open_args;
293    *
294    *
295    *     // set up incremental descriptor
296    *     inc_int.funcs  = my_funcs;
297    *     inc_int.object = my_object;
298    *
299    *     // set up optional parameter
300    *     parameter.tag  = FT_PARAM_TAG_INCREMENTAL;
301    *     parameter.data = &inc_int;
302    *
303    *     // set up FT_Open_Args structure
304    *     open_args.flags      = FT_OPEN_PATHNAME | FT_OPEN_PARAMS;
305    *     open_args.pathname   = my_font_pathname;
306    *     open_args.num_params = 1;
307    *     open_args.params     = &parameter; // we use one optional argument
308    *
309    *     // open the font
310    *     error = FT_Open_Face( library, &open_args, index, &face );
311    *     ...
312    *   }
313    *
314    */
315   typedef struct  FT_Incremental_InterfaceRec_
316   {
317     const FT_Incremental_FuncsRec*  funcs;
318     FT_Incremental                  object;
319 
320   } FT_Incremental_InterfaceRec;
321 
322 
323   /***************************************************************************
324    *
325    * @type:
326    *   FT_Incremental_Interface
327    *
328    * @description:
329    *   A pointer to an @FT_Incremental_InterfaceRec structure.
330    *
331    */
332   typedef FT_Incremental_InterfaceRec*   FT_Incremental_Interface;
333 
334 
335   /* */
336 
337 
338 FT_END_HEADER
339 
340 #endif /* FTINCREM_H_ */
341 
342 
343 /* END */
344