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