Writing an image in DIB format

Exporting a DIB

The ImgX functions provide a very simple function called ImgXWriteDIB which allows you to write a DIB in memory to disk in any supported image format. In most cases this is the only ImgX function you will need to use.

Using ImgXWriteDIB

Using the ImgXWriteDIB function to export an image is very simple. The following code fragment illustrates exporting a DIB to a file called "SAMPLE.TIF".

HANDLE hDIB ;

// Handle to a global memory block containing a DIB

HWND hWnd;

// Handle to Main Window

...

retval = ImgXWriteDIB( "sample.tif", NULL,hDIB, NULL,hWnd, IMGXOPT_COMPRESS );

if( retval != IMGX_OK )

ImgErrBox( hWnd );

...

In this example the DIB is written as a compressed TIFF file without any intervention by the end-user. If the function returns a value other than IMGX_OK then an error has occurred. When an error occurs you can call the ImgErrBox function to display a messagebox containing a description of the error or call ImgErrString which returns the string into a buffer. If you just want to get the error code in numeric form call the ImgGetStatus function.

If you want the end-user to specify a filename and image type then call the ImgXWriteDIB function like this:

...

retval = ImgXWriteDIB( NULL, NULL, hDIB, NULL, hWnd, IMGXOPT_FILE_PROMPT );

...

The IMGXOPT_FILE_PROMPT flag causes ImgXWriteDIB to display a file save dialog which will allow the user to select an image format and filename. When the IMGXOPT_FILE_PROMPT option is specified, the lpFilename and lpExt parameters are both ignored.

If you want to specify writing a file with a nonstandard extension then call ImageXWriteDIB like this:

...

retval = ImgXWriteDIB( "sample.001", "pcx", hDIB, NULL, hWnd, IMGXOPT_COMPRESS );

...

This will cause the image to be written to a file called sample.001 in PCX format. The extension specified must not contain a period and must be a supported image type.

The ImgXWriteDIB function also allows you to pass a handle to an Option Block as the 4th parameter. If you don't have an Option Block then just pass NULL. In most cases you won't need an Option Block but they can be useful in specifying some format specific information like compression types, etc. For instance if you wanted to write a TIFF file with Group 3 Fax compression instead of the default Packbits compression you could create an Option block and pass it to the function. This example would do just that:

HANDLE hOptBlk;

...

hOptBlk = ImgXOptBlkCreate( "TIFF_COMPRESS = GROUP3" );

retval = ImgXWriteDIB( "sample.tif", NULL, hDIB,hoptBlk, hWnd, IMGXOPT_COMPRESS );

if( retval != IMGX_OK )

ImgXErrBox( hWnd );

ImgXOptBlkDel( hOptBlk );

...

This code causes the image to be written to the file sample.tif in Group 3 FAX format. Appendix D lists the various generic Option block settings and the various format-specific Option block settings.

The most important thing when calling ImgXWriteDIB is that the DIB is in CF_DIB format (This is the format returned by the ImgGetDIB function). CF_DIB means that the DIB is contained in a global memory block and is ordered in a particular way. The first thing in the block should be a BITMAPINFOHEADER structure which describes the DIB. The BITMAPINFOHEADER structure is the standard DIB header and includes information like width, height, color format, resolution and many other details about the image. Next in the memory block should be an array of RGBQUAD structures which contain the palette information except in the case of 24 bit images since they have no palette. Even bi-level images will have two entries for black and white or really whatever colors you want. Lastly the block contains the actual raster data which makes up the image with each row aligned to DWORD or 4 byte boundaries.

CF_DIB is the standard format for handling DIBs and is the same format used when pasting or copying DIBs from the Windows clipboard. Also the Microsoft DIB manipulation code found in the Windows SDK uses this format.

Note that if a default status procedure has been setup using the ImgSetDefaultStatusProc function, you will receive status information during the export operation.