DTWAIN_GetImageInfo
|
The DTWAIN_GetImageInfo returns the description of the image data that is to be transferred from the Source.
DTWAIN_BOOL DTWAIN_GetImageInfo (
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:
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 Source Selection Function
See Also |