DTWAIN_GetImageInfo

The DTWAIN_GetImageInfo returns the description of the image data that is to be transferred from the Source.

DTWAIN_SOURCE	Source,
LPDTWAIN_FLOAT	pXResolution
LPDTWAIN_FLOAT	pYResolution
LPLONG	pWidth
LPLONG	pLength
LPLONG	pNumSamples
LPDTWAIN_ARRAY	pBitsPerSample
LPLONG	pBitsPerPixel
LPDTWAIN_BOOL	pPlanar
LPLONG	pPixelType
LPLONG	pCompression );

Address of a DTWAIN_FLOAT that will receive the X-resolution of the image, or NULL if this parameter is to be ignored.

Address of a DTWAIN_FLOAT that will receive the Y-resolution of the image, or NULL if this parameter is to be ignored

Address of a LONG that will receive the image width, or NULL if this parameter is to be ignored

Address of a LONG that will receive the image length, or NULL if this parameter is to be ignored

Address of a LONG that will receive the number of samples of the image, or NULL if this parameter is to be ignored

Address of a DTWAIN_ARRAY that will store the number of bits for each sample, or NULL if this parameter is to be ignored.

Address of a LONG that will receive the number of bits per pixel, or NULL if this parameter is to be ignored

Address of a DTWAIN_BOOL that will receive the pixel order type, or NULL if this parameter is to be ignored.

Address of a LONG that will receive the color (pixel-type) of the image, or NULL if this parameter is to be ignored.

Address of a LONG that will receive the image compression type, or NULL if this parameter is to be ignored.

If the function succeeds, TRUE is returned. If the function fails, FALSE is returned.

The DTWAIN_GetImageInfo function returns the description of the image data that is being transferred by the TWAIN Source Source. All the parameters to DTWAIN_GetImageInfo are addresses (LPDTWAIN_FLOAT, LPLONG, LPDTWAIN_ARRAY), since DTWAIN will fill these addresses with the information.

The DTWAIN_FLOAT variables located at pXResolution, pYResolution, pWidth, and pLength are set to the image's X and Y resolutions, width and length respectively. The units used for these values are determined by the DTWAIN_GetSourceUnit function.

The LONG located at the address pNumSamples is set to the number of samples that make up the image. For example, if the image uses Red-Green-Blue (RGB), the samples-per-pixel is 3. For Black and White or Grayscale, the samples-per-pixel is 1.

The DTWAIN_ARRAY pointed to by pBitsPerSample will be filled with the number of bits of information per sample. The number of samples is determined by pNumSamples. For a 24-bit RGB image, this value is usually 8 for red, 8 for green, and 8 for blue. In this case, pNumSamples will be a DTWAIN_ARRAY consisting of 3 values all equal to 8. The values stored in the DTWAIN_ARRAY will have a LONG data type.

The LONG located at the address pBitsPerPixel is set to the number of bits per pixel of data. The usual values are 1, 8, and 24.

The DTWAIN_BOOL located at the address pPlanar is set to FALSE if the samples of pixels follow one another in a pixel-by-pixel basis. For example, if the pixel samples are R-G-B, R-G-B, R-G-B, etc., the location at pPlanar is set to FALSE. If the pixel sample is planar, for example all the red pixels followed by all the green pixels, followed by all the blue pixels, the location at pPlanar is set to TRUE.

The LONG located at the address pPixelType determines the color type of the image. This value can be one of the following:

Constant	Value	Meaning
DTWAIN_PIXELBW	0	Black and White
DTWAIN_PIXELGRAY	1	Gray scale
DTWAIN_PIXELRGB	2	Red-Green-Blue Color

The LONG located at the address pCompression determines the compression used for the image. The compression value can be one of the values found in the DTWAIN Constants topic.

The information returned by DTWAIN_GetImageInfo is reliable only at the time DTWAIN sends the DTWAIN_TN_TRANSFERREADY notification and DTWAIN_TN_TRANSFERDONE notification to the application (this is equivalent to TWAIN State 6).

Some devices will report a "-1" for the image width and height before the acquisition (when DTWAIN_TN_TRANSFERREADY is sent), therefore

the width / height information is only available when DTWAIN_TN_TRANSFERDONE is sent. Usually these devices are hand-held scanners or scanners that can only determine the width and height of the image after the acquisition has completed.

For languages that have difficulties with DTWAIN_FLOAT parameters, the alternate function that can be used as a replacement for DTWAIN_GetImageInfo is DTWAIN_GetImageInfoString.