ReactOS  0.4.13-dev-982-g9853eab
ftmm.h
Go to the documentation of this file.
1 /***************************************************************************/
2 /* */
3 /* ftmm.h */
4 /* */
5 /* FreeType Multiple Master font interface (specification). */
6 /* */
7 /* Copyright 1996-2018 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 <ft2build.h>
24 #include FT_TYPE1_TABLES_H
25 
26 
28 
29 
30  /*************************************************************************/
31  /* */
32  /* <Section> */
33  /* multiple_masters */
34  /* */
35  /* <Title> */
36  /* Multiple Masters */
37  /* */
38  /* <Abstract> */
39  /* How to manage Multiple Masters fonts. */
40  /* */
41  /* <Description> */
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. */
45  /* */
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. */
50  /* */
51  /*************************************************************************/
52 
53 
54  /*************************************************************************/
55  /* */
56  /* <Struct> */
57  /* FT_MM_Axis */
58  /* */
59  /* <Description> */
60  /* A structure to model a given axis in design space for Multiple */
61  /* Masters fonts. */
62  /* */
63  /* This structure can't be used for TrueType GX or OpenType variation */
64  /* fonts. */
65  /* */
66  /* <Fields> */
67  /* name :: The axis's name. */
68  /* */
69  /* minimum :: The axis's minimum design coordinate. */
70  /* */
71  /* maximum :: The axis's maximum design coordinate. */
72  /* */
73  typedef struct FT_MM_Axis_
74  {
78 
79  } FT_MM_Axis;
80 
81 
82  /*************************************************************************/
83  /* */
84  /* <Struct> */
85  /* FT_Multi_Master */
86  /* */
87  /* <Description> */
88  /* A structure to model the axes and space of a Multiple Masters */
89  /* font. */
90  /* */
91  /* This structure can't be used for TrueType GX or OpenType variation */
92  /* fonts. */
93  /* */
94  /* <Fields> */
95  /* num_axis :: Number of axes. Cannot exceed~4. */
96  /* */
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. */
101  /* */
102  /* axis :: A table of axis descriptors. */
103  /* */
104  typedef struct FT_Multi_Master_
105  {
109 
110  } FT_Multi_Master;
111 
112 
113  /*************************************************************************/
114  /* */
115  /* <Struct> */
116  /* FT_Var_Axis */
117  /* */
118  /* <Description> */
119  /* A structure to model a given axis in design space for Multiple */
120  /* Masters, TrueType GX, and OpenType variation fonts. */
121  /* */
122  /* <Fields> */
123  /* name :: The axis's name. */
124  /* Not always meaningful for TrueType GX or OpenType */
125  /* variation fonts. */
126  /* */
127  /* minimum :: The axis's minimum design coordinate. */
128  /* */
129  /* def :: The axis's default design coordinate. */
130  /* FreeType computes meaningful default values for Adobe */
131  /* MM fonts. */
132  /* */
133  /* maximum :: The axis's maximum design coordinate. */
134  /* */
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. */
138  /* */
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. */
143  /* */
144  /* <Note> */
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. */
148  /* */
149  typedef struct FT_Var_Axis_
150  {
152 
156 
159 
160  } FT_Var_Axis;
161 
162 
163  /*************************************************************************/
164  /* */
165  /* <Struct> */
166  /* FT_Var_Named_Style */
167  /* */
168  /* <Description> */
169  /* A structure to model a named instance in a TrueType GX or OpenType */
170  /* variation font. */
171  /* */
172  /* This structure can't be used for Adobe MM fonts. */
173  /* */
174  /* <Fields> */
175  /* coords :: The design coordinates for this instance. */
176  /* This is an array with one entry for each axis. */
177  /* */
178  /* strid :: The entry in `name' table identifying this instance. */
179  /* */
180  /* psid :: The entry in `name' table identifying a PostScript name */
181  /* for this instance. Value 0xFFFF indicates a missing */
182  /* entry. */
183  /* */
184  typedef struct FT_Var_Named_Style_
185  {
188  FT_UInt psid; /* since 2.7.1 */
189 
191 
192 
193  /*************************************************************************/
194  /* */
195  /* <Struct> */
196  /* FT_MM_Var */
197  /* */
198  /* <Description> */
199  /* A structure to model the axes and space of an Adobe MM, TrueType */
200  /* GX, or OpenType variation font. */
201  /* */
202  /* Some fields are specific to one format and not to the others. */
203  /* */
204  /* <Fields> */
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. */
208  /* */
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). */
214  /* */
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'. */
221  /* */
222  /* For Adobe Multiple Masters fonts, this value is */
223  /* always zero because the format does not support */
224  /* named styles. */
225  /* */
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. */
231  /* */
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. */
236  /* */
237  typedef struct FT_MM_Var_
238  {
244 
245  } FT_MM_Var;
246 
247 
248  /*************************************************************************/
249  /* */
250  /* <Function> */
251  /* FT_Get_Multi_Master */
252  /* */
253  /* <Description> */
254  /* Retrieve a variation descriptor of a given Adobe MM font. */
255  /* */
256  /* This function can't be used with TrueType GX or OpenType variation */
257  /* fonts. */
258  /* */
259  /* <Input> */
260  /* face :: A handle to the source face. */
261  /* */
262  /* <Output> */
263  /* amaster :: The Multiple Masters descriptor. */
264  /* */
265  /* <Return> */
266  /* FreeType error code. 0~means success. */
267  /* */
270  FT_Multi_Master *amaster );
271 
272 
273  /*************************************************************************/
274  /* */
275  /* <Function> */
276  /* FT_Get_MM_Var */
277  /* */
278  /* <Description> */
279  /* Retrieve a variation descriptor for a given font. */
280  /* */
281  /* This function works with all supported variation formats. */
282  /* */
283  /* <Input> */
284  /* face :: A handle to the source face. */
285  /* */
286  /* <Output> */
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. */
290  /* */
291  /* <Return> */
292  /* FreeType error code. 0~means success. */
293  /* */
296  FT_MM_Var* *amaster );
297 
298 
299  /*************************************************************************/
300  /* */
301  /* <Function> */
302  /* FT_Done_MM_Var */
303  /* */
304  /* <Description> */
305  /* Free the memory allocated by @FT_Get_MM_Var. */
306  /* */
307  /* <Input> */
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'. */
310  /* */
311  /* <Return> */
312  /* FreeType error code. 0~means success. */
313  /* */
316  FT_MM_Var *amaster );
317 
318 
319  /*************************************************************************/
320  /* */
321  /* <Function> */
322  /* FT_Set_MM_Design_Coordinates */
323  /* */
324  /* <Description> */
325  /* For Adobe MM fonts, choose an interpolated font design through */
326  /* design coordinates. */
327  /* */
328  /* This function can't be used with TrueType GX or OpenType variation */
329  /* fonts. */
330  /* */
331  /* <InOut> */
332  /* face :: A handle to the source face. */
333  /* */
334  /* <Input> */
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. */
339  /* */
340  /* coords :: An array of design coordinates. */
341  /* */
342  /* <Return> */
343  /* FreeType error code. 0~means success. */
344  /* */
345  /* <Note> */
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. */
348  /* */
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. */
353  /* */
356  FT_UInt num_coords,
357  FT_Long* coords );
358 
359 
360  /*************************************************************************/
361  /* */
362  /* <Function> */
363  /* FT_Set_Var_Design_Coordinates */
364  /* */
365  /* <Description> */
366  /* Choose an interpolated font design through design coordinates. */
367  /* */
368  /* This function works with all supported variation formats. */
369  /* */
370  /* <InOut> */
371  /* face :: A handle to the source face. */
372  /* */
373  /* <Input> */
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. */
378  /* */
379  /* coords :: An array of design coordinates. */
380  /* */
381  /* <Return> */
382  /* FreeType error code. 0~means success. */
383  /* */
384  /* <Note> */
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). */
389  /* */
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. */
394  /* */
397  FT_UInt num_coords,
398  FT_Fixed* coords );
399 
400 
401  /*************************************************************************/
402  /* */
403  /* <Function> */
404  /* FT_Get_Var_Design_Coordinates */
405  /* */
406  /* <Description> */
407  /* Get the design coordinates of the currently selected interpolated */
408  /* font. */
409  /* */
410  /* This function works with all supported variation formats. */
411  /* */
412  /* <Input> */
413  /* face :: A handle to the source face. */
414  /* */
415  /* num_coords :: The number of design coordinates to retrieve. If it */
416  /* is larger than the number of axes, set the excess */
417  /* values to~0. */
418  /* */
419  /* <Output> */
420  /* coords :: The design coordinates array. */
421  /* */
422  /* <Return> */
423  /* FreeType error code. 0~means success. */
424  /* */
425  /* <Since> */
426  /* 2.7.1 */
427  /* */
430  FT_UInt num_coords,
431  FT_Fixed* coords );
432 
433 
434  /*************************************************************************/
435  /* */
436  /* <Function> */
437  /* FT_Set_MM_Blend_Coordinates */
438  /* */
439  /* <Description> */
440  /* Choose an interpolated font design through normalized blend */
441  /* coordinates. */
442  /* */
443  /* This function works with all supported variation formats. */
444  /* */
445  /* <InOut> */
446  /* face :: A handle to the source face. */
447  /* */
448  /* <Input> */
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. */
453  /* */
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 */
457  /* fonts). */
458  /* */
459  /* <Return> */
460  /* FreeType error code. 0~means success. */
461  /* */
462  /* <Note> */
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). */
467  /* */
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. */
472  /* */
475  FT_UInt num_coords,
476  FT_Fixed* coords );
477 
478 
479  /*************************************************************************/
480  /* */
481  /* <Function> */
482  /* FT_Get_MM_Blend_Coordinates */
483  /* */
484  /* <Description> */
485  /* Get the normalized blend coordinates of the currently selected */
486  /* interpolated font. */
487  /* */
488  /* This function works with all supported variation formats. */
489  /* */
490  /* <Input> */
491  /* face :: A handle to the source face. */
492  /* */
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. */
497  /* */
498  /* <Output> */
499  /* coords :: The normalized blend coordinates array. */
500  /* */
501  /* <Return> */
502  /* FreeType error code. 0~means success. */
503  /* */
504  /* <Since> */
505  /* 2.7.1 */
506  /* */
509  FT_UInt num_coords,
510  FT_Fixed* coords );
511 
512 
513  /*************************************************************************/
514  /* */
515  /* <Function> */
516  /* FT_Set_Var_Blend_Coordinates */
517  /* */
518  /* <Description> */
519  /* This is another name of @FT_Set_MM_Blend_Coordinates. */
520  /* */
523  FT_UInt num_coords,
524  FT_Fixed* coords );
525 
526 
527  /*************************************************************************/
528  /* */
529  /* <Function> */
530  /* FT_Get_Var_Blend_Coordinates */
531  /* */
532  /* <Description> */
533  /* This is another name of @FT_Get_MM_Blend_Coordinates. */
534  /* */
535  /* <Since> */
536  /* 2.7.1 */
537  /* */
540  FT_UInt num_coords,
541  FT_Fixed* coords );
542 
543 
544  /*************************************************************************/
545  /* */
546  /* <Enum> */
547  /* FT_VAR_AXIS_FLAG_XXX */
548  /* */
549  /* <Description> */
550  /* A list of bit flags used in the return value of */
551  /* @FT_Get_Var_Axis_Flags. */
552  /* */
553  /* <Values> */
554  /* FT_VAR_AXIS_FLAG_HIDDEN :: */
555  /* The variation axis should not be exposed to user interfaces. */
556  /* */
557  /* <Since> */
558  /* 2.8.1 */
559  /* */
560 #define FT_VAR_AXIS_FLAG_HIDDEN 1
561 
562 
563  /*************************************************************************/
564  /* */
565  /* <Function> */
566  /* FT_Get_Var_Axis_Flags */
567  /* */
568  /* <Description> */
569  /* Get the `flags' field of an OpenType Variation Axis Record. */
570  /* */
571  /* Not meaningful for Adobe MM fonts (`*flags' is always zero). */
572  /* */
573  /* <Input> */
574  /* master :: The variation descriptor. */
575  /* */
576  /* axis_index :: The index of the requested variation axis. */
577  /* */
578  /* <Output> */
579  /* flags :: The `flags' field. See @FT_VAR_AXIS_FLAG_XXX for */
580  /* possible values. */
581  /* */
582  /* <Return> */
583  /* FreeType error code. 0~means success. */
584  /* */
585  /* <Since> */
586  /* 2.8.1 */
587  /* */
590  FT_UInt axis_index,
591  FT_UInt* flags );
592 
593 
594  /*************************************************************************/
595  /* */
596  /* <Function> */
597  /* FT_Set_Named_Instance */
598  /* */
599  /* <Description> */
600  /* Set or change the current named instance. */
601  /* */
602  /* <Input> */
603  /* face :: A handle to the source face. */
604  /* */
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 */
608  /* instance. */
609  /* */
610  /* <Return> */
611  /* FreeType error code. 0~means success. */
612  /* */
613  /* <Note> */
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). */
619  /* */
620  /* For Adobe MM fonts (which don't have named instances) this */
621  /* function simply resets the current face to the default instance. */
622  /* */
623  /* <Since> */
624  /* 2.9 */
625  /* */
628  FT_UInt instance_index );
629 
630  /* */
631 
632 
634 
635 #endif /* FTMM_H_ */
636 
637 
638 /* END */
FT_Long maximum
Definition: ftmm.h:77
int FT_Error
Definition: fttypes.h:300
FT_Set_MM_Design_Coordinates(FT_Face face, FT_UInt num_coords, FT_Long *coords)
Definition: ftmm.c:170
signed long FT_Long
Definition: fttypes.h:242
FT_Done_MM_Var(FT_Library library, FT_MM_Var *amaster)
Definition: ftmm.c:151
unsigned long FT_ULong
Definition: fttypes.h:253
FT_ULong tag
Definition: ftmm.h:157
#define FT_END_HEADER
Definition: ftheader.h:54
FT_Get_Var_Blend_Coordinates(FT_Face face, FT_UInt num_coords, FT_Fixed *coords)
Definition: ftmm.c:411
FT_UInt strid
Definition: ftmm.h:187
FT_Get_Var_Design_Coordinates(FT_Face face, FT_UInt num_coords, FT_Fixed *coords)
Definition: ftmm.c:253
FT_Fixed maximum
Definition: ftmm.h:155
FT_BEGIN_HEADER struct FT_MM_Axis_ FT_MM_Axis
GLuint coords
Definition: glext.h:7368
FT_Library library
Definition: cffdrivr.c:654
FT_String * name
Definition: ftmm.h:151
FT_UInt num_namedstyles
Definition: ftmm.h:241
FT_Get_Var_Axis_Flags(FT_MM_Var *master, FT_UInt axis_index, FT_UInt *flags)
Definition: ftmm.c:439
#define FT_BEGIN_HEADER
Definition: ftheader.h:36
FT_Fixed * coords
Definition: ftmm.h:186
FT_UInt strid
Definition: ftmm.h:158
struct FT_MM_Var_ FT_MM_Var
struct FT_Var_Named_Style_ FT_Var_Named_Style
FT_UInt num_axis
Definition: ftmm.h:106
FT_String * name
Definition: ftmm.h:75
FT_Var_Named_Style * namedstyle
Definition: ftmm.h:243
char FT_String
Definition: fttypes.h:187
FT_Set_Var_Blend_Coordinates(FT_Face face, FT_UInt num_coords, FT_Fixed *coords)
Definition: ftmm.c:332
FT_Fixed minimum
Definition: ftmm.h:153
GLbitfield flags
Definition: glext.h:7161
FT_Set_MM_Blend_Coordinates(FT_Face face, FT_UInt num_coords, FT_Fixed *coords)
Definition: ftmm.c:281
struct FT_Multi_Master_ FT_Multi_Master
FT_Long minimum
Definition: ftmm.h:76
FT_Var_Axis * axis
Definition: ftmm.h:242
FT_Get_Multi_Master(FT_Face face, FT_Multi_Master *amaster)
Definition: ftmm.c:97
FT_UInt num_designs
Definition: ftmm.h:107
signed long FT_Fixed
Definition: fttypes.h:288
unsigned int FT_UInt
Definition: fttypes.h:231
#define FT_EXPORT(x)
Definition: ftconfig.h:461
FT_Set_Named_Instance(FT_Face face, FT_UInt instance_index)
Definition: ftmm.c:463
FT_UInt num_axis
Definition: ftmm.h:239
FT_MM_Axis axis[T1_MAX_MM_AXIS]
Definition: ftmm.h:108
FT_Get_MM_Var(FT_Face face, FT_MM_Var **amaster)
Definition: ftmm.c:124
FT_UInt num_designs
Definition: ftmm.h:240
FT_Get_MM_Blend_Coordinates(FT_Face face, FT_UInt num_coords, FT_Fixed *coords)
Definition: ftmm.c:380
FT_Set_Var_Design_Coordinates(FT_Face face, FT_UInt num_coords, FT_Fixed *coords)
Definition: ftmm.c:205
struct FT_Var_Axis_ FT_Var_Axis
GLenum GLuint GLint GLenum face
Definition: glext.h:7025
FT_Fixed def
Definition: ftmm.h:154
#define T1_MAX_MM_AXIS
Definition: t1tables.h:279
FT_UInt psid
Definition: ftmm.h:188