The IG_load_...() functions provide the means to bring images from image files into ImageGear. The image files may be on a mass storage device such as a disk, or they may already be in memory.

When you load an image using an IG_load_...() function, ImageGear provides a handle of ImageGear type HIGEAR. Having HIGEAR handles for your images allows your application to perform the entire range of ImageGear's imaging operations.

Alternately, you can import images that exist as plain bitmaps, DIBs, or DDBs in your application. You can scan images from elsewhere directly into ImageGear. You can locate and extract ASCII or graphics images from multi-page (multi-image) files, using ImageGear's GUI browse and other capabilities.

IG_load_ ...() functions create a DIB in memory, and transfer the bitmap and other pertinent information (such as the image's color palette, if one is associated with it; and header information such as width, height, and bits per pixel) into this DIB. These functions do not display the image unless the word "display" is included in the function name, such as in IG_load_file_display().

Here are a few examples that demonstrate how to call the functions in this group. Refer to Load Functions in the Core Component API Function Reference for more information on the IG_load_ ...() functions:

Loading an Image from File

The following example code loads the file "picture.bmp" from the current directory, creating a DIB in memory, and creates a unique ImageGear handle for it, returning this handle to you in hIGear.

#include "gear.h"

// Handle to the image.
HIGEAR image;
AT_ERRCOUNT errorCount;

// Load image, and obtain its ImageGear handle.
errorCount = IG_load_file ("picture.bmp", &image);

Loading an Image from File Using a File Descriptor Handle

Names of some IG_load_ ...() functions contain the letters "FD", for example IG_load_FD_CB(). These functions access the file by its File Descriptor handle, which is an integer value returned to you when you open the file using certain Windows functions. You may use these IG_load_FD...() functions to load an image from a file, if the file is already open and your application has its File Descriptor handle.

The following example above ImageGear IG_load_FD...() loading from a file that has already been opened by means of the Windows function _lopen() or other file I/O function that returns a File Descriptor handle.

If nErrcount is zero, a DIB is created, the image is loaded, and your HIGEAR object, hIGear, contains its HIGEAR handle.

HIGEAR image;
INT fileDescriptor;
LONG offset;
UINT pageNumber;
AT_ERRCOUNT errorCount;

// Open the file.
fileDescriptor = _lopen ("picture.bmp", OF_READ);
// Use 0 for a single-page file.
pageNumber = 0;
// Use 0 to access the file from the beginning.
offset = 0;

// Load image, and obtain its ImageGear handle.
errorCount = IG_load_FD (fileDescriptor, offset, pageNumber, 0, &image);

Loading an Image from Memory

IG_load_mem() is used to load an image from memory. The image in memory must be in the same format as if the image were on disk. For example, the image must contain an appropriate header, the bitmap data, and if necessary, a palette. This in-memory file must be of a format recognized by ImageGear (see "File Format Reference").

In the following call, dwWholeSize must be the size of the entire memory image, not just of the bitmap. lpWhereFile must point to the first byte of this whole image. And nPageNum, if not zero, specifies the page number to load if loading from a multi-page (multiple image) file. Please note that the first page of a multi-page file is page number 1, not page number 0. The function IG_load_mem() creates a DIB and loads into it the image specified, and returns in hIGear the new HIGEAR image handle. The HIGEAR image handle is how you will refer to this image in subsequent calls to ImageGear functions.

HIGEAR image;
// Pointer to image file in memory.
char * imageLocation;
// Size of image file in memory.
DWORD imageSize;
UINT pageNumber;
UINT tiled;
AT_ERRCOUNT errorCount;

// Use 0 for a single-page file.
pageNumber = 0;
// Set to 1 for a non-tiled image, otherwise set to a specific tile to load.
tile = 1;

// Set imageLocation and imageSize.

// Load image, and obtain its ImageGear handle.
errorCount = IG_load_mem(imageLocation, imageSize, pageNumber, tile, &hIGear);

See Also:

Detecting Image File Format