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