freetype2/freetype/ftsizes.h

0001 /****************************************************************************
0002  *
0003  * ftsizes.h
0004  *
0005  *   FreeType size objects management (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   /**************************************************************************
0020    *
0021    * Typical application would normally not need to use these functions.
0022    * However, they have been placed in a public API for the rare cases where
0023    * they are needed.
0024    *
0025    */
0026
0027
0028 #ifndef FTSIZES_H_
0029 #define FTSIZES_H_
0030
0031
0032 #include <freetype/freetype.h>
0033
0034 #ifdef FREETYPE_H
0035 #error "freetype.h of FreeType 1 has been loaded!"
0036 #error "Please fix the directory search order for header files"
0037 #error "so that freetype.h of FreeType 2 is found first."
0038 #endif
0039
0040
0041 FT_BEGIN_HEADER
0042
0043
0044   /**************************************************************************
0045    *
0046    * @section:
0047    *   sizes_management
0048    *
0049    * @title:
0050    *   Size Management
0051    *
0052    * @abstract:
0053    *   Managing multiple sizes per face.
0054    *
0055    * @description:
0056    *   When creating a new face object (e.g., with @FT_New_Face), an @FT_Size
0057    *   object is automatically created and used to store all pixel-size
0058    *   dependent information, available in the `face->size` field.
0059    *
0060    *   It is however possible to create more sizes for a given face, mostly
0061    *   in order to manage several character pixel sizes of the same font
0062    *   family and style.  See @FT_New_Size and @FT_Done_Size.
0063    *
0064    *   Note that @FT_Set_Pixel_Sizes and @FT_Set_Char_Size only modify the
0065    *   contents of the current 'active' size; you thus need to use
0066    *   @FT_Activate_Size to change it.
0067    *
0068    *   99% of applications won't need the functions provided here, especially
0069    *   if they use the caching sub-system, so be cautious when using these.
0070    *
0071    */
0072
0073
0074   /**************************************************************************
0075    *
0076    * @function:
0077    *   FT_New_Size
0078    *
0079    * @description:
0080    *   Create a new size object from a given face object.
0081    *
0082    * @input:
0083    *   face ::
0084    *     A handle to a parent face object.
0085    *
0086    * @output:
0087    *   asize ::
0088    *     A handle to a new size object.
0089    *
0090    * @return:
0091    *   FreeType error code.  0~means success.
0092    *
0093    * @note:
0094    *   You need to call @FT_Activate_Size in order to select the new size for
0095    *   upcoming calls to @FT_Set_Pixel_Sizes, @FT_Set_Char_Size,
0096    *   @FT_Load_Glyph, @FT_Load_Char, etc.
0097    */
0098   FT_EXPORT( FT_Error )
0099   FT_New_Size( FT_Face   face,
0100                FT_Size*  size );
0101
0102
0103   /**************************************************************************
0104    *
0105    * @function:
0106    *   FT_Done_Size
0107    *
0108    * @description:
0109    *   Discard a given size object.  Note that @FT_Done_Face automatically
0110    *   discards all size objects allocated with @FT_New_Size.
0111    *
0112    * @input:
0113    *   size ::
0114    *     A handle to a target size object.
0115    *
0116    * @return:
0117    *   FreeType error code.  0~means success.
0118    */
0119   FT_EXPORT( FT_Error )
0120   FT_Done_Size( FT_Size  size );
0121
0122
0123   /**************************************************************************
0124    *
0125    * @function:
0126    *   FT_Activate_Size
0127    *
0128    * @description:
0129    *   Even though it is possible to create several size objects for a given
0130    *   face (see @FT_New_Size for details), functions like @FT_Load_Glyph or
0131    *   @FT_Load_Char only use the one that has been activated last to
0132    *   determine the 'current character pixel size'.
0133    *
0134    *   This function can be used to 'activate' a previously created size
0135    *   object.
0136    *
0137    * @input:
0138    *   size ::
0139    *     A handle to a target size object.
0140    *
0141    * @return:
0142    *   FreeType error code.  0~means success.
0143    *
0144    * @note:
0145    *   If `face` is the size's parent face object, this function changes the
0146    *   value of `face->size` to the input size handle.
0147    */
0148   FT_EXPORT( FT_Error )
0149   FT_Activate_Size( FT_Size  size );
0150
0151   /* */
0152
0153
0154 FT_END_HEADER
0155
0156 #endif /* FTSIZES_H_ */
0157
0158
0159 /* END */