arg->data: NULL
res->data: NULL

This function exists as a mechanism for the application to determine whether the scanner driver managed to initialize itself and the scanner properly. If any problem occurred during initialization, res->errno should be set to one of the SCE #defines in scanner.h; otherwise, no action is necessary.

arg->data: int * (Metric)
res->data: SCWINDOW *
typedef struct tag_scwindow {
   float x, y, width, height;
} SCWINDOW;

This function returns the size of the scannable area supported by the scanner. Fill res->data in with the x, y, width, and height of the scannable area in inches or centimeters, depending on whether arg->data is SC_INCHES or SC_CENTIM.

arg->data: NULL
res->data: SCMINMAXRES *
typedef struct tag_scminmaxres {
    float minx, miny, maxx, maxy;
} SCMINMAXRES;

This function sets the smallest and largest horizontal and vertical resolutions. res->data->minx should be set to the smallest horizontal resolution supported in hardware by the scanner, res->data->miny to the smallest vertical resolution, res->data->maxx to the largest horizontal resolution, and res->data->maxy to the largest vertical resolution.

arg->data: NULL
res->data: int *

This function sets the number of resolution pairs supported in hardware. *res->data should be set to the number of (xres, yres) resolution pairs supported in hardware by the scanner.

arg->data: int *
res->data: float *

This function sets floating-point numbers representing supported hardware resolutions. arg->data points to the metric of the resolution; either SC_INCHES for pixels/inch or SC_CENTIM for pixels/centimeter. res->data should be set to point to a floating-point array that represent supported hardware resolutions. There should be an even number of resolutions, with all of the horizontal resolutions first, then all of the vertical resolutions.

---

Note: All scanner drivers must support arbitrary resolutions; software routines are provided to perform zoom operations. The above information is provided so that scanner application developers can retrieve pure data from the scanner and perform their own zooming (with filters; libscan zooming does no filtering) to achieve the desired resolution.

---

arg->data: NULL
res->data: int *

This function sets the number of data types supported by the driver. *res->data should be set to the number of data types supported by this scanner driver.

arg->data: NULL
res->data: SCDATATYPE *
typedef struct tag_scdatatype {
    unsigned int packing : 4;
    unsigned int channels : 4;
    unsigned int type : 8;
    unsigned int bpp : 8;
} SCDATATYPE;

The res->data of the SCN_TYPES() function points to an array of SCDATATYPE objects, one for each of the types supported by the scanner driver.

All scanner drivers must support monochrome data; that is, the type { SC_PACKPIX, 1, SC_MONO, 1 }. All scanner drivers that support any kind of greyscale or color output must support the type { SC_PACKPIX, 1, SC_GREY, 8 }; that is, 8-bit gray-scale. All scanner drivers that support any kind of color output must support either { SC_PACKPIX, 3, SC_RGB, 8 } (24-bit CHUNKY color data) or { SC_PACKPLANE, 3, SC_RGB, 8 } (24-bit planar color data).

Library routines in libscan.a exist to facilitate compliance with these conventions.

arg->data: NULL
res->data: SCFEEDERFLAGS *
typedef unsigned int SCFEEDERFLAGS;

This function returns the feeder flags for this scanner to the application. See “Header Files” in Chapter 6.

arg->data: SCFEEDERFLAGS *
res->data: NULL

This function sets the feeder flags.

arg->data: NULL
res->data: NULL

This function determines whether or not the feeder is ready for an advance command.

arg->data: NULL
res->data: NULL

This function causes the feeder to advance to the next document.

arg->data: SCSETUP *
res->data: NULL

typedef struct tag_scsetup {
    int preview;
    SCDATATYPE type;
    int rmetric;
    float xres, yres;
    int wmetric;
    float x, y, width, height;
} SCSETUP;

The SCN_SETUP() function sets the scanning parameters. The upper-left x and y coordinates, the width, and the height are specified in either pixels, inches, or centimeters, depending on whether arg->data->wmetric is SC_PIXELS, SC_INCHES, or SC_CENTIM.

Set the scanning horizontal and vertical resolutions, in pixels per inch or pixels per centimeter, depending on the value of arg->data->rmetric. Set the data type for scanning. If this is a preview, arg->data->preview will have a nonzero value.

---

Note: If a resolution or combination of resolutions not supported in hardware is specified, the driver MUST zoom the image in order to supply the requested resolution. Library routines to aid zooming are available in libscan.a.

---

arg->data: NULL
res->data: SCSIZE *
typedef struct tag_scsize {
    long xbytes, xpixels, ysize;
} SCSIZE;

This function returns, to the scanning application, the width of a scan line in bytes and pixels, and the number of scan lines in the scan. This is called after SCN_SETUP() so the application knows exactly how much data to expect.

arg->data: NULL

res->data: NULL

This function tells the scanner driver to initiate scanning.

arg->data: NULL
res->data: NULL

This function stops the scan and releases any resources temporarily allocated. The application has decided to stop retrieving data before scanning has been completed. The driver should physically stop the scan and release any resources that were temporarily allocated for the scan.

arg->data: NULL
res->data: NULL

This function cleans up and calls exit(2). The application has demanded that the driver terminate. This function should not return; it should perform any necessary cleanup and then call exit.

GRIDTOFLOAT(int pos, int n)
FLOATTOGRID(float pos, int n)

These macros determine which destination pixel or line the source pixel or line at pos corresponds to. For example, if we are scanning at 120 dpi, but the application has requested 100 dpi, and our scan height is 1 inch, we need to skip 20 scan lines to provide the desired resolution. The following loop obtains scan lines from the scanner and passes them on to the application:

float fy;
int imgy, scany;

while (imgy < 100) {
    fy = GRIDTOFLOAT(imgy, 100);
    scany = FLOATTOGRID(fy, 120);
    ...
    /* Get the scany'th scan line from the scanner */
    /* Do conversion and horizontal zooming */
    /* Call SCDriverPutRow */
    imgy++;
}

int *SCCreateZoomMap(int anx, int bnx);

This function creates a zoom map. When zooming in the horizontal direction, it is wasteful to use GRIDTOFLOAT and FLOATTOGRID for every pixel of every line, since the same calculations would be repeated many times. A zoom map is an array of bnx integers, each of which is the pixel between 0 and anx - 1 that should be used when zooming a row of anx pixels to a row of bnx pixels. The zooming and conversion functions all take zoom maps for efficient zooming; for conversion functions where no zooming is to occur, the zmap parameter can be NULL.

void SCDestroyZoomMap(int *zmap);

This function frees memory allocated to store a zoom map.

void SCZoomRow1(char *abuf, int anx, char *bbuf, int bnx, int *zmap);

This function zooms a row of anx pixels to a row of bnx pixels, 1 bit per pixel.

void SCZoomRow8(char *abuf, int anx, char *bbuf, int bnx, int *zmap);

This function zooms a row of anx pixels to a row of bnx pixels, 8 bits per pixel.

void SCZoomRow24(void *abuf, int anx, void *bbuf, int bnx, int *zmap);

This function zooms a row of anx pixels to a row of bnx pixels, 24 bits per pixel.

void SCZoomRow32(void *abuf, int anx, void *bbuf, int bnx, int *zmap);

This function zooms a row of anx pixels to a row of bnx pixels, 32 bits per pixel.

void SCBandRGB8ToPixelRGB8(void *frombuf, int fromx, 
        void *tobuf, int tox, int *zmap);

This function converts a row of fromx pixels, laid out in three rows (R, G, and B) of 8-bit components per pixel, to a row of tox pixels, 24 bits per pixel.

void SCGrey8ToMono(unsigned char thresh, void *frombuf, 
        int fromx, void *tobuf, int tox, int *zmap);

This function converts a row of pixels from 8-bit greyscale to monochrome, thresholding each pixel with thresh.

SCQUEUE * SCCreateQueue(int nelems);

This function creates a queue that is multi-threaded safe and blocks on an empty dequeue. nelems is the maximum number of elements that can be stored in the newly created queue. Enqueue operations on full queues block until another thread has completed a dequeue operation.

int SCDestroyQueue(SCQUEUE *q);

This function frees the resources used by a queue.

void SCEnqueue(SCQUEUE *q, void *data);

This function adds an element to the tail of the queue. It unblocks a thread waiting to dequeue or blocks it if the queue is full.

void * SCDequeue(SCQUEUE *q);

This function removes an element from the head of a queue and returns it. SCDequeue() unblocks a thread waiting to enqueue or blocks it if the queue is empty.

void * SCQueueSetExit(SCQUEUE *q);

This function sets a flag associated with a queue that tells all users of the queue to exit. Any thread blocking in SCEnqueue() or SCDequeue() is terminated. SCQueueSetExit() is used by the main thread of a scanner driver to tell the child threads to exit when the user aborts a scan.