Docs » Support API » Bitmap Handling

Bitmap Handling¶

Synopsis¶

This section contains functions for handling FT_Bitmap objects. Note that none of the functions changes the bitmap's ‘flow’ (as indicated by the sign of the ‘pitch’ field in FT_Bitmap).

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.

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.

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 FT_Pixel_Mode format.
source_offset	The offset vector to the upper left corner of the source bitmap in 26.6 pixel format. This can be a fractional pixel value.
color	The color used to draw ‘source’ onto ‘target’.

inout

target	A handle to an `FT_Bitmap` object. It should be either initialized as empty with a call to FT_Bitmap_Init, or it should be of type FT_PIXEL_MODE_BGRA.
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).

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.