1 /****************************************************************************
2 *
3 * sfnt.h
4 *
5 * High-level 'sfnt' driver interface (specification).
6 *
7 * Copyright (C) 1996-2019 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 SFNT_H_
20 #define SFNT_H_
21
22
23 #include <ft2build.h>
24 #include FT_INTERNAL_DRIVER_H
25 #include FT_INTERNAL_TRUETYPE_TYPES_H
26 #include FT_INTERNAL_WOFF_TYPES_H
27
28
29 FT_BEGIN_HEADER
30
31
32 /**************************************************************************
33 *
34 * @functype:
35 * TT_Init_Face_Func
36 *
37 * @description:
38 * First part of the SFNT face object initialization. This finds the
39 * face in a SFNT file or collection, and load its format tag in
40 * face->format_tag.
41 *
42 * @input:
43 * stream ::
44 * The input stream.
45 *
46 * face ::
47 * A handle to the target face object.
48 *
49 * face_index ::
50 * The index of the TrueType font, if we are opening a collection, in
51 * bits 0-15. The numbered instance index~+~1 of a GX (sub)font, if
52 * applicable, in bits 16-30.
53 *
54 * num_params ::
55 * The number of additional parameters.
56 *
57 * params ::
58 * Optional additional parameters.
59 *
60 * @return:
61 * FreeType error code. 0 means success.
62 *
63 * @note:
64 * The stream cursor must be at the font file's origin.
65 *
66 * This function recognizes fonts embedded in a 'TrueType collection'.
67 *
68 * Once the format tag has been validated by the font driver, it should
69 * then call the TT_Load_Face_Func() callback to read the rest of the
70 * SFNT tables in the object.
71 */
72 typedef FT_Error
73 (*TT_Init_Face_Func)( FT_Stream stream,
74 TT_Face face,
75 FT_Int face_index,
76 FT_Int num_params,
77 FT_Parameter* params );
78
79
80 /**************************************************************************
81 *
82 * @functype:
83 * TT_Load_Face_Func
84 *
85 * @description:
86 * Second part of the SFNT face object initialization. This loads the
87 * common SFNT tables (head, OS/2, maxp, metrics, etc.) in the face
88 * object.
89 *
90 * @input:
91 * stream ::
92 * The input stream.
93 *
94 * face ::
95 * A handle to the target face object.
96 *
97 * face_index ::
98 * The index of the TrueType font, if we are opening a collection, in
99 * bits 0-15. The numbered instance index~+~1 of a GX (sub)font, if
100 * applicable, in bits 16-30.
101 *
102 * num_params ::
103 * The number of additional parameters.
104 *
105 * params ::
106 * Optional additional parameters.
107 *
108 * @return:
109 * FreeType error code. 0 means success.
110 *
111 * @note:
112 * This function must be called after TT_Init_Face_Func().
113 */
114 typedef FT_Error
115 (*TT_Load_Face_Func)( FT_Stream stream,
116 TT_Face face,
117 FT_Int face_index,
118 FT_Int num_params,
119 FT_Parameter* params );
120
121
122 /**************************************************************************
123 *
124 * @functype:
125 * TT_Done_Face_Func
126 *
127 * @description:
128 * A callback used to delete the common SFNT data from a face.
129 *
130 * @input:
131 * face ::
132 * A handle to the target face object.
133 *
134 * @note:
135 * This function does NOT destroy the face object.
136 */
137 typedef void
138 (*TT_Done_Face_Func)( TT_Face face );
139
140
141 /**************************************************************************
142 *
143 * @functype:
144 * TT_Load_Any_Func
145 *
146 * @description:
147 * Load any font table into client memory.
148 *
149 * @input:
150 * face ::
151 * The face object to look for.
152 *
153 * tag ::
154 * The tag of table to load. Use the value 0 if you want to access the
155 * whole font file, else set this parameter to a valid TrueType table
156 * tag that you can forge with the MAKE_TT_TAG macro.
157 *
158 * offset ::
159 * The starting offset in the table (or the file if tag == 0).
160 *
161 * length ::
162 * The address of the decision variable:
163 *
164 * If `length == NULL`: Loads the whole table. Returns an error if
165 * 'offset' == 0!
166 *
167 * If `*length == 0`: Exits immediately; returning the length of the
168 * given table or of the font file, depending on the value of 'tag'.
169 *
170 * If `*length != 0`: Loads the next 'length' bytes of table or font,
171 * starting at offset 'offset' (in table or font too).
172 *
173 * @output:
174 * buffer ::
175 * The address of target buffer.
176 *
177 * @return:
178 * TrueType error code. 0 means success.
179 */
180 typedef FT_Error
181 (*TT_Load_Any_Func)( TT_Face face,
182 FT_ULong tag,
183 FT_Long offset,
184 FT_Byte *buffer,
185 FT_ULong* length );
186
187
188 /**************************************************************************
189 *
190 * @functype:
191 * TT_Find_SBit_Image_Func
192 *
193 * @description:
194 * Check whether an embedded bitmap (an 'sbit') exists for a given glyph,
195 * at a given strike.
196 *
197 * @input:
198 * face ::
199 * The target face object.
200 *
201 * glyph_index ::
202 * The glyph index.
203 *
204 * strike_index ::
205 * The current strike index.
206 *
207 * @output:
208 * arange ::
209 * The SBit range containing the glyph index.
210 *
211 * astrike ::
212 * The SBit strike containing the glyph index.
213 *
214 * aglyph_offset ::
215 * The offset of the glyph data in 'EBDT' table.
216 *
217 * @return:
218 * FreeType error code. 0 means success. Returns
219 * SFNT_Err_Invalid_Argument if no sbit exists for the requested glyph.
220 */
221 typedef FT_Error
222 (*TT_Find_SBit_Image_Func)( TT_Face face,
223 FT_UInt glyph_index,
224 FT_ULong strike_index,
225 TT_SBit_Range *arange,
226 TT_SBit_Strike *astrike,
227 FT_ULong *aglyph_offset );
228
229
230 /**************************************************************************
231 *
232 * @functype:
233 * TT_Load_SBit_Metrics_Func
234 *
235 * @description:
236 * Get the big metrics for a given embedded bitmap.
237 *
238 * @input:
239 * stream ::
240 * The input stream.
241 *
242 * range ::
243 * The SBit range containing the glyph.
244 *
245 * @output:
246 * big_metrics ::
247 * A big SBit metrics structure for the glyph.
248 *
249 * @return:
250 * FreeType error code. 0 means success.
251 *
252 * @note:
253 * The stream cursor must be positioned at the glyph's offset within the
254 * 'EBDT' table before the call.
255 *
256 * If the image format uses variable metrics, the stream cursor is
257 * positioned just after the metrics header in the 'EBDT' table on
258 * function exit.
259 */
260 typedef FT_Error
261 (*TT_Load_SBit_Metrics_Func)( FT_Stream stream,
262 TT_SBit_Range range,
263 TT_SBit_Metrics metrics );
264
265
266 /**************************************************************************
267 *
268 * @functype:
269 * TT_Load_SBit_Image_Func
270 *
271 * @description:
272 * Load a given glyph sbit image from the font resource. This also
273 * returns its metrics.
274 *
275 * @input:
276 * face ::
277 * The target face object.
278 *
279 * strike_index ::
280 * The strike index.
281 *
282 * glyph_index ::
283 * The current glyph index.
284 *
285 * load_flags ::
286 * The current load flags.
287 *
288 * stream ::
289 * The input stream.
290 *
291 * @output:
292 * amap ::
293 * The target pixmap.
294 *
295 * ametrics ::
296 * A big sbit metrics structure for the glyph image.
297 *
298 * @return:
299 * FreeType error code. 0 means success. Returns an error if no glyph
300 * sbit exists for the index.
301 *
302 * @note:
303 * The `map.buffer` field is always freed before the glyph is loaded.
304 */
305 typedef FT_Error
306 (*TT_Load_SBit_Image_Func)( TT_Face face,
307 FT_ULong strike_index,
308 FT_UInt glyph_index,
309 FT_UInt load_flags,
310 FT_Stream stream,
311 FT_Bitmap *amap,
312 TT_SBit_MetricsRec *ametrics );
313
314
315 /**************************************************************************
316 *
317 * @functype:
318 * TT_Set_SBit_Strike_Func
319 *
320 * @description:
321 * Select an sbit strike for a given size request.
322 *
323 * @input:
324 * face ::
325 * The target face object.
326 *
327 * req ::
328 * The size request.
329 *
330 * @output:
331 * astrike_index ::
332 * The index of the sbit strike.
333 *
334 * @return:
335 * FreeType error code. 0 means success. Returns an error if no sbit
336 * strike exists for the selected ppem values.
337 */
338 typedef FT_Error
339 (*TT_Set_SBit_Strike_Func)( TT_Face face,
340 FT_Size_Request req,
341 FT_ULong* astrike_index );
342
343
344 /**************************************************************************
345 *
346 * @functype:
347 * TT_Load_Strike_Metrics_Func
348 *
349 * @description:
350 * Load the metrics of a given strike.
351 *
352 * @input:
353 * face ::
354 * The target face object.
355 *
356 * strike_index ::
357 * The strike index.
358 *
359 * @output:
360 * metrics ::
361 * the metrics of the strike.
362 *
363 * @return:
364 * FreeType error code. 0 means success. Returns an error if no such
365 * sbit strike exists.
366 */
367 typedef FT_Error
368 (*TT_Load_Strike_Metrics_Func)( TT_Face face,
369 FT_ULong strike_index,
370 FT_Size_Metrics* metrics );
371
372
373 /**************************************************************************
374 *
375 * @functype:
376 * TT_Get_PS_Name_Func
377 *
378 * @description:
379 * Get the PostScript glyph name of a glyph.
380 *
381 * @input:
382 * idx ::
383 * The glyph index.
384 *
385 * PSname ::
386 * The address of a string pointer. Will be `NULL` in case of error,
387 * otherwise it is a pointer to the glyph name.
388 *
389 * You must not modify the returned string!
390 *
391 * @output:
392 * FreeType error code. 0 means success.
393 */
394 typedef FT_Error
395 (*TT_Get_PS_Name_Func)( TT_Face face,
396 FT_UInt idx,
397 FT_String** PSname );
398
399
400 /**************************************************************************
401 *
402 * @functype:
403 * TT_Load_Metrics_Func
404 *
405 * @description:
406 * Load a metrics table, which is a table with a horizontal and a
407 * vertical version.
408 *
409 * @input:
410 * face ::
411 * A handle to the target face object.
412 *
413 * stream ::
414 * The input stream.
415 *
416 * vertical ::
417 * A boolean flag. If set, load the vertical one.
418 *
419 * @return:
420 * FreeType error code. 0 means success.
421 */
422 typedef FT_Error
423 (*TT_Load_Metrics_Func)( TT_Face face,
424 FT_Stream stream,
425 FT_Bool vertical );
426
427
428 /**************************************************************************
429 *
430 * @functype:
431 * TT_Get_Metrics_Func
432 *
433 * @description:
434 * Load the horizontal or vertical header in a face object.
435 *
436 * @input:
437 * face ::
438 * A handle to the target face object.
439 *
440 * vertical ::
441 * A boolean flag. If set, load vertical metrics.
442 *
443 * gindex ::
444 * The glyph index.
445 *
446 * @output:
447 * abearing ::
448 * The horizontal (or vertical) bearing. Set to zero in case of error.
449 *
450 * aadvance ::
451 * The horizontal (or vertical) advance. Set to zero in case of error.
452 */
453 typedef void
454 (*TT_Get_Metrics_Func)( TT_Face face,
455 FT_Bool vertical,
456 FT_UInt gindex,
457 FT_Short* abearing,
458 FT_UShort* aadvance );
459
460
461 /**************************************************************************
462 *
463 * @functype:
464 * TT_Set_Palette_Func
465 *
466 * @description:
467 * Load the colors into `face->palette` for a given palette index.
468 *
469 * @input:
470 * face ::
471 * The target face object.
472 *
473 * idx ::
474 * The palette index.
475 *
476 * @return:
477 * FreeType error code. 0 means success.
478 */
479 typedef FT_Error
480 (*TT_Set_Palette_Func)( TT_Face face,
481 FT_UInt idx );
482
483
484 /**************************************************************************
485 *
486 * @functype:
487 * TT_Get_Colr_Layer_Func
488 *
489 * @description:
490 * Iteratively get the color layer data of a given glyph index.
491 *
492 * @input:
493 * face ::
494 * The target face object.
495 *
496 * base_glyph ::
497 * The glyph index the colored glyph layers are associated with.
498 *
499 * @inout:
500 * iterator ::
501 * An @FT_LayerIterator object. For the first call you should set
502 * `iterator->p` to `NULL`. For all following calls, simply use the
503 * same object again.
504 *
505 * @output:
506 * aglyph_index ::
507 * The glyph index of the current layer.
508 *
509 * acolor_index ::
510 * The color index into the font face's color palette of the current
511 * layer. The value 0xFFFF is special; it doesn't reference a palette
512 * entry but indicates that the text foreground color should be used
513 * instead (to be set up by the application outside of FreeType).
514 *
515 * @return:
516 * Value~1 if everything is OK. If there are no more layers (or if there
517 * are no layers at all), value~0 gets returned. In case of an error,
518 * value~0 is returned also.
519 */
520 typedef FT_Bool
521 (*TT_Get_Colr_Layer_Func)( TT_Face face,
522 FT_UInt base_glyph,
523 FT_UInt *aglyph_index,
524 FT_UInt *acolor_index,
525 FT_LayerIterator* iterator );
526
527
528 /**************************************************************************
529 *
530 * @functype:
531 * TT_Blend_Colr_Func
532 *
533 * @description:
534 * Blend the bitmap in `new_glyph` into `base_glyph` using the color
535 * specified by `color_index`. If `color_index` is 0xFFFF, use
536 * `face->foreground_color` if `face->have_foreground_color` is set.
537 * Otherwise check `face->palette_data.palette_flags`: If present and
538 * @FT_PALETTE_FOR_DARK_BACKGROUND is set, use BGRA value 0xFFFFFFFF
539 * (white opaque). Otherwise use BGRA value 0x000000FF (black opaque).
540 *
541 * @input:
542 * face ::
543 * The target face object.
544 *
545 * color_index ::
546 * Color index from the COLR table.
547 *
548 * base_glyph ::
549 * Slot for bitmap to be merged into. The underlying bitmap may get
550 * reallocated.
551 *
552 * new_glyph ::
553 * Slot to be incooperated into `base_glyph`.
554 *
555 * @return:
556 * FreeType error code. 0 means success. Returns an error if
557 * color_index is invalid or reallocation fails.
558 */
559 typedef FT_Error
560 (*TT_Blend_Colr_Func)( TT_Face face,
561 FT_UInt color_index,
562 FT_GlyphSlot base_glyph,
563 FT_GlyphSlot new_glyph );
564
565
566 /**************************************************************************
567 *
568 * @functype:
569 * TT_Get_Name_Func
570 *
571 * @description:
572 * From the 'name' table, return a given ENGLISH name record in ASCII.
573 *
574 * @input:
575 * face ::
576 * A handle to the source face object.
577 *
578 * nameid ::
579 * The name id of the name record to return.
580 *
581 * @inout:
582 * name ::
583 * The address of an allocated string pointer. `NULL` if no name is
584 * present.
585 *
586 * @return:
587 * FreeType error code. 0 means success.
588 */
589 typedef FT_Error
590 (*TT_Get_Name_Func)( TT_Face face,
591 FT_UShort nameid,
592 FT_String** name );
593
594
595 /**************************************************************************
596 *
597 * @functype:
598 * TT_Get_Name_ID_Func
599 *
600 * @description:
601 * Search whether an ENGLISH version for a given name ID is in the 'name'
602 * table.
603 *
604 * @input:
605 * face ::
606 * A handle to the source face object.
607 *
608 * nameid ::
609 * The name id of the name record to return.
610 *
611 * @output:
612 * win ::
613 * If non-negative, an index into the 'name' table with the
614 * corresponding (3,1) or (3,0) Windows entry.
615 *
616 * apple ::
617 * If non-negative, an index into the 'name' table with the
618 * corresponding (1,0) Apple entry.
619 *
620 * @return:
621 * 1 if there is either a win or apple entry (or both), 0 otheriwse.
622 */
623 typedef FT_Bool
624 (*TT_Get_Name_ID_Func)( TT_Face face,
625 FT_UShort nameid,
626 FT_Int *win,
627 FT_Int *apple );
628
629
630 /**************************************************************************
631 *
632 * @functype:
633 * TT_Load_Table_Func
634 *
635 * @description:
636 * Load a given TrueType table.
637 *
638 * @input:
639 * face ::
640 * A handle to the target face object.
641 *
642 * stream ::
643 * The input stream.
644 *
645 * @return:
646 * FreeType error code. 0 means success.
647 *
648 * @note:
649 * The function uses `face->goto_table` to seek the stream to the start
650 * of the table, except while loading the font directory.
651 */
652 typedef FT_Error
653 (*TT_Load_Table_Func)( TT_Face face,
654 FT_Stream stream );
655
656
657 /**************************************************************************
658 *
659 * @functype:
660 * TT_Free_Table_Func
661 *
662 * @description:
663 * Free a given TrueType table.
664 *
665 * @input:
666 * face ::
667 * A handle to the target face object.
668 */
669 typedef void
670 (*TT_Free_Table_Func)( TT_Face face );
671
672
673 /*
674 * @functype:
675 * TT_Face_GetKerningFunc
676 *
677 * @description:
678 * Return the horizontal kerning value between two glyphs.
679 *
680 * @input:
681 * face ::
682 * A handle to the source face object.
683 *
684 * left_glyph ::
685 * The left glyph index.
686 *
687 * right_glyph ::
688 * The right glyph index.
689 *
690 * @return:
691 * The kerning value in font units.
692 */
693 typedef FT_Int
694 (*TT_Face_GetKerningFunc)( TT_Face face,
695 FT_UInt left_glyph,
696 FT_UInt right_glyph );
697
698
699 /**************************************************************************
700 *
701 * @struct:
702 * SFNT_Interface
703 *
704 * @description:
705 * This structure holds pointers to the functions used to load and free
706 * the basic tables that are required in a 'sfnt' font file.
707 *
708 * @fields:
709 * Check the various xxx_Func() descriptions for details.
710 */
711 typedef struct SFNT_Interface_
712 {
713 TT_Loader_GotoTableFunc goto_table;
714
715 TT_Init_Face_Func init_face;
716 TT_Load_Face_Func load_face;
717 TT_Done_Face_Func done_face;
718 FT_Module_Requester get_interface;
719
720 TT_Load_Any_Func load_any;
721
722 /* these functions are called by `load_face' but they can also */
723 /* be called from external modules, if there is a need to do so */
724 TT_Load_Table_Func load_head;
725 TT_Load_Metrics_Func load_hhea;
726 TT_Load_Table_Func load_cmap;
727 TT_Load_Table_Func load_maxp;
728 TT_Load_Table_Func load_os2;
729 TT_Load_Table_Func load_post;
730
731 TT_Load_Table_Func load_name;
732 TT_Free_Table_Func free_name;
733
734 /* this field was called `load_kerning' up to version 2.1.10 */
735 TT_Load_Table_Func load_kern;
736
737 TT_Load_Table_Func load_gasp;
738 TT_Load_Table_Func load_pclt;
739
740 /* see `ttload.h'; this field was called `load_bitmap_header' up to */
741 /* version 2.1.10 */
742 TT_Load_Table_Func load_bhed;
743
744 TT_Load_SBit_Image_Func load_sbit_image;
745
746 /* see `ttpost.h' */
747 TT_Get_PS_Name_Func get_psname;
748 TT_Free_Table_Func free_psnames;
749
750 /* starting here, the structure differs from version 2.1.7 */
751
752 /* this field was introduced in version 2.1.8, named `get_psname' */
753 TT_Face_GetKerningFunc get_kerning;
754
755 /* new elements introduced after version 2.1.10 */
756
757 /* load the font directory, i.e., the offset table and */
758 /* the table directory */
759 TT_Load_Table_Func load_font_dir;
760 TT_Load_Metrics_Func load_hmtx;
761
762 TT_Load_Table_Func load_eblc;
763 TT_Free_Table_Func free_eblc;
764
765 TT_Set_SBit_Strike_Func set_sbit_strike;
766 TT_Load_Strike_Metrics_Func load_strike_metrics;
767
768 TT_Load_Table_Func load_cpal;
769 TT_Load_Table_Func load_colr;
770 TT_Free_Table_Func free_cpal;
771 TT_Free_Table_Func free_colr;
772 TT_Set_Palette_Func set_palette;
773 TT_Get_Colr_Layer_Func get_colr_layer;
774 TT_Blend_Colr_Func colr_blend;
775
776 TT_Get_Metrics_Func get_metrics;
777
778 TT_Get_Name_Func get_name;
779 TT_Get_Name_ID_Func get_name_id;
780
781 } SFNT_Interface;
782
783
784 /* transitional */
785 typedef SFNT_Interface* SFNT_Service;
786
787
788 #define FT_DEFINE_SFNT_INTERFACE( \
789 class_, \
790 goto_table_, \
791 init_face_, \
792 load_face_, \
793 done_face_, \
794 get_interface_, \
795 load_any_, \
796 load_head_, \
797 load_hhea_, \
798 load_cmap_, \
799 load_maxp_, \
800 load_os2_, \
801 load_post_, \
802 load_name_, \
803 free_name_, \
804 load_kern_, \
805 load_gasp_, \
806 load_pclt_, \
807 load_bhed_, \
808 load_sbit_image_, \
809 get_psname_, \
810 free_psnames_, \
811 get_kerning_, \
812 load_font_dir_, \
813 load_hmtx_, \
814 load_eblc_, \
815 free_eblc_, \
816 set_sbit_strike_, \
817 load_strike_metrics_, \
818 load_cpal_, \
819 load_colr_, \
820 free_cpal_, \
821 free_colr_, \
822 set_palette_, \
823 get_colr_layer_, \
824 colr_blend_, \
825 get_metrics_, \
826 get_name_, \
827 get_name_id_ ) \
828 static const SFNT_Interface class_ = \
829 { \
830 goto_table_, \
831 init_face_, \
832 load_face_, \
833 done_face_, \
834 get_interface_, \
835 load_any_, \
836 load_head_, \
837 load_hhea_, \
838 load_cmap_, \
839 load_maxp_, \
840 load_os2_, \
841 load_post_, \
842 load_name_, \
843 free_name_, \
844 load_kern_, \
845 load_gasp_, \
846 load_pclt_, \
847 load_bhed_, \
848 load_sbit_image_, \
849 get_psname_, \
850 free_psnames_, \
851 get_kerning_, \
852 load_font_dir_, \
853 load_hmtx_, \
854 load_eblc_, \
855 free_eblc_, \
856 set_sbit_strike_, \
857 load_strike_metrics_, \
858 load_cpal_, \
859 load_colr_, \
860 free_cpal_, \
861 free_colr_, \
862 set_palette_, \
863 get_colr_layer_, \
864 colr_blend_, \
865 get_metrics_, \
866 get_name_, \
867 get_name_id_ \
868 };
869
870
871 FT_END_HEADER
872
873 #endif /* SFNT_H_ */
874
875
876 /* END */