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