1 /***************************************************************************/
5 /* High-level `sfnt' driver interface (specification). */
7 /* Copyright 1996-2000 by */
8 /* David Turner, Robert Wilhelm, and Werner Lemberg. */
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. */
16 /***************************************************************************/
23 #include <freetype/freetype.h>
24 #include <freetype/internal/ftdriver.h>
25 #include <freetype/internal/tttypes.h>
28 /*************************************************************************/
31 /* TT_Init_Face_Func */
34 /* First part of the SFNT face object initialization. This will find */
35 /* the face in a SFNT file or collection, and load its format tag in */
36 /* face->format_tag. */
39 /* stream :: The input stream. */
41 /* face :: A handle to the target face object. */
43 /* face_index :: The index of the TrueType font, if we are opening a */
46 /* num_params :: The number of additional parameters. */
48 /* params :: Optional additional parameters. */
51 /* FreeType error code. 0 means success. */
54 /* The stream cursor must be at the font file's origin. */
56 /* This function recognizes fonts embedded in a `TrueType */
59 /* Once the format tag has been validated by the font driver, it */
60 /* should then call the TT_Load_Face_Func() callback to read the rest */
61 /* of the SFNT tables in the object. */
64 FT_Error (*TT_Init_Face_Func)( FT_Stream stream,
68 FT_Parameter* params );
71 /*************************************************************************/
74 /* TT_Load_Face_Func */
77 /* Second part of the SFNT face object initialization. This will */
78 /* load the common SFNT tables (head, OS/2, maxp, metrics, etc.) in */
79 /* the face object. */
82 /* stream :: The input stream. */
84 /* face :: A handle to the target face object. */
86 /* face_index :: The index of the TrueType font, if we are opening a */
89 /* num_params :: The number of additional parameters. */
91 /* params :: Optional additional parameters. */
94 /* FreeType error code. 0 means success. */
97 /* This function must be called after TT_Init_Face_Func(). */
100 FT_Error (*TT_Load_Face_Func)( FT_Stream stream,
104 FT_Parameter* params );
107 /*************************************************************************/
110 /* TT_Done_Face_Func */
113 /* A callback used to delete the common SFNT data from a face. */
116 /* face :: A handle to the target face object. */
119 /* This function does NOT destroy the face object. */
122 void (*TT_Done_Face_Func)( TT_Face face );
126 FT_Module_Interface (*SFNT_Get_Interface_Func)( FT_Module module,
127 const char* interface );
130 /*************************************************************************/
133 /* TT_Load_SFNT_Header_Func */
136 /* Loads the header of a SFNT font file. Supports collections. */
139 /* face :: A handle to the target face object. */
141 /* stream :: The input stream. */
143 /* face_index :: The index of the TrueType font, if we are opening a */
147 /* sfnt :: The SFNT header. */
150 /* FreeType error code. 0 means success. */
153 /* The stream cursor must be at the font file's origin. */
155 /* This function recognizes fonts embedded in a `TrueType */
158 /* This function checks that the header is valid by looking at the */
159 /* values of `search_range', `entry_selector', and `range_shift'. */
162 FT_Error (*TT_Load_SFNT_Header_Func)( TT_Face face,
168 /*************************************************************************/
171 /* TT_Load_Directory_Func */
174 /* Loads the table directory into a face object. */
177 /* face :: A handle to the target face object. */
179 /* stream :: The input stream. */
181 /* sfnt :: The SFNT header. */
184 /* FreeType error code. 0 means success. */
187 /* The stream cursor must be on the first byte after the 4-byte font */
188 /* format tag. This is the case just after a call to */
189 /* TT_Load_Format_Tag(). */
192 FT_Error (*TT_Load_Directory_Func)( TT_Face face,
197 /*************************************************************************/
200 /* TT_Load_Any_Func */
203 /* Loads any font table into client memory. */
206 /* face :: The face object to look for. */
208 /* tag :: The tag of table to load. Use the value 0 if you want */
209 /* to access the whole font file, else set this parameter */
210 /* to a valid TrueType table tag that you can forge with */
211 /* the MAKE_TT_TAG macro. */
213 /* offset :: The starting offset in the table (or the file if */
216 /* length :: The address of the decision variable: */
218 /* If length == NULL: */
219 /* Loads the whole table. Returns an error if */
222 /* If *length == 0: */
223 /* Exits immediately; returning the length of the given */
224 /* table or of the font file, depending on the value of */
227 /* If *length != 0: */
228 /* Loads the next `length' bytes of table or font, */
229 /* starting at offset `offset' (in table or font too). */
232 /* buffer :: The address of target buffer. */
235 /* TrueType error code. 0 means success. */
238 FT_Error (*TT_Load_Any_Func)( TT_Face face,
245 /*************************************************************************/
248 /* TT_Load_SBit_Image_Func */
251 /* Loads a given glyph sbit image from the font resource. This also */
252 /* returns its metrics. */
255 /* face :: The target face object. */
257 /* x_ppem :: The horizontal resolution in points per EM. */
259 /* y_ppem :: The vertical resolution in points per EM. */
261 /* glyph_index :: The current glyph index. */
263 /* stream :: The input stream. */
266 /* map :: The target pixmap. */
268 /* metrics :: A big sbit metrics structure for the glyph image. */
271 /* FreeType error code. 0 means success. Returns an error if no */
272 /* glyph sbit exists for the index. */
275 /* The `map.buffer' field is always freed before the glyph is loaded. */
278 FT_Error (*TT_Load_SBit_Image_Func)( TT_Face face,
285 TT_SBit_Metrics* metrics );
288 /*************************************************************************/
291 /* TT_Get_PS_Name_Func */
294 /* Gets the PostScript glyph name of a glyph. */
297 /* index :: The glyph index. */
299 /* PSname :: The address of a string pointer. Will be NULL in case */
300 /* of error, otherwise it is a pointer to the glyph name. */
302 /* You must not modify the returned string! */
305 /* FreeType error code. 0 means success. */
308 FT_Error (*TT_Get_PS_Name_Func)( TT_Face face,
310 FT_String** PSname );
313 /*************************************************************************/
316 /* TT_Load_Metrics_Func */
319 /* Loads the horizontal or vertical header in a face object. */
322 /* face :: A handle to the target face object. */
324 /* stream :: The input stream. */
326 /* vertical :: A boolean flag. If set, load vertical metrics. */
329 /* FreeType error code. 0 means success. */
332 FT_Error (*TT_Load_Metrics_Func)( TT_Face face,
337 /*************************************************************************/
340 /* TT_CharMap_Load_Func */
343 /* Loads a given TrueType character map into memory. */
346 /* face :: A handle to the parent face object. */
348 /* stream :: A handle to the current stream object. */
351 /* cmap :: A pointer to a cmap object. */
354 /* FreeType error code. 0 means success. */
357 /* The function assumes that the stream is already in use (i.e., */
358 /* opened). In case of error, all partially allocated tables are */
362 FT_Error (*TT_CharMap_Load_Func)( TT_Face face,
367 /*************************************************************************/
370 /* TT_CharMap_Free_Func */
373 /* Destroys a character mapping table. */
376 /* face :: A handle to the parent face object. */
378 /* cmap :: A handle to a cmap object. */
381 /* FreeType error code. 0 means success. */
384 FT_Error (*TT_CharMap_Free_Func)( TT_Face face,
385 TT_CMapTable* cmap );
388 /*************************************************************************/
391 /* TT_Load_Table_Func */
394 /* Loads a given TrueType table. */
397 /* face :: A handle to the target face object. */
399 /* stream :: The input stream. */
402 /* FreeType error code. 0 means success. */
405 /* The function will use `face->goto_table' to seek the stream to */
406 /* the start of the table. */
409 FT_Error (*TT_Load_Table_Func)( TT_Face face,
413 /*************************************************************************/
416 /* TT_Free_Table_Func */
419 /* Frees a given TrueType table. */
422 /* face :: A handle to the target face object. */
425 void (*TT_Free_Table_Func)( TT_Face face );
428 /*************************************************************************/
434 /* This structure holds pointers to the functions used to load and */
435 /* free the basic tables that are required in a `sfnt' font file. */
438 /* Check the various xxx_Func() descriptions for details. */
440 typedef struct SFNT_Interface_
442 TT_Goto_Table_Func goto_table;
444 TT_Init_Face_Func init_face;
445 TT_Load_Face_Func load_face;
446 TT_Done_Face_Func done_face;
447 SFNT_Get_Interface_Func get_interface;
449 TT_Load_Any_Func load_any;
450 TT_Load_SFNT_Header_Func load_sfnt_header;
451 TT_Load_Directory_Func load_directory;
453 /* these functions are called by `load_face' but they can also */
454 /* be called from external modules, if there is a need to do so */
455 TT_Load_Table_Func load_header;
456 TT_Load_Metrics_Func load_metrics;
457 TT_Load_Table_Func load_charmaps;
458 TT_Load_Table_Func load_max_profile;
459 TT_Load_Table_Func load_os2;
460 TT_Load_Table_Func load_psnames;
462 TT_Load_Table_Func load_names;
463 TT_Free_Table_Func free_names;
465 /* optional tables */
466 TT_Load_Table_Func load_hdmx;
467 TT_Free_Table_Func free_hdmx;
469 TT_Load_Table_Func load_kerning;
470 TT_Load_Table_Func load_gasp;
471 TT_Load_Table_Func load_pclt;
474 TT_Load_Table_Func load_sbits;
475 TT_Load_SBit_Image_Func load_sbit_image;
476 TT_Free_Table_Func free_sbits;
479 TT_Get_PS_Name_Func get_psname;
480 TT_Free_Table_Func free_psnames;
483 TT_CharMap_Load_Func load_charmap;
484 TT_CharMap_Free_Func free_charmap;