SCGetDataTypes(3)

NAME
     SCGetDataTypes - determine the data types supported by a scanner

SYNOPSIS
     #include <stdio.h>
     #include <scanner.h>

     int SCGetDataTypes(SCANNER *s, SCDATATYPE **dt, int *ntypes);

DESCRIPTION
     SCGetDataTypes sets *dt to point to an array of the data types supported
     by the scanner driver.  *ntypes gets the number of data types pointed to
     by *dt.  s specifies a connection to a scanner driver obtained from a
     call to SCOpen(3), SCOpenFile(3), or SCOpenScreen(3).

     SCDATATYPE is defined in <scanner.h> as follows:

          typedef struct tag_scdatatype {
              unsigned int packing : 4;
              unsigned int channels : 4;
              unsigned int type : 8;
              unsigned int bpp : 8;
          } SCDATATYPE;


     packing indicates how the data for each pixel is laid out.  Its value
     will be one of SC_PACKPIX, SC_PACKBAND, or SC_PACKPLANE, which are
     defined in <scanner.h>.  If packing is SC_PACKPIX, then all the data for
     each pixel is together.  If packing is SC_PACKBAND then the data is
     banded by row, and if packing is SC_PACKPLANE then the data is laid out
     in planes (see below).

     channels is the number of channels of data for this type.  Black and
     white data (SC_MONO, SC_GREY) consists of one channel, while color data
     consists of three (SC_RGB, SC_CMY) or four (SC_CMYK).

     type is used to interpret the channels of data.  type should be one of
     SC_MONO, SC_GREY, SC_RGB, SC_CMY, or SC_CMYK, which are defined in
     <scanner.h>.

     bpp is the number of bits per pixel in each channel.  Thus, for
     monochrome data, there is 1 bit per pixel, and for 24 bit RGB color,
     there are 8 bits per pixel (* 3 channels == 24 bits).

   SCDATATYPE Illustration
     Suppose type is SC_RGB, and bpp is 8.  In this case channels must be 3
     (because type is SC_RGB), and the data is 24 bit per pixel color data.

     Further suppose that our image data consists of 4 rows of 4 pixels each.
     In the illustrations that follow, an R represents one byte of red data, a
     G represents one byte of green data, and a B represents one byte of blue
     data.  The value of packing affects the layout of the image data as
     folows:

   packing == SC_PACKPIX
     In this case, the pixel values for each channel will be together in each
     row.

          RGBRGBRGBRGB
          RGBRGBRGBRGB
          RGBRGBRGBRGB
          RGBRGBRGBRGB


   packing == SC_BANDED
     In this case, the red, green and blue channels of pixel data will be
     separated by row.

          RRRR
          GGGG
          BBBB
          RRRR
          GGGG
          BBBB
          RRRR
          GGGG
          BBBB
          RRRR
          GGGG
          BBBB


   packing == SC_PACKPLANE
     All the red data for the entire image is first, followed by all the green
     data, followed by all the blue data.

          RRRR
          RRRR
          RRRR
          RRRR
          RRRR
          GGGG
          GGGG
          GGGG
          GGGG
          BBBB
          BBBB
          BBBB
          BBBB
          BBBB

   Data Type Conventions
     Scanner applications need not be written to support all possible data
     types.  There are four basic data types that are typically used:

          Monochrome:
          packing == SC_PACKPIX
          channels == 1
          type == SC_MONO
          bpp == 1


     ALL scanner drivers MUST support Monochrome format.

          8 Bit Greyscale:
          packing == SC_PACKPIX
          channels == 1
          type == SC_GREY
          bpp == 8


     All scanner drivers that support any kind of greyscale or color output
     MUST support 8 Bit Greyscale format.

     For color output, there are two possible situations when dealing with
     well-behaved scanner drivers.  One is that the red, green, and blue
     channels are scanned in three seperate passes; in this case, the data
     type is:

          Planar 24 bit RGB color:
          packing == SC_PACKPLANE
          channels == 3
          type == SC_RGB
          bpp == 8


     The other situation is a one-pass color scanner that gets all of the data
     in one pass.  The data type for color data from this kind of scanner is:

          Packed 24 bit RGB color:
          packing == SC_PACKPIX
          channels == 3
          type == SC_RGB
          bpp == 8


     A scanning application that is prepared to deal with these four data
     types should be able to interact well with any well-behaved scanner
     driver.

     For information on setting the data type for scanning, see SCSetup(3).

RETURN VALUE
     SCGetDataTypes returns 0 if successful.  If an error occurs, -1 is
     returned and SCerrno is set to indicate the reason for failure.

EXECUTION ERROR CODES
     SCGetDataTypes will fail under the following circumstances.

     SCEDEV                   Scanner driver error

     SCECOMM                  Error communicating with scanner driver

WARNING
     The memory pointed to by *dt after a call to SCGetDataTypes belongs to
     libscan(3) and should not be modified by the calling program.  Nor should
     any assumptions be made about its values after subsequent calls to
     SCGetDataTypes; in other words, it should be copied to memory owned by
     the calling program before future calls to SCGetDataTypes.

SEE ALSO
     libscan(3), SCOpen(3), SCSetup(3).