1 /***************************************************************************/
5 /* Basic SFNT/TrueType tables definitions and interface */
6 /* (specification only). */
8 /* Copyright 1996-2018 by */
9 /* David Turner, Robert Wilhelm, and Werner Lemberg. */
11 /* This file is part of the FreeType project, and may only be used, */
12 /* modified, and distributed under the terms of the FreeType project */
13 /* license, LICENSE.TXT. By continuing to use, modify, or distribute */
14 /* this file you indicate that you have read the license and */
15 /* understand and accept it fully. */
17 /***************************************************************************/
25 #include FT_FREETYPE_H
28 #error "freetype.h of FreeType 1 has been loaded!"
29 #error "Please fix the directory search order for header files"
30 #error "so that freetype.h of FreeType 2 is found first."
36 /*************************************************************************/
45 /* TrueType specific table types and functions. */
48 /* This section contains definitions of some basic tables specific to */
49 /* TrueType and OpenType as well as some routines used to access and */
62 /* FT_Get_Sfnt_Table */
63 /* FT_Load_Sfnt_Table */
64 /* FT_Sfnt_Table_Info */
66 /* FT_Get_CMap_Language_ID */
67 /* FT_Get_CMap_Format */
69 /* FT_PARAM_TAG_UNPATENTED_HINTING */
71 /*************************************************************************/
74 /*************************************************************************/
80 /* A structure to model a TrueType font header table. All fields */
81 /* follow the OpenType specification. */
83 typedef struct TT_Header_
85 FT_Fixed Table_Version
;
86 FT_Fixed Font_Revision
;
88 FT_Long CheckSum_Adjust
;
92 FT_UShort Units_Per_EM
;
103 FT_UShort Lowest_Rec_PPEM
;
105 FT_Short Font_Direction
;
106 FT_Short Index_To_Loc_Format
;
107 FT_Short Glyph_Data_Format
;
112 /*************************************************************************/
118 /* A structure to model a TrueType horizontal header, the `hhea' */
119 /* table, as well as the corresponding horizontal metrics table, */
123 /* Version :: The table version. */
125 /* Ascender :: The font's ascender, i.e., the distance */
126 /* from the baseline to the top-most of all */
127 /* glyph points found in the font. */
129 /* This value is invalid in many fonts, as */
130 /* it is usually set by the font designer, */
131 /* and often reflects only a portion of the */
132 /* glyphs found in the font (maybe ASCII). */
134 /* You should use the `sTypoAscender' field */
135 /* of the `OS/2' table instead if you want */
136 /* the correct one. */
138 /* Descender :: The font's descender, i.e., the distance */
139 /* from the baseline to the bottom-most of */
140 /* all glyph points found in the font. It */
143 /* This value is invalid in many fonts, as */
144 /* it is usually set by the font designer, */
145 /* and often reflects only a portion of the */
146 /* glyphs found in the font (maybe ASCII). */
148 /* You should use the `sTypoDescender' */
149 /* field of the `OS/2' table instead if you */
150 /* want the correct one. */
152 /* Line_Gap :: The font's line gap, i.e., the distance */
153 /* to add to the ascender and descender to */
154 /* get the BTB, i.e., the */
155 /* baseline-to-baseline distance for the */
158 /* advance_Width_Max :: This field is the maximum of all advance */
159 /* widths found in the font. It can be */
160 /* used to compute the maximum width of an */
161 /* arbitrary string of text. */
163 /* min_Left_Side_Bearing :: The minimum left side bearing of all */
164 /* glyphs within the font. */
166 /* min_Right_Side_Bearing :: The minimum right side bearing of all */
167 /* glyphs within the font. */
169 /* xMax_Extent :: The maximum horizontal extent (i.e., the */
170 /* `width' of a glyph's bounding box) for */
171 /* all glyphs in the font. */
173 /* caret_Slope_Rise :: The rise coefficient of the cursor's */
174 /* slope of the cursor (slope=rise/run). */
176 /* caret_Slope_Run :: The run coefficient of the cursor's */
179 /* caret_Offset :: The cursor's offset for slanted fonts. */
181 /* Reserved :: 8~reserved bytes. */
183 /* metric_Data_Format :: Always~0. */
185 /* number_Of_HMetrics :: Number of HMetrics entries in the `hmtx' */
186 /* table -- this value can be smaller than */
187 /* the total number of glyphs in the font. */
189 /* long_metrics :: A pointer into the `hmtx' table. */
191 /* short_metrics :: A pointer into the `hmtx' table. */
194 /* For an OpenType variation font, the values of the following fields */
195 /* can change after a call to @FT_Set_Var_Design_Coordinates (and */
196 /* friends) if the font contains an `MVAR' table: `caret_Slope_Rise', */
197 /* `caret_Slope_Run', and `caret_Offset'. */
199 typedef struct TT_HoriHeader_
206 FT_UShort advance_Width_Max
; /* advance width maximum */
208 FT_Short min_Left_Side_Bearing
; /* minimum left-sb */
209 FT_Short min_Right_Side_Bearing
; /* minimum right-sb */
210 FT_Short xMax_Extent
; /* xmax extents */
211 FT_Short caret_Slope_Rise
;
212 FT_Short caret_Slope_Run
;
213 FT_Short caret_Offset
;
215 FT_Short Reserved
[4];
217 FT_Short metric_Data_Format
;
218 FT_UShort number_Of_HMetrics
;
220 /* The following fields are not defined by the OpenType specification */
221 /* but they are used to connect the metrics header to the relevant */
230 /*************************************************************************/
236 /* A structure used to model a TrueType vertical header, the `vhea' */
237 /* table, as well as the corresponding vertical metrics table, */
241 /* Version :: The table version. */
243 /* Ascender :: The font's ascender, i.e., the distance */
244 /* from the baseline to the top-most of */
245 /* all glyph points found in the font. */
247 /* This value is invalid in many fonts, as */
248 /* it is usually set by the font designer, */
249 /* and often reflects only a portion of */
250 /* the glyphs found in the font (maybe */
253 /* You should use the `sTypoAscender' */
254 /* field of the `OS/2' table instead if */
255 /* you want the correct one. */
257 /* Descender :: The font's descender, i.e., the */
258 /* distance from the baseline to the */
259 /* bottom-most of all glyph points found */
260 /* in the font. It is negative. */
262 /* This value is invalid in many fonts, as */
263 /* it is usually set by the font designer, */
264 /* and often reflects only a portion of */
265 /* the glyphs found in the font (maybe */
268 /* You should use the `sTypoDescender' */
269 /* field of the `OS/2' table instead if */
270 /* you want the correct one. */
272 /* Line_Gap :: The font's line gap, i.e., the distance */
273 /* to add to the ascender and descender to */
274 /* get the BTB, i.e., the */
275 /* baseline-to-baseline distance for the */
278 /* advance_Height_Max :: This field is the maximum of all */
279 /* advance heights found in the font. It */
280 /* can be used to compute the maximum */
281 /* height of an arbitrary string of text. */
283 /* min_Top_Side_Bearing :: The minimum top side bearing of all */
284 /* glyphs within the font. */
286 /* min_Bottom_Side_Bearing :: The minimum bottom side bearing of all */
287 /* glyphs within the font. */
289 /* yMax_Extent :: The maximum vertical extent (i.e., the */
290 /* `height' of a glyph's bounding box) for */
291 /* all glyphs in the font. */
293 /* caret_Slope_Rise :: The rise coefficient of the cursor's */
294 /* slope of the cursor (slope=rise/run). */
296 /* caret_Slope_Run :: The run coefficient of the cursor's */
299 /* caret_Offset :: The cursor's offset for slanted fonts. */
301 /* Reserved :: 8~reserved bytes. */
303 /* metric_Data_Format :: Always~0. */
305 /* number_Of_VMetrics :: Number of VMetrics entries in the */
306 /* `vmtx' table -- this value can be */
307 /* smaller than the total number of glyphs */
310 /* long_metrics :: A pointer into the `vmtx' table. */
312 /* short_metrics :: A pointer into the `vmtx' table. */
315 /* For an OpenType variation font, the values of the following fields */
316 /* can change after a call to @FT_Set_Var_Design_Coordinates (and */
317 /* friends) if the font contains an `MVAR' table: `Ascender', */
318 /* `Descender', `Line_Gap', `caret_Slope_Rise', `caret_Slope_Run', */
319 /* and `caret_Offset'. */
321 typedef struct TT_VertHeader_
328 FT_UShort advance_Height_Max
; /* advance height maximum */
330 FT_Short min_Top_Side_Bearing
; /* minimum top-sb */
331 FT_Short min_Bottom_Side_Bearing
; /* minimum bottom-sb */
332 FT_Short yMax_Extent
; /* ymax extents */
333 FT_Short caret_Slope_Rise
;
334 FT_Short caret_Slope_Run
;
335 FT_Short caret_Offset
;
337 FT_Short Reserved
[4];
339 FT_Short metric_Data_Format
;
340 FT_UShort number_Of_VMetrics
;
342 /* The following fields are not defined by the OpenType specification */
343 /* but they are used to connect the metrics header to the relevant */
352 /*************************************************************************/
358 /* A structure to model a TrueType `OS/2' table. All fields comply */
359 /* to the OpenType specification. */
361 /* Note that we now support old Mac fonts that do not include an */
362 /* `OS/2' table. In this case, the `version' field is always set to */
366 /* For an OpenType variation font, the values of the following fields */
367 /* can change after a call to @FT_Set_Var_Design_Coordinates (and */
368 /* friends) if the font contains an `MVAR' table: `sCapHeight', */
369 /* `sTypoAscender', `sTypoDescender', `sTypoLineGap', `sxHeight', */
370 /* `usWinAscent', `usWinDescent', `yStrikeoutPosition', */
371 /* `yStrikeoutSize', `ySubscriptXOffset', `ySubScriptXSize', */
372 /* `ySubscriptYOffset', `ySubscriptYSize', `ySuperscriptXOffset', */
373 /* `ySuperscriptXSize', `ySuperscriptYOffset', and */
374 /* `ySuperscriptYSize'. */
376 /* Possible values for bits in the `ulUnicodeRangeX' fields are given */
377 /* by the @TT_UCR_XXX macros. */
380 typedef struct TT_OS2_
382 FT_UShort version
; /* 0x0001 - more or 0xFFFF */
383 FT_Short xAvgCharWidth
;
384 FT_UShort usWeightClass
;
385 FT_UShort usWidthClass
;
387 FT_Short ySubscriptXSize
;
388 FT_Short ySubscriptYSize
;
389 FT_Short ySubscriptXOffset
;
390 FT_Short ySubscriptYOffset
;
391 FT_Short ySuperscriptXSize
;
392 FT_Short ySuperscriptYSize
;
393 FT_Short ySuperscriptXOffset
;
394 FT_Short ySuperscriptYOffset
;
395 FT_Short yStrikeoutSize
;
396 FT_Short yStrikeoutPosition
;
397 FT_Short sFamilyClass
;
401 FT_ULong ulUnicodeRange1
; /* Bits 0-31 */
402 FT_ULong ulUnicodeRange2
; /* Bits 32-63 */
403 FT_ULong ulUnicodeRange3
; /* Bits 64-95 */
404 FT_ULong ulUnicodeRange4
; /* Bits 96-127 */
406 FT_Char achVendID
[4];
408 FT_UShort fsSelection
;
409 FT_UShort usFirstCharIndex
;
410 FT_UShort usLastCharIndex
;
411 FT_Short sTypoAscender
;
412 FT_Short sTypoDescender
;
413 FT_Short sTypoLineGap
;
414 FT_UShort usWinAscent
;
415 FT_UShort usWinDescent
;
417 /* only version 1 and higher: */
419 FT_ULong ulCodePageRange1
; /* Bits 0-31 */
420 FT_ULong ulCodePageRange2
; /* Bits 32-63 */
422 /* only version 2 and higher: */
426 FT_UShort usDefaultChar
;
427 FT_UShort usBreakChar
;
428 FT_UShort usMaxContext
;
430 /* only version 5 and higher: */
432 FT_UShort usLowerOpticalPointSize
; /* in twips (1/20th points) */
433 FT_UShort usUpperOpticalPointSize
; /* in twips (1/20th points) */
438 /*************************************************************************/
444 /* A structure to model a TrueType `post' table. All fields comply */
445 /* to the OpenType specification. This structure does not reference */
446 /* a font's PostScript glyph names; use @FT_Get_Glyph_Name to */
450 /* For an OpenType variation font, the values of the following fields */
451 /* can change after a call to @FT_Set_Var_Design_Coordinates (and */
452 /* friends) if the font contains an `MVAR' table: `underlinePosition' */
453 /* and `underlineThickness'. */
455 typedef struct TT_Postscript_
458 FT_Fixed italicAngle
;
459 FT_Short underlinePosition
;
460 FT_Short underlineThickness
;
461 FT_ULong isFixedPitch
;
462 FT_ULong minMemType42
;
463 FT_ULong maxMemType42
;
464 FT_ULong minMemType1
;
465 FT_ULong maxMemType1
;
467 /* Glyph names follow in the `post' table, but we don't */
468 /* load them by default. */
473 /*************************************************************************/
479 /* A structure to model a TrueType `PCLT' table. All fields comply */
480 /* to the OpenType specification. */
482 typedef struct TT_PCLT_
489 FT_UShort TypeFamily
;
492 FT_Char TypeFace
[16];
493 FT_Char CharacterComplement
[8];
495 FT_Char StrokeWeight
;
503 /*************************************************************************/
509 /* The maximum profile (`maxp') table contains many max values, which */
510 /* can be used to pre-allocate arrays for speeding up glyph loading */
514 /* version :: The version number. */
516 /* numGlyphs :: The number of glyphs in this TrueType */
519 /* maxPoints :: The maximum number of points in a */
520 /* non-composite TrueType glyph. See also */
521 /* `maxCompositePoints'. */
523 /* maxContours :: The maximum number of contours in a */
524 /* non-composite TrueType glyph. See also */
525 /* `maxCompositeContours'. */
527 /* maxCompositePoints :: The maximum number of points in a */
528 /* composite TrueType glyph. See also */
531 /* maxCompositeContours :: The maximum number of contours in a */
532 /* composite TrueType glyph. See also */
535 /* maxZones :: The maximum number of zones used for */
538 /* maxTwilightPoints :: The maximum number of points in the */
539 /* twilight zone used for glyph hinting. */
541 /* maxStorage :: The maximum number of elements in the */
542 /* storage area used for glyph hinting. */
544 /* maxFunctionDefs :: The maximum number of function */
545 /* definitions in the TrueType bytecode for */
548 /* maxInstructionDefs :: The maximum number of instruction */
549 /* definitions in the TrueType bytecode for */
552 /* maxStackElements :: The maximum number of stack elements used */
553 /* during bytecode interpretation. */
555 /* maxSizeOfInstructions :: The maximum number of TrueType opcodes */
556 /* used for glyph hinting. */
558 /* maxComponentElements :: The maximum number of simple (i.e., non- */
559 /* composite) glyphs in a composite glyph. */
561 /* maxComponentDepth :: The maximum nesting depth of composite */
565 /* This structure is only used during font loading. */
567 typedef struct TT_MaxProfile_
572 FT_UShort maxContours
;
573 FT_UShort maxCompositePoints
;
574 FT_UShort maxCompositeContours
;
576 FT_UShort maxTwilightPoints
;
577 FT_UShort maxStorage
;
578 FT_UShort maxFunctionDefs
;
579 FT_UShort maxInstructionDefs
;
580 FT_UShort maxStackElements
;
581 FT_UShort maxSizeOfInstructions
;
582 FT_UShort maxComponentElements
;
583 FT_UShort maxComponentDepth
;
588 /*************************************************************************/
594 /* An enumeration to specify indices of SFNT tables loaded and parsed */
595 /* by FreeType during initialization of an SFNT font. Used in the */
596 /* @FT_Get_Sfnt_Table API function. */
599 /* FT_SFNT_HEAD :: To access the font's @TT_Header structure. */
601 /* FT_SFNT_MAXP :: To access the font's @TT_MaxProfile structure. */
603 /* FT_SFNT_OS2 :: To access the font's @TT_OS2 structure. */
605 /* FT_SFNT_HHEA :: To access the font's @TT_HoriHeader structure. */
607 /* FT_SFNT_VHEA :: To access the font's @TT_VertHeader structure. */
609 /* FT_SFNT_POST :: To access the font's @TT_Postscript structure. */
611 /* FT_SFNT_PCLT :: To access the font's @TT_PCLT structure. */
613 typedef enum FT_Sfnt_Tag_
627 /* these constants are deprecated; use the corresponding `FT_Sfnt_Tag' */
629 #define ft_sfnt_head FT_SFNT_HEAD
630 #define ft_sfnt_maxp FT_SFNT_MAXP
631 #define ft_sfnt_os2 FT_SFNT_OS2
632 #define ft_sfnt_hhea FT_SFNT_HHEA
633 #define ft_sfnt_vhea FT_SFNT_VHEA
634 #define ft_sfnt_post FT_SFNT_POST
635 #define ft_sfnt_pclt FT_SFNT_PCLT
638 /*************************************************************************/
641 /* FT_Get_Sfnt_Table */
644 /* Return a pointer to a given SFNT table stored within a face. */
647 /* face :: A handle to the source. */
649 /* tag :: The index of the SFNT table. */
652 /* A type-less pointer to the table. This will be NULL in case of */
653 /* error, or if the corresponding table was not found *OR* loaded */
656 /* Use a typecast according to `tag' to access the structure */
660 /* The table is owned by the face object and disappears with it. */
662 /* This function is only useful to access SFNT tables that are loaded */
663 /* by the sfnt, truetype, and opentype drivers. See @FT_Sfnt_Tag for */
666 /* Here an example how to access the `vhea' table: */
669 /* TT_VertHeader* vert_header; */
673 /* (TT_VertHeader*)FT_Get_Sfnt_Table( face, FT_SFNT_VHEA ); */
677 FT_Get_Sfnt_Table( FT_Face face
,
681 /**************************************************************************
687 * Load any SFNT font table into client memory.
691 * A handle to the source face.
694 * The four-byte tag of the table to load. Use value~0 if you want
695 * to access the whole font file. Otherwise, you can use one of the
696 * definitions found in the @FT_TRUETYPE_TAGS_H file, or forge a new
697 * one with @FT_MAKE_TAG.
700 * The starting offset in the table (or file if tag~==~0).
704 * The target buffer address. The client must ensure that the memory
705 * array is big enough to hold the data.
709 * If the `length' parameter is NULL, try to load the whole table.
710 * Return an error code if it fails.
712 * Else, if `*length' is~0, exit immediately while returning the
713 * table's (or file) full size in it.
715 * Else the number of bytes to read from the table or file, from the
719 * FreeType error code. 0~means success.
722 * If you need to determine the table's length you should first call this
723 * function with `*length' set to~0, as in the following example:
726 * FT_ULong length = 0;
729 * error = FT_Load_Sfnt_Table( face, tag, 0, NULL, &length );
730 * if ( error ) { ... table does not exist ... }
732 * buffer = malloc( length );
733 * if ( buffer == NULL ) { ... not enough memory ... }
735 * error = FT_Load_Sfnt_Table( face, tag, 0, buffer, &length );
736 * if ( error ) { ... could not load table ... }
739 * Note that structures like @TT_Header or @TT_OS2 can't be used with
740 * this function; they are limited to @FT_Get_Sfnt_Table. Reason is that
741 * those structures depend on the processor architecture, with varying
742 * size (e.g. 32bit vs. 64bit) or order (big endian vs. little endian).
745 FT_EXPORT( FT_Error
)
746 FT_Load_Sfnt_Table( FT_Face face
,
753 /**************************************************************************
759 * Return information on an SFNT table.
763 * A handle to the source face.
766 * The index of an SFNT table. The function returns
767 * FT_Err_Table_Missing for an invalid value.
771 * The name tag of the SFNT table. If the value is NULL, `table_index'
772 * is ignored, and `length' returns the number of SFNT tables in the
777 * The length of the SFNT table (or the number of SFNT tables, depending
781 * FreeType error code. 0~means success.
784 * While parsing fonts, FreeType handles SFNT tables with length zero as
788 FT_EXPORT( FT_Error
)
789 FT_Sfnt_Table_Info( FT_Face face
,
795 /*************************************************************************/
798 /* FT_Get_CMap_Language_ID */
801 /* Return cmap language ID as specified in the OpenType standard. */
802 /* Definitions of language ID values are in file @FT_TRUETYPE_IDS_H. */
806 /* The target charmap. */
809 /* The language ID of `charmap'. If `charmap' doesn't belong to an */
810 /* SFNT face, just return~0 as the default value. */
812 /* For a format~14 cmap (to access Unicode IVS), the return value is */
815 FT_EXPORT( FT_ULong
)
816 FT_Get_CMap_Language_ID( FT_CharMap charmap
);
819 /*************************************************************************/
822 /* FT_Get_CMap_Format */
825 /* Return the format of an SFNT `cmap' table. */
829 /* The target charmap. */
832 /* The format of `charmap'. If `charmap' doesn't belong to an SFNT */
833 /* face, return -1. */
836 FT_Get_CMap_Format( FT_CharMap charmap
);
843 #endif /* TTTABLES_H_ */