ImgXWriteDIB

int IMAPI ImgXWriteDIB ( lpFile, lpExt, hDIB, hOptBlk, hWnd, lOpts )

This function is used to write a DIB in memory to a supported image format.

Parameter

Type

Description

lpFile

LPSTR

Points to ASCII string containing the name of the file to save the image in or NULL.

lpExt

LPSTR

Points to a ASCII string containing the extension of the image format to use when saving this image or NULL.

hDIB

HANDLE

This is a global memory handle to a Windows DIB in CF_DIB format.

hOptBlk

HANDLE

Handle to an option block for this image or NULL

hWnd

HANDLE

This is a handle to the applications main window.

lOpts

LONG

Contains flags which set various options when saving the image.

Return Value

The return value is IMGX_OK if the image was saved otherwise it is IMGX_ERR.

Comments

If you need to write a DIB to memory, then you will need to call the low-level functions ImgXBeginWriteMem, ImgXWriteBlock, and ImgXEndWriteMem.

If you need to write a DIB in sections (bands) then you will need to call the low-level functions ImgXBeginWrite, ImgXWriteBlock, and ImgXEndWrite.

The filename pointed to by lpFile must contain a supported file extension unless the lpExt parameter points a string containing the format extension to use. The lpFile parameter can be NULL if you specify the IMGXOPT_FILE_PROMPT option in the lOpts parameter.

If you are saving an image and wish to use a nonstandard file extension then the lpExt parameter must point to a string containing the 1-3 character extension of the image type you wish to save the image as. This parameter can be set to NULL when saving images using a standard file extension.

For instance, if you wish to save an image as a TIFF file in a file called SAMPLE.001 you would have to pass a pointer to "SAMPLE.001" as the lpFile parameter and a pointer to a string, "TIF", as the lpExt parameter.

The lpOpts parameter allows you to specify some additional parameters to the function. Multiple options can be specified by logically or-ing them i.e. IMGXOPT_COMPRESS | IMGXOPT_OVERWRITE.

The following options can be specified in the lOpts parameter:

Options

Description

IMGXOPT_COMPRESS

This option caused the image to be written in compressed form if the image format supports compression otherwise it is ignored.

IMGXOPT_OVERWRITE

This option causes any existing file with the same name to be overwritten.

IMGXOPT_OVERWRITE_PROMPT

This option causes the function to prompt the user if an existing file has the same name. The user can then select to overwrite the existing file or select a new filename.

IMGXOPT_FILE_PROMPT

This options causes the common file save dialog to be displayed to prompt the user for the output filename. The user can also select the format of the file to export. This filename will override any filename specified in the lpszFilename parameter. If you specify this option you can pass NULL as the lpFile parameter.

IMGXOPT_SAVE_PROMPT

This option causes the common file save dialog to be displayed to prompt the user for the output filename. In addition to the std dialog controls this option also allows the user to specify compression types and other information specific to the format of the image. This filename will override any filename specified in the lpszFilename parameter. If you specify this option you can pass NULL as the lpFile parameter.

Parameter	Type	Description
lpFile	LPSTR	Points to ASCII string containing the name of the file to save the image in or NULL.
lpExt	LPSTR	Points to a ASCII string containing the extension of the image format to use when saving this image or NULL.
hDIB	HANDLE	This is a global memory handle to a Windows DIB in CF_DIB format.
hOptBlk	HANDLE	Handle to an option block for this image or NULL
hWnd	HANDLE	This is a handle to the applications main window.
lOpts	LONG	Contains flags which set various options when saving the image.

Options	Description
IMGXOPT_COMPRESS	This option caused the image to be written in compressed form if the image format supports compression otherwise it is ignored.
IMGXOPT_OVERWRITE	This option causes any existing file with the same name to be overwritten.
IMGXOPT_OVERWRITE_PROMPT	This option causes the function to prompt the user if an existing file has the same name. The user can then select to overwrite the existing file or select a new filename.
IMGXOPT_FILE_PROMPT	This options causes the common file save dialog to be displayed to prompt the user for the output filename. The user can also select the format of the file to export. This filename will override any filename specified in the lpszFilename parameter. If you specify this option you can pass NULL as the lpFile parameter.
IMGXOPT_SAVE_PROMPT	This option causes the common file save dialog to be displayed to prompt the user for the output filename. In addition to the std dialog controls this option also allows the user to specify compression types and other information specific to the format of the image. This filename will override any filename specified in the lpszFilename parameter. If you specify this option you can pass NULL as the lpFile parameter.