XFA: merge patch from CL 817753002
[pdfium.git] / core / src / fxge / fx_freetype / fxft2.5.01 / include / freetype / ftmm.h
1 /***************************************************************************/
2 /*                                                                         */
3 /*  ftmm.h                                                                 */
4 /*                                                                         */
5 /*    FreeType Multiple Master font interface (specification).             */
6 /*                                                                         */
7 /*  Copyright 1996-2001, 2003, 2004, 2006, 2009 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 "t1tables.h"
25
26
27 FT_BEGIN_HEADER
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   /*    George Williams has extended this interface to make it work with   */
47   /*    both Type~1 Multiple Masters fonts and GX distortable (var)        */
48   /*    fonts.  Some of these routines only work with MM fonts, others     */
49   /*    will work with both types.  They are similar enough that a         */
50   /*    consistent interface makes sense.                                  */
51   /*                                                                       */
52   /*************************************************************************/
53
54
55   /*************************************************************************/
56   /*                                                                       */
57   /* <Struct>                                                              */
58   /*    FT_MM_Axis                                                         */
59   /*                                                                       */
60   /* <Description>                                                         */
61   /*    A simple structure used to model a given axis in design space for  */
62   /*    Multiple Masters fonts.                                            */
63   /*                                                                       */
64   /*    This structure can't be used for GX var 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   {
75     FT_String*  name;
76     FT_Long     minimum;
77     FT_Long     maximum;
78
79   } FT_MM_Axis;
80
81
82   /*************************************************************************/
83   /*                                                                       */
84   /* <Struct>                                                              */
85   /*    FT_Multi_Master                                                    */
86   /*                                                                       */
87   /* <Description>                                                         */
88   /*    A structure used to model the axes and space of a Multiple Masters */
89   /*    font.                                                              */
90   /*                                                                       */
91   /*    This structure can't be used for GX var fonts.                     */
92   /*                                                                       */
93   /* <Fields>                                                              */
94   /*    num_axis    :: Number of axes.  Cannot exceed~4.                   */
95   /*                                                                       */
96   /*    num_designs :: Number of designs; should be normally 2^num_axis    */
97   /*                   even though the Type~1 specification strangely      */
98   /*                   allows for intermediate designs to be present. This */
99   /*                   number cannot exceed~16.                            */
100   /*                                                                       */
101   /*    axis        :: A table of axis descriptors.                        */
102   /*                                                                       */
103   typedef struct  FT_Multi_Master_
104   {
105     FT_UInt     num_axis;
106     FT_UInt     num_designs;
107     FT_MM_Axis  axis[T1_MAX_MM_AXIS];
108
109   } FT_Multi_Master;
110
111
112   /*************************************************************************/
113   /*                                                                       */
114   /* <Struct>                                                              */
115   /*    FT_Var_Axis                                                        */
116   /*                                                                       */
117   /* <Description>                                                         */
118   /*    A simple structure used to model a given axis in design space for  */
119   /*    Multiple Masters and GX var fonts.                                 */
120   /*                                                                       */
121   /* <Fields>                                                              */
122   /*    name    :: The axis's name.                                        */
123   /*               Not always meaningful for GX.                           */
124   /*                                                                       */
125   /*    minimum :: The axis's minimum design coordinate.                   */
126   /*                                                                       */
127   /*    def     :: The axis's default design coordinate.                   */
128   /*               FreeType computes meaningful default values for MM; it  */
129   /*               is then an integer value, not in 16.16 format.          */
130   /*                                                                       */
131   /*    maximum :: The axis's maximum design coordinate.                   */
132   /*                                                                       */
133   /*    tag     :: The axis's tag (the GX equivalent to `name').           */
134   /*               FreeType provides default values for MM if possible.    */
135   /*                                                                       */
136   /*    strid   :: The entry in `name' table (another GX version of        */
137   /*               `name').                                                */
138   /*               Not meaningful for MM.                                  */
139   /*                                                                       */
140   typedef struct  FT_Var_Axis_
141   {
142     FT_String*  name;
143
144     FT_Fixed    minimum;
145     FT_Fixed    def;
146     FT_Fixed    maximum;
147
148     FT_ULong    tag;
149     FT_UInt     strid;
150
151   } FT_Var_Axis;
152
153
154   /*************************************************************************/
155   /*                                                                       */
156   /* <Struct>                                                              */
157   /*    FT_Var_Named_Style                                                 */
158   /*                                                                       */
159   /* <Description>                                                         */
160   /*    A simple structure used to model a named style in a GX var font.   */
161   /*                                                                       */
162   /*    This structure can't be used for MM fonts.                         */
163   /*                                                                       */
164   /* <Fields>                                                              */
165   /*    coords :: The design coordinates for this style.                   */
166   /*              This is an array with one entry for each axis.           */
167   /*                                                                       */
168   /*    strid  :: The entry in `name' table identifying this style.        */
169   /*                                                                       */
170   typedef struct  FT_Var_Named_Style_
171   {
172     FT_Fixed*  coords;
173     FT_UInt    strid;
174
175   } FT_Var_Named_Style;
176
177
178   /*************************************************************************/
179   /*                                                                       */
180   /* <Struct>                                                              */
181   /*    FT_MM_Var                                                          */
182   /*                                                                       */
183   /* <Description>                                                         */
184   /*    A structure used to model the axes and space of a Multiple Masters */
185   /*    or GX var distortable font.                                        */
186   /*                                                                       */
187   /*    Some fields are specific to one format and not to the other.       */
188   /*                                                                       */
189   /* <Fields>                                                              */
190   /*    num_axis        :: The number of axes.  The maximum value is~4 for */
191   /*                       MM; no limit in GX.                             */
192   /*                                                                       */
193   /*    num_designs     :: The number of designs; should be normally       */
194   /*                       2^num_axis for MM fonts.  Not meaningful for GX */
195   /*                       (where every glyph could have a different       */
196   /*                       number of designs).                             */
197   /*                                                                       */
198   /*    num_namedstyles :: The number of named styles; only meaningful for */
199   /*                       GX which allows certain design coordinates to   */
200   /*                       have a string ID (in the `name' table)          */
201   /*                       associated with them.  The font can tell the    */
202   /*                       user that, for example, Weight=1.5 is `Bold'.   */
203   /*                                                                       */
204   /*    axis            :: A table of axis descriptors.                    */
205   /*                       GX fonts contain slightly more data than MM.    */
206   /*                                                                       */
207   /*    namedstyles     :: A table of named styles.                        */
208   /*                       Only meaningful with GX.                        */
209   /*                                                                       */
210   typedef struct  FT_MM_Var_
211   {
212     FT_UInt              num_axis;
213     FT_UInt              num_designs;
214     FT_UInt              num_namedstyles;
215     FT_Var_Axis*         axis;
216     FT_Var_Named_Style*  namedstyle;
217
218   } FT_MM_Var;
219
220
221   /* */
222
223
224   /*************************************************************************/
225   /*                                                                       */
226   /* <Function>                                                            */
227   /*    FT_Get_Multi_Master                                                */
228   /*                                                                       */
229   /* <Description>                                                         */
230   /*    Retrieve the Multiple Master descriptor of a given font.           */
231   /*                                                                       */
232   /*    This function can't be used with GX fonts.                         */
233   /*                                                                       */
234   /* <Input>                                                               */
235   /*    face    :: A handle to the source face.                            */
236   /*                                                                       */
237   /* <Output>                                                              */
238   /*    amaster :: The Multiple Masters descriptor.                        */
239   /*                                                                       */
240   /* <Return>                                                              */
241   /*    FreeType error code.  0~means success.                             */
242   /*                                                                       */
243   FT_EXPORT( FT_Error )
244   FT_Get_Multi_Master( FT_Face           face,
245                        FT_Multi_Master  *amaster );
246
247
248   /*************************************************************************/
249   /*                                                                       */
250   /* <Function>                                                            */
251   /*    FT_Get_MM_Var                                                      */
252   /*                                                                       */
253   /* <Description>                                                         */
254   /*    Retrieve the Multiple Master/GX var descriptor of a given font.    */
255   /*                                                                       */
256   /* <Input>                                                               */
257   /*    face    :: A handle to the source face.                            */
258   /*                                                                       */
259   /* <Output>                                                              */
260   /*    amaster :: The Multiple Masters/GX var descriptor.                 */
261   /*               Allocates a data structure, which the user must free    */
262   /*               (a single call to FT_FREE will do it).                  */
263   /*                                                                       */
264   /* <Return>                                                              */
265   /*    FreeType error code.  0~means success.                             */
266   /*                                                                       */
267   FT_EXPORT( FT_Error )
268   FT_Get_MM_Var( FT_Face      face,
269                  FT_MM_Var*  *amaster );
270
271
272   /*************************************************************************/
273   /*                                                                       */
274   /* <Function>                                                            */
275   /*    FT_Set_MM_Design_Coordinates                                       */
276   /*                                                                       */
277   /* <Description>                                                         */
278   /*    For Multiple Masters fonts, choose an interpolated font design     */
279   /*    through design coordinates.                                        */
280   /*                                                                       */
281   /*    This function can't be used with GX fonts.                         */
282   /*                                                                       */
283   /* <InOut>                                                               */
284   /*    face       :: A handle to the source face.                         */
285   /*                                                                       */
286   /* <Input>                                                               */
287   /*    num_coords :: The number of design coordinates (must be equal to   */
288   /*                  the number of axes in the font).                     */
289   /*                                                                       */
290   /*    coords     :: An array of design coordinates.                      */
291   /*                                                                       */
292   /* <Return>                                                              */
293   /*    FreeType error code.  0~means success.                             */
294   /*                                                                       */
295   FT_EXPORT( FT_Error )
296   FT_Set_MM_Design_Coordinates( FT_Face   face,
297                                 FT_UInt   num_coords,
298                                 FT_Long*  coords );
299
300
301   /*************************************************************************/
302   /*                                                                       */
303   /* <Function>                                                            */
304   /*    FT_Set_Var_Design_Coordinates                                      */
305   /*                                                                       */
306   /* <Description>                                                         */
307   /*    For Multiple Master or GX Var fonts, choose an interpolated font   */
308   /*    design through design coordinates.                                 */
309   /*                                                                       */
310   /* <InOut>                                                               */
311   /*    face       :: A handle to the source face.                         */
312   /*                                                                       */
313   /* <Input>                                                               */
314   /*    num_coords :: The number of design coordinates (must be equal to   */
315   /*                  the number of axes in the font).                     */
316   /*                                                                       */
317   /*    coords     :: An array of design coordinates.                      */
318   /*                                                                       */
319   /* <Return>                                                              */
320   /*    FreeType error code.  0~means success.                             */
321   /*                                                                       */
322   FT_EXPORT( FT_Error )
323   FT_Set_Var_Design_Coordinates( FT_Face    face,
324                                  FT_UInt    num_coords,
325                                  FT_Fixed*  coords );
326
327
328   /*************************************************************************/
329   /*                                                                       */
330   /* <Function>                                                            */
331   /*    FT_Set_MM_Blend_Coordinates                                        */
332   /*                                                                       */
333   /* <Description>                                                         */
334   /*    For Multiple Masters and GX var fonts, choose an interpolated font */
335   /*    design through normalized blend coordinates.                       */
336   /*                                                                       */
337   /* <InOut>                                                               */
338   /*    face       :: A handle to the source face.                         */
339   /*                                                                       */
340   /* <Input>                                                               */
341   /*    num_coords :: The number of design coordinates (must be equal to   */
342   /*                  the number of axes in the font).                     */
343   /*                                                                       */
344   /*    coords     :: The design coordinates array (each element must be   */
345   /*                  between 0 and 1.0).                                  */
346   /*                                                                       */
347   /* <Return>                                                              */
348   /*    FreeType error code.  0~means success.                             */
349   /*                                                                       */
350   FT_EXPORT( FT_Error )
351   FT_Set_MM_Blend_Coordinates( FT_Face    face,
352                                FT_UInt    num_coords,
353                                FT_Fixed*  coords );
354
355
356   /*************************************************************************/
357   /*                                                                       */
358   /* <Function>                                                            */
359   /*    FT_Set_Var_Blend_Coordinates                                       */
360   /*                                                                       */
361   /* <Description>                                                         */
362   /*    This is another name of @FT_Set_MM_Blend_Coordinates.              */
363   /*                                                                       */
364   FT_EXPORT( FT_Error )
365   FT_Set_Var_Blend_Coordinates( FT_Face    face,
366                                 FT_UInt    num_coords,
367                                 FT_Fixed*  coords );
368
369
370   /* */
371
372
373 FT_END_HEADER
374
375 #endif /* __FTMM_H__ */
376
377
378 /* END */