ftadvanc.h (5470B)
1 /**************************************************************************** 2 * 3 * ftadvanc.h 4 * 5 * Quick computation of advance widths (specification only). 6 * 7 * Copyright (C) 2008-2025 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 FTADVANC_H_ 20 #define FTADVANC_H_ 21 22 23 #include <freetype/freetype.h> 24 25 #ifdef FREETYPE_H 26 #error "freetype.h of FreeType 1 has been loaded!" 27 #error "Please fix the directory search order for header files" 28 #error "so that freetype.h of FreeType 2 is found first." 29 #endif 30 31 32 FT_BEGIN_HEADER 33 34 35 /************************************************************************** 36 * 37 * @section: 38 * quick_advance 39 * 40 * @title: 41 * Quick retrieval of advance values 42 * 43 * @abstract: 44 * Retrieve horizontal and vertical advance values without processing 45 * glyph outlines, if possible. 46 * 47 * @description: 48 * This section contains functions to quickly extract advance values 49 * without handling glyph outlines, if possible. 50 * 51 * @order: 52 * FT_Get_Advance 53 * FT_Get_Advances 54 * 55 */ 56 57 58 /************************************************************************** 59 * 60 * @enum: 61 * FT_ADVANCE_FLAG_FAST_ONLY 62 * 63 * @description: 64 * A bit-flag to be OR-ed with the `flags` parameter of the 65 * @FT_Get_Advance and @FT_Get_Advances functions. 66 * 67 * If set, it indicates that you want these functions to fail if the 68 * corresponding hinting mode or font driver doesn't allow for very quick 69 * advance computation. 70 * 71 * Typically, glyphs that are either unscaled, unhinted, bitmapped, or 72 * light-hinted can have their advance width computed very quickly. 73 * 74 * Normal and bytecode hinted modes that require loading, scaling, and 75 * hinting of the glyph outline, are extremely slow by comparison. 76 */ 77 #define FT_ADVANCE_FLAG_FAST_ONLY 0x20000000L 78 79 80 /************************************************************************** 81 * 82 * @function: 83 * FT_Get_Advance 84 * 85 * @description: 86 * Retrieve the advance value of a given glyph outline in an @FT_Face. 87 * 88 * @input: 89 * face :: 90 * The source @FT_Face handle. 91 * 92 * gindex :: 93 * The glyph index. 94 * 95 * load_flags :: 96 * A set of bit flags similar to those used when calling 97 * @FT_Load_Glyph, used to determine what kind of advances you need. 98 * 99 * @output: 100 * padvance :: 101 * The advance value. If scaling is performed (based on the value of 102 * `load_flags`), the advance value is in 16.16 format. Otherwise, it 103 * is in font units. 104 * 105 * If @FT_LOAD_VERTICAL_LAYOUT is set, this is the vertical advance 106 * corresponding to a vertical layout. Otherwise, it is the horizontal 107 * advance in a horizontal layout. 108 * 109 * @return: 110 * FreeType error code. 0 means success. 111 * 112 * @note: 113 * This function may fail if you use @FT_ADVANCE_FLAG_FAST_ONLY and if 114 * the corresponding font backend doesn't have a quick way to retrieve 115 * the advances. 116 * 117 * A scaled advance is returned in 16.16 format but isn't transformed by 118 * the affine transformation specified by @FT_Set_Transform. 119 */ 120 FT_EXPORT( FT_Error ) 121 FT_Get_Advance( FT_Face face, 122 FT_UInt gindex, 123 FT_Int32 load_flags, 124 FT_Fixed *padvance ); 125 126 127 /************************************************************************** 128 * 129 * @function: 130 * FT_Get_Advances 131 * 132 * @description: 133 * Retrieve the advance values of several glyph outlines in an @FT_Face. 134 * 135 * @input: 136 * face :: 137 * The source @FT_Face handle. 138 * 139 * start :: 140 * The first glyph index. 141 * 142 * count :: 143 * The number of advance values you want to retrieve. 144 * 145 * load_flags :: 146 * A set of bit flags similar to those used when calling 147 * @FT_Load_Glyph. 148 * 149 * @output: 150 * padvance :: 151 * The advance values. This array, to be provided by the caller, must 152 * contain at least `count` elements. 153 * 154 * If scaling is performed (based on the value of `load_flags`), the 155 * advance values are in 16.16 format. Otherwise, they are in font 156 * units. 157 * 158 * If @FT_LOAD_VERTICAL_LAYOUT is set, these are the vertical advances 159 * corresponding to a vertical layout. Otherwise, they are the 160 * horizontal advances in a horizontal layout. 161 * 162 * @return: 163 * FreeType error code. 0 means success. 164 * 165 * @note: 166 * This function may fail if you use @FT_ADVANCE_FLAG_FAST_ONLY and if 167 * the corresponding font backend doesn't have a quick way to retrieve 168 * the advances. 169 * 170 * Scaled advances are returned in 16.16 format but aren't transformed by 171 * the affine transformation specified by @FT_Set_Transform. 172 */ 173 FT_EXPORT( FT_Error ) 174 FT_Get_Advances( FT_Face face, 175 FT_UInt start, 176 FT_UInt count, 177 FT_Int32 load_flags, 178 FT_Fixed *padvances ); 179 180 /* */ 181 182 183 FT_END_HEADER 184 185 #endif /* FTADVANC_H_ */ 186 187 188 /* END */