1 /**************************************************************************** 2 * 3 * ftsizes.h 4 * 5 * FreeType size objects management (specification). 6 * 7 * Copyright (C) 1996-2020 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 /************************************************************************** 20 * 21 * Typical application would normally not need to use these functions. 22 * However, they have been placed in a public API for the rare cases where 23 * they are needed. 24 * 25 */ 26 27 28 #ifndef FTSIZES_H_ 29 #define FTSIZES_H_ 30 31 32 #include <freetype/freetype.h> 33 34 #ifdef FREETYPE_H 35 #error "freetype.h of FreeType 1 has been loaded!" 36 #error "Please fix the directory search order for header files" 37 #error "so that freetype.h of FreeType 2 is found first." 38 #endif 39 40 41 FT_BEGIN_HEADER 42 43 44 /************************************************************************** 45 * 46 * @section: 47 * sizes_management 48 * 49 * @title: 50 * Size Management 51 * 52 * @abstract: 53 * Managing multiple sizes per face. 54 * 55 * @description: 56 * When creating a new face object (e.g., with @FT_New_Face), an @FT_Size 57 * object is automatically created and used to store all pixel-size 58 * dependent information, available in the `face->size` field. 59 * 60 * It is however possible to create more sizes for a given face, mostly 61 * in order to manage several character pixel sizes of the same font 62 * family and style. See @FT_New_Size and @FT_Done_Size. 63 * 64 * Note that @FT_Set_Pixel_Sizes and @FT_Set_Char_Size only modify the 65 * contents of the current 'active' size; you thus need to use 66 * @FT_Activate_Size to change it. 67 * 68 * 99% of applications won't need the functions provided here, especially 69 * if they use the caching sub-system, so be cautious when using these. 70 * 71 */ 72 73 74 /************************************************************************** 75 * 76 * @function: 77 * FT_New_Size 78 * 79 * @description: 80 * Create a new size object from a given face object. 81 * 82 * @input: 83 * face :: 84 * A handle to a parent face object. 85 * 86 * @output: 87 * asize :: 88 * A handle to a new size object. 89 * 90 * @return: 91 * FreeType error code. 0~means success. 92 * 93 * @note: 94 * You need to call @FT_Activate_Size in order to select the new size for 95 * upcoming calls to @FT_Set_Pixel_Sizes, @FT_Set_Char_Size, 96 * @FT_Load_Glyph, @FT_Load_Char, etc. 97 */ 98 FT_EXPORT( FT_Error ) 99 FT_New_Size( FT_Face face, 100 FT_Size* size ); 101 102 103 /************************************************************************** 104 * 105 * @function: 106 * FT_Done_Size 107 * 108 * @description: 109 * Discard a given size object. Note that @FT_Done_Face automatically 110 * discards all size objects allocated with @FT_New_Size. 111 * 112 * @input: 113 * size :: 114 * A handle to a target size object. 115 * 116 * @return: 117 * FreeType error code. 0~means success. 118 */ 119 FT_EXPORT( FT_Error ) 120 FT_Done_Size( FT_Size size ); 121 122 123 /************************************************************************** 124 * 125 * @function: 126 * FT_Activate_Size 127 * 128 * @description: 129 * Even though it is possible to create several size objects for a given 130 * face (see @FT_New_Size for details), functions like @FT_Load_Glyph or 131 * @FT_Load_Char only use the one that has been activated last to 132 * determine the 'current character pixel size'. 133 * 134 * This function can be used to 'activate' a previously created size 135 * object. 136 * 137 * @input: 138 * size :: 139 * A handle to a target size object. 140 * 141 * @return: 142 * FreeType error code. 0~means success. 143 * 144 * @note: 145 * If `face` is the size's parent face object, this function changes the 146 * value of `face->size` to the input size handle. 147 */ 148 FT_EXPORT( FT_Error ) 149 FT_Activate_Size( FT_Size size ); 150 151 /* */ 152 153 154 FT_END_HEADER 155 156 #endif /* FTSIZES_H_ */ 157 158 159 /* END */ 160