1 /***************************************************************************/
5 /* High-level `sfnt' driver interface (specification). */
7 /* Copyright 1996-2001, 2002, 2003, 2004, 2005, 2006 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 */
49 /* num_params :: The number of additional parameters. */
51 /* params :: Optional additional parameters. */
54 /* FreeType error code. 0 means success. */
57 /* The stream cursor must be at the font file's origin. */
59 /* This function recognizes fonts embedded in a `TrueType */
62 /* Once the format tag has been validated by the font driver, it */
63 /* should then call the TT_Load_Face_Func() callback to read the rest */
64 /* of the SFNT tables in the object. */
67 (*TT_Init_Face_Func)( FT_Stream stream,
71 FT_Parameter* params );
74 /*************************************************************************/
77 /* TT_Load_Face_Func */
80 /* Second part of the SFNT face object initialization. This loads */
81 /* the common SFNT tables (head, OS/2, maxp, metrics, etc.) in the */
85 /* stream :: The input stream. */
87 /* face :: A handle to the target face object. */
89 /* face_index :: The index of the TrueType font, if we are opening a */
92 /* num_params :: The number of additional parameters. */
94 /* params :: Optional additional parameters. */
97 /* FreeType error code. 0 means success. */
100 /* This function must be called after TT_Init_Face_Func(). */
103 (*TT_Load_Face_Func)( FT_Stream stream,
107 FT_Parameter* params );
110 /*************************************************************************/
113 /* TT_Done_Face_Func */
116 /* A callback used to delete the common SFNT data from a face. */
119 /* face :: A handle to the target face object. */
122 /* This function does NOT destroy the face object. */
125 (*TT_Done_Face_Func)( TT_Face face );
128 #ifdef FT_CONFIG_OPTION_OLD_INTERNALS
130 /*************************************************************************/
133 /* TT_Load_SFNT_HeaderRec_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 (*TT_Load_SFNT_HeaderRec_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 (*TT_Load_Directory_Func)( TT_Face face,
196 #endif /* FT_CONFIG_OPTION_OLD_INTERNALS */
199 /*************************************************************************/
202 /* TT_Load_Any_Func */
205 /* Load any font table into client memory. */
208 /* face :: The face object to look for. */
210 /* tag :: The tag of table to load. Use the value 0 if you want */
211 /* to access the whole font file, else set this parameter */
212 /* to a valid TrueType table tag that you can forge with */
213 /* the MAKE_TT_TAG macro. */
215 /* offset :: The starting offset in the table (or the file if */
218 /* length :: The address of the decision variable: */
220 /* If length == NULL: */
221 /* Loads the whole table. Returns an error if */
224 /* If *length == 0: */
225 /* Exits immediately; returning the length of the given */
226 /* table or of the font file, depending on the value of */
229 /* If *length != 0: */
230 /* Loads the next `length' bytes of table or font, */
231 /* starting at offset `offset' (in table or font too). */
234 /* buffer :: The address of target buffer. */
237 /* TrueType error code. 0 means success. */
240 (*TT_Load_Any_Func)( TT_Face face,
247 /*************************************************************************/
250 /* TT_Find_SBit_Image_Func */
253 /* Check whether an embedded bitmap (an `sbit') exists for a given */
254 /* glyph, at a given strike. */
257 /* face :: The target face object. */
259 /* glyph_index :: The glyph index. */
261 /* strike_index :: The current strike index. */
264 /* arange :: The SBit range containing the glyph index. */
266 /* astrike :: The SBit strike containing the glyph index. */
268 /* aglyph_offset :: The offset of the glyph data in `EBDT' table. */
271 /* FreeType error code. 0 means success. Returns */
272 /* SFNT_Err_Invalid_Argument if no sbit exists for the requested */
276 (*TT_Find_SBit_Image_Func)( TT_Face face,
278 FT_ULong strike_index,
279 TT_SBit_Range *arange,
280 TT_SBit_Strike *astrike,
281 FT_ULong *aglyph_offset );
284 /*************************************************************************/
287 /* TT_Load_SBit_Metrics_Func */
290 /* Get the big metrics for a given embedded bitmap. */
293 /* stream :: The input stream. */
295 /* range :: The SBit range containing the glyph. */
298 /* big_metrics :: A big SBit metrics structure for the glyph. */
301 /* FreeType error code. 0 means success. */
304 /* The stream cursor must be positioned at the glyph's offset within */
305 /* the `EBDT' table before the call. */
307 /* If the image format uses variable metrics, the stream cursor is */
308 /* positioned just after the metrics header in the `EBDT' table on */
312 (*TT_Load_SBit_Metrics_Func)( FT_Stream stream,
314 TT_SBit_Metrics metrics );
317 /*************************************************************************/
320 /* TT_Load_SBit_Image_Func */
323 /* Load a given glyph sbit image from the font resource. This also */
324 /* returns its metrics. */
328 /* The target face object. */
330 /* strike_index :: */
331 /* The strike index. */
334 /* The current glyph index. */
337 /* The current load flags. */
340 /* The input stream. */
344 /* The target pixmap. */
347 /* A big sbit metrics structure for the glyph image. */
350 /* FreeType error code. 0 means success. Returns an error if no */
351 /* glyph sbit exists for the index. */
354 /* The `map.buffer' field is always freed before the glyph is loaded. */
357 (*TT_Load_SBit_Image_Func)( TT_Face face,
358 FT_ULong strike_index,
363 TT_SBit_MetricsRec *ametrics );
366 #ifdef FT_CONFIG_OPTION_OLD_INTERNALS
368 /*************************************************************************/
371 /* TT_Set_SBit_Strike_OldFunc */
374 /* Select an sbit strike for a given size request. */
377 /* face :: The target face object. */
379 /* req :: The size request. */
382 /* astrike_index :: The index of the sbit strike. */
385 /* FreeType error code. 0 means success. Returns an error if no */
386 /* sbit strike exists for the selected ppem values. */
389 (*TT_Set_SBit_Strike_OldFunc)( TT_Face face,
392 FT_ULong* astrike_index );
395 /*************************************************************************/
398 /* TT_CharMap_Load_Func */
401 /* Loads a given TrueType character map into memory. */
404 /* face :: A handle to the parent face object. */
406 /* stream :: A handle to the current stream object. */
409 /* cmap :: A pointer to a cmap object. */
412 /* FreeType error code. 0 means success. */
415 /* The function assumes that the stream is already in use (i.e., */
416 /* opened). In case of error, all partially allocated tables are */
420 (*TT_CharMap_Load_Func)( TT_Face face,
425 /*************************************************************************/
428 /* TT_CharMap_Free_Func */
431 /* Destroys a character mapping table. */
434 /* face :: A handle to the parent face object. */
436 /* cmap :: A handle to a cmap object. */
439 /* FreeType error code. 0 means success. */
442 (*TT_CharMap_Free_Func)( TT_Face face,
445 #endif /* FT_CONFIG_OPTION_OLD_INTERNALS */
448 /*************************************************************************/
451 /* TT_Set_SBit_Strike_Func */
454 /* Select an sbit strike for a given size request. */
457 /* face :: The target face object. */
459 /* req :: The size request. */
462 /* astrike_index :: The index of the sbit strike. */
465 /* FreeType error code. 0 means success. Returns an error if no */
466 /* sbit strike exists for the selected ppem values. */
469 (*TT_Set_SBit_Strike_Func)( TT_Face face,
471 FT_ULong* astrike_index );
474 /*************************************************************************/
477 /* TT_Load_Strike_Metrics_Func */
480 /* Load the metrics of a given strike. */
483 /* face :: The target face object. */
485 /* strike_index :: The strike index. */
488 /* metrics :: the metrics of the strike. */
491 /* FreeType error code. 0 means success. Returns an error if no */
492 /* such sbit strike exists. */
495 (*TT_Load_Strike_Metrics_Func)( TT_Face face,
496 FT_ULong strike_index,
497 FT_Size_Metrics* metrics );
500 /*************************************************************************/
503 /* TT_Get_PS_Name_Func */
506 /* Get the PostScript glyph name of a glyph. */
509 /* idx :: The glyph index. */
511 /* PSname :: The address of a string pointer. Will be NULL in case */
512 /* of error, otherwise it is a pointer to the glyph name. */
514 /* You must not modify the returned string! */
517 /* FreeType error code. 0 means success. */
520 (*TT_Get_PS_Name_Func)( TT_Face face,
522 FT_String** PSname );
525 /*************************************************************************/
528 /* TT_Load_Metrics_Func */
531 /* Load a metrics table, which is a table with a horizontal and a */
532 /* vertical version. */
535 /* face :: A handle to the target face object. */
537 /* stream :: The input stream. */
539 /* vertical :: A boolean flag. If set, load the vertical one. */
542 /* FreeType error code. 0 means success. */
545 (*TT_Load_Metrics_Func)( TT_Face face,
550 /*************************************************************************/
553 /* TT_Get_Metrics_Func */
556 /* Load the horizontal or vertical header in a face object. */
559 /* face :: A handle to the target face object. */
561 /* stream :: The input stream. */
563 /* vertical :: A boolean flag. If set, load vertical metrics. */
566 /* FreeType error code. 0 means success. */
569 (*TT_Get_Metrics_Func)( TT_Face face,
573 FT_UShort* aadvance );
576 /*************************************************************************/
579 /* TT_Load_Table_Func */
582 /* Load a given TrueType table. */
585 /* face :: A handle to the target face object. */
587 /* stream :: The input stream. */
590 /* FreeType error code. 0 means success. */
593 /* The function uses `face->goto_table' to seek the stream to the */
594 /* start of the table, except while loading the font directory. */
597 (*TT_Load_Table_Func)( TT_Face face,
601 /*************************************************************************/
604 /* TT_Free_Table_Func */
607 /* Free a given TrueType table. */
610 /* face :: A handle to the target face object. */
613 (*TT_Free_Table_Func)( TT_Face face );
618 * TT_Face_GetKerningFunc
621 * Return the horizontal kerning value between two glyphs.
624 * face :: A handle to the source face object.
625 * left_glyph :: The left glyph index.
626 * right_glyph :: The right glyph index.
629 * The kerning value in font units.
632 (*TT_Face_GetKerningFunc)( TT_Face face,
634 FT_UInt right_glyph );
637 /*************************************************************************/
643 /* This structure holds pointers to the functions used to load and */
644 /* free the basic tables that are required in a `sfnt' font file. */
647 /* Check the various xxx_Func() descriptions for details. */
649 typedef struct SFNT_Interface_
651 TT_Loader_GotoTableFunc goto_table;
653 TT_Init_Face_Func init_face;
654 TT_Load_Face_Func load_face;
655 TT_Done_Face_Func done_face;
656 FT_Module_Requester get_interface;
658 TT_Load_Any_Func load_any;
660 #ifdef FT_CONFIG_OPTION_OLD_INTERNALS
661 TT_Load_SFNT_HeaderRec_Func load_sfnt_header;
662 TT_Load_Directory_Func load_directory;
665 /* these functions are called by `load_face' but they can also */
666 /* be called from external modules, if there is a need to do so */
667 TT_Load_Table_Func load_head;
668 TT_Load_Metrics_Func load_hhea;
669 TT_Load_Table_Func load_cmap;
670 TT_Load_Table_Func load_maxp;
671 TT_Load_Table_Func load_os2;
672 TT_Load_Table_Func load_post;
674 TT_Load_Table_Func load_name;
675 TT_Free_Table_Func free_name;
677 /* optional tables */
678 #ifdef FT_CONFIG_OPTION_OLD_INTERNALS
679 TT_Load_Table_Func load_hdmx_stub;
680 TT_Free_Table_Func free_hdmx_stub;
683 /* this field was called `load_kerning' up to version 2.1.10 */
684 TT_Load_Table_Func load_kern;
686 TT_Load_Table_Func load_gasp;
687 TT_Load_Table_Func load_pclt;
689 /* see `ttload.h'; this field was called `load_bitmap_header' up to */
691 TT_Load_Table_Func load_bhed;
693 #ifdef FT_CONFIG_OPTION_OLD_INTERNALS
696 TT_Set_SBit_Strike_OldFunc set_sbit_strike_stub;
697 TT_Load_Table_Func load_sbits_stub;
700 * The following two fields appeared in version 2.1.8, and were placed
701 * between `load_sbits' and `load_sbit_image'. We support them as a
702 * special exception since they are used by Xfont library within the
703 * X.Org xserver, and because the probability that other rogue clients
704 * use the other version 2.1.7 fields below is _extremely_ low.
706 * Note that this forces us to disable an interesting memory-saving
707 * optimization though...
710 TT_Find_SBit_Image_Func find_sbit_image;
711 TT_Load_SBit_Metrics_Func load_sbit_metrics;
715 TT_Load_SBit_Image_Func load_sbit_image;
717 #ifdef FT_CONFIG_OPTION_OLD_INTERNALS
718 TT_Free_Table_Func free_sbits_stub;
722 TT_Get_PS_Name_Func get_psname;
723 TT_Free_Table_Func free_psnames;
725 #ifdef FT_CONFIG_OPTION_OLD_INTERNALS
726 TT_CharMap_Load_Func load_charmap_stub;
727 TT_CharMap_Free_Func free_charmap_stub;
730 /* starting here, the structure differs from version 2.1.7 */
732 /* this field was introduced in version 2.1.8, named `get_psname' */
733 TT_Face_GetKerningFunc get_kerning;
735 /* new elements introduced after version 2.1.10 */
737 /* load the font directory, i.e., the offset table and */
738 /* the table directory */
739 TT_Load_Table_Func load_font_dir;
740 TT_Load_Metrics_Func load_hmtx;
742 TT_Load_Table_Func load_eblc;
743 TT_Free_Table_Func free_eblc;
745 TT_Set_SBit_Strike_Func set_sbit_strike;
746 TT_Load_Strike_Metrics_Func load_strike_metrics;
748 TT_Get_Metrics_Func get_metrics;
754 typedef SFNT_Interface* SFNT_Service;
756 #ifndef FT_CONFIG_OPTION_PIC
758 #ifdef FT_CONFIG_OPTION_OLD_INTERNALS
759 #define FT_DEFINE_DRIVERS_OLD_INTERNAL(a) \
762 #define FT_DEFINE_DRIVERS_OLD_INTERNAL(a)
764 #define FT_INTERNAL(a) \
767 #define FT_DEFINE_SFNT_INTERFACE(class_, \
768 goto_table_, init_face_, load_face_, done_face_, get_interface_, \
769 load_any_, load_sfnt_header_, load_directory_, load_head_, \
770 load_hhea_, load_cmap_, load_maxp_, load_os2_, load_post_, \
771 load_name_, free_name_, load_hdmx_stub_, free_hdmx_stub_, \
772 load_kern_, load_gasp_, load_pclt_, load_bhed_, \
773 set_sbit_strike_stub_, load_sbits_stub_, find_sbit_image_, \
774 load_sbit_metrics_, load_sbit_image_, free_sbits_stub_, \
775 get_psname_, free_psnames_, load_charmap_stub_, free_charmap_stub_, \
776 get_kerning_, load_font_dir_, load_hmtx_, load_eblc_, free_eblc_, \
777 set_sbit_strike_, load_strike_metrics_, get_metrics_ ) \
778 static const SFNT_Interface class_ = \
780 FT_INTERNAL(goto_table_) \
781 FT_INTERNAL(init_face_) \
782 FT_INTERNAL(load_face_) \
783 FT_INTERNAL(done_face_) \
784 FT_INTERNAL(get_interface_) \
785 FT_INTERNAL(load_any_) \
786 FT_DEFINE_DRIVERS_OLD_INTERNAL(load_sfnt_header_) \
787 FT_DEFINE_DRIVERS_OLD_INTERNAL(load_directory_) \
788 FT_INTERNAL(load_head_) \
789 FT_INTERNAL(load_hhea_) \
790 FT_INTERNAL(load_cmap_) \
791 FT_INTERNAL(load_maxp_) \
792 FT_INTERNAL(load_os2_) \
793 FT_INTERNAL(load_post_) \
794 FT_INTERNAL(load_name_) \
795 FT_INTERNAL(free_name_) \
796 FT_DEFINE_DRIVERS_OLD_INTERNAL(load_hdmx_stub_) \
797 FT_DEFINE_DRIVERS_OLD_INTERNAL(free_hdmx_stub_) \
798 FT_INTERNAL(load_kern_) \
799 FT_INTERNAL(load_gasp_) \
800 FT_INTERNAL(load_pclt_) \
801 FT_INTERNAL(load_bhed_) \
802 FT_DEFINE_DRIVERS_OLD_INTERNAL(set_sbit_strike_stub_) \
803 FT_DEFINE_DRIVERS_OLD_INTERNAL(load_sbits_stub_) \
804 FT_DEFINE_DRIVERS_OLD_INTERNAL(find_sbit_image_) \
805 FT_DEFINE_DRIVERS_OLD_INTERNAL(load_sbit_metrics_) \
806 FT_INTERNAL(load_sbit_image_) \
807 FT_DEFINE_DRIVERS_OLD_INTERNAL(free_sbits_stub_) \
808 FT_INTERNAL(get_psname_) \
809 FT_INTERNAL(free_psnames_) \
810 FT_DEFINE_DRIVERS_OLD_INTERNAL(load_charmap_stub_) \
811 FT_DEFINE_DRIVERS_OLD_INTERNAL(free_charmap_stub_) \
812 FT_INTERNAL(get_kerning_) \
813 FT_INTERNAL(load_font_dir_) \
814 FT_INTERNAL(load_hmtx_) \
815 FT_INTERNAL(load_eblc_) \
816 FT_INTERNAL(free_eblc_) \
817 FT_INTERNAL(set_sbit_strike_) \
818 FT_INTERNAL(load_strike_metrics_) \
819 FT_INTERNAL(get_metrics_) \
822 #else /* FT_CONFIG_OPTION_PIC */
824 #ifdef FT_CONFIG_OPTION_OLD_INTERNALS
825 #define FT_DEFINE_DRIVERS_OLD_INTERNAL(a, a_) \
828 #define FT_DEFINE_DRIVERS_OLD_INTERNAL(a, a_)
830 #define FT_INTERNAL(a, a_) \
833 #define FT_DEFINE_SFNT_INTERFACE(class_, \
834 goto_table_, init_face_, load_face_, done_face_, get_interface_, \
835 load_any_, load_sfnt_header_, load_directory_, load_head_, \
836 load_hhea_, load_cmap_, load_maxp_, load_os2_, load_post_, \
837 load_name_, free_name_, load_hdmx_stub_, free_hdmx_stub_, \
838 load_kern_, load_gasp_, load_pclt_, load_bhed_, \
839 set_sbit_strike_stub_, load_sbits_stub_, find_sbit_image_, \
840 load_sbit_metrics_, load_sbit_image_, free_sbits_stub_, \
841 get_psname_, free_psnames_, load_charmap_stub_, free_charmap_stub_, \
842 get_kerning_, load_font_dir_, load_hmtx_, load_eblc_, free_eblc_, \
843 set_sbit_strike_, load_strike_metrics_, get_metrics_ ) \
845 FT_Init_Class_##class_( FT_Library library, SFNT_Interface* clazz ) \
847 FT_UNUSED(library); \
848 FT_INTERNAL(goto_table,goto_table_) \
849 FT_INTERNAL(init_face,init_face_) \
850 FT_INTERNAL(load_face,load_face_) \
851 FT_INTERNAL(done_face,done_face_) \
852 FT_INTERNAL(get_interface,get_interface_) \
853 FT_INTERNAL(load_any,load_any_) \
854 FT_DEFINE_DRIVERS_OLD_INTERNAL(load_sfnt_header,load_sfnt_header_) \
855 FT_DEFINE_DRIVERS_OLD_INTERNAL(load_directory,load_directory_) \
856 FT_INTERNAL(load_head,load_head_) \
857 FT_INTERNAL(load_hhea,load_hhea_) \
858 FT_INTERNAL(load_cmap,load_cmap_) \
859 FT_INTERNAL(load_maxp,load_maxp_) \
860 FT_INTERNAL(load_os2,load_os2_) \
861 FT_INTERNAL(load_post,load_post_) \
862 FT_INTERNAL(load_name,load_name_) \
863 FT_INTERNAL(free_name,free_name_) \
864 FT_DEFINE_DRIVERS_OLD_INTERNAL(load_hdmx_stub,load_hdmx_stub_) \
865 FT_DEFINE_DRIVERS_OLD_INTERNAL(free_hdmx_stub,free_hdmx_stub_) \
866 FT_INTERNAL(load_kern,load_kern_) \
867 FT_INTERNAL(load_gasp,load_gasp_) \
868 FT_INTERNAL(load_pclt,load_pclt_) \
869 FT_INTERNAL(load_bhed,load_bhed_) \
870 FT_DEFINE_DRIVERS_OLD_INTERNAL(set_sbit_strike_stub,set_sbit_strike_stub_) \
871 FT_DEFINE_DRIVERS_OLD_INTERNAL(load_sbits_stub,load_sbits_stub_) \
872 FT_DEFINE_DRIVERS_OLD_INTERNAL(find_sbit_image,find_sbit_image_) \
873 FT_DEFINE_DRIVERS_OLD_INTERNAL(load_sbit_metrics,load_sbit_metrics_) \
874 FT_INTERNAL(load_sbit_image,load_sbit_image_) \
875 FT_DEFINE_DRIVERS_OLD_INTERNAL(free_sbits_stub,free_sbits_stub_) \
876 FT_INTERNAL(get_psname,get_psname_) \
877 FT_INTERNAL(free_psnames,free_psnames_) \
878 FT_DEFINE_DRIVERS_OLD_INTERNAL(load_charmap_stub,load_charmap_stub_) \
879 FT_DEFINE_DRIVERS_OLD_INTERNAL(free_charmap_stub,free_charmap_stub_) \
880 FT_INTERNAL(get_kerning,get_kerning_) \
881 FT_INTERNAL(load_font_dir,load_font_dir_) \
882 FT_INTERNAL(load_hmtx,load_hmtx_) \
883 FT_INTERNAL(load_eblc,load_eblc_) \
884 FT_INTERNAL(free_eblc,free_eblc_) \
885 FT_INTERNAL(set_sbit_strike,set_sbit_strike_) \
886 FT_INTERNAL(load_strike_metrics,load_strike_metrics_) \
887 FT_INTERNAL(get_metrics,get_metrics_) \
890 #endif /* FT_CONFIG_OPTION_PIC */
894 #endif /* __SFNT_H__ */