Returns a regular expression string that can be used by a regular expression engine to 
identify the bitmap. FreeImageQt makes use of this function. 
FreeImage_GetFIFFromFilename
DLL_API FREE_IMAGE_FORMAT DLL_CALLCONV FreeImage_GetFIFFromFilename(const char 
*filename);
This function takes a filename or a file-extension and returns the plugin that can read/write 
files with that extension in the form of a FREE_IMAGE_FORMAT identifier. 
/** 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_GetFIFFromFilenameU
DLL_API FREE_IMAGE_FORMAT DLL_CALLCONV FreeImage_GetFIFFromFilenameU(const wchar_t 
*filename);
This function works exactly like FreeImage_GetFIFFromFilename 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.
FreeImage_FIFSupportsReading
DLL_API BOOL DLL_CALLCONV FreeImage_FIFSupportsReading(FREE_IMAGE_FORMAT fif);
Returns TRUE if the plugin belonging to the given FREE_IMAGE_FORMAT can be used to 
load bitmaps, FALSE otherwise.
FreeImage_FIFSupportsWriting
DLL_API BOOL DLL_CALLCONV FreeImage_FIFSupportsWriting(FREE_IMAGE_FORMAT fif);
Returns TRUE if the plugin belonging to the given FREE_IMAGE_FORMAT can be used to 
save bitmaps, FALSE otherwise.
FreeImage 3.13.1 documentation
Bitmap function reference    43
Error processing SSI file
/** Generic image writer
@param dib Pointer to the dib to be saved
@param lpszPathName Pointer to the full file name
@param flag Optional save flag constant
@return Returns true if successful, returns false otherwise
*/
bool GenericWriter(FIBITMAP* dib, const char* lpszPathName, int flag) {
FREE_IMAGE_FORMAT fif = FIF_UNKNOWN;
BOOL bSuccess = FALSE;
// Try to guess the file format from the file extension
fif = FreeImage_GetFIFFromFilename(lpszPathName);
if(fif != FIF_UNKNOWN ) {
// Check that the dib can be saved in this format
BOOL bCanSave;
FREE_IMAGE_TYPE image_type = FreeImage_GetImageType(dib);
if(image_type == FIT_BITMAP) {
// standard bitmap type
// check that the plugin has sufficient writing
// and export capabilities ...
WORD bpp = FreeImage_GetBPP(dib);
bCanSave = (FreeImage_FIFSupportsWriting(fif) && 
FreeImage_FIFSupportsExportBPP(fif, bpp));
} else {
// special bitmap type
// check that the plugin has sufficient export capabilities
bCanSave = FreeImage_FIFSupportsExportType(fif, image_type);
}
if(bCanSave) {
bSuccess = FreeImage_Save(fif, dib, lpszPathName, flag);
}
}
return (bSuccess == TRUE) ? true : false;
}
FreeImage_FIFSupportsExportType
DLL_API BOOL DLL_CALLCONV FreeImage_FIFSupportsExportType(FREE_IMAGE_FORMAT fif, 
FREE_IMAGE_TYPE type);
Returns TRUE if the plugin belonging to the given FREE_IMAGE_FORMAT can save a 
bitmap in the desired data type, returns FALSE otherwise. See the list of Supported file
formats in the appendix for a list of plugins that can save non-standard images. 
FreeImage_FIFSupportsExportBPP
DLL_API BOOL DLL_CALLCONV FreeImage_FIFSupportsExportBPP(FREE_IMAGE_FORMAT fif, int 
bpp);
Returns TRUE if the plugin belonging to the given FREE_IMAGE_FORMAT can save a 
bitmap in the desired bit depth, returns FALSE otherwise.
44    Bitmap function reference
FreeImage 3.13.1 documentation
Error processing SSI file
/**
Builds a series of string pairs that specify filters you can apply to save a file.
The filter string is to be used by a 'File Save As' dialog box (GetSaveFileName or 
CFileDialog).
@param szFilter Input and output parameters. szFilter is an array of char whose 
length should be 2048 or more.
@param bpp The bit depth of the image to be saved.
@param image_type The image type to be saved
@return Return the number of supported export formats
*/
int GetSaveAsFilterString(char *szFilter, WORD bpp, FREE_IMAGE_TYPE image_type) {
int i, iCount;
char Filter[2048];
char *token;
szFilter[0] = '\0';
iCount = 0;
// Build a string for each format
for(i = 0; i < FreeImage_GetFIFCount(); i++) {
// Check that the dib can be saved in this format
BOOL bCanSave;
FREE_IMAGE_FORMAT fif = (FREE_IMAGE_FORMAT)i;
if(image_type == FIT_BITMAP) {
// standard bitmap type
bCanSave = (FreeImage_FIFSupportsWriting(fif) && 
FreeImage_FIFSupportsExportBPP(fif, bpp));
} else {
// special bitmap type
bCanSave = FreeImage_FIFSupportsExportType(fif, image_type);
}
if(bCanSave) {
// Handle the special case of PNM files
strcpy(Filter, FreeImage_GetFormatFromFIF((FREE_IMAGE_FORMAT)i));
if((bpp == 1) && (!strncmp(Filter, "PGM", 3) || !strncmp(Filter, "PPM", 3)))
continue;
if((bpp == 8) && (!strncmp(Filter, "PBM", 3) || !strncmp(Filter, "PPM", 3)))
continue;
if((bpp == 24) && (!strncmp(Filter, "PGM", 3) || !strncmp(Filter, "PBM", 3)))
continue;
// Description
sprintf(Filter, "%s (%s)|", FreeImage_GetFIFDescription((FREE_IMAGE_FORMAT)i), 
FreeImage_GetFIFExtensionList((FREE_IMAGE_FORMAT)i));
strcat(szFilter, Filter);
// Extension(s)
strcpy(Filter, FreeImage_GetFIFExtensionList((FREE_IMAGE_FORMAT)i));
token = strtok(Filter, ",");
while(token != NULL) {
strcat(szFilter, "*.");
strcat(szFilter, token);
strcat(szFilter, ";");
// get next token
token = strtok(NULL, ",");
}
szFilter[strlen(szFilter)-1] = '|';
iCount++;
}
}
strcat(szFilter, "|");
return iCount;
}
FreeImage_FIFSupportsICCProfiles
DLL_API BOOL DLL_CALLCONV FreeImage_FIFSupportsICCProfiles(FREE_IMAGE_FORMAT fif);
Returns TRUE if the plugin belonging to the given FREE_IMAGE_FORMAT can load or save 
an ICC profile, returns FALSE otherwise.
FreeImage 3.13.1 documentation
Bitmap function reference    45
Error processing SSI file
// determine, whether profile support is present
if (FreeImage_FIFSupportsICCProfiles(FIF_TIFF)) {
// profile support present
}
FreeImage_RegisterLocalPlugin
DLL_API FREE_IMAGE_FORMAT DLL_CALLCONV FreeImage_RegisterLocalPlugin(FI_InitProc 
proc_address, const char *format FI_DEFAULT(0), const char *description FI_DEFAULT(0), 
const char *extension FI_DEFAULT(0), const char *regexpr FI_DEFAULT(0));
Registers a new plugin to be used in FreeImage. The plugin is residing directly in the 
application driving FreeImage. The first parameter is a pointer to a function that is used to 
initialise the plugin. The initialization function is responsible for filling in a Plugin structure and 
storing a system-assigned format identification number used for message logging.
static int s_format_id;
void stdcall
Init(Plugin *plugin, int format_id) {
s_format_id = format_id;
// pointer to a function that returns a type-string
// for the bitmap. For example, a plugin that loads
// BMPs returns the string “BMP”.
plugin->format_proc = Format;
// pointer to a function that returns a descriptive
// string for the bitmap type. For example, a plugin
// that loads BMPs may return “Windows or OS/2 Bitmap”
plugin->description_proc = Description;
// pointer to a function that returns a comma delimited
// list of possible file extension that are valid for
// this plugin. A JPEG plugin would return “jpeg,jif,jfif”
plugin->extension_proc = Extension;
// pointer to a function that is used to load the bitmap
plugin->load_proc = Load;
// pointer to a function that is used to save the bitmap
plugin->save_proc = Save;
// pointer to a function that will try to identify a 
// bitmap by looking at the first few bytes of the bitmap.
plugin->validate_proc = Validate;
}
FreeImage_RegisterExternalPlugin
DLL_API FREE_IMAGE_FORMAT DLL_CALLCONV FreeImage_RegisterExternalPlugin(const char 
*path, const char *format FI_DEFAULT(0), const char *description FI_DEFAULT(0), const 
char *extension FI_DEFAULT(0), const char *regexpr FI_DEFAULT(0));
Registers a new plugin to be used in FreeImage. The plugin is residing in a DLL. Functionally 
this function is the same as FreeImage_RegisterLocalPlugin, but now FreeImage calls an Init 
function in a DLL instead of a local function in an application. The Init function must be called 
“Init” and must use the stdcall calling convention.
46    Bitmap function reference
FreeImage 3.13.1 documentation
Error processing SSI file
Multipage functions
FreeImage features a set of functions that can be used to manipulate pages in a multi-page 
bitmap format. Currently TIFF, ICO and GIF formats are supported for this. The multi-page 
API makes it possible to access and change pages in a multi-bitmap, delete pages and 
change the order of pages. All of this is offered with a minimum implementation in a plugin 
and low requirement of memory through a sophisticated, compressing cache mechanism.
In the multipage API, whenever a ‘page’ parameter is needed by a function, it is always 
0-based.
FreeImage_OpenMultiBitmap
DLL_API FIMULTIBITMAP * DLL_CALLCONV FreeImage_OpenMultiBitmap(FREE_IMAGE_FORMAT fif, 
const char *filename, BOOL create_new, BOOL read_only, BOOL keep_cache_in_memory 
FI_DEFAULT(FALSE), int flags FI_DEFAULT(0));
Opens a multi-page bitmap. 
The first parameter tells FreeImage the bitmap-type of bitmap to be opened. Currently 
FIF_TIFF, FIF_ICO and FIF_GIF are supported. The second parameter specifies the name of 
the bitmap. When the third parameter is TRUE, it means that a new bitmap will be created 
rather than an existing one being opened. When the fourth parameter is TRUE the bitmap is 
opened read-only. The keep_cache_in_memory parameter is one purely for performance. 
When it is TRUE, all gathered bitmap data in the page manipulation process is kept in 
memory, otherwise it is lazily flushed to a temporary file on the hard disk in 64 Kb blocks. 
Note that depending on the amount of manipulation being performed and the size of the 
bitmap, the temporary data can become quite large. It’s advised to lazily flush to disc. The last 
parameter is used to change the behaviour or enable a feature in the bitmap plugin. Each 
plugin has its own set of parameters. 
FreeImage_OpenMultiBitmapFromHandle
DLL_API FIMULTIBITMAP * DLL_CALLCONV 
FreeImage_OpenMultiBitmapFromHandle(FREE_IMAGE_FORMAT fif, FreeImageIO *io, fi_handle 
handle, int flags FI_DEFAULT(0));
This function lets one open an existing multi-page bitmap from a handle in read-only mode
As with FreeImage_LoadFromHandle, a pointer to a FreeImageIO structure and a fi_handle 
must be specified. The actual implementation of FreeImage_CloseMultiBitmap is sufficient, to 
close such a multipage bitmap opened from a handle. 
FreeImage_CloseMultiBitmap
DLL_API BOOL DLL_CALLCONV FreeImage_CloseMultiBitmap(FIMULTIBITMAP *bitmap, int flags 
FI_DEFAULT(0));
Closes a previously opened multi-page bitmap and, when the bitmap was not opened read-
only, applies any changes made to it.
The flags parameter is used to change the behaviour or enable a feature in the bitmap plugin. 
Each plugin has its own set of parameters (see Table 4). Some bitmap savers can receive 
parameters to change the saving behaviour. When the parameter is not available or unused 
you can pass the value 0 or <TYPE_OF_BITMAP>_DEFAULT (e.g. TIFF_DEFAULT, 
ICO_DEFAULT, etc).
FreeImage 3.13.1 documentation
Bitmap function reference    47
Error processing SSI file
FreeImage_GetPageCount
DLL_API int DLL_CALLCONV FreeImage_GetPageCount(FIMULTIBITMAP *bitmap);
Returns the number of pages currently available in the multi-paged bitmap.
FreeImage_AppendPage
DLL_API void DLL_CALLCONV FreeImage_AppendPage(FIMULTIBITMAP *bitmap, FIBITMAP *data);
Appends a new page to the end of the bitmap.
FreeImage_InsertPage
DLL_API void DLL_CALLCONV FreeImage_InsertPage(FIMULTIBITMAP *bitmap, int page, 
FIBITMAP *data);
Inserts a new page before the given position in the bitmap. Page has to be a number smaller 
than the current number of pages available in the bitmap.
FreeImage_DeletePage
DLL_API void DLL_CALLCONV FreeImage_DeletePage(FIMULTIBITMAP *bitmap, int page);
Deletes the page on the given position.
FreeImage_LockPage
DLL_API FIBITMAP * DLL_CALLCONV FreeImage_LockPage(FIMULTIBITMAP *bitmap, int page);
Locks a page in memory for editing. The page can now be saved to a different file or inserted 
into another multi-page bitmap. When you are done with the bitmap you have to call 
FreeImage_UnlockPage to give the page back to the bitmap and/or apply any changes made 
in the page.
It is forbidden to use  FreeImage_Unload on a locked page: you must use 
FreeImage_UnlockPage instead.
FreeImage_UnlockPage
DLL_API void DLL_CALLCONV FreeImage_UnlockPage(FIMULTIBITMAP *bitmap, FIBITMAP *data, 
BOOL changed);
Unlocks a previously locked page and gives it back to the multi-page engine. When the last 
parameter is TRUE, the page is marked changed and the new page data is applied in the 
multi-page bitmap.
FreeImage_MovePage
DLL_API BOOL DLL_CALLCONV FreeImage_MovePage(FIMULTIBITMAP *bitmap, int target, int 
source);
48    Bitmap function reference
FreeImage 3.13.1 documentation
Error processing SSI file
Moves the source page to the position of the target page. Returns TRUE on success, FALSE 
on failure.
FreeImage_GetLockedPageNumbers
DLL_API BOOL DLL_CALLCONV FreeImage_GetLockedPageNumbers(FIMULTIBITMAP *bitmap, int 
*pages, int *count);
Returns an array of page-numbers that are currently locked in memory. When the pages 
parameter is NULL, the size of the array is returned in the count variable. You can then 
allocate the array of the desired size and call FreeImage_GetLockedPageNumbers again to 
populate the array.
bool CloneMultiPage(FREE_IMAGE_FORMAT fif, char *input, char *output, int 
output_flag) {
BOOL bMemoryCache = TRUE;
// Open src file (read-only, use memory cache)
FIMULTIBITMAP *src = FreeImage_OpenMultiBitmap(fif, input, FALSE, TRUE, 
bMemoryCache);
if(src) {
// Open dst file (creation, use memory cache)
FIMULTIBITMAP *dst = FreeImage_OpenMultiBitmap(fif, output, TRUE, FALSE, 
bMemoryCache);
// Get src page count
int count = FreeImage_GetPageCount(src);
// Clone src to dst
for(int page = 0; page < count; page++) {
// Load the bitmap at position 'page'
FIBITMAP *dib = FreeImage_LockPage(src, page);
if(dib) {
// add a new bitmap to dst
FreeImage_AppendPage(dst, dib);
// Unload the bitmap (do not apply any change to src)
FreeImage_UnlockPage(src, dib, FALSE);
}
}
// Close src
FreeImage_CloseMultiBitmap(src, 0);
// Save and close dst
FreeImage_CloseMultiBitmap(dst, output_flag);
return true;
}
return false;
}
FreeImage 3.13.1 documentation
Bitmap function reference    49
Error processing SSI file
Memory I/O streams
Memory I/O routines use a specialized version of the FreeImageIO structure, targeted to 
save/load FIBITMAP images to/from a memory stream. Just like you would do with a file 
stream. Memory file streams support loading and saving of FIBITMAP in a memory file 
(managed internally by FreeImage). They also support seeking and telling in the memory file.
Examples of using these functions would be to store image files as blobs in a database, or to 
write image files to a Internet stream. 
FreeImage_OpenMemory
DLL_API FIMEMORY *DLL_CALLCONV FreeImage_OpenMemory(BYTE *data FI_DEFAULT(0), DWORD 
size_in_bytes FI_DEFAULT(0));
Open a memory stream. The function returns a pointer to the opened memory stream.
When called with default arguments (0), this function opens a memory stream for read / write 
access. The stream will support loading and saving of FIBITMAP in a memory file (managed 
internally by FreeImage). It will also support seeking and telling in the memory file. 
This function can also be used to wrap a memory buffer provided by the application driving 
FreeImage. A buffer containing image data is given as function arguments data (start of the 
buffer) and size_in_bytes (buffer size in bytes). A memory buffer wrapped by FreeImage is 
read only. Images can be loaded but cannot be saved. 
FreeImage_CloseMemory
DLL_API void DLL_CALLCONV FreeImage_CloseMemory(FIMEMORY *stream);
Close and free a memory stream. 
When the stream is managed by FreeImage, the memory file is destroyed. Otherwise 
(wrapped buffer), it’s destruction is left to the application driving FreeImage.
You always need to call this function once you’re done with a memory stream 
(whatever the way you opened the stream), or you will have a memory leak.
FreeImage_LoadFromMemory
DLL_API FIBITMAP *DLL_CALLCONV FreeImage_LoadFromMemory(FREE_IMAGE_FORMAT fif, 
FIMEMORY *stream, int flags FI_DEFAULT(0));
This function does for memory streams what FreeImage_Load does for file streams. 
FreeImage_LoadFromMemory decodes a bitmap, allocates memory for it and then returns it 
as a FIBITMAP. The first parameter defines the type of bitmap to be loaded. For example, 
when FIF_BMP is passed, a BMP file is loaded into memory (an overview of possible 
FREE_IMAGE_FORMAT constants is available in Table 1). The second parameter tells 
FreeImage the memory stream it has to decode. The last parameter is used to change the 
behaviour or enable a feature in the bitmap plugin. Each plugin has its own set of parameters.
Some bitmap loaders can receive parameters to change the loading behaviour (see Table 3). 
When the parameter is not available or unused you can pass the value 0 or 
<TYPE_OF_BITMAP>_DEFAULT (e.g. BMP_DEFAULT, ICO_DEFAULT, etc).
50    Bitmap function reference
FreeImage 3.13.1 documentation
Error processing SSI file
void testLoadMemIO(const char *lpszPathName) {
struct stat buf;
int result;
// get data associated with lpszPathName
result = stat(lpszPathName, &buf);
if(result == 0) {
// allocate a memory buffer and load temporary data
BYTE *mem_buffer = (BYTE*)malloc(buf.st_size * sizeof(BYTE));
if(mem_buffer) {
FILE *stream = fopen(lpszPathName, "rb");
if(stream) {
fread(mem_buffer, sizeof(BYTE), buf.st_size, stream);
fclose(stream);
// attach the binary data to a memory stream
FIMEMORY *hmem = FreeImage_OpenMemory(mem_buffer, buf.st_size);
// get the file type
FREE_IMAGE_FORMAT fif = FreeImage_GetFileTypeFromMemory(hmem, 0);
// load an image from the memory stream
FIBITMAP *check = FreeImage_LoadFromMemory(fif, hmem, 0);
// save as a regular file
FreeImage_Save(FIF_PNG, check, "blob.png", PNG_DEFAULT);
FreeImage_Unload(check);
// always close the memory stream
FreeImage_CloseMemory(hmem);
}
}
// user is responsible for freeing the data
free(mem_buffer);
}
}
FreeImage_SaveToMemory
DLL_API BOOL DLL_CALLCONV FreeImage_SaveToMemory(FREE_IMAGE_FORMAT fif, FIBITMAP *dib, 
FIMEMORY *stream, int flags FI_DEFAULT(0));
This function does for memory streams what FreeImage_Save does for file streams. 
FreeImage_SaveToMemory saves a previously loaded FIBITMAP to a memory file managed 
by FreeImage. The first parameter defines the type of the bitmap to be saved. For example, 
when FIF_BMP is passed, a BMP file is saved  (an overview of  possible 
FREE_IMAGE_FORMAT constants is available in Table 1). The second parameter is the 
memory stream where the bitmap must be saved. When the memory file pointer point to the 
beginning of the memory file, any existing data is overwritten. Otherwise, you can save 
multiple images on the same stream. 
Note that some bitmap save plugins have restrictions on the bitmap types they can save. For 
example, the JPEG plugin can only save 24-bit and 8-bit greyscale bitmaps. The last 
parameter is used to change the behaviour or enable a feature in the bitmap plugin. Each 
plugin has its own set of parameters.
Some bitmap savers can receive parameters to change the saving behaviour (see Table 4). 
When the parameter is not available or unused you can pass the value 0 or 
<TYPE_OF_BITMAP>_DEFAULT (e.g. BMP_DEFAULT, ICO_DEFAULT, etc).
FreeImage 3.13.1 documentation
Bitmap function reference    51
Error processing SSI file
void testSaveMemIO(const char *lpszPathName) {
FIMEMORY *hmem = NULL; 
// load and decode a regular file
FREE_IMAGE_FORMAT fif = FreeImage_GetFileType(lpszPathName);
FIBITMAP *dib = FreeImage_Load(fif, lpszPathName, 0);
// open a memory stream
hmem = FreeImage_OpenMemory();
// encode and save the image to the memory
FreeImage_SaveToMemory(fif, dib, hmem, 0);
// at this point, hmem contains the entire data in memory stored in fif format. 
// the amount of space used by the memory is equal to file_size
long file_size = FreeImage_TellMemory(hmem);
printf("File size : %ld\n", file_size);
// its easy to load an image from memory as well
// seek to the start of the memory stream
FreeImage_SeekMemory(hmem, 0L, SEEK_SET);
// get the file type
FREE_IMAGE_FORMAT mem_fif = FreeImage_GetFileTypeFromMemory(hmem, 0);
// load an image from the memory handle 
FIBITMAP *check = FreeImage_LoadFromMemory(mem_fif, hmem, 0);
// save as a regular file
FreeImage_Save(FIF_PNG, check, "dump.png", PNG_DEFAULT);
// make sure to close the stream since FreeImage_SaveToMemory 
// will cause internal memory allocations and this is the only 
// way to free this allocated memory
FreeImage_CloseMemory(hmem);
FreeImage_Unload(check);
FreeImage_Unload(dib);
}
FreeImage_AcquireMemory
DLL_API BOOL DLL_CALLCONV FreeImage_AcquireMemory(FIMEMORY *stream, BYTE **data, DWORD 
*size_in_bytes);
Provides a direct buffer access to a memory stream. Upon entry, stream is the target memory 
stream, returned value data is a pointer to the memory buffer, returned value size_in_bytes is 
the buffer size in bytes. The function returns TRUE if successful, FALSE otherwise.
When the memory stream is managed internally by FreeImage, the data pointer 
returned by FreeImage_AcquireMemory may become invalid as soon as you call 
FreeImage_SaveToMemory. 
52    Bitmap function reference
FreeImage 3.13.1 documentation
Error processing SSI file
Error processing SSI file