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