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 */