1 /***************************************************************************/
5 /* FreeType Multiple Master font interface (specification). */
7 /* Copyright 1996-2018 by */
8 /* David Turner, Robert Wilhelm, and Werner Lemberg. */
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. */
16 /***************************************************************************/
24 #include FT_TYPE1_TABLES_H
30 /*************************************************************************/
33 /* multiple_masters */
36 /* Multiple Masters */
39 /* How to manage Multiple Masters fonts. */
42 /* The following types and functions are used to manage Multiple */
43 /* Master fonts, i.e., the selection of specific design instances by */
44 /* setting design axis coordinates. */
46 /* Besides Adobe MM fonts, the interface supports Apple's TrueType GX */
47 /* and OpenType variation fonts. Some of the routines only work with */
48 /* Adobe MM fonts, others will work with all three types. They are */
49 /* similar enough that a consistent interface makes sense. */
51 /*************************************************************************/
54 /*************************************************************************/
60 /* A structure to model a given axis in design space for Multiple */
63 /* This structure can't be used for TrueType GX or OpenType variation */
67 /* name :: The axis's name. */
69 /* minimum :: The axis's minimum design coordinate. */
71 /* maximum :: The axis's maximum design coordinate. */
73 typedef struct FT_MM_Axis_
82 /*************************************************************************/
88 /* A structure to model the axes and space of a Multiple Masters */
91 /* This structure can't be used for TrueType GX or OpenType variation */
95 /* num_axis :: Number of axes. Cannot exceed~4. */
97 /* num_designs :: Number of designs; should be normally 2^num_axis */
98 /* even though the Type~1 specification strangely */
99 /* allows for intermediate designs to be present. */
100 /* This number cannot exceed~16. */
102 /* axis :: A table of axis descriptors. */
104 typedef struct FT_Multi_Master_
108 FT_MM_Axis axis
[T1_MAX_MM_AXIS
];
113 /*************************************************************************/
119 /* A structure to model a given axis in design space for Multiple */
120 /* Masters, TrueType GX, and OpenType variation fonts. */
123 /* name :: The axis's name. */
124 /* Not always meaningful for TrueType GX or OpenType */
125 /* variation fonts. */
127 /* minimum :: The axis's minimum design coordinate. */
129 /* def :: The axis's default design coordinate. */
130 /* FreeType computes meaningful default values for Adobe */
133 /* maximum :: The axis's maximum design coordinate. */
135 /* tag :: The axis's tag (the equivalent to `name' for TrueType */
136 /* GX and OpenType variation fonts). FreeType provides */
137 /* default values for Adobe MM fonts if possible. */
139 /* strid :: The axis name entry in the font's `name' table. This */
140 /* is another (and often better) version of the `name' */
141 /* field for TrueType GX or OpenType variation fonts. Not */
142 /* meaningful for Adobe MM fonts. */
145 /* The fields `minimum', `def', and `maximum' are 16.16 fractional */
146 /* values for TrueType GX and OpenType variation fonts. For Adobe MM */
147 /* fonts, the values are integers. */
149 typedef struct FT_Var_Axis_
163 /*************************************************************************/
166 /* FT_Var_Named_Style */
169 /* A structure to model a named instance in a TrueType GX or OpenType */
170 /* variation font. */
172 /* This structure can't be used for Adobe MM fonts. */
175 /* coords :: The design coordinates for this instance. */
176 /* This is an array with one entry for each axis. */
178 /* strid :: The entry in `name' table identifying this instance. */
180 /* psid :: The entry in `name' table identifying a PostScript name */
181 /* for this instance. Value 0xFFFF indicates a missing */
184 typedef struct FT_Var_Named_Style_
188 FT_UInt psid
; /* since 2.7.1 */
190 } FT_Var_Named_Style
;
193 /*************************************************************************/
199 /* A structure to model the axes and space of an Adobe MM, TrueType */
200 /* GX, or OpenType variation font. */
202 /* Some fields are specific to one format and not to the others. */
205 /* num_axis :: The number of axes. The maximum value is~4 for */
206 /* Adobe MM fonts; no limit in TrueType GX or */
207 /* OpenType variation fonts. */
209 /* num_designs :: The number of designs; should be normally */
210 /* 2^num_axis for Adobe MM fonts. Not meaningful */
211 /* for TrueType GX or OpenType variation fonts */
212 /* (where every glyph could have a different */
213 /* number of designs). */
215 /* num_namedstyles :: The number of named styles; a `named style' is */
216 /* a tuple of design coordinates that has a string */
217 /* ID (in the `name' table) associated with it. */
218 /* The font can tell the user that, for example, */
219 /* [Weight=1.5,Width=1.1] is `Bold'. Another name */
220 /* for `named style' is `named instance'. */
222 /* For Adobe Multiple Masters fonts, this value is */
223 /* always zero because the format does not support */
226 /* axis :: An axis descriptor table. */
227 /* TrueType GX and OpenType variation fonts */
228 /* contain slightly more data than Adobe MM fonts. */
229 /* Memory management of this pointer is done */
230 /* internally by FreeType. */
232 /* namedstyle :: A named style (instance) table. */
233 /* Only meaningful for TrueType GX and OpenType */
234 /* variation fonts. Memory management of this */
235 /* pointer is done internally by FreeType. */
237 typedef struct FT_MM_Var_
241 FT_UInt num_namedstyles
;
243 FT_Var_Named_Style
* namedstyle
;
248 /*************************************************************************/
251 /* FT_Get_Multi_Master */
254 /* Retrieve a variation descriptor of a given Adobe MM font. */
256 /* This function can't be used with TrueType GX or OpenType variation */
260 /* face :: A handle to the source face. */
263 /* amaster :: The Multiple Masters descriptor. */
266 /* FreeType error code. 0~means success. */
268 FT_EXPORT( FT_Error
)
269 FT_Get_Multi_Master( FT_Face face
,
270 FT_Multi_Master
*amaster
);
273 /*************************************************************************/
279 /* Retrieve a variation descriptor for a given font. */
281 /* This function works with all supported variation formats. */
284 /* face :: A handle to the source face. */
287 /* amaster :: The variation descriptor. */
288 /* Allocates a data structure, which the user must */
289 /* deallocate with a call to @FT_Done_MM_Var after use. */
292 /* FreeType error code. 0~means success. */
294 FT_EXPORT( FT_Error
)
295 FT_Get_MM_Var( FT_Face face
,
296 FT_MM_Var
* *amaster
);
299 /*************************************************************************/
305 /* Free the memory allocated by @FT_Get_MM_Var. */
308 /* library :: A handle of the face's parent library object that was */
309 /* used in the call to @FT_Get_MM_Var to create `amaster'. */
312 /* FreeType error code. 0~means success. */
314 FT_EXPORT( FT_Error
)
315 FT_Done_MM_Var( FT_Library library
,
316 FT_MM_Var
*amaster
);
319 /*************************************************************************/
322 /* FT_Set_MM_Design_Coordinates */
325 /* For Adobe MM fonts, choose an interpolated font design through */
326 /* design coordinates. */
328 /* This function can't be used with TrueType GX or OpenType variation */
332 /* face :: A handle to the source face. */
335 /* num_coords :: The number of available design coordinates. If it */
336 /* is larger than the number of axes, ignore the excess */
337 /* values. If it is smaller than the number of axes, */
338 /* use default values for the remaining axes. */
340 /* coords :: An array of design coordinates. */
343 /* FreeType error code. 0~means success. */
346 /* [Since 2.8.1] To reset all axes to the default values, call the */
347 /* function with `num_coords' set to zero and `coords' set to NULL. */
349 /* [Since 2.9] If `num_coords' is larger than zero, this function */
350 /* sets the @FT_FACE_FLAG_VARIATION bit in @FT_Face's `face_flags' */
351 /* field (i.e., @FT_IS_VARIATION will return true). If `num_coords' */
352 /* is zero, this bit flag gets unset. */
354 FT_EXPORT( FT_Error
)
355 FT_Set_MM_Design_Coordinates( FT_Face face
,
360 /*************************************************************************/
363 /* FT_Set_Var_Design_Coordinates */
366 /* Choose an interpolated font design through design coordinates. */
368 /* This function works with all supported variation formats. */
371 /* face :: A handle to the source face. */
374 /* num_coords :: The number of available design coordinates. If it */
375 /* is larger than the number of axes, ignore the excess */
376 /* values. If it is smaller than the number of axes, */
377 /* use default values for the remaining axes. */
379 /* coords :: An array of design coordinates. */
382 /* FreeType error code. 0~means success. */
385 /* [Since 2.8.1] To reset all axes to the default values, call the */
386 /* function with `num_coords' set to zero and `coords' set to NULL. */
387 /* [Since 2.9] `Default values' means the currently selected named */
388 /* instance (or the base font if no named instance is selected). */
390 /* [Since 2.9] If `num_coords' is larger than zero, this function */
391 /* sets the @FT_FACE_FLAG_VARIATION bit in @FT_Face's `face_flags' */
392 /* field (i.e., @FT_IS_VARIATION will return true). If `num_coords' */
393 /* is zero, this bit flag gets unset. */
395 FT_EXPORT( FT_Error
)
396 FT_Set_Var_Design_Coordinates( FT_Face face
,
401 /*************************************************************************/
404 /* FT_Get_Var_Design_Coordinates */
407 /* Get the design coordinates of the currently selected interpolated */
410 /* This function works with all supported variation formats. */
413 /* face :: A handle to the source face. */
415 /* num_coords :: The number of design coordinates to retrieve. If it */
416 /* is larger than the number of axes, set the excess */
420 /* coords :: The design coordinates array. */
423 /* FreeType error code. 0~means success. */
428 FT_EXPORT( FT_Error
)
429 FT_Get_Var_Design_Coordinates( FT_Face face
,
434 /*************************************************************************/
437 /* FT_Set_MM_Blend_Coordinates */
440 /* Choose an interpolated font design through normalized blend */
443 /* This function works with all supported variation formats. */
446 /* face :: A handle to the source face. */
449 /* num_coords :: The number of available design coordinates. If it */
450 /* is larger than the number of axes, ignore the excess */
451 /* values. If it is smaller than the number of axes, */
452 /* use default values for the remaining axes. */
454 /* coords :: The design coordinates array (each element must be */
455 /* between 0 and 1.0 for Adobe MM fonts, and between */
456 /* -1.0 and 1.0 for TrueType GX and OpenType variation */
460 /* FreeType error code. 0~means success. */
463 /* [Since 2.8.1] To reset all axes to the default values, call the */
464 /* function with `num_coords' set to zero and `coords' set to NULL. */
465 /* [Since 2.9] `Default values' means the currently selected named */
466 /* instance (or the base font if no named instance is selected). */
468 /* [Since 2.9] If `num_coords' is larger than zero, this function */
469 /* sets the @FT_FACE_FLAG_VARIATION bit in @FT_Face's `face_flags' */
470 /* field (i.e., @FT_IS_VARIATION will return true). If `num_coords' */
471 /* is zero, this bit flag gets unset. */
473 FT_EXPORT( FT_Error
)
474 FT_Set_MM_Blend_Coordinates( FT_Face face
,
479 /*************************************************************************/
482 /* FT_Get_MM_Blend_Coordinates */
485 /* Get the normalized blend coordinates of the currently selected */
486 /* interpolated font. */
488 /* This function works with all supported variation formats. */
491 /* face :: A handle to the source face. */
493 /* num_coords :: The number of normalized blend coordinates to */
494 /* retrieve. If it is larger than the number of axes, */
495 /* set the excess values to~0.5 for Adobe MM fonts, and */
496 /* to~0 for TrueType GX and OpenType variation fonts. */
499 /* coords :: The normalized blend coordinates array. */
502 /* FreeType error code. 0~means success. */
507 FT_EXPORT( FT_Error
)
508 FT_Get_MM_Blend_Coordinates( FT_Face face
,
513 /*************************************************************************/
516 /* FT_Set_Var_Blend_Coordinates */
519 /* This is another name of @FT_Set_MM_Blend_Coordinates. */
521 FT_EXPORT( FT_Error
)
522 FT_Set_Var_Blend_Coordinates( FT_Face face
,
527 /*************************************************************************/
530 /* FT_Get_Var_Blend_Coordinates */
533 /* This is another name of @FT_Get_MM_Blend_Coordinates. */
538 FT_EXPORT( FT_Error
)
539 FT_Get_Var_Blend_Coordinates( FT_Face face
,
544 /*************************************************************************/
547 /* FT_VAR_AXIS_FLAG_XXX */
550 /* A list of bit flags used in the return value of */
551 /* @FT_Get_Var_Axis_Flags. */
554 /* FT_VAR_AXIS_FLAG_HIDDEN :: */
555 /* The variation axis should not be exposed to user interfaces. */
560 #define FT_VAR_AXIS_FLAG_HIDDEN 1
563 /*************************************************************************/
566 /* FT_Get_Var_Axis_Flags */
569 /* Get the `flags' field of an OpenType Variation Axis Record. */
571 /* Not meaningful for Adobe MM fonts (`*flags' is always zero). */
574 /* master :: The variation descriptor. */
576 /* axis_index :: The index of the requested variation axis. */
579 /* flags :: The `flags' field. See @FT_VAR_AXIS_FLAG_XXX for */
580 /* possible values. */
583 /* FreeType error code. 0~means success. */
588 FT_EXPORT( FT_Error
)
589 FT_Get_Var_Axis_Flags( FT_MM_Var
* master
,
594 /*************************************************************************/
597 /* FT_Set_Named_Instance */
600 /* Set or change the current named instance. */
603 /* face :: A handle to the source face. */
605 /* instance_index :: The index of the requested instance, starting */
606 /* with value 1. If set to value 0, FreeType */
607 /* switches to font access without a named */
611 /* FreeType error code. 0~means success. */
614 /* The function uses the value of `instance_index' to set bits 16-30 */
615 /* of the face's `face_index' field. It also resets any variation */
616 /* applied to the font, and the @FT_FACE_FLAG_VARIATION bit of the */
617 /* face's `face_flags' field gets reset to zero (i.e., */
618 /* @FT_IS_VARIATION will return false). */
620 /* For Adobe MM fonts (which don't have named instances) this */
621 /* function simply resets the current face to the default instance. */
626 FT_EXPORT( FT_Error
)
627 FT_Set_Named_Instance( FT_Face face
,
628 FT_UInt instance_index
);