The IG_load_...() functions provide the means to bring images from image files into ImageGear's sphere of influence. 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().
 |
For information about loading CMYK images, see Color Management. |
Here are a few examples that demonstrate how to call the functions in this group. Refer to "Core Component API Function Reference" for more information on the IG_load_ ...() functions.
Example 1:
 Copy Code |
|
|---|---|
#include "gear.h" HIGEAR hIGear; /* HIGEAR handle returned */ AT_ERRCOUNT nErrcount; /* Count of errors reported */ nErrcount = IG_load_file ("picture.bmp", &hIGear); |
|
The example code above 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.
Example 2:
| Copy Code |
|
|---|---|
HIGEAR hIGear; /* handle returned by ImageGear */ char * lpWhereFile; /* ptr to image file in mem */ DWORD dwWholeSize; /* size of image file in mem */ UINT nPageNum; /* will be 0 for this call */ AT_ERRCOUNT nErrcount; /* to test for errors */ nPageNum = 0; /* not a multi-page file */ lpWhereFile = ...; /* where mem image file begins */ dwWholeSize = ...; /* size of whole mem image */ nErrcount = IG_load_mem (lpWhereFile, dwWholeSize,nPageNum, 0, &hIGear); |
|
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 above 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 by which you will refer to this image in subsequent calls to ImageGear functions.
Example 3:
| Copy Code |
|
|---|---|
HIGEAR hIGear; /* handle ret'd by IG_load_FD */ INT fd; /* File Descriptor handle */ LONG lOffset; /* offset to image in file */ UINT nPageNum; /* will be 0 for this call */ AT_ERRCOUNT nErrcount; /* to test for errors */ fd = _lopen ( "picture.bmp", OF_READ ); /* open file */ nPagenum = 0; /* not a multi-page file */ lOffset = 0; /* access file from start */ /* Load image, and obtain its ImageGear handle: */ nErrcount = IG_load_FD (fd, lOffset, nPageNum, 0, &hIGear); |
|
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 example above shows ImageGear IG_load_FD...() loading from a file that has been already 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.