DTWAIN_GetImageInfo

Top  Previous  Next

 

 

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

 

DTWAIN_BOOL DTWAIN_GetImageInfo (

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 );

 

Parameters

Source

Specifies a TWAIN Source.

 

pXResolution

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

 

pYResolution

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

 

pWidth

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

 

pLength

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

 

pNumSamples

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

 

pBitsPerSample

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

 

pBitsPerPixel

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

 

pPlanar

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

 

pPixelType

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

 

pCompression

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

 

Return Values

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

 

Comments

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.

 

Important Note!

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.

 

TWAIN State Transitions

The source must be opened in State 6

 

Prerequisite Function Call(s)

DTWAIN_SysInitialize

 

DTWAIN Source Selection Function

DTWAIN Acquisition Function

 

See Also

DTWAIN_GetSourceUnit