1 /****************************************************************************
2 *
3 * ftmm.h
4 *
5 * FreeType Multiple Master font interface (specification).
6 *
7 * Copyright (C) 1996-2023 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 FTMM_H_
20 #define FTMM_H_
21
22
23 #include <freetype/t1tables.h>
24
25
26 FT_BEGIN_HEADER
27
28
29 /**************************************************************************
30 *
31 * @section:
32 * multiple_masters
33 *
34 * @title:
35 * Multiple Masters
36 *
37 * @abstract:
38 * How to manage Multiple Masters fonts.
39 *
40 * @description:
41 * The following types and functions are used to manage Multiple Master
42 * fonts, i.e., the selection of specific design instances by setting
43 * design axis coordinates.
44 *
45 * Besides Adobe MM fonts, the interface supports Apple's TrueType GX and
46 * OpenType variation fonts. Some of the routines only work with Adobe
47 * MM fonts, others will work with all three types. They are similar
48 * enough that a consistent interface makes sense.
49 *
50 * For Adobe MM fonts, macro @FT_IS_SFNT returns false. For GX and
51 * OpenType variation fonts, it returns true.
52 *
53 */
54
55
56 /**************************************************************************
57 *
58 * @struct:
59 * FT_MM_Axis
60 *
61 * @description:
62 * A structure to model a given axis in design space for Multiple Masters
63 * fonts.
64 *
65 * This structure can't be used for TrueType GX or OpenType variation
66 * fonts.
67 *
68 * @fields:
69 * name ::
70 * The axis's name.
71 *
72 * minimum ::
73 * The axis's minimum design coordinate.
74 *
75 * maximum ::
76 * The axis's maximum design coordinate.
77 */
78 typedef struct FT_MM_Axis_
79 {
80 FT_String* name;
81 FT_Long minimum;
82 FT_Long maximum;
83
84 } FT_MM_Axis;
85
86
87 /**************************************************************************
88 *
89 * @struct:
90 * FT_Multi_Master
91 *
92 * @description:
93 * A structure to model the axes and space of a Multiple Masters font.
94 *
95 * This structure can't be used for TrueType GX or OpenType variation
96 * fonts.
97 *
98 * @fields:
99 * num_axis ::
100 * Number of axes. Cannot exceed~4.
101 *
102 * num_designs ::
103 * Number of designs; should be normally 2^num_axis even though the
104 * Type~1 specification strangely allows for intermediate designs to be
105 * present. This number cannot exceed~16.
106 *
107 * axis ::
108 * A table of axis descriptors.
109 */
110 typedef struct FT_Multi_Master_
111 {
112 FT_UInt num_axis;
113 FT_UInt num_designs;
114 FT_MM_Axis axis[T1_MAX_MM_AXIS];
115
116 } FT_Multi_Master;
117
118
119 /**************************************************************************
120 *
121 * @struct:
122 * FT_Var_Axis
123 *
124 * @description:
125 * A structure to model a given axis in design space for Multiple
126 * Masters, TrueType GX, and OpenType variation fonts.
127 *
128 * @fields:
129 * name ::
130 * The axis's name. Not always meaningful for TrueType GX or OpenType
131 * variation fonts.
132 *
133 * minimum ::
134 * The axis's minimum design coordinate.
135 *
136 * def ::
137 * The axis's default design coordinate. FreeType computes meaningful
138 * default values for Adobe MM fonts.
139 *
140 * maximum ::
141 * The axis's maximum design coordinate.
142 *
143 * tag ::
144 * The axis's tag (the equivalent to 'name' for TrueType GX and
145 * OpenType variation fonts). FreeType provides default values for
146 * Adobe MM fonts if possible.
147 *
148 * strid ::
149 * The axis name entry in the font's 'name' table. This is another
150 * (and often better) version of the 'name' field for TrueType GX or
151 * OpenType variation fonts. Not meaningful for Adobe MM fonts.
152 *
153 * @note:
154 * The fields `minimum`, `def`, and `maximum` are 16.16 fractional values
155 * for TrueType GX and OpenType variation fonts. For Adobe MM fonts, the
156 * values are whole numbers (i.e., the fractional part is zero).
157 */
158 typedef struct FT_Var_Axis_
159 {
160 FT_String* name;
161
162 FT_Fixed minimum;
163 FT_Fixed def;
164 FT_Fixed maximum;
165
166 FT_ULong tag;
167 FT_UInt strid;
168
169 } FT_Var_Axis;
170
171
172 /**************************************************************************
173 *
174 * @struct:
175 * FT_Var_Named_Style
176 *
177 * @description:
178 * A structure to model a named instance in a TrueType GX or OpenType
179 * variation font.
180 *
181 * This structure can't be used for Adobe MM fonts.
182 *
183 * @fields:
184 * coords ::
185 * The design coordinates for this instance. This is an array with one
186 * entry for each axis.
187 *
188 * strid ::
189 * The entry in 'name' table identifying this instance.
190 *
191 * psid ::
192 * The entry in 'name' table identifying a PostScript name for this
193 * instance. Value 0xFFFF indicates a missing entry.
194 */
195 typedef struct FT_Var_Named_Style_
196 {
197 FT_Fixed* coords;
198 FT_UInt strid;
199 FT_UInt psid; /* since 2.7.1 */
200
201 } FT_Var_Named_Style;
202
203
204 /**************************************************************************
205 *
206 * @struct:
207 * FT_MM_Var
208 *
209 * @description:
210 * A structure to model the axes and space of an Adobe MM, TrueType GX,
211 * or OpenType variation font.
212 *
213 * Some fields are specific to one format and not to the others.
214 *
215 * @fields:
216 * num_axis ::
217 * The number of axes. The maximum value is~4 for Adobe MM fonts; no
218 * limit in TrueType GX or OpenType variation fonts.
219 *
220 * num_designs ::
221 * The number of designs; should be normally 2^num_axis for Adobe MM
222 * fonts. Not meaningful for TrueType GX or OpenType variation fonts
223 * (where every glyph could have a different number of designs).
224 *
225 * num_namedstyles ::
226 * The number of named styles; a 'named style' is a tuple of design
227 * coordinates that has a string ID (in the 'name' table) associated
228 * with it. The font can tell the user that, for example,
229 * [Weight=1.5,Width=1.1] is 'Bold'. Another name for 'named style' is
230 * 'named instance'.
231 *
232 * For Adobe Multiple Masters fonts, this value is always zero because
233 * the format does not support named styles.
234 *
235 * axis ::
236 * An axis descriptor table. TrueType GX and OpenType variation fonts
237 * contain slightly more data than Adobe MM fonts. Memory management
238 * of this pointer is done internally by FreeType.
239 *
240 * namedstyle ::
241 * A named style (instance) table. Only meaningful for TrueType GX and
242 * OpenType variation fonts. Memory management of this pointer is done
243 * internally by FreeType.
244 */
245 typedef struct FT_MM_Var_
246 {
247 FT_UInt num_axis;
248 FT_UInt num_designs;
249 FT_UInt num_namedstyles;
250 FT_Var_Axis* axis;
251 FT_Var_Named_Style* namedstyle;
252
253 } FT_MM_Var;
254
255
256 /**************************************************************************
257 *
258 * @function:
259 * FT_Get_Multi_Master
260 *
261 * @description:
262 * Retrieve a variation descriptor of a given Adobe MM font.
263 *
264 * This function can't be used with TrueType GX or OpenType variation
265 * fonts.
266 *
267 * @input:
268 * face ::
269 * A handle to the source face.
270 *
271 * @output:
272 * amaster ::
273 * The Multiple Masters descriptor.
274 *
275 * @return:
276 * FreeType error code. 0~means success.
277 */
278 FT_EXPORT( FT_Error )
279 FT_Get_Multi_Master( FT_Face face,
280 FT_Multi_Master *amaster );
281
282
283 /**************************************************************************
284 *
285 * @function:
286 * FT_Get_MM_Var
287 *
288 * @description:
289 * Retrieve a variation descriptor for a given font.
290 *
291 * This function works with all supported variation formats.
292 *
293 * @input:
294 * face ::
295 * A handle to the source face.
296 *
297 * @output:
298 * amaster ::
299 * The variation descriptor. Allocates a data structure, which the
300 * user must deallocate with a call to @FT_Done_MM_Var after use.
301 *
302 * @return:
303 * FreeType error code. 0~means success.
304 */
305 FT_EXPORT( FT_Error )
306 FT_Get_MM_Var( FT_Face face,
307 FT_MM_Var* *amaster );
308
309
310 /**************************************************************************
311 *
312 * @function:
313 * FT_Done_MM_Var
314 *
315 * @description:
316 * Free the memory allocated by @FT_Get_MM_Var.
317 *
318 * @input:
319 * library ::
320 * A handle of the face's parent library object that was used in the
321 * call to @FT_Get_MM_Var to create `amaster`.
322 *
323 * @return:
324 * FreeType error code. 0~means success.
325 */
326 FT_EXPORT( FT_Error )
327 FT_Done_MM_Var( FT_Library library,
328 FT_MM_Var *amaster );
329
330
331 /**************************************************************************
332 *
333 * @function:
334 * FT_Set_MM_Design_Coordinates
335 *
336 * @description:
337 * For Adobe MM fonts, choose an interpolated font design through design
338 * coordinates.
339 *
340 * This function can't be used with TrueType GX or OpenType variation
341 * fonts.
342 *
343 * @inout:
344 * face ::
345 * A handle to the source face.
346 *
347 * @input:
348 * num_coords ::
349 * The number of available design coordinates. If it is larger than
350 * the number of axes, ignore the excess values. If it is smaller than
351 * the number of axes, use default values for the remaining axes.
352 *
353 * coords ::
354 * An array of design coordinates.
355 *
356 * @return:
357 * FreeType error code. 0~means success.
358 *
359 * @note:
360 * [Since 2.8.1] To reset all axes to the default values, call the
361 * function with `num_coords` set to zero and `coords` set to `NULL`.
362 *
363 * [Since 2.9] If `num_coords` is larger than zero, this function sets
364 * the @FT_FACE_FLAG_VARIATION bit in @FT_Face's `face_flags` field
365 * (i.e., @FT_IS_VARIATION will return true). If `num_coords` is zero,
366 * this bit flag gets unset.
367 */
368 FT_EXPORT( FT_Error )
369 FT_Set_MM_Design_Coordinates( FT_Face face,
370 FT_UInt num_coords,
371 FT_Long* coords );
372
373
374 /**************************************************************************
375 *
376 * @function:
377 * FT_Set_Var_Design_Coordinates
378 *
379 * @description:
380 * Choose an interpolated font design through design coordinates.
381 *
382 * This function works with all supported variation formats.
383 *
384 * @inout:
385 * face ::
386 * A handle to the source face.
387 *
388 * @input:
389 * num_coords ::
390 * The number of available design coordinates. If it is larger than
391 * the number of axes, ignore the excess values. If it is smaller than
392 * the number of axes, use default values for the remaining axes.
393 *
394 * coords ::
395 * An array of design coordinates.
396 *
397 * @return:
398 * FreeType error code. 0~means success.
399 *
400 * @note:
401 * The design coordinates are 16.16 fractional values for TrueType GX and
402 * OpenType variation fonts. For Adobe MM fonts, the values are supposed
403 * to be whole numbers (i.e., the fractional part is zero).
404 *
405 * [Since 2.8.1] To reset all axes to the default values, call the
406 * function with `num_coords` set to zero and `coords` set to `NULL`.
407 * [Since 2.9] 'Default values' means the currently selected named
408 * instance (or the base font if no named instance is selected).
409 *
410 * [Since 2.9] If `num_coords` is larger than zero, this function sets
411 * the @FT_FACE_FLAG_VARIATION bit in @FT_Face's `face_flags` field
412 * (i.e., @FT_IS_VARIATION will return true). If `num_coords` is zero,
413 * this bit flag gets unset.
414 */
415 FT_EXPORT( FT_Error )
416 FT_Set_Var_Design_Coordinates( FT_Face face,
417 FT_UInt num_coords,
418 FT_Fixed* coords );
419
420
421 /**************************************************************************
422 *
423 * @function:
424 * FT_Get_Var_Design_Coordinates
425 *
426 * @description:
427 * Get the design coordinates of the currently selected interpolated
428 * font.
429 *
430 * This function works with all supported variation formats.
431 *
432 * @input:
433 * face ::
434 * A handle to the source face.
435 *
436 * num_coords ::
437 * The number of design coordinates to retrieve. If it is larger than
438 * the number of axes, set the excess values to~0.
439 *
440 * @output:
441 * coords ::
442 * The design coordinates array.
443 *
444 * @return:
445 * FreeType error code. 0~means success.
446 *
447 * @note:
448 * The design coordinates are 16.16 fractional values for TrueType GX and
449 * OpenType variation fonts. For Adobe MM fonts, the values are whole
450 * numbers (i.e., the fractional part is zero).
451 *
452 * @since:
453 * 2.7.1
454 */
455 FT_EXPORT( FT_Error )
456 FT_Get_Var_Design_Coordinates( FT_Face face,
457 FT_UInt num_coords,
458 FT_Fixed* coords );
459
460
461 /**************************************************************************
462 *
463 * @function:
464 * FT_Set_MM_Blend_Coordinates
465 *
466 * @description:
467 * Choose an interpolated font design through normalized blend
468 * coordinates.
469 *
470 * This function works with all supported variation formats.
471 *
472 * @inout:
473 * face ::
474 * A handle to the source face.
475 *
476 * @input:
477 * num_coords ::
478 * The number of available design coordinates. If it is larger than
479 * the number of axes, ignore the excess values. If it is smaller than
480 * the number of axes, use default values for the remaining axes.
481 *
482 * coords ::
483 * The design coordinates array. Each element is a 16.16 fractional
484 * value and must be between 0 and 1.0 for Adobe MM fonts, and between
485 * -1.0 and 1.0 for TrueType GX and OpenType variation fonts.
486 *
487 * @return:
488 * FreeType error code. 0~means success.
489 *
490 * @note:
491 * [Since 2.8.1] To reset all axes to the default values, call the
492 * function with `num_coords` set to zero and `coords` set to `NULL`.
493 * [Since 2.9] 'Default values' means the currently selected named
494 * instance (or the base font if no named instance is selected).
495 *
496 * [Since 2.9] If `num_coords` is larger than zero, this function sets
497 * the @FT_FACE_FLAG_VARIATION bit in @FT_Face's `face_flags` field
498 * (i.e., @FT_IS_VARIATION will return true). If `num_coords` is zero,
499 * this bit flag gets unset.
500 */
501 FT_EXPORT( FT_Error )
502 FT_Set_MM_Blend_Coordinates( FT_Face face,
503 FT_UInt num_coords,
504 FT_Fixed* coords );
505
506
507 /**************************************************************************
508 *
509 * @function:
510 * FT_Get_MM_Blend_Coordinates
511 *
512 * @description:
513 * Get the normalized blend coordinates of the currently selected
514 * interpolated font.
515 *
516 * This function works with all supported variation formats.
517 *
518 * @input:
519 * face ::
520 * A handle to the source face.
521 *
522 * num_coords ::
523 * The number of normalized blend coordinates to retrieve. If it is
524 * larger than the number of axes, set the excess values to~0.5 for
525 * Adobe MM fonts, and to~0 for TrueType GX and OpenType variation
526 * fonts.
527 *
528 * @output:
529 * coords ::
530 * The normalized blend coordinates array (as 16.16 fractional values).
531 *
532 * @return:
533 * FreeType error code. 0~means success.
534 *
535 * @since:
536 * 2.7.1
537 */
538 FT_EXPORT( FT_Error )
539 FT_Get_MM_Blend_Coordinates( FT_Face face,
540 FT_UInt num_coords,
541 FT_Fixed* coords );
542
543
544 /**************************************************************************
545 *
546 * @function:
547 * FT_Set_Var_Blend_Coordinates
548 *
549 * @description:
550 * This is another name of @FT_Set_MM_Blend_Coordinates.
551 */
552 FT_EXPORT( FT_Error )
553 FT_Set_Var_Blend_Coordinates( FT_Face face,
554 FT_UInt num_coords,
555 FT_Fixed* coords );
556
557
558 /**************************************************************************
559 *
560 * @function:
561 * FT_Get_Var_Blend_Coordinates
562 *
563 * @description:
564 * This is another name of @FT_Get_MM_Blend_Coordinates.
565 *
566 * @since:
567 * 2.7.1
568 */
569 FT_EXPORT( FT_Error )
570 FT_Get_Var_Blend_Coordinates( FT_Face face,
571 FT_UInt num_coords,
572 FT_Fixed* coords );
573
574
575 /**************************************************************************
576 *
577 * @function:
578 * FT_Set_MM_WeightVector
579 *
580 * @description:
581 * For Adobe MM fonts, choose an interpolated font design by directly
582 * setting the weight vector.
583 *
584 * This function can't be used with TrueType GX or OpenType variation
585 * fonts.
586 *
587 * @inout:
588 * face ::
589 * A handle to the source face.
590 *
591 * @input:
592 * len ::
593 * The length of the weight vector array. If it is larger than the
594 * number of designs, the extra values are ignored. If it is less than
595 * the number of designs, the remaining values are set to zero.
596 *
597 * weightvector ::
598 * An array representing the weight vector.
599 *
600 * @return:
601 * FreeType error code. 0~means success.
602 *
603 * @note:
604 * Adobe Multiple Master fonts limit the number of designs, and thus the
605 * length of the weight vector to 16~elements.
606 *
607 * If `len` is larger than zero, this function sets the
608 * @FT_FACE_FLAG_VARIATION bit in @FT_Face's `face_flags` field (i.e.,
609 * @FT_IS_VARIATION will return true). If `len` is zero, this bit flag
610 * is unset and the weight vector array is reset to the default values.
611 *
612 * The Adobe documentation also states that the values in the
613 * WeightVector array must total 1.0 +/-~0.001. In practice this does
614 * not seem to be enforced, so is not enforced here, either.
615 *
616 * @since:
617 * 2.10
618 */
619 FT_EXPORT( FT_Error )
620 FT_Set_MM_WeightVector( FT_Face face,
621 FT_UInt len,
622 FT_Fixed* weightvector );
623
624
625 /**************************************************************************
626 *
627 * @function:
628 * FT_Get_MM_WeightVector
629 *
630 * @description:
631 * For Adobe MM fonts, retrieve the current weight vector of the font.
632 *
633 * This function can't be used with TrueType GX or OpenType variation
634 * fonts.
635 *
636 * @inout:
637 * face ::
638 * A handle to the source face.
639 *
640 * len ::
641 * A pointer to the size of the array to be filled. If the size of the
642 * array is less than the number of designs, `FT_Err_Invalid_Argument`
643 * is returned, and `len` is set to the required size (the number of
644 * designs). If the size of the array is greater than the number of
645 * designs, the remaining entries are set to~0. On successful
646 * completion, `len` is set to the number of designs (i.e., the number
647 * of values written to the array).
648 *
649 * @output:
650 * weightvector ::
651 * An array to be filled.
652 *
653 * @return:
654 * FreeType error code. 0~means success.
655 *
656 * @note:
657 * Adobe Multiple Master fonts limit the number of designs, and thus the
658 * length of the WeightVector to~16.
659 *
660 * @since:
661 * 2.10
662 */
663 FT_EXPORT( FT_Error )
664 FT_Get_MM_WeightVector( FT_Face face,
665 FT_UInt* len,
666 FT_Fixed* weightvector );
667
668
669 /**************************************************************************
670 *
671 * @enum:
672 * FT_VAR_AXIS_FLAG_XXX
673 *
674 * @description:
675 * A list of bit flags used in the return value of
676 * @FT_Get_Var_Axis_Flags.
677 *
678 * @values:
679 * FT_VAR_AXIS_FLAG_HIDDEN ::
680 * The variation axis should not be exposed to user interfaces.
681 *
682 * @since:
683 * 2.8.1
684 */
685 #define FT_VAR_AXIS_FLAG_HIDDEN 1
686
687
688 /**************************************************************************
689 *
690 * @function:
691 * FT_Get_Var_Axis_Flags
692 *
693 * @description:
694 * Get the 'flags' field of an OpenType Variation Axis Record.
695 *
696 * Not meaningful for Adobe MM fonts (`*flags` is always zero).
697 *
698 * @input:
699 * master ::
700 * The variation descriptor.
701 *
702 * axis_index ::
703 * The index of the requested variation axis.
704 *
705 * @output:
706 * flags ::
707 * The 'flags' field. See @FT_VAR_AXIS_FLAG_XXX for possible values.
708 *
709 * @return:
710 * FreeType error code. 0~means success.
711 *
712 * @since:
713 * 2.8.1
714 */
715 FT_EXPORT( FT_Error )
716 FT_Get_Var_Axis_Flags( FT_MM_Var* master,
717 FT_UInt axis_index,
718 FT_UInt* flags );
719
720
721 /**************************************************************************
722 *
723 * @function:
724 * FT_Set_Named_Instance
725 *
726 * @description:
727 * Set or change the current named instance.
728 *
729 * @input:
730 * face ::
731 * A handle to the source face.
732 *
733 * instance_index ::
734 * The index of the requested instance, starting with value 1. If set
735 * to value 0, FreeType switches to font access without a named
736 * instance.
737 *
738 * @return:
739 * FreeType error code. 0~means success.
740 *
741 * @note:
742 * The function uses the value of `instance_index` to set bits 16-30 of
743 * the face's `face_index` field. It also resets any variation applied
744 * to the font, and the @FT_FACE_FLAG_VARIATION bit of the face's
745 * `face_flags` field gets reset to zero (i.e., @FT_IS_VARIATION will
746 * return false).
747 *
748 * For Adobe MM fonts (which don't have named instances) this function
749 * simply resets the current face to the default instance.
750 *
751 * @since:
752 * 2.9
753 */
754 FT_EXPORT( FT_Error )
755 FT_Set_Named_Instance( FT_Face face,
756 FT_UInt instance_index );
757
758
759 /**************************************************************************
760 *
761 * @function:
762 * FT_Get_Default_Named_Instance
763 *
764 * @description:
765 * Retrieve the index of the default named instance, to be used with
766 * @FT_Set_Named_Instance.
767 *
768 * The default instance of a variation font is that instance for which
769 * the nth axis coordinate is equal to `axis[n].def` (as specified in the
770 * @FT_MM_Var structure), with~n covering all axes.
771 *
772 * FreeType synthesizes a named instance for the default instance if the
773 * font does not contain such an entry.
774 *
775 * @input:
776 * face ::
777 * A handle to the source face.
778 *
779 * @output:
780 * instance_index ::
781 * The index of the default named instance.
782 *
783 * @return:
784 * FreeType error code. 0~means success.
785 *
786 * @note:
787 * For Adobe MM fonts (which don't have named instances) this function
788 * always returns zero for `instance_index`.
789 *
790 * @since:
791 * 2.13.1
792 */
793 FT_EXPORT( FT_Error )
794 FT_Get_Default_Named_Instance( FT_Face face,
795 FT_UInt *instance_index );
796
797 /* */
798
799
800 FT_END_HEADER
801
802 #endif /* FTMM_H_ */
803
804
805 /* END */