Skip to content

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 `FT_Pixel_Mode` format.
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 `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).

`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.