sane_get_parameters

This function is used to obtain the current scan parameters. The returned parameters are guaranteed to be accurate between the time a scan has been started (sane_start() has been called) and the completion of that request. Outside of that window, the returned values are best-effort estimates of what the parameters will be when sane_start() gets invoked. Calling this function before a scan has actually started allows, for example, to get an estimate of how big the scanned image will be. The parameters passed to this function are the handle h of the device for which the parameters should be obtained and a pointer p to a parameter structure. The parameter structure is described in more detail below.

SANE_Status sane_get_parameters (SANE_Handle h,
                                 SANE_Parameters * p);

The scan parameters are returned in a structure of type SANE_Parameters. The C declaration of this structure is given below.

typedef struct
  {
    SANE_Frame format;
    SANE_Bool last_frame;
    SANE_Int lines;
    SANE_Int depth;
    SANE_Int pixels_per_line;
    SANE_Int bytes_per_line;
  }
SANE_Parameters;

Member format specifies the format of the next frame to be returned. The possible values for type SANE_Frame are described in Table 4.9. The meaning of these values is described in more detail in Section 3.2.

表 4.9: Frame Format (SANE_Frame)

Symbol	Code	Description
SANE_FRAME_GRAY	0	Band covering human visual range.
SANE_FRAME_RGB	1	Pixel-interleaved red/green/blue bands.
SANE_FRAME_RED	2	Red band of a red/green/blue image.
SANE_FRAME_GREEN	3	Green band of a red/green/blue image.
SANE_FRAME_BLUE	4	Blue band of a red/green/blue image.

Member last_frame is set to SANE_TRUE if and only if the frame that is currently being acquired (or the frame that will be acquired next if there is no current frame) is the last frame of a multi frame image (e.g., the current frame is the blue component of a red, green, blue image).

Member lines specifies how many scan lines the frame is comprised of. If this value is -1, the number of lines is not known a priori and the frontend should call sane_read() until it returns a status of SANE_STATUS_EOF.

Member bytes_per_line specifies the number of bytes that comprise one scan line.

Member depth specifies the number of bits per sample.

Member pixels_per_line specifies the number of pixels that comprise one scan line.

Assume $B$ is the number of channels in the frame, then the bit depth $d$ (as given by member depth) and the number of pixels per line $n$ (as given by this member pixels_per_line) are related to $c$, the number of bytes per line (as given by member bytes_per_line) as follows:

$$c >= \left\{ \begin{array}{ll} \lceil B\cdot n / 8\rceil ... ...\lceil (d + 7)/8 \rceil & \mbox{if $d>1$} \end{array} \right.$$

Note that the number of bytes per line can be larger than the minimum value imposed by the right side of this equation. A frontend must be able to properly cope with such ``padded'' image formats.