Back to home page

EIC code displayed by LXR

 
 

    


File indexing completed on 2024-11-15 09:38:12

0001 /****************************************************************************
0002  *
0003  * ftmm.h
0004  *
0005  *   FreeType Multiple Master font interface (specification).
0006  *
0007  * Copyright (C) 1996-2023 by
0008  * David Turner, Robert Wilhelm, and Werner Lemberg.
0009  *
0010  * This file is part of the FreeType project, and may only be used,
0011  * modified, and distributed under the terms of the FreeType project
0012  * license, LICENSE.TXT.  By continuing to use, modify, or distribute
0013  * this file you indicate that you have read the license and
0014  * understand and accept it fully.
0015  *
0016  */
0017 
0018 
0019 #ifndef FTMM_H_
0020 #define FTMM_H_
0021 
0022 
0023 #include <freetype/t1tables.h>
0024 
0025 
0026 FT_BEGIN_HEADER
0027 
0028 
0029   /**************************************************************************
0030    *
0031    * @section:
0032    *   multiple_masters
0033    *
0034    * @title:
0035    *   Multiple Masters
0036    *
0037    * @abstract:
0038    *   How to manage Multiple Masters fonts.
0039    *
0040    * @description:
0041    *   The following types and functions are used to manage Multiple Master
0042    *   fonts, i.e., the selection of specific design instances by setting
0043    *   design axis coordinates.
0044    *
0045    *   Besides Adobe MM fonts, the interface supports Apple's TrueType GX and
0046    *   OpenType variation fonts.  Some of the routines only work with Adobe
0047    *   MM fonts, others will work with all three types.  They are similar
0048    *   enough that a consistent interface makes sense.
0049    *
0050    *   For Adobe MM fonts, macro @FT_IS_SFNT returns false.  For GX and
0051    *   OpenType variation fonts, it returns true.
0052    *
0053    */
0054 
0055 
0056   /**************************************************************************
0057    *
0058    * @struct:
0059    *   FT_MM_Axis
0060    *
0061    * @description:
0062    *   A structure to model a given axis in design space for Multiple Masters
0063    *   fonts.
0064    *
0065    *   This structure can't be used for TrueType GX or OpenType variation
0066    *   fonts.
0067    *
0068    * @fields:
0069    *   name ::
0070    *     The axis's name.
0071    *
0072    *   minimum ::
0073    *     The axis's minimum design coordinate.
0074    *
0075    *   maximum ::
0076    *     The axis's maximum design coordinate.
0077    */
0078   typedef struct  FT_MM_Axis_
0079   {
0080     FT_String*  name;
0081     FT_Long     minimum;
0082     FT_Long     maximum;
0083 
0084   } FT_MM_Axis;
0085 
0086 
0087   /**************************************************************************
0088    *
0089    * @struct:
0090    *   FT_Multi_Master
0091    *
0092    * @description:
0093    *   A structure to model the axes and space of a Multiple Masters font.
0094    *
0095    *   This structure can't be used for TrueType GX or OpenType variation
0096    *   fonts.
0097    *
0098    * @fields:
0099    *   num_axis ::
0100    *     Number of axes.  Cannot exceed~4.
0101    *
0102    *   num_designs ::
0103    *     Number of designs; should be normally 2^num_axis even though the
0104    *     Type~1 specification strangely allows for intermediate designs to be
0105    *     present.  This number cannot exceed~16.
0106    *
0107    *   axis ::
0108    *     A table of axis descriptors.
0109    */
0110   typedef struct  FT_Multi_Master_
0111   {
0112     FT_UInt     num_axis;
0113     FT_UInt     num_designs;
0114     FT_MM_Axis  axis[T1_MAX_MM_AXIS];
0115 
0116   } FT_Multi_Master;
0117 
0118 
0119   /**************************************************************************
0120    *
0121    * @struct:
0122    *   FT_Var_Axis
0123    *
0124    * @description:
0125    *   A structure to model a given axis in design space for Multiple
0126    *   Masters, TrueType GX, and OpenType variation fonts.
0127    *
0128    * @fields:
0129    *   name ::
0130    *     The axis's name.  Not always meaningful for TrueType GX or OpenType
0131    *     variation fonts.
0132    *
0133    *   minimum ::
0134    *     The axis's minimum design coordinate.
0135    *
0136    *   def ::
0137    *     The axis's default design coordinate.  FreeType computes meaningful
0138    *     default values for Adobe MM fonts.
0139    *
0140    *   maximum ::
0141    *     The axis's maximum design coordinate.
0142    *
0143    *   tag ::
0144    *     The axis's tag (the equivalent to 'name' for TrueType GX and
0145    *     OpenType variation fonts).  FreeType provides default values for
0146    *     Adobe MM fonts if possible.
0147    *
0148    *   strid ::
0149    *     The axis name entry in the font's 'name' table.  This is another
0150    *     (and often better) version of the 'name' field for TrueType GX or
0151    *     OpenType variation fonts.  Not meaningful for Adobe MM fonts.
0152    *
0153    * @note:
0154    *   The fields `minimum`, `def`, and `maximum` are 16.16 fractional values
0155    *   for TrueType GX and OpenType variation fonts.  For Adobe MM fonts, the
0156    *   values are whole numbers (i.e., the fractional part is zero).
0157    */
0158   typedef struct  FT_Var_Axis_
0159   {
0160     FT_String*  name;
0161 
0162     FT_Fixed    minimum;
0163     FT_Fixed    def;
0164     FT_Fixed    maximum;
0165 
0166     FT_ULong    tag;
0167     FT_UInt     strid;
0168 
0169   } FT_Var_Axis;
0170 
0171 
0172   /**************************************************************************
0173    *
0174    * @struct:
0175    *   FT_Var_Named_Style
0176    *
0177    * @description:
0178    *   A structure to model a named instance in a TrueType GX or OpenType
0179    *   variation font.
0180    *
0181    *   This structure can't be used for Adobe MM fonts.
0182    *
0183    * @fields:
0184    *   coords ::
0185    *     The design coordinates for this instance.  This is an array with one
0186    *     entry for each axis.
0187    *
0188    *   strid ::
0189    *     The entry in 'name' table identifying this instance.
0190    *
0191    *   psid ::
0192    *     The entry in 'name' table identifying a PostScript name for this
0193    *     instance.  Value 0xFFFF indicates a missing entry.
0194    */
0195   typedef struct  FT_Var_Named_Style_
0196   {
0197     FT_Fixed*  coords;
0198     FT_UInt    strid;
0199     FT_UInt    psid;   /* since 2.7.1 */
0200 
0201   } FT_Var_Named_Style;
0202 
0203 
0204   /**************************************************************************
0205    *
0206    * @struct:
0207    *   FT_MM_Var
0208    *
0209    * @description:
0210    *   A structure to model the axes and space of an Adobe MM, TrueType GX,
0211    *   or OpenType variation font.
0212    *
0213    *   Some fields are specific to one format and not to the others.
0214    *
0215    * @fields:
0216    *   num_axis ::
0217    *     The number of axes.  The maximum value is~4 for Adobe MM fonts; no
0218    *     limit in TrueType GX or OpenType variation fonts.
0219    *
0220    *   num_designs ::
0221    *     The number of designs; should be normally 2^num_axis for Adobe MM
0222    *     fonts.  Not meaningful for TrueType GX or OpenType variation fonts
0223    *     (where every glyph could have a different number of designs).
0224    *
0225    *   num_namedstyles ::
0226    *     The number of named styles; a 'named style' is a tuple of design
0227    *     coordinates that has a string ID (in the 'name' table) associated
0228    *     with it.  The font can tell the user that, for example,
0229    *     [Weight=1.5,Width=1.1] is 'Bold'.  Another name for 'named style' is
0230    *     'named instance'.
0231    *
0232    *     For Adobe Multiple Masters fonts, this value is always zero because
0233    *     the format does not support named styles.
0234    *
0235    *   axis ::
0236    *     An axis descriptor table.  TrueType GX and OpenType variation fonts
0237    *     contain slightly more data than Adobe MM fonts.  Memory management
0238    *     of this pointer is done internally by FreeType.
0239    *
0240    *   namedstyle ::
0241    *     A named style (instance) table.  Only meaningful for TrueType GX and
0242    *     OpenType variation fonts.  Memory management of this pointer is done
0243    *     internally by FreeType.
0244    */
0245   typedef struct  FT_MM_Var_
0246   {
0247     FT_UInt              num_axis;
0248     FT_UInt              num_designs;
0249     FT_UInt              num_namedstyles;
0250     FT_Var_Axis*         axis;
0251     FT_Var_Named_Style*  namedstyle;
0252 
0253   } FT_MM_Var;
0254 
0255 
0256   /**************************************************************************
0257    *
0258    * @function:
0259    *   FT_Get_Multi_Master
0260    *
0261    * @description:
0262    *   Retrieve a variation descriptor of a given Adobe MM font.
0263    *
0264    *   This function can't be used with TrueType GX or OpenType variation
0265    *   fonts.
0266    *
0267    * @input:
0268    *   face ::
0269    *     A handle to the source face.
0270    *
0271    * @output:
0272    *   amaster ::
0273    *     The Multiple Masters descriptor.
0274    *
0275    * @return:
0276    *   FreeType error code.  0~means success.
0277    */
0278   FT_EXPORT( FT_Error )
0279   FT_Get_Multi_Master( FT_Face           face,
0280                        FT_Multi_Master  *amaster );
0281 
0282 
0283   /**************************************************************************
0284    *
0285    * @function:
0286    *   FT_Get_MM_Var
0287    *
0288    * @description:
0289    *   Retrieve a variation descriptor for a given font.
0290    *
0291    *   This function works with all supported variation formats.
0292    *
0293    * @input:
0294    *   face ::
0295    *     A handle to the source face.
0296    *
0297    * @output:
0298    *   amaster ::
0299    *     The variation descriptor.  Allocates a data structure, which the
0300    *     user must deallocate with a call to @FT_Done_MM_Var after use.
0301    *
0302    * @return:
0303    *   FreeType error code.  0~means success.
0304    */
0305   FT_EXPORT( FT_Error )
0306   FT_Get_MM_Var( FT_Face      face,
0307                  FT_MM_Var*  *amaster );
0308 
0309 
0310   /**************************************************************************
0311    *
0312    * @function:
0313    *   FT_Done_MM_Var
0314    *
0315    * @description:
0316    *   Free the memory allocated by @FT_Get_MM_Var.
0317    *
0318    * @input:
0319    *   library ::
0320    *     A handle of the face's parent library object that was used in the
0321    *     call to @FT_Get_MM_Var to create `amaster`.
0322    *
0323    * @return:
0324    *   FreeType error code.  0~means success.
0325    */
0326   FT_EXPORT( FT_Error )
0327   FT_Done_MM_Var( FT_Library   library,
0328                   FT_MM_Var   *amaster );
0329 
0330 
0331   /**************************************************************************
0332    *
0333    * @function:
0334    *   FT_Set_MM_Design_Coordinates
0335    *
0336    * @description:
0337    *   For Adobe MM fonts, choose an interpolated font design through design
0338    *   coordinates.
0339    *
0340    *   This function can't be used with TrueType GX or OpenType variation
0341    *   fonts.
0342    *
0343    * @inout:
0344    *   face ::
0345    *     A handle to the source face.
0346    *
0347    * @input:
0348    *   num_coords ::
0349    *     The number of available design coordinates.  If it is larger than
0350    *     the number of axes, ignore the excess values.  If it is smaller than
0351    *     the number of axes, use default values for the remaining axes.
0352    *
0353    *   coords ::
0354    *     An array of design coordinates.
0355    *
0356    * @return:
0357    *   FreeType error code.  0~means success.
0358    *
0359    * @note:
0360    *   [Since 2.8.1] To reset all axes to the default values, call the
0361    *   function with `num_coords` set to zero and `coords` set to `NULL`.
0362    *
0363    *   [Since 2.9] If `num_coords` is larger than zero, this function sets
0364    *   the @FT_FACE_FLAG_VARIATION bit in @FT_Face's `face_flags` field
0365    *   (i.e., @FT_IS_VARIATION will return true).  If `num_coords` is zero,
0366    *   this bit flag gets unset.
0367    */
0368   FT_EXPORT( FT_Error )
0369   FT_Set_MM_Design_Coordinates( FT_Face   face,
0370                                 FT_UInt   num_coords,
0371                                 FT_Long*  coords );
0372 
0373 
0374   /**************************************************************************
0375    *
0376    * @function:
0377    *   FT_Set_Var_Design_Coordinates
0378    *
0379    * @description:
0380    *   Choose an interpolated font design through design coordinates.
0381    *
0382    *   This function works with all supported variation formats.
0383    *
0384    * @inout:
0385    *   face ::
0386    *     A handle to the source face.
0387    *
0388    * @input:
0389    *   num_coords ::
0390    *     The number of available design coordinates.  If it is larger than
0391    *     the number of axes, ignore the excess values.  If it is smaller than
0392    *     the number of axes, use default values for the remaining axes.
0393    *
0394    *   coords ::
0395    *     An array of design coordinates.
0396    *
0397    * @return:
0398    *   FreeType error code.  0~means success.
0399    *
0400    * @note:
0401    *   The design coordinates are 16.16 fractional values for TrueType GX and
0402    *   OpenType variation fonts.  For Adobe MM fonts, the values are supposed
0403    *   to be whole numbers (i.e., the fractional part is zero).
0404    *
0405    *   [Since 2.8.1] To reset all axes to the default values, call the
0406    *   function with `num_coords` set to zero and `coords` set to `NULL`.
0407    *   [Since 2.9] 'Default values' means the currently selected named
0408    *   instance (or the base font if no named instance is selected).
0409    *
0410    *   [Since 2.9] If `num_coords` is larger than zero, this function sets
0411    *   the @FT_FACE_FLAG_VARIATION bit in @FT_Face's `face_flags` field
0412    *   (i.e., @FT_IS_VARIATION will return true).  If `num_coords` is zero,
0413    *   this bit flag gets unset.
0414    */
0415   FT_EXPORT( FT_Error )
0416   FT_Set_Var_Design_Coordinates( FT_Face    face,
0417                                  FT_UInt    num_coords,
0418                                  FT_Fixed*  coords );
0419 
0420 
0421   /**************************************************************************
0422    *
0423    * @function:
0424    *   FT_Get_Var_Design_Coordinates
0425    *
0426    * @description:
0427    *   Get the design coordinates of the currently selected interpolated
0428    *   font.
0429    *
0430    *   This function works with all supported variation formats.
0431    *
0432    * @input:
0433    *   face ::
0434    *     A handle to the source face.
0435    *
0436    *   num_coords ::
0437    *     The number of design coordinates to retrieve.  If it is larger than
0438    *     the number of axes, set the excess values to~0.
0439    *
0440    * @output:
0441    *   coords ::
0442    *     The design coordinates array.
0443    *
0444    * @return:
0445    *   FreeType error code.  0~means success.
0446    *
0447    * @note:
0448    *   The design coordinates are 16.16 fractional values for TrueType GX and
0449    *   OpenType variation fonts.  For Adobe MM fonts, the values are whole
0450    *   numbers (i.e., the fractional part is zero).
0451    *
0452    * @since:
0453    *   2.7.1
0454    */
0455   FT_EXPORT( FT_Error )
0456   FT_Get_Var_Design_Coordinates( FT_Face    face,
0457                                  FT_UInt    num_coords,
0458                                  FT_Fixed*  coords );
0459 
0460 
0461   /**************************************************************************
0462    *
0463    * @function:
0464    *   FT_Set_MM_Blend_Coordinates
0465    *
0466    * @description:
0467    *   Choose an interpolated font design through normalized blend
0468    *   coordinates.
0469    *
0470    *   This function works with all supported variation formats.
0471    *
0472    * @inout:
0473    *   face ::
0474    *     A handle to the source face.
0475    *
0476    * @input:
0477    *   num_coords ::
0478    *     The number of available design coordinates.  If it is larger than
0479    *     the number of axes, ignore the excess values.  If it is smaller than
0480    *     the number of axes, use default values for the remaining axes.
0481    *
0482    *   coords ::
0483    *     The design coordinates array.  Each element is a 16.16 fractional
0484    *     value and must be between 0 and 1.0 for Adobe MM fonts, and between
0485    *     -1.0 and 1.0 for TrueType GX and OpenType variation fonts.
0486    *
0487    * @return:
0488    *   FreeType error code.  0~means success.
0489    *
0490    * @note:
0491    *   [Since 2.8.1] To reset all axes to the default values, call the
0492    *   function with `num_coords` set to zero and `coords` set to `NULL`.
0493    *   [Since 2.9] 'Default values' means the currently selected named
0494    *   instance (or the base font if no named instance is selected).
0495    *
0496    *   [Since 2.9] If `num_coords` is larger than zero, this function sets
0497    *   the @FT_FACE_FLAG_VARIATION bit in @FT_Face's `face_flags` field
0498    *   (i.e., @FT_IS_VARIATION will return true).  If `num_coords` is zero,
0499    *   this bit flag gets unset.
0500    */
0501   FT_EXPORT( FT_Error )
0502   FT_Set_MM_Blend_Coordinates( FT_Face    face,
0503                                FT_UInt    num_coords,
0504                                FT_Fixed*  coords );
0505 
0506 
0507   /**************************************************************************
0508    *
0509    * @function:
0510    *   FT_Get_MM_Blend_Coordinates
0511    *
0512    * @description:
0513    *   Get the normalized blend coordinates of the currently selected
0514    *   interpolated font.
0515    *
0516    *   This function works with all supported variation formats.
0517    *
0518    * @input:
0519    *   face ::
0520    *     A handle to the source face.
0521    *
0522    *   num_coords ::
0523    *     The number of normalized blend coordinates to retrieve.  If it is
0524    *     larger than the number of axes, set the excess values to~0.5 for
0525    *     Adobe MM fonts, and to~0 for TrueType GX and OpenType variation
0526    *     fonts.
0527    *
0528    * @output:
0529    *   coords ::
0530    *     The normalized blend coordinates array (as 16.16 fractional values).
0531    *
0532    * @return:
0533    *   FreeType error code.  0~means success.
0534    *
0535    * @since:
0536    *   2.7.1
0537    */
0538   FT_EXPORT( FT_Error )
0539   FT_Get_MM_Blend_Coordinates( FT_Face    face,
0540                                FT_UInt    num_coords,
0541                                FT_Fixed*  coords );
0542 
0543 
0544   /**************************************************************************
0545    *
0546    * @function:
0547    *   FT_Set_Var_Blend_Coordinates
0548    *
0549    * @description:
0550    *   This is another name of @FT_Set_MM_Blend_Coordinates.
0551    */
0552   FT_EXPORT( FT_Error )
0553   FT_Set_Var_Blend_Coordinates( FT_Face    face,
0554                                 FT_UInt    num_coords,
0555                                 FT_Fixed*  coords );
0556 
0557 
0558   /**************************************************************************
0559    *
0560    * @function:
0561    *   FT_Get_Var_Blend_Coordinates
0562    *
0563    * @description:
0564    *   This is another name of @FT_Get_MM_Blend_Coordinates.
0565    *
0566    * @since:
0567    *   2.7.1
0568    */
0569   FT_EXPORT( FT_Error )
0570   FT_Get_Var_Blend_Coordinates( FT_Face    face,
0571                                 FT_UInt    num_coords,
0572                                 FT_Fixed*  coords );
0573 
0574 
0575   /**************************************************************************
0576    *
0577    * @function:
0578    *   FT_Set_MM_WeightVector
0579    *
0580    * @description:
0581    *   For Adobe MM fonts, choose an interpolated font design by directly
0582    *   setting the weight vector.
0583    *
0584    *   This function can't be used with TrueType GX or OpenType variation
0585    *   fonts.
0586    *
0587    * @inout:
0588    *   face ::
0589    *     A handle to the source face.
0590    *
0591    * @input:
0592    *   len ::
0593    *     The length of the weight vector array.  If it is larger than the
0594    *     number of designs, the extra values are ignored.  If it is less than
0595    *     the number of designs, the remaining values are set to zero.
0596    *
0597    *   weightvector ::
0598    *     An array representing the weight vector.
0599    *
0600    * @return:
0601    *   FreeType error code.  0~means success.
0602    *
0603    * @note:
0604    *   Adobe Multiple Master fonts limit the number of designs, and thus the
0605    *   length of the weight vector to 16~elements.
0606    *
0607    *   If `len` is larger than zero, this function sets the
0608    *   @FT_FACE_FLAG_VARIATION bit in @FT_Face's `face_flags` field (i.e.,
0609    *   @FT_IS_VARIATION will return true).  If `len` is zero, this bit flag
0610    *   is unset and the weight vector array is reset to the default values.
0611    *
0612    *   The Adobe documentation also states that the values in the
0613    *   WeightVector array must total 1.0 +/-~0.001.  In practice this does
0614    *   not seem to be enforced, so is not enforced here, either.
0615    *
0616    * @since:
0617    *   2.10
0618    */
0619   FT_EXPORT( FT_Error )
0620   FT_Set_MM_WeightVector( FT_Face    face,
0621                           FT_UInt    len,
0622                           FT_Fixed*  weightvector );
0623 
0624 
0625   /**************************************************************************
0626    *
0627    * @function:
0628    *   FT_Get_MM_WeightVector
0629    *
0630    * @description:
0631    *   For Adobe MM fonts, retrieve the current weight vector of the font.
0632    *
0633    *   This function can't be used with TrueType GX or OpenType variation
0634    *   fonts.
0635    *
0636    * @inout:
0637    *   face ::
0638    *     A handle to the source face.
0639    *
0640    *   len ::
0641    *     A pointer to the size of the array to be filled.  If the size of the
0642    *     array is less than the number of designs, `FT_Err_Invalid_Argument`
0643    *     is returned, and `len` is set to the required size (the number of
0644    *     designs).  If the size of the array is greater than the number of
0645    *     designs, the remaining entries are set to~0.  On successful
0646    *     completion, `len` is set to the number of designs (i.e., the number
0647    *     of values written to the array).
0648    *
0649    * @output:
0650    *   weightvector ::
0651    *     An array to be filled.
0652    *
0653    * @return:
0654    *   FreeType error code.  0~means success.
0655    *
0656    * @note:
0657    *   Adobe Multiple Master fonts limit the number of designs, and thus the
0658    *   length of the WeightVector to~16.
0659    *
0660    * @since:
0661    *   2.10
0662    */
0663   FT_EXPORT( FT_Error )
0664   FT_Get_MM_WeightVector( FT_Face    face,
0665                           FT_UInt*   len,
0666                           FT_Fixed*  weightvector );
0667 
0668 
0669   /**************************************************************************
0670    *
0671    * @enum:
0672    *   FT_VAR_AXIS_FLAG_XXX
0673    *
0674    * @description:
0675    *   A list of bit flags used in the return value of
0676    *   @FT_Get_Var_Axis_Flags.
0677    *
0678    * @values:
0679    *   FT_VAR_AXIS_FLAG_HIDDEN ::
0680    *     The variation axis should not be exposed to user interfaces.
0681    *
0682    * @since:
0683    *   2.8.1
0684    */
0685 #define FT_VAR_AXIS_FLAG_HIDDEN  1
0686 
0687 
0688   /**************************************************************************
0689    *
0690    * @function:
0691    *   FT_Get_Var_Axis_Flags
0692    *
0693    * @description:
0694    *   Get the 'flags' field of an OpenType Variation Axis Record.
0695    *
0696    *   Not meaningful for Adobe MM fonts (`*flags` is always zero).
0697    *
0698    * @input:
0699    *   master ::
0700    *     The variation descriptor.
0701    *
0702    *   axis_index ::
0703    *     The index of the requested variation axis.
0704    *
0705    * @output:
0706    *   flags ::
0707    *     The 'flags' field.  See @FT_VAR_AXIS_FLAG_XXX for possible values.
0708    *
0709    * @return:
0710    *   FreeType error code.  0~means success.
0711    *
0712    * @since:
0713    *   2.8.1
0714    */
0715   FT_EXPORT( FT_Error )
0716   FT_Get_Var_Axis_Flags( FT_MM_Var*  master,
0717                          FT_UInt     axis_index,
0718                          FT_UInt*    flags );
0719 
0720 
0721   /**************************************************************************
0722    *
0723    * @function:
0724    *   FT_Set_Named_Instance
0725    *
0726    * @description:
0727    *   Set or change the current named instance.
0728    *
0729    * @input:
0730    *   face ::
0731    *     A handle to the source face.
0732    *
0733    *   instance_index ::
0734    *     The index of the requested instance, starting with value 1.  If set
0735    *     to value 0, FreeType switches to font access without a named
0736    *     instance.
0737    *
0738    * @return:
0739    *   FreeType error code.  0~means success.
0740    *
0741    * @note:
0742    *   The function uses the value of `instance_index` to set bits 16-30 of
0743    *   the face's `face_index` field.  It also resets any variation applied
0744    *   to the font, and the @FT_FACE_FLAG_VARIATION bit of the face's
0745    *   `face_flags` field gets reset to zero (i.e., @FT_IS_VARIATION will
0746    *   return false).
0747    *
0748    *   For Adobe MM fonts (which don't have named instances) this function
0749    *   simply resets the current face to the default instance.
0750    *
0751    * @since:
0752    *   2.9
0753    */
0754   FT_EXPORT( FT_Error )
0755   FT_Set_Named_Instance( FT_Face  face,
0756                          FT_UInt  instance_index );
0757 
0758 
0759   /**************************************************************************
0760    *
0761    * @function:
0762    *   FT_Get_Default_Named_Instance
0763    *
0764    * @description:
0765    *   Retrieve the index of the default named instance, to be used with
0766    *   @FT_Set_Named_Instance.
0767    *
0768    *   The default instance of a variation font is that instance for which
0769    *   the nth axis coordinate is equal to `axis[n].def` (as specified in the
0770    *   @FT_MM_Var structure), with~n covering all axes.
0771    *
0772    *   FreeType synthesizes a named instance for the default instance if the
0773    *   font does not contain such an entry.
0774    *
0775    * @input:
0776    *   face ::
0777    *     A handle to the source face.
0778    *
0779    * @output:
0780    *   instance_index ::
0781    *     The index of the default named instance.
0782    *
0783    * @return:
0784    *   FreeType error code.  0~means success.
0785    *
0786    * @note:
0787    *   For Adobe MM fonts (which don't have named instances) this function
0788    *   always returns zero for `instance_index`.
0789    *
0790    * @since:
0791    *   2.13.1
0792    */
0793   FT_EXPORT( FT_Error )
0794   FT_Get_Default_Named_Instance( FT_Face   face,
0795                                  FT_UInt  *instance_index );
0796 
0797   /* */
0798 
0799 
0800 FT_END_HEADER
0801 
0802 #endif /* FTMM_H_ */
0803 
0804 
0805 /* END */