Bitmap information functions
Once a bitmap is loaded into memory, you can retrieve all kinds of information from it or 
access specific parts from the bitmap, such as the pixel bits and the palette.
FreeImage_GetImageType
DLL_API FREE_IMAGE_TYPE DLL_CALLCONV FreeImage_GetImageType(FIBITMAP *dib);
Returns the data type of a bitmap (see Table 2).
FreeImage_GetColorsUsed
1 4 8 16 24 32 
DLL_API unsigned DLL_CALLCONV FreeImage_GetColorsUsed(FIBITMAP *dib);
Returns the number of colors used in a bitmap. This function returns the palette-size for 
palletised bitmaps, and 0 for high-colour bitmaps.
There has been some criticism on the name of this function. Some users expect this 
function to return the actual number of colors being used in a bitmap, while the function 
actually returns the size of the palette. The name of this function originates from a 
member in BITMAPINFOHEADER named biClrUsed. The function actually returns the 
content of this member.
FreeImage_GetBPP
DLL_API unsigned DLL_CALLCONV FreeImage_GetBPP(FIBITMAP *dib);
Returns the size of one pixel in the bitmap in bits. For example when each pixel takes 32-bits 
of space in the bitmap, this function returns 32. Possible bit depths are 1, 4, 8, 16, 24, 32 for 
standard bitmaps and 16-, 32-, 48-, 64-, 96- and 128-bit for non standard bitmaps. 
FreeImage_GetWidth
DLL_API unsigned DLL_CALLCONV FreeImage_GetWidth(FIBITMAP *dib);
Returns the width of the bitmap in pixel units.
FreeImage_GetHeight
DLL_API unsigned DLL_CALLCONV FreeImage_GetHeight(FIBITMAP *dib);
Returns the height of the bitmap in pixel units.
FreeImage 3.13.1 documentation
Bitmap function reference    13
Error processing SSI file
FreeImage_GetLine
DLL_API unsigned DLL_CALLCONV FreeImage_GetLine(FIBITMAP *dib);
Returns the width of the bitmap in bytes.
See also: FreeImage_GetPitch. 
There has been some criticism on the name of this function. Some people expect it to 
return a scanline in the pixel data, while it actually returns the width of the bitmap in 
bytes. As far as I know the term Line is common terminology for the width of a bitmap 
in bytes. It is at least used by Microsoft DirectX.
FreeImage_GetPitch
DLL_API unsigned DLL_CALLCONV FreeImage_GetPitch(FIBITMAP *dib);
Returns the width of the bitmap in bytes, rounded to the next 32-bit boundary, also known as 
pitch or stride or scan width.
In FreeImage each scanline starts at a 32-bit boundary for performance reasons. 
This accessor is essential when using low level pixel manipulation functions (see also 
the chapter on Pixel access functions).
FreeImage_GetDIBSize
DLL_API unsigned DLL_CALLCONV FreeImage_GetDIBSize(FIBITMAP *dib);
Returns  the size of the DIB-element  of a FIBITMAP in  memory,  i.e. the 
BITMAPINFOHEADER + palette + data bits (note that this is not the real size of a FIBITMAP, 
only the size of its DIB-element).
FreeImage_GetPalette
1 4 8 16 24 32 
DLL_API RGBQUAD *DLL_CALLCONV FreeImage_GetPalette(FIBITMAP *dib);
Returns a pointer to the bitmap’s palette. If the bitmap doesn’t have a palette (i.e. when the 
pixel bit depth is greater than 8), this function returns NULL.
// this code assumes there is a bitmap loaded and
// present in a variable called ‘dib’
if(FreeImage_GetBPP(dib) == 8) {
// Build a greyscale palette
RGBQUAD *pal = FreeImage_GetPalette(dib);
for (int i = 0; i < 256; i++) {
pal[i].rgbRed = i;
pal[i].rgbGreen = i;
pal[i].rgbBlue = i;
}
14    Bitmap function reference
FreeImage 3.13.1 documentation
Error processing SSI file
FreeImage_GetDotsPerMeterX
DLL_API unsigned DLL_CALLCONV FreeImage_GetDotsPerMeterX(FIBITMAP *dib);
Returns the horizontal resolution, in pixels-per-meter, of the target device for the bitmap.
FreeImage_GetDotsPerMeterY
DLL_API unsigned DLL_CALLCONV FreeImage_GetDotsPerMeterY(FIBITMAP *dib);
Returns the vertical resolution, in pixels-per-meter, of the target device for the bitmap.
FreeImage_SetDotsPerMeterX
DLL_API void DLL_CALLCONV FreeImage_SetDotsPerMeterX(FIBITMAP *dib, unsigned res);
Set the horizontal resolution, in pixels-per-meter, of the target device for the bitmap.
FreeImage_SetDotsPerMeterY
DLL_API void DLL_CALLCONV FreeImage_SetDotsPerMeterY(FIBITMAP *dib, unsigned res);
Set the vertical resolution, in pixels-per-meter, of the target device for the bitmap.
FreeImage_GetInfoHeader
1 4 8 16 24 32 
DLL_API BITMAPINFOHEADER *DLL_CALLCONV FreeImage_GetInfoHeader(FIBITMAP *dib);
Returns a pointer to the BITMAPINFOHEADER of the DIB-element in a FIBITMAP.
FreeImage_GetInfo
1 4 8 16 24 32 
DLL_API BITMAPINFO *DLL_CALLCONV FreeImage_GetInfo(FIBITMAP *dib);
Alias for FreeImage_GetInfoHeader that returns a pointer to a BITMAPINFO rather than to a 
BITMAPINFOHEADER.
FreeImage_GetColorType
DLL_API FREE_IMAGE_COLOR_TYPE DLL_CALLCONV FreeImage_GetColorType(FIBITMAP *dib);
Investigates the color type of the bitmap by reading the bitmap’s pixel bits and analysing 
them. FreeImage_GetColorType can returns one of the following values:
FreeImage 3.13.1 documentation
Bitmap function reference    15
Error processing SSI file
Value
Description
FIC_MINISBLACK
Monochrome bitmap (1-bit) : first palette entry is black. Palletised bitmap (4 or 8-bit) and 
single channel non standard bitmap: the bitmap has a greyscale palette
FIC_MINISWHITE
Monochrome bitmap (1-bit) : first palette entry is white. Palletised bitmap (4 or 8-bit) : the 
bitmap has an inverted greyscale palette
FIC_PALETTE
Palettized bitmap (1, 4 or 8 bit)
FIC_RGB
High-color bitmap (16, 24 or 32 bit), RGB16 or RGBF
FIC_RGBALPHA
High-color bitmap with an alpha channel (32 bit bitmap, RGBA16 or RGBAF)
FIC_CMYK
CMYK bitmap (32 bit only)
Table 5: FREE_IMAGE_COLOR_TYPE constants.
To be judged greyscale (i.e. FIC_MINISBLACK), a bitmap must have a palette with 
these characteristics:
- The red, green, and blue values of each palette entry must be equal,
- The interval between adjacent palette entries must be positive and equal to 1.
The CMYK color model (i.e. FIC_CMYK) is the preferred one, if one needs a picture for 
the print industry or press. In almost every case, this is done by graphic artists: they 
take a RGB picture (e.g. from a digital camera) and correct the values as appropriate 
for the picture (single pixel, brightness, contrast...). Finally, they export an CMYK 
separated image. This will go directly to a layout program and then to the print 
machines. Most FreeImage users will never need to use CMYK separated images, 
because the printer drivers will do the conversion job. But in the professional print, the 
proofed conversion is essential to get a brilliant print result (where no driver will do 
something like conversion). That’s why printed pictures in some magazines look so 
much better than our home-made prints.
FreeImage_GetRedMask
1 4 8 16 24 32 
DLL_API unsigned DLL_CALLCONV FreeImage_GetRedMask(FIBITMAP *dib);
Returns a bit pattern describing the red color component of a pixel in a FIBITMAP.
FreeImage_GetGreenMask
1 4 8 16 24 32 
DLL_API unsigned DLL_CALLCONV FreeImage_GetGreenMask(FIBITMAP *dib);
Returns a bit pattern describing the green color component of a pixel in a FIBITMAP.
FreeImage_GetBlueMask
1 4 8 16 24 32 
DLL_API unsigned DLL_CALLCONV FreeImage_GetBlueMask(FIBITMAP *dib);
Returns a bit pattern describing the blue color component of a pixel in a FIBITMAP. 
16    Bitmap function reference
FreeImage 3.13.1 documentation
Error processing SSI file
// this code assumes there is a bitmap loaded and
// present in a variable called ‘dib’
unsigned red_mask, green_mask, blue_mask;
red_mask = FreeImage_GetRedMask(dib);
green_mask = FreeImage_GetGreenMask(dib);
blue_mask = FreeImage_GetBlueMask(dib);
if(FreeImage_GetBPP(dib) == 16) {
if ((red_mask == FI16_565_RED_MASK) && (green_mask == FI16_565_GREEN_MASK) && 
(blue_mask == FI16_565_BLUE_MASK)) {
// We are in RGB16 565 mode
} else {
// We are in RGB16 555 mode
}
}
FreeImage_GetTransparencyCount
1 4 8 16 24 32 
DLL_API unsigned DLL_CALLCONV FreeImage_GetTransparencyCount(FIBITMAP *dib);
Returns the number of transparent colors in a palletised bitmap. When the bitmap is not 
palletised, FreeImage_GetTransparencyCount always returns 0.
FreeImage_GetTransparencyTable
1
4 8 
DLL_API BYTE * DLL_CALLCONV FreeImage_GetTransparencyTable(FIBITMAP *dib);
Returns a pointer to the bitmap’s transparency table. Only palletised bitmaps have a 
transparency table. High-color bitmaps store the transparency values directly in the bitmap 
bits. FreeImage_GetTransparencyTable returns NULL for these bitmaps.
FreeImage_SetTransparencyTable
1
4 8 
DLL_API void DLL_CALLCONV FreeImage_SetTransparencyTable(FIBITMAP *dib, BYTE *table, 
int count);
Set the bitmap’s transparency table. Only palletised bitmaps have a transparency table. High-
color  bitmaps  store  the  transparency  values  directly  in  the  bitmap  bits. 
FreeImage_SetTransparencyTable does nothing for these bitmaps.
FreeImage 3.13.1 documentation
Bitmap function reference    17
Error processing SSI file
#include "FreeImage.h"
int main(int argc, char* argv[]) {
FIBITMAP *hDIB24bpp = FreeImage_Load(FIF_BMP, "test.bmp", 0);
if (hDIB24bpp) {
// color-quantize 24bpp (results in a 8bpp bitmap to set transparency)
FIBITMAP *hDIB8bpp = FreeImage_ColorQuantize(hDIB24bpp, FIQ_WUQUANT);
// get palette and find bright green
RGBQUAD  *Palette  = FreeImage_GetPalette(hDIB8bpp);
BYTE      Transparency[256];
for (unsigned i = 0; i < 256; i++) {
Transparency[i] = 0xFF;
if (Palette[i].rgbGreen >= 0xFE && 
Palette[i].rgbBlue  == 0x00 &&
Palette[i].rgbRed   == 0x00) {
Transparency[i] = 0x00;
}
}
// set the tranparency table
FreeImage_SetTransparencyTable(hDIB8bpp, Transparency, 256);
// save 8bpp image as transparent PNG
FreeImage_Save(FIF_PNG, hDIB8bpp, "test.png", 0);
FreeImage_Unload(hDIB24bpp);
FreeImage_Unload(hDIB8bpp);
}
return 0;
}
FreeImage_SetTransparent
1
4 8 32 
DLL_API void DLL_CALLCONV FreeImage_SetTransparent(FIBITMAP *dib, BOOL enabled);
Tells FreeImage if it should make use of the transparency table or the alpha channel that may 
accompany a bitmap. When calling this function with a bitmap whose bitdepth is different from 
1-, 4-, 8- or 32-bit, transparency is disabled whatever the value of the Boolean parameter.
FreeImage_IsTransparent
1 4 8 16 24 32 
DLL_API BOOL DLL_CALLCONV FreeImage_IsTransparent(FIBITMAP *dib);
Returns TRUE when the transparency table is enabled (1-, 4- or 8-bit images) or when the 
input dib contains alpha values (32-bit images). Returns FALSE otherwise. 
FreeImage_SetTransparentIndex
1
4 8 
DLL_API void DLL_CALLCONV FreeImage_SetTransparentIndex(FIBITMAP *dib, int index);
Sets the index of the palette entry to be used as transparent color for the image specified. 
Does nothing on high color images. 
This method sets the index of the palette entry to be used as single transparent color for the 
image specified. This works on palletised images only and does nothing for high color 
images.
Although it is possible for palletised images to have more than one transparent color, this 
method sets the palette entry specified as the single transparent color for the image. All other 
colors will be set to be non-transparent by this method.
As with FreeImage_SetTransparencyTable, this method also sets the image's transparency 
property to TRUE (as it is set and obtained by  FreeImage_SetTransparent and 
FreeImage_IsTransparent respectively) for palletised images. 
18    Bitmap function reference
FreeImage 3.13.1 documentation
Error processing SSI file
FreeImage_GetTransparentIndex
1
4 8 
DLL_API int DLL_CALLCONV FreeImage_GetTransparentIndex(FIBITMAP *dib);
Returns the palette entry used as transparent color for the image specified. Works for 
palletised images only and returns -1 for high color images or if the image has no color set to 
be transparent. 
Although it is possible for palletised images to have more than one transparent color, this 
function always returns the index of the first palette entry, set to be transparent. 
FreeImage_HasBackgroundColor
8 24 32 
DLL_API BOOL DLL_CALLCONV FreeImage_HasBackgroundColor(FIBITMAP *dib);
Returns TRUE when the image has a file background color, FALSE otherwise.
FreeImage_GetBackgroundColor
8 24 32 
DLL_API BOOL DLL_CALLCONV FreeImage_GetBackgroundColor(FIBITMAP *dib, RGBQUAD 
*bkcolor);
Retrieves the file background color of an image. Returns TRUE if successful, FALSE 
otherwise. For 8-bit images, the color index in the palette is returned in the rgbReserved 
member of the bkcolor parameter.
FreeImage_SetBackgroundColor
8 24 32 
DLL_API BOOL DLL_CALLCONV FreeImage_SetBackgroundColor(FIBITMAP *dib, RGBQUAD 
*bkcolor);
Set the file background color of an image. When saving an image to PNG, this background 
color is transparently saved to the PNG file.
When the bkcolor parameter is NULL, the background color is removed from the image.
FreeImage 3.13.1 documentation
Bitmap function reference    19
Error processing SSI file
Filetype functions
The following functions retrieve the FREE_IMAGE_FORMAT from a bitmap by reading up to 
16 bytes and analysing it.
Note that for some bitmap types no FREE_IMAGE_FORMAT can be retrieved. This has to do 
with the bit-layout of the bitmap-types, which are sometimes not compatible with FreeImage’s 
file-type retrieval system. The unidentifiable formats are: CUT, MNG, PCD, TARGA and 
WBMP. However, these formats can be identified using the FreeImage_GetFIFFromFilename 
function.
FreeImage_GetFileType
DLL_API FREE_IMAGE_FORMAT DLL_CALLCONV FreeImage_GetFileType(const char *filename, int 
size FI_DEFAULT(0));
Orders FreeImage to analyze the bitmap signature. The function then returns one of the 
predefined FREE_IMAGE_FORMAT constants or a bitmap identification number registered 
by a plugin. The size parameter is currently not used and can be set to 0.
Because not all formats can be identified by their header (some images don't have a 
header or one at the end of the file), FreeImage_GetFileType may return 
FIF_UNKNOWN whereas a plugin is available for the file being analysed. In this case, 
you can use FreeImage_GetFIFFromFilename to guess the file format from the file 
extension, but this last function is slower and less accurate.
/** Generic image loader
@param lpszPathName Pointer to the full file name
@param flag Optional load flag constant
@return Returns the loaded dib if successful, returns NULL otherwise
*/
FIBITMAP* GenericLoader(const char* lpszPathName, int flag) {
FREE_IMAGE_FORMAT fif = FIF_UNKNOWN;
// check the file signature and deduce its format
// (the second argument is currently not used by FreeImage)
fif = FreeImage_GetFileType(lpszPathName, 0);
if(fif == FIF_UNKNOWN) {
// no signature ?
// try to guess the file format from the file extension
fif = FreeImage_GetFIFFromFilename(lpszPathName);
}
// check that the plugin has reading capabilities ...
if((fif != FIF_UNKNOWN) && FreeImage_FIFSupportsReading(fif)) {
// ok, let's load the file
FIBITMAP *dib = FreeImage_Load(fif, lpszPathName, flag);
// unless a bad file format, we are done !
return dib;
}
return NULL;
}
FreeImage_GetFileTypeU
DLL_API FREE_IMAGE_FORMAT DLL_CALLCONV FreeImage_GetFileTypeU(const wchar_t *filename, 
int size FI_DEFAULT(0));
This function works exactly like FreeImage_GetFileType but supports UNICODE filenames. 
Note that this function only works on WIN32 operating systems. On other systems, the 
function does nothing and returns FIF_UNKNOWN.
20    Bitmap function reference
FreeImage 3.13.1 documentation
Error processing SSI file
FreeImage_GetFileTypeFromHandle
DLL_API FREE_IMAGE_FORMAT DLL_CALLCONV FreeImage_GetFileTypeFromHandle(FreeImageIO 
*io, fi_handle handle, int size FI_DEFAULT(0));
Uses the FreeImageIO structure as described in the topic Bitmap management functions to 
identify a bitmap type. Now the bitmap bits are retrieved from an arbitrary place.
FreeImage_GetFileTypeFromMemory
DLL_API FREE_IMAGE_FORMAT DLL_CALLCONV FreeImage_GetFileTypeFromMemory(FIMEMORY 
*stream, int size FI_DEFAULT(0));
Uses a memory handle to identify a bitmap type. The bitmap bits are retrieved from an 
arbitrary place (see the chapter on Memory I/O streams for more information on memory 
handles).
FreeImage 3.13.1 documentation
Bitmap function reference    21
Error processing SSI file
Pixel access functions
The pixel access functions provide you with an easy way to read, write and work pixel-by-pixel 
with FIBITMAP data. 
FreeImage is able to work not only with standard bitmap data (e.g. 1-, 4-, 8-, 16-, 24- and 32-
bit) but also with scientific data such as 16-bit greyscale images, or images made up of long, 
double or complex values (often used in signal and image processing algorithms). An 
overview of the supported data types is given in Table 2.
In FreeImage, FIBITMAP are based on a coordinate system that is upside down 
relative to usual graphics conventions. Thus, the scanlines are stored upside down, 
with the first scan in memory being the bottommost scan in the image.
Bit Formats
In a FIBITMAP the format of the bits are defined by a pixel’s bit depth that can be read via a 
call to FreeImage_GetBPP (see also FreeImage_GetImageType). Possible bit depths include 
1-, 4-, 8-, 16-, 24-, 32-, 48-, 64-, 96-  and 128-bit. All formats share the following rules: 
Every scanline is DWORD-aligned. The scanline is buffered to alignment; the 
buffering is set to 0. 
The scanlines are stored upside down, with the first scan (scan 0) in memory being 
the bottommost scan in the image. 
Each format has the following specifics: 
1-bit DIBs are stored using each bit as an index into the color table. The most 
significant bit is the leftmost pixel. 
4-bit DIBs are stored with each 4 bits representing an index into the color table. The 
most significant nibble is the leftmost pixel. 
8-bit DIBs are the easiest to store because each byte is an index into the color table. 
24-bit DIBs have every 3 bytes representing a color, using the same ordering as the 
RGBTRIPLE structure. 
32-bit DIB have every 4 bytes representing a color associated to a alpha value (used 
to indicate transparency), using the same ordering as the RGBQUAD structure.
Non standard image types such as short, long, float or double do not have a color 
table. Pixels are stored in a similar way as 8-bit DIB.
Complex image types are stored in a similar way as 24- or 32bit DIB, using the same 
ordering as the FICOMPLEX structure.
16-bit RGB[A] or float RGB[A] image types are stored in a similar way as 24- or 32bit 
DIB, using the same ordering as the FIRGB[A]16 or FIRGB[A]F structures.
Color model
A color model is an abstract mathematical model describing the way colors can be 
represented as tuples of numbers, typically as three or four values or color components (e.g. 
RGB and CMYK are color models). FreeImage mainly uses the RGB[A] color model to 
represent pixels in memory. 
However, the pixel layout used by this model is OS dependant. Using a byte by byte memory 
order to label the pixel layout, then FreeImage uses a BGR[A] pixel layout under a Little 
Endian processor (Windows, Linux) and uses a RGB[A] pixel layout under a Big Endian 
22    Bitmap function reference
FreeImage 3.13.1 documentation
Error processing SSI file
Error processing SSI file