1 /**************************************************************************** 2 * 3 * ftbitmap.h 4 * 5 * FreeType utility functions for bitmaps (specification). 6 * 7 * Copyright (C) 2004-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 #ifndef FTBITMAP_H_ 20 #define FTBITMAP_H_ 21 22 23 #include <freetype/freetype.h> 24 #include <freetype/ftcolor.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 * bitmap_handling 40 * 41 * @title: 42 * Bitmap Handling 43 * 44 * @abstract: 45 * Handling FT_Bitmap objects. 46 * 47 * @description: 48 * This section contains functions for handling @FT_Bitmap objects, 49 * automatically adjusting the target's bitmap buffer size as needed. 50 * 51 * Note that none of the functions changes the bitmap's 'flow' (as 52 * indicated by the sign of the `pitch` field in @FT_Bitmap). 53 * 54 * To set the flow, assign an appropriate positive or negative value to 55 * the `pitch` field of the target @FT_Bitmap object after calling 56 * @FT_Bitmap_Init but before calling any of the other functions 57 * described here. 58 */ 59 60 61 /************************************************************************** 62 * 63 * @function: 64 * FT_Bitmap_Init 65 * 66 * @description: 67 * Initialize a pointer to an @FT_Bitmap structure. 68 * 69 * @inout: 70 * abitmap :: 71 * A pointer to the bitmap structure. 72 * 73 * @note: 74 * A deprecated name for the same function is `FT_Bitmap_New`. 75 */ 76 FT_EXPORT( void ) 77 FT_Bitmap_Init( FT_Bitmap *abitmap ); 78 79 80 /* deprecated */ 81 FT_EXPORT( void ) 82 FT_Bitmap_New( FT_Bitmap *abitmap ); 83 84 85 /************************************************************************** 86 * 87 * @function: 88 * FT_Bitmap_Copy 89 * 90 * @description: 91 * Copy a bitmap into another one. 92 * 93 * @input: 94 * library :: 95 * A handle to a library object. 96 * 97 * source :: 98 * A handle to the source bitmap. 99 * 100 * @output: 101 * target :: 102 * A handle to the target bitmap. 103 * 104 * @return: 105 * FreeType error code. 0~means success. 106 * 107 * @note: 108 * `source->buffer` and `target->buffer` must neither be equal nor 109 * overlap. 110 */ 111 FT_EXPORT( FT_Error ) 112 FT_Bitmap_Copy( FT_Library library, 113 const FT_Bitmap *source, 114 FT_Bitmap *target ); 115 116 117 /************************************************************************** 118 * 119 * @function: 120 * FT_Bitmap_Embolden 121 * 122 * @description: 123 * Embolden a bitmap. The new bitmap will be about `xStrength` pixels 124 * wider and `yStrength` pixels higher. The left and bottom borders are 125 * kept unchanged. 126 * 127 * @input: 128 * library :: 129 * A handle to a library object. 130 * 131 * xStrength :: 132 * How strong the glyph is emboldened horizontally. Expressed in 26.6 133 * pixel format. 134 * 135 * yStrength :: 136 * How strong the glyph is emboldened vertically. Expressed in 26.6 137 * pixel format. 138 * 139 * @inout: 140 * bitmap :: 141 * A handle to the target bitmap. 142 * 143 * @return: 144 * FreeType error code. 0~means success. 145 * 146 * @note: 147 * The current implementation restricts `xStrength` to be less than or 148 * equal to~8 if bitmap is of pixel_mode @FT_PIXEL_MODE_MONO. 149 * 150 * If you want to embolden the bitmap owned by a @FT_GlyphSlotRec, you 151 * should call @FT_GlyphSlot_Own_Bitmap on the slot first. 152 * 153 * Bitmaps in @FT_PIXEL_MODE_GRAY2 and @FT_PIXEL_MODE_GRAY@ format are 154 * converted to @FT_PIXEL_MODE_GRAY format (i.e., 8bpp). 155 */ 156 FT_EXPORT( FT_Error ) 157 FT_Bitmap_Embolden( FT_Library library, 158 FT_Bitmap* bitmap, 159 FT_Pos xStrength, 160 FT_Pos yStrength ); 161 162 163 /************************************************************************** 164 * 165 * @function: 166 * FT_Bitmap_Convert 167 * 168 * @description: 169 * Convert a bitmap object with depth 1bpp, 2bpp, 4bpp, 8bpp or 32bpp to 170 * a bitmap object with depth 8bpp, making the number of used bytes per 171 * line (a.k.a. the 'pitch') a multiple of `alignment`. 172 * 173 * @input: 174 * library :: 175 * A handle to a library object. 176 * 177 * source :: 178 * The source bitmap. 179 * 180 * alignment :: 181 * The pitch of the bitmap is a multiple of this argument. Common 182 * values are 1, 2, or 4. 183 * 184 * @output: 185 * target :: 186 * The target bitmap. 187 * 188 * @return: 189 * FreeType error code. 0~means success. 190 * 191 * @note: 192 * It is possible to call @FT_Bitmap_Convert multiple times without 193 * calling @FT_Bitmap_Done (the memory is simply reallocated). 194 * 195 * Use @FT_Bitmap_Done to finally remove the bitmap object. 196 * 197 * The `library` argument is taken to have access to FreeType's memory 198 * handling functions. 199 * 200 * `source->buffer` and `target->buffer` must neither be equal nor 201 * overlap. 202 */ 203 FT_EXPORT( FT_Error ) 204 FT_Bitmap_Convert( FT_Library library, 205 const FT_Bitmap *source, 206 FT_Bitmap *target, 207 FT_Int alignment ); 208 209 210 /************************************************************************** 211 * 212 * @function: 213 * FT_Bitmap_Blend 214 * 215 * @description: 216 * Blend a bitmap onto another bitmap, using a given color. 217 * 218 * @input: 219 * library :: 220 * A handle to a library object. 221 * 222 * source :: 223 * The source bitmap, which can have any @FT_Pixel_Mode format. 224 * 225 * source_offset :: 226 * The offset vector to the upper left corner of the source bitmap in 227 * 26.6 pixel format. It should represent an integer offset; the 228 * function will set the lowest six bits to zero to enforce that. 229 * 230 * color :: 231 * The color used to draw `source` onto `target`. 232 * 233 * @inout: 234 * target :: 235 * A handle to an `FT_Bitmap` object. It should be either initialized 236 * as empty with a call to @FT_Bitmap_Init, or it should be of type 237 * @FT_PIXEL_MODE_BGRA. 238 * 239 * atarget_offset :: 240 * The offset vector to the upper left corner of the target bitmap in 241 * 26.6 pixel format. It should represent an integer offset; the 242 * function will set the lowest six bits to zero to enforce that. 243 * 244 * @return: 245 * FreeType error code. 0~means success. 246 * 247 * @note: 248 * This function doesn't perform clipping. 249 * 250 * The bitmap in `target` gets allocated or reallocated as needed; the 251 * vector `atarget_offset` is updated accordingly. 252 * 253 * In case of allocation or reallocation, the bitmap's pitch is set to 254 * `4 * width`. Both `source` and `target` must have the same bitmap 255 * flow (as indicated by the sign of the `pitch` field). 256 * 257 * `source->buffer` and `target->buffer` must neither be equal nor 258 * overlap. 259 * 260 * @since: 261 * 2.10 262 */ 263 FT_EXPORT( FT_Error ) 264 FT_Bitmap_Blend( FT_Library library, 265 const FT_Bitmap* source, 266 const FT_Vector source_offset, 267 FT_Bitmap* target, 268 FT_Vector *atarget_offset, 269 FT_Color color ); 270 271 272 /************************************************************************** 273 * 274 * @function: 275 * FT_GlyphSlot_Own_Bitmap 276 * 277 * @description: 278 * Make sure that a glyph slot owns `slot->bitmap`. 279 * 280 * @input: 281 * slot :: 282 * The glyph slot. 283 * 284 * @return: 285 * FreeType error code. 0~means success. 286 * 287 * @note: 288 * This function is to be used in combination with @FT_Bitmap_Embolden. 289 */ 290 FT_EXPORT( FT_Error ) 291 FT_GlyphSlot_Own_Bitmap( FT_GlyphSlot slot ); 292 293 294 /************************************************************************** 295 * 296 * @function: 297 * FT_Bitmap_Done 298 * 299 * @description: 300 * Destroy a bitmap object initialized with @FT_Bitmap_Init. 301 * 302 * @input: 303 * library :: 304 * A handle to a library object. 305 * 306 * bitmap :: 307 * The bitmap object to be freed. 308 * 309 * @return: 310 * FreeType error code. 0~means success. 311 * 312 * @note: 313 * The `library` argument is taken to have access to FreeType's memory 314 * handling functions. 315 */ 316 FT_EXPORT( FT_Error ) 317 FT_Bitmap_Done( FT_Library library, 318 FT_Bitmap *bitmap ); 319 320 321 /* */ 322 323 324 FT_END_HEADER 325 326 #endif /* FTBITMAP_H_ */ 327 328 329 /* END */ 330