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

source code of include/freetype2/freetype/ftmm.h