FreeType » Docs » Support API » Bitmap Handling
Bitmap Handling¶
Synopsis¶
This section contains functions for handling FT_Bitmap objects, automatically adjusting the target's bitmap buffer size as needed.
Note that none of the functions changes the bitmap's ‘flow’ (as indicated by the sign of the pitch field in FT_Bitmap).
To set the flow, assign an appropriate positive or negative value to the pitch field of the target FT_Bitmap object after calling FT_Bitmap_Init but before calling any of the other functions described here.
FT_Bitmap_Init¶
Defined in FT_BITMAP_H (freetype/ftbitmap.h).
FT_EXPORT( void )
FT_Bitmap_Init( FT_Bitmap *abitmap );
/* deprecated */
FT_EXPORT( void )
FT_Bitmap_New( FT_Bitmap *abitmap );
Initialize a pointer to an FT_Bitmap structure.
inout
| abitmap |
A pointer to the bitmap structure. |
note
A deprecated name for the same function is FT_Bitmap_New.
FT_Bitmap_Copy¶
Defined in FT_BITMAP_H (freetype/ftbitmap.h).
FT_EXPORT( FT_Error )
FT_Bitmap_Copy( FT_Library library,
const FT_Bitmap *source,
FT_Bitmap *target );
Copy a bitmap into another one.
input
| library |
A handle to a library object. |
| source |
A handle to the source bitmap. |
output
| target |
A handle to the target bitmap. |
return
FreeType error code. 0 means success.
note
source->buffer and target->buffer must neither be equal nor overlap.
FT_Bitmap_Embolden¶
Defined in FT_BITMAP_H (freetype/ftbitmap.h).
FT_EXPORT( FT_Error )
FT_Bitmap_Embolden( FT_Library library,
FT_Bitmap* bitmap,
FT_Pos xStrength,
FT_Pos yStrength );
Embolden a bitmap. The new bitmap will be about xStrength pixels wider and yStrength pixels higher. The left and bottom borders are kept unchanged.
input
| library |
A handle to a library object. |
| xStrength |
How strong the glyph is emboldened horizontally. Expressed in 26.6 pixel format. |
| yStrength |
How strong the glyph is emboldened vertically. Expressed in 26.6 pixel format. |
inout
| bitmap |
A handle to the target bitmap. |
return
FreeType error code. 0 means success.
note
The current implementation restricts xStrength to be less than or equal to 8 if bitmap is of pixel_mode FT_PIXEL_MODE_MONO.
If you want to embolden the bitmap owned by a FT_GlyphSlotRec, you should call FT_GlyphSlot_Own_Bitmap on the slot first.
Bitmaps in FT_PIXEL_MODE_GRAY2 and FT_PIXEL_MODE_GRAY@ format are converted to FT_PIXEL_MODE_GRAY format (i.e., 8bpp).
FT_Bitmap_Convert¶
Defined in FT_BITMAP_H (freetype/ftbitmap.h).
FT_EXPORT( FT_Error )
FT_Bitmap_Convert( FT_Library library,
const FT_Bitmap *source,
FT_Bitmap *target,
FT_Int alignment );
Convert a bitmap object with depth 1bpp, 2bpp, 4bpp, 8bpp or 32bpp to a bitmap object with depth 8bpp, making the number of used bytes per line (a.k.a. the ‘pitch’) a multiple of alignment.
input
| library |
A handle to a library object. |
| source |
The source bitmap. |
| alignment |
The pitch of the bitmap is a multiple of this argument. Common values are 1, 2, or 4. |
output
| target |
The target bitmap. |
return
FreeType error code. 0 means success.
note
It is possible to call FT_Bitmap_Convert multiple times without calling FT_Bitmap_Done (the memory is simply reallocated).
Use FT_Bitmap_Done to finally remove the bitmap object.
The library argument is taken to have access to FreeType's memory handling functions.
source->buffer and target->buffer must neither be equal nor overlap.
FT_Bitmap_Blend¶
Defined in FT_BITMAP_H (freetype/ftbitmap.h).
FT_EXPORT( FT_Error )
FT_Bitmap_Blend( FT_Library library,
const FT_Bitmap* source,
const FT_Vector source_offset,
FT_Bitmap* target,
FT_Vector *atarget_offset,
FT_Color color );
Blend a bitmap onto another bitmap, using a given color.
input
| library |
A handle to a library object. |
| source |
The source bitmap, which can have any |
| source_offset |
The offset vector to the upper left corner of the source bitmap in 26.6 pixel format. It should represent an integer offset; the function will set the lowest six bits to zero to enforce that. |
| color |
The color used to draw |
inout
| target |
A handle to an |
| atarget_offset |
The offset vector to the upper left corner of the target bitmap in 26.6 pixel format. It should represent an integer offset; the function will set the lowest six bits to zero to enforce that. |
return
FreeType error code. 0 means success.
note
This function doesn't perform clipping.
The bitmap in target gets allocated or reallocated as needed; the vector atarget_offset is updated accordingly.
In case of allocation or reallocation, the bitmap's pitch is set to 4 * width. Both source and target must have the same bitmap flow (as indicated by the sign of the pitch field).
source->buffer and target->buffer must neither be equal nor overlap.
since
2.10
FT_GlyphSlot_Own_Bitmap¶
Defined in FT_BITMAP_H (freetype/ftbitmap.h).
FT_EXPORT( FT_Error )
FT_GlyphSlot_Own_Bitmap( FT_GlyphSlot slot );
Make sure that a glyph slot owns slot->bitmap.
input
| slot |
The glyph slot. |
return
FreeType error code. 0 means success.
note
This function is to be used in combination with FT_Bitmap_Embolden.
FT_Bitmap_Done¶
Defined in FT_BITMAP_H (freetype/ftbitmap.h).
FT_EXPORT( FT_Error )
FT_Bitmap_Done( FT_Library library,
FT_Bitmap *bitmap );
Destroy a bitmap object initialized with FT_Bitmap_Init.
input
| library |
A handle to a library object. |
| bitmap |
The bitmap object to be freed. |
return
FreeType error code. 0 means success.
note
The library argument is taken to have access to FreeType's memory handling functions.