1 /***************************************************************************/
5 /* High-level `sfnt' driver interface (specification). */
7 /* Copyright 1996-2016 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 /***************************************************************************/
24 #include FT_INTERNAL_DRIVER_H
25 #include FT_INTERNAL_TRUETYPE_TYPES_H
31 /*************************************************************************/
34 /* TT_Init_Face_Func */
37 /* First part of the SFNT face object initialization. This finds */
38 /* the face in a SFNT file or collection, and load its format tag in */
39 /* face->format_tag. */
42 /* stream :: The input stream. */
44 /* face :: A handle to the target face object. */
46 /* face_index :: The index of the TrueType font, if we are opening a */
47 /* collection, in bits 0-15. The numbered instance */
48 /* index~+~1 of a GX (sub)font, if applicable, in bits */
51 /* num_params :: The number of additional parameters. */
53 /* params :: Optional additional parameters. */
56 /* FreeType error code. 0 means success. */
59 /* The stream cursor must be at the font file's origin. */
61 /* This function recognizes fonts embedded in a `TrueType */
64 /* Once the format tag has been validated by the font driver, it */
65 /* should then call the TT_Load_Face_Func() callback to read the rest */
66 /* of the SFNT tables in the object. */
69 (*TT_Init_Face_Func
)( FT_Stream stream
,
73 FT_Parameter
* params
);
76 /*************************************************************************/
79 /* TT_Load_Face_Func */
82 /* Second part of the SFNT face object initialization. This loads */
83 /* the common SFNT tables (head, OS/2, maxp, metrics, etc.) in the */
87 /* stream :: The input stream. */
89 /* face :: A handle to the target face object. */
91 /* face_index :: The index of the TrueType font, if we are opening a */
92 /* collection, in bits 0-15. The numbered instance */
93 /* index~+~1 of a GX (sub)font, if applicable, in bits */
96 /* num_params :: The number of additional parameters. */
98 /* params :: Optional additional parameters. */
101 /* FreeType error code. 0 means success. */
104 /* This function must be called after TT_Init_Face_Func(). */
107 (*TT_Load_Face_Func
)( FT_Stream stream
,
111 FT_Parameter
* params
);
114 /*************************************************************************/
117 /* TT_Done_Face_Func */
120 /* A callback used to delete the common SFNT data from a face. */
123 /* face :: A handle to the target face object. */
126 /* This function does NOT destroy the face object. */
129 (*TT_Done_Face_Func
)( TT_Face face
);
132 /*************************************************************************/
135 /* TT_Load_Any_Func */
138 /* Load any font table into client memory. */
141 /* face :: The face object to look for. */
143 /* tag :: The tag of table to load. Use the value 0 if you want */
144 /* to access the whole font file, else set this parameter */
145 /* to a valid TrueType table tag that you can forge with */
146 /* the MAKE_TT_TAG macro. */
148 /* offset :: The starting offset in the table (or the file if */
151 /* length :: The address of the decision variable: */
153 /* If length == NULL: */
154 /* Loads the whole table. Returns an error if */
157 /* If *length == 0: */
158 /* Exits immediately; returning the length of the given */
159 /* table or of the font file, depending on the value of */
162 /* If *length != 0: */
163 /* Loads the next `length' bytes of table or font, */
164 /* starting at offset `offset' (in table or font too). */
167 /* buffer :: The address of target buffer. */
170 /* TrueType error code. 0 means success. */
173 (*TT_Load_Any_Func
)( TT_Face face
,
180 /*************************************************************************/
183 /* TT_Find_SBit_Image_Func */
186 /* Check whether an embedded bitmap (an `sbit') exists for a given */
187 /* glyph, at a given strike. */
190 /* face :: The target face object. */
192 /* glyph_index :: The glyph index. */
194 /* strike_index :: The current strike index. */
197 /* arange :: The SBit range containing the glyph index. */
199 /* astrike :: The SBit strike containing the glyph index. */
201 /* aglyph_offset :: The offset of the glyph data in `EBDT' table. */
204 /* FreeType error code. 0 means success. Returns */
205 /* SFNT_Err_Invalid_Argument if no sbit exists for the requested */
209 (*TT_Find_SBit_Image_Func
)( TT_Face face
,
211 FT_ULong strike_index
,
212 TT_SBit_Range
*arange
,
213 TT_SBit_Strike
*astrike
,
214 FT_ULong
*aglyph_offset
);
217 /*************************************************************************/
220 /* TT_Load_SBit_Metrics_Func */
223 /* Get the big metrics for a given embedded bitmap. */
226 /* stream :: The input stream. */
228 /* range :: The SBit range containing the glyph. */
231 /* big_metrics :: A big SBit metrics structure for the glyph. */
234 /* FreeType error code. 0 means success. */
237 /* The stream cursor must be positioned at the glyph's offset within */
238 /* the `EBDT' table before the call. */
240 /* If the image format uses variable metrics, the stream cursor is */
241 /* positioned just after the metrics header in the `EBDT' table on */
245 (*TT_Load_SBit_Metrics_Func
)( FT_Stream stream
,
247 TT_SBit_Metrics metrics
);
250 /*************************************************************************/
253 /* TT_Load_SBit_Image_Func */
256 /* Load a given glyph sbit image from the font resource. This also */
257 /* returns its metrics. */
261 /* The target face object. */
263 /* strike_index :: */
264 /* The strike index. */
267 /* The current glyph index. */
270 /* The current load flags. */
273 /* The input stream. */
277 /* The target pixmap. */
280 /* A big sbit metrics structure for the glyph image. */
283 /* FreeType error code. 0 means success. Returns an error if no */
284 /* glyph sbit exists for the index. */
287 /* The `map.buffer' field is always freed before the glyph is loaded. */
290 (*TT_Load_SBit_Image_Func
)( TT_Face face
,
291 FT_ULong strike_index
,
296 TT_SBit_MetricsRec
*ametrics
);
299 /*************************************************************************/
302 /* TT_Set_SBit_Strike_Func */
305 /* Select an sbit strike for a given size request. */
308 /* face :: The target face object. */
310 /* req :: The size request. */
313 /* astrike_index :: The index of the sbit strike. */
316 /* FreeType error code. 0 means success. Returns an error if no */
317 /* sbit strike exists for the selected ppem values. */
320 (*TT_Set_SBit_Strike_Func
)( TT_Face face
,
322 FT_ULong
* astrike_index
);
325 /*************************************************************************/
328 /* TT_Load_Strike_Metrics_Func */
331 /* Load the metrics of a given strike. */
334 /* face :: The target face object. */
336 /* strike_index :: The strike index. */
339 /* metrics :: the metrics of the strike. */
342 /* FreeType error code. 0 means success. Returns an error if no */
343 /* such sbit strike exists. */
346 (*TT_Load_Strike_Metrics_Func
)( TT_Face face
,
347 FT_ULong strike_index
,
348 FT_Size_Metrics
* metrics
);
351 /*************************************************************************/
354 /* TT_Get_PS_Name_Func */
357 /* Get the PostScript glyph name of a glyph. */
360 /* idx :: The glyph index. */
362 /* PSname :: The address of a string pointer. Will be NULL in case */
363 /* of error, otherwise it is a pointer to the glyph name. */
365 /* You must not modify the returned string! */
368 /* FreeType error code. 0 means success. */
371 (*TT_Get_PS_Name_Func
)( TT_Face face
,
373 FT_String
** PSname
);
376 /*************************************************************************/
379 /* TT_Load_Metrics_Func */
382 /* Load a metrics table, which is a table with a horizontal and a */
383 /* vertical version. */
386 /* face :: A handle to the target face object. */
388 /* stream :: The input stream. */
390 /* vertical :: A boolean flag. If set, load the vertical one. */
393 /* FreeType error code. 0 means success. */
396 (*TT_Load_Metrics_Func
)( TT_Face face
,
401 /*************************************************************************/
404 /* TT_Get_Metrics_Func */
407 /* Load the horizontal or vertical header in a face object. */
410 /* face :: A handle to the target face object. */
412 /* vertical :: A boolean flag. If set, load vertical metrics. */
414 /* gindex :: The glyph index. */
417 /* abearing :: The horizontal (or vertical) bearing. Set to zero in */
420 /* aadvance :: The horizontal (or vertical) advance. Set to zero in */
424 (*TT_Get_Metrics_Func
)( TT_Face face
,
428 FT_UShort
* aadvance
);
431 /*************************************************************************/
434 /* TT_Get_Name_Func */
437 /* From the `name' table, return a given ENGLISH name record in */
441 /* face :: A handle to the source face object. */
443 /* nameid :: The name id of the name record to return. */
446 /* name :: The address of an allocated string pointer. NULL if */
447 /* no name is present. */
450 /* FreeType error code. 0 means success. */
453 (*TT_Get_Name_Func
)( TT_Face face
,
458 /*************************************************************************/
461 /* TT_Load_Table_Func */
464 /* Load a given TrueType table. */
467 /* face :: A handle to the target face object. */
469 /* stream :: The input stream. */
472 /* FreeType error code. 0 means success. */
475 /* The function uses `face->goto_table' to seek the stream to the */
476 /* start of the table, except while loading the font directory. */
479 (*TT_Load_Table_Func
)( TT_Face face
,
483 /*************************************************************************/
486 /* TT_Free_Table_Func */
489 /* Free a given TrueType table. */
492 /* face :: A handle to the target face object. */
495 (*TT_Free_Table_Func
)( TT_Face face
);
500 * TT_Face_GetKerningFunc
503 * Return the horizontal kerning value between two glyphs.
506 * face :: A handle to the source face object.
507 * left_glyph :: The left glyph index.
508 * right_glyph :: The right glyph index.
511 * The kerning value in font units.
514 (*TT_Face_GetKerningFunc
)( TT_Face face
,
516 FT_UInt right_glyph
);
519 /*************************************************************************/
525 /* This structure holds pointers to the functions used to load and */
526 /* free the basic tables that are required in a `sfnt' font file. */
529 /* Check the various xxx_Func() descriptions for details. */
531 typedef struct SFNT_Interface_
533 TT_Loader_GotoTableFunc goto_table
;
535 TT_Init_Face_Func init_face
;
536 TT_Load_Face_Func load_face
;
537 TT_Done_Face_Func done_face
;
538 FT_Module_Requester get_interface
;
540 TT_Load_Any_Func load_any
;
542 /* these functions are called by `load_face' but they can also */
543 /* be called from external modules, if there is a need to do so */
544 TT_Load_Table_Func load_head
;
545 TT_Load_Metrics_Func load_hhea
;
546 TT_Load_Table_Func load_cmap
;
547 TT_Load_Table_Func load_maxp
;
548 TT_Load_Table_Func load_os2
;
549 TT_Load_Table_Func load_post
;
551 TT_Load_Table_Func load_name
;
552 TT_Free_Table_Func free_name
;
554 /* this field was called `load_kerning' up to version 2.1.10 */
555 TT_Load_Table_Func load_kern
;
557 TT_Load_Table_Func load_gasp
;
558 TT_Load_Table_Func load_pclt
;
560 /* see `ttload.h'; this field was called `load_bitmap_header' up to */
562 TT_Load_Table_Func load_bhed
;
564 TT_Load_SBit_Image_Func load_sbit_image
;
567 TT_Get_PS_Name_Func get_psname
;
568 TT_Free_Table_Func free_psnames
;
570 /* starting here, the structure differs from version 2.1.7 */
572 /* this field was introduced in version 2.1.8, named `get_psname' */
573 TT_Face_GetKerningFunc get_kerning
;
575 /* new elements introduced after version 2.1.10 */
577 /* load the font directory, i.e., the offset table and */
578 /* the table directory */
579 TT_Load_Table_Func load_font_dir
;
580 TT_Load_Metrics_Func load_hmtx
;
582 TT_Load_Table_Func load_eblc
;
583 TT_Free_Table_Func free_eblc
;
585 TT_Set_SBit_Strike_Func set_sbit_strike
;
586 TT_Load_Strike_Metrics_Func load_strike_metrics
;
588 TT_Get_Metrics_Func get_metrics
;
590 TT_Get_Name_Func get_name
;
596 typedef SFNT_Interface
* SFNT_Service
;
598 #ifndef FT_CONFIG_OPTION_PIC
600 #define FT_DEFINE_SFNT_INTERFACE( \
629 load_strike_metrics_, \
632 static const SFNT_Interface class_ = \
661 load_strike_metrics_, \
666 #else /* FT_CONFIG_OPTION_PIC */
668 #define FT_INTERNAL( a, a_ ) \
671 #define FT_DEFINE_SFNT_INTERFACE( \
700 load_strike_metrics_, \
704 FT_Init_Class_ ## class_( FT_Library library, \
705 SFNT_Interface* clazz ) \
707 FT_UNUSED( library ); \
709 clazz->goto_table = goto_table_; \
710 clazz->init_face = init_face_; \
711 clazz->load_face = load_face_; \
712 clazz->done_face = done_face_; \
713 clazz->get_interface = get_interface_; \
714 clazz->load_any = load_any_; \
715 clazz->load_head = load_head_; \
716 clazz->load_hhea = load_hhea_; \
717 clazz->load_cmap = load_cmap_; \
718 clazz->load_maxp = load_maxp_; \
719 clazz->load_os2 = load_os2_; \
720 clazz->load_post = load_post_; \
721 clazz->load_name = load_name_; \
722 clazz->free_name = free_name_; \
723 clazz->load_kern = load_kern_; \
724 clazz->load_gasp = load_gasp_; \
725 clazz->load_pclt = load_pclt_; \
726 clazz->load_bhed = load_bhed_; \
727 clazz->load_sbit_image = load_sbit_image_; \
728 clazz->get_psname = get_psname_; \
729 clazz->free_psnames = free_psnames_; \
730 clazz->get_kerning = get_kerning_; \
731 clazz->load_font_dir = load_font_dir_; \
732 clazz->load_hmtx = load_hmtx_; \
733 clazz->load_eblc = load_eblc_; \
734 clazz->free_eblc = free_eblc_; \
735 clazz->set_sbit_strike = set_sbit_strike_; \
736 clazz->load_strike_metrics = load_strike_metrics_; \
737 clazz->get_metrics = get_metrics_; \
738 clazz->get_name = get_name_; \
741 #endif /* FT_CONFIG_OPTION_PIC */