1 | /**************************************************************************** |
2 | * |
3 | * ftbitmap.h |
4 | * |
5 | * FreeType utility functions for bitmaps (specification). |
6 | * |
7 | * Copyright (C) 2004-2023 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 | |