diff --git a/_static/css/custom.css b/_static/css/custom.css index b8e3adf..2e614fc 100644 --- a/_static/css/custom.css +++ b/_static/css/custom.css @@ -58,3 +58,21 @@ div#network-protocol table.docutils td { margin: 0px; line-height: 0px; } + +/* Changebar-like re-styling of attention directives. */ +.rst-content .attention .admonition-title { + display: none; +} + +.rst-content .attention { + margin: 0; + margin-left: -8px; + padding: 0; + padding-left: 6px; + border-left: 2px solid; + background: none; +} + +.rst-content .attention p:last-child { + margin-bottom: 24px; +} diff --git a/api.rst b/api.rst index f9eec8b..cbcd3af 100644 --- a/api.rst +++ b/api.rst @@ -3,17 +3,19 @@ The SANE Application Programmer Interface (API) =============================================== -This Section defines version 1 of the SANE application -programmer interface (API). Any SANE frontend must depend on the -interface defined in this section only. Converseley, any SANE backend -must implement its functionality in accordance with this specification. -The interface as documented here is declared as a C callable interface -in a file called ``sane/sane.h``. This file should -normally be included via a C pre-processor directive of the form: +.. attention:: - :: + This Section defines version 2 of the SANE application + programmer interface (API). Any SANE frontend must depend on the + interface defined in this section only. Converseley, any SANE backend + must implement its functionality in accordance with this specification. + The interface as documented here is declared as a C callable interface + in a file called ``sane/sane-2.h``. This file should + normally be included via a C pre-processor directive of the form: - #include + :: + + #include .. _sec:saneversioncode: @@ -330,20 +332,30 @@ legible string. Device Descriptor Type ~~~~~~~~~~~~~~~~~~~~~~ -Each SANE device is represented by a structure of type -:type:`SANE_Device`. The C declaration of this type -is given below. +.. attention:: - :: + Each SANE device is represented by a structure of type + :type:`SANE_Device`. The C declaration of this type + is given below. - typedef struct - { - SANE_String_Const name; - SANE_String_Const vendor; - SANE_String_Const model; - SANE_String_Const type; - } - SANE_Device; + :: + + typedef struct + { + SANE_String_Const name; + SANE_String_Const vendor; + SANE_String_Const model; + SANE_String_Const type; + SANE_String_Const email_backend_author; + SANE_String_Const backend_website; + SANE_String_Const device_location; + SANE_String_Const comment; + SANE_String_Const reserved_string; + SANE_Int backend_version_code; + SANE_Int backend_capablity_flags; + SANE_Int reserved_int; + } + SANE_Device; .. index:: device-name @@ -358,7 +370,7 @@ is *recommended* that backends keep unique names below 32 characters in length. However, applications *must* be able to cope with arbitrary length unique names. -The remaining members in the device structure provide additional +The next three members in the device structure provide additional information on the device corresponding to the unique name. Specifically, members :member:`vendor`, :member:`model`, and :member:`type` are single-line @@ -435,6 +447,52 @@ virtual devices that have no physical vendor associated. Also, there are no predefined model name strings since those are vendor specific and therefore completely under control of the respective backends. +.. attention:: + + The backend has to set up the string :member:`email_backend_author` + with the name and the email address of the backend author or a + contact person in the format: + + .. code-block:: none + + Firstname Lastname + + The string :member:`backend_website` has to be set up by the + backend with the website or ftp address of the backend in the + format: + + .. code-block:: none + + http://www.domain.org/sane-hello/index.html + + The backend should fill the string :member:`device_location` with a + text that describes where a user can find this device, the text + should be read from the backend config file. This could e.g. look + like this: + + .. code-block:: none + + building 93, 2nd plane, room 2124 + + The string :member:`comment` can be used to display any comment to + the user, the text should be read from the backend config file. + + The string :member:`reserved_string` is planed for future use, the + backend has to set this string to ``""``. + + With member :member:`backend_version_code` a frontend can find out + the version of a backend it is connected to via one or more meta + backends. + + The member :member:`backend_capability_flags` contains 32 bits that + are planned to give the backend the chance to inform the frontend + about its capabilities. The meaning of the flags will be defined + when there is the need for it. The backend has to set all not + defined bits (in the moment all 32 bits) to 0. + + The member :member:`reserved_int` is planned for future use, the + backend has to set the value of the integer to 0. + .. index:: SANE_Option_Descriptor .. _sec:odesc: @@ -752,6 +810,104 @@ in :numref:`tab:constraints`. | | | value. | +----------------------------------------+------+--------------------------------------------------------------------------------+ +.. _sec:i18n: + +Internationalization +~~~~~~~~~~~~~~~~~~~~ + +.. attention:: + + All backend texts should be written in english. Localization + (translation of backend texts) has to be done in the frontend. To + automatically prepare translation tables (e.g. english to german) + it is necessary to mark the texts that shall be translated. + +How is a text marked for translation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. attention:: + + The keyword :macro:`SANE_I18N` is used to mark a text for + translation. :macro:`SANE_I18N` has to be defined as a dummy + prototype: + + :: + + #ifndef SANE_I18N + # define SANE_I18N(text) text + #endif + + You should not mark prototypes or variables with :macro:`SANE_I18N` + because it is not possible (or very hard) to find out the texts + that are covered by prototypes + (:math:`\verb|SANE_I18N|(\verb|START_SCAN_TEXT|)`) and variables + (:math:`\verb|SANE_I18N|(\verb|option[7].name|)`). + + A correct marked text can look like this: + + :: + + snprintf(buf, sizeof(buf), SANE_I18N("Start scan") + + or + + :: + + #define START_SCAN_TEXT SANE_I18N("Start scan") + + It also is allowed to mark texts in structs because the prototype + :macro:`SANE_I18N` has no effect to the compiler. + +Which texts shall be marked for translation? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. attention:: + + All option texts that are visible for the user should be marked for + translation. This is: + + - member :member:`title` + - member :member:`desc` + - member :member:`string_list` + + of :type:`SANE_Option_Descriptor`. + + It is not allowed to mark/translate member :member:`name`. Please + also do not mark any error or debug messages that are displayed by + the backend. + +File formats and translation functions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. attention:: + + The recommended file formats for translation tables are the + :file:`po` files and :file:`mo` or :file:`gmo` files. The po file + contains the original text marked with the keyword :token:`msgid` + and the translated text marked with the keyword :token:`msgstr`. A + :file:`po` file that contains all needed :token:`msgid`'s can be + created e.g. by the gnu gettext tool :program:`xgettext` with the + option :option:`-k SANE_I18N`. The translator adds the translated + texts to the :file:`po` files. The gettext tool :program:`msgfmt` + converts the :file:`po` files to the :file:`mo` or :file:`gmo` + files. + + Translation is done in the frontend. A backend has nothing to do + with the translation of texts. The frontend should use the + function :func:`gettext()` to translate the texts. This e.g. can + look like this: + + :: + + snprintf(buf, sizeof(buf), gettext("english text")); + + If a frontend author decides to use translation functions that need + different translation tables, then the frontend is responsible to + create/convert the translation tables. In this case it should use + the :file:`po` files to create its own translation tables from it. + + Note that it is strongly recommended to use the gettext tools. + Operations ---------- @@ -868,6 +1024,12 @@ insufficient amount of memory is available. be specified explicitly by a user which would make it unnecessary and undesirable to call this function first. + .. attention:: + + The same information about + a device has to be returned when :func:`sane_open` is called. + + .. index:: sane_open :func:`sane_open` @@ -876,13 +1038,25 @@ insufficient amount of memory is available. This function is used to establish a connection to a particular device. The name of the device to be opened is passed in argument :data:`name`. If the call completes successfully, a handle -for the device is returned in :data:`*h`. As a special case, +for the device is returned in :data:`*h`. + +.. attention:: + + The description of the device is returned in + :data:`**device_description`. This is the same description that is + returned in the list by :func:`sane_get_devices()`. The returned + data :data:`*h` and :data:`*device_description` is guaranteed to + remain unchanged and valid until a call to :func:`sane_close()` is + performed. + +As a special case, specifying a zero-length string as the device requests opening the first available device (if there is such a device). :: - SANE_Status sane_open (SANE_String_Const name, SANE_Handle * h); + SANE_Status sane_open (SANE_String_Const name, SANE_Handle * h, + const SANE_Device ** device_description); This function may fail with one of the following status codes. @@ -1056,7 +1230,9 @@ This function may fail with one of the following status codes. Access to the option has been denied due to insufficient or invalid authentication. + .. index:: sane_get_parameters +.. _sec:sanegetparameters: :func:`sane_get_parameters` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1085,85 +1261,266 @@ The scan parameters are returned in a structure of type :type:`SANE_Parameters`. The C declaration of this structure is given below. - :: +.. attention:: - 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; + :: -.. index:: SANE_Frame + typedef struct + { + SANE_Frame format; + SANE_int flags; + SANE_Int lines; + SANE_Int depth; + SANE_Int pixels_per_line; + SANE_Int bytes_per_line; + SANE_Int channels_per_image; + SANE_String format_desc; + SANE_String proposed_filename; + SANE_Int dpi_x; + SANE_Int dpi_y; + char reserved[32]; /* 32 bytes for future use */ + } + SANE_Parameters; -Member :member:`format` specifies the format of the next frame -to be returned. The possible values for type -:type:`SANE_Frame` are described in -:numref:`tab:frameformat`. The meaning of these values is -described in more detail in Section :numref:`sec:imageformat`. + .. index:: SANE_Frame -.. tabularcolumns:: |\X{8}{32}|r|l| -.. table:: Frame Format (:type:`SANE_Frame`) - :name: tab:frameformat - :align: center + Member :member:`format` specifies the format of the next frame + to be returned. The possible values for type + :type:`SANE_Frame` are described in + :numref:`tab:frameformat`. The meaning of these values is + described in more detail in Section :numref:`sec:imageformat`. - +-----------------------------+------+-----------------------------------------+ - | Symbol | Code | Description | - +=============================+======+=========================================+ - | .. macro:: SANE_FRAME_GRAY | 0 | Band covering human visual range. | - +-----------------------------+------+-----------------------------------------+ - | .. macro:: SANE_FRAME_RGB | 1 | Pixel-interleaved red/green/blue bands. | - +-----------------------------+------+-----------------------------------------+ - | .. macro:: SANE_FRAME_RED | 2 | Red band of a red/green/blue image. | - +-----------------------------+------+-----------------------------------------+ - | .. macro:: SANE_FRAME_GREEN | 3 | Green band of a red/green/blue image. | - +-----------------------------+------+-----------------------------------------+ - | .. macro:: SANE_FRAME_BLUE | 4 | Blue band of a red/green/blue image. | - +-----------------------------+------+-----------------------------------------+ + .. tabularcolumns:: |\X{8}{32}|r|c|l| + .. table:: Frame Format (:type:`SANE_Frame`) + :name: tab:frameformat + :align: center -Member :member:`last_frame` is set to -:macro:`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). + +-----------------------------+------+---------------+-----------------------------------------+ + | Symbol | Code | SANE standard | Description | + +=============================+======+===============+=========================================+ + | .. macro:: SANE_FRAME_GRAY | 0 | version 1 | Band covering human visual range. | + +-----------------------------+------+---------------+-----------------------------------------+ + | .. macro:: SANE_FRAME_RGB | 1 | version 1 | Pixel-interleaved red/green/blue bands. | + +-----------------------------+------+---------------+-----------------------------------------+ + | .. macro:: SANE_FRAME_RED | 2 | version 1 | Red band of a red/green/blue image. | + +-----------------------------+------+---------------+-----------------------------------------+ + | .. macro:: SANE_FRAME_GREEN | 3 | version 1 | Green band of a red/green/blue image. | + +-----------------------------+------+---------------+-----------------------------------------+ + | .. macro:: SANE_FRAME_BLUE | 4 | version 1 | Blue band of a red/green/blue image. | + +-----------------------------+------+---------------+-----------------------------------------+ + | .. macro:: SANE_FRAME_RAW | 5 | version 2 | Arbitrary pixel property transmission. | + +-----------------------------+------+---------------+-----------------------------------------+ + | .. macro:: SANE_FRAME_MIME | 6 | version 2 | Data described by a mime descriptor. | + +-----------------------------+------+---------------+-----------------------------------------+ -Member :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 :func:`sane_read()` -until it returns a status of :macro:`SANE_STATUS_EOF`. + The :member:`flags` member is a 32 bit bitfield, for which up to now 4 + informational bits are defined, all unused bits have to be set to 0: -Member :member:`bytes_per_line` specifies the number of bytes -that comprise one scan line. + - .. macro:: SANE_PFLAG_LAST_FRAME -Member :member:`depth` specifies the number of bits per -sample. + (bit 0, bitvalue 1) is set to 1 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). Note, that it is possible to transmit + multiple images in succession. -Member :member:`pixels_per_line` specifies the number of -pixels that comprise one scan line. + - .. macro:: SANE_PFLAG_MORE_IMAGES -Assume :math:`B` is the number of channels in the frame, then the bit -depth :math:`d` (as given by member :member:`depth`) and the -number of pixels per line :math:`n` (as given by this member -:member:`pixels_per_line`) are related to :math:`c`, the -number of bytes per line (as given by member -:member:`bytes_per_line`) as follows: + (bit 1, bitvalue 2) is set to 1 to indicate further pending + images. It is permissible to set that value to 1 "in good + faith", as it has to be determined at a very early time, where + it might not be detectable, if there actually are more images + to transfer. E.g. you will usually not know if the document + feeder contains further pages when starting to scan the current + one. Thus you are allowed to set that bit but later fail at + :func:`sane_start()`. -.. math:: + - .. macro:: SANE_PFLAG_NEW_PAGE - c >= \left\{ - \begin{array}{ll} - \lceil B\cdot n / 8\rceil & \mbox{if $d=1$}\\ - B\cdot n \cdot \lceil (d + 7)/8 \rceil & \mbox{if $d>1$} - \end{array} - \right. + (bit 2, bitvalue 4) is set to 1 to indicate that the current + frame comes from a new physical page. This bit is of + informational character only to help frontends to group + multi-image scans. -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. + - .. macro:: SANE_PFLAG_BACKSIDE + + (bit 3, bitvalue 8) tells if the current image was acquired + from the front (0) or backside (1) of the currently processed + sheet. It is of informational character and allows to group and + order multi-image transfers regardless of scanner acquisition + order (front first/back first). + + Note, that :member:`flags` is compatible to member + :member:`last_frame` of :type:`SANE_Parameters` of SANE standard + version 1 (same size and only bit 0 (bitvalue 1) was used with same + function). + + Member :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 :func:`sane_read()` + until it returns a status of :macro:`SANE_STATUS_EOF`. + Note, that even when transferring formats that have this + information inband, it is recommended to set that member, if + available. If unavailable or not applicable, set to -1 as mentioned + above. + + Member :member:`bytes_per_line` specifies the number of bytes + that comprise one scan line. + If :member:`bytes_per_line` is set to 0, which can currently only + be the case for :macro:`SANE_FRAME_MIME`, the frontend shall not + assume a constant line length. Instead it should simply try to read + until :macro:`SANE_STATUS_EOF` with an arbitrary block length. + + Member :member:`depth` specifies the number of bits per + sample. + Note, that only 0 (for not applicable), 1, and n*8 are allowed + values. Data with other depths has to be scaled up accordingly. + + Member :member:`pixels_per_line` specifies the number of + pixels that comprise one scan line. + + Assume :math:`B` is the number of channels in the frame, then the bit + depth :math:`d` (as given by member :member:`depth`) and the + number of pixels per line :math:`n` (as given by this member + :member:`pixels_per_line`) are related to :math:`c`, the + number of bytes per line (as given by member + :member:`bytes_per_line`) as follows: + + .. math:: + + c >= \left\{ + \begin{array}{ll} + \lceil B\cdot n / 8\rceil & \mbox{if $d=1$}\\ + B\cdot n \cdot \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. + + Member :member:`channels_per_image` specifies the number of + channels the image consists of. When the image is transmitted in + more than one frame :member:`channels_per_image` has to be the same + for all frames for this image. + + Member :member:`format_desc` is used for the new frametypes + :macro:`SANE_FRAME_RAW` and :macro:`SANE_FRAME_MIME`. Its meaning + differs between the two types: + + - .. macro:: SANE_FRAME_RAW + + The :member:`format_desc` contains a description of the channel + data and an optional depth information separated by a colon(:). + + A plane is descibed by one channel, e.g. "``gray``" or + "``gray:12``". + + Channel interleaved data is described by a comma separated list + of channel descriptions, for example "``red,green,blue``" or + "``red:8,green:8,blue:8``", the channel data is sent in the + given order. + + The depth information does **not** define the size of the + transmitted channel data, it is only an information for the + frontend. The channel data has to be sent in the size defined + by member :member:`depth`. + + Well known channels are ``red``, ``green``, ``blue`` and + ``gray``. It also is allowed to use other channel + descriptions, e.g. if you use an infrared camera or scanner it + could be ``infrared`` or a wavelength description like + ``1100nm``, but be aware that a frontend may not be able to + display such channels with useful colors. + + Note that an image can be sent in single planes, in one + interleaved frame that contains all channels or in several + frames that contain one or more (interleaved) channels. When an + RGB image is sent it is prefered to send the image data in one + interleaved frame that consist of red, green and blue data in + this order. The number of channels is defined in member + :member:`channels_per_image`. + + - .. macro:: SANE_FRAME_MIME + + The :member:`format_desc` contains the MIME type/subtype + :samp:`*(;${parameter})` fields as described in RFC + 1521, 4. The Content-Type header field, without the prefixing + “Content-Type:”. Note, that it is discouraged to transfer + proprietary file formats over SANE. If at all possible, please + stick to the IANA assigned MIME types, and make sure the data + stream is compliant with the corresponding specification. When + data is transmitted with the frame type + :macro:`SANE_FRAME_MIME` all data has to be transmitted within + one frame, multiple frames are not allowed (so the flag + :member:`last_frame` has to be set when using this frame type). + A fully compliant SANE backend is required to transmit in + either SANE native frametypes, or in a MIME type, for which a + converting meta backend exists and is freely available for all + platforms. + + Other formats may be transmitted, but the only thing the + average frontend can do with them, is save them. This is not + considered a good option, as it does not facilitate + transmitting the data to a client application that may be + running the frontend. However, if the data transferred by the + backend is not an image in nature, it wouldn't make sense to + try converting it anyway, so it is acceptable to use a simple + :macro:`SANE_FRAME_MIME` transfer for that case. But even then, + try to stick to well known stuff with freely existing standards + and viewers as well. + + The member :member:`proposed_filename` can be used to suggest a + reasonable default filename or -extension in case the backend can + make such a suggestion, like e.g. an image database. If no such + suggestion is intended, set the field to ``""``. + + In the case of raw frames, :member:`proposed_filename` is expected + to hold the basename for the image, with the extension determined + by the save function of the frontend, as the frontend can fully + understand the data and is thus able to encode it in any format it + wishes. + + For MIME frames :member:`proposed_filename` can contain either: + + - A name with a leading dot, which is considered to be a proposed + filename extension. This could also be gotten from the mime + database, but for systems lacking it, this might be + convenient. Or: + + - A complete filename, including extension. + + Note, that for frontends that are able to parse a given MIME type + internally, it is perfectly permissible to ignore the extension + part of the proposed filename and only make use of the basename, + when using internal save algorithms for different formats. + + In any case, if the frontend makes use of this field, the frontend + must mangle this proposal or the final filename it produces with + its help to suit local filesystem restrictions. + + Special care should be taken not to cause security flaws this way. + For Unix, that means killing out all path separators (/) [to avoid + to save away stuff in obscure places or create critical files like + /etc/hosts.allow] and avoiding to overwrite existing files. + (Creating of leading dot files - like .rhosts - is not an issue here, + because that's only a proposed filename extension as mentioned above. + + The string :member:`proposed_comment` can be used to transmit + additional image data, that can be stored in the comment areas + several fileformats offer. It can contain any textual information + the backend wishes to convey to the user, like date/time of + exposure, enganged filters, etc. + + The members :member:`dpi_x`, :member:`dpi_y` encode the horizontal + and vertical resolution. Note, that multiple-image scans may have + different resolutions of each image. It is not permissible to + change resolution between frames of the same image. + + The member :member:`reserved` is an array of 32 bytes (char) to + keep the size of the struct unchanged when future extensions are + done. The backend has to set the reserved bytes to 0. .. index:: sane_start @@ -1228,6 +1585,10 @@ succeeds, the number of bytes returned can be anywhere in the range from SANE_Status sane_read (SANE_Handle h, SANE_Byte * buf, SANE_Int maxlen, SANE_Int * len); +For efficiency reasons, medium to large +block sizes (in the range of a few kilobytes) should be used. +Returning short reads is allowed to allow for small buffers +in the backend. If this function is called when no data is available, one of two things may happen, depending on the I/O mode that is in effect for handle :data:`h`. @@ -1251,6 +1612,8 @@ This function may fail with one of the following status codes. :macro:`SANE_STATUS_EOF`: No more data is available for the current frame. + If :func:`sane_read` sends back any image data it + is not allowed to return with :macro:`SANE_STATUS_EOF`. :macro:`SANE_STATUS_JAMMED`: The document feeder is jammed. @@ -1441,7 +1804,7 @@ available options at the beginning and then build a dialog (either graphical or a command-line oriented option list) that allows to control the available options. It should be noted that the number of options is fixed for a given handle. However, as options are set, other options may -become active or inactive. Thus, after setting an option, it maybe +become active or inactive. Thus, after setting an option, it may be necessary to re-read some or all option descriptors. While setting up the device, it is also admissible to call :func:`sane_get_parameters()` to get an estimate of what the @@ -1466,37 +1829,138 @@ select-style interface is desired, the frontend may attempt to call functions may fail if the backend does not support the requested operation. -Image data is collected by repeatedly calling -:func:`sane_read()`. Eventually, this function will return -an end-of-file status (:macro:`SANE_STATUS_EOF`). This -indicates the end of the current frame. If the frontend expects -additional frames (e.g., the individual channels in of a red/green/blue -image or multiple images), it can call :func:`sane_start()` -again. Once all desired frames have been acquired, function -:func:`sane_cancel()` must be called. This operation can -also be called at any other time to cancel a pending operation. Note -that :func:`sane_cancel()` must be called even if the last -read operation returned :macro:`SANE_STATUS_EOF`. +.. attention:: -When done using the device, the handle should be closed by a call to -:func:`sane_close()`. Finally, before exiting the -application, function :func:`sane_exit()` must be called. It -is important not to forget to call this function since otherwise some -resources (e.g., temporary files or locks) may remain unclaimed. + Image data is collected by repeatedly calling + :func:`sane_read()` until this function will return + an end-of-file status (:macro:`SANE_STATUS_EOF`). This + indicates the end of the current frame. If the frontend expects + additional frames (e.g., the individual channels of a red/green/blue + image or multiple images), it can call :func:`sane_start()` + again. + If the :macro:`SANE_PFLAG_LAST_FRAME` bit is set in + :member:`flags`, the current image is complete. In this case, it + should be tested, if :member:`flags` has the + :member:`SANE_PFLAG_MORE_IMAGES` bit set. If yes, further calls to + :func:`sane_start()` can be made to acquire more images. Please + note, that as this bit has to be set at the beginning of a the + transmission of the last frame before the new image, it is + possible, that no reliable decision can be made at this time. It is + thus permissible for a backend to set this bit, and then later at + the actual call to :func:`sane_start()` return an error like + :macro:`SANE_STATUS_NO_DOCS`. Such a sequence is permitted to + transmit multiple images from a single page as well as multiple + pages. This behaviour should be controlled by backend options as + required, to allow single-page scanning as well as + ADF-batch-scanning. The frontend should always continue reading all + images until a frame with :macro:`SANE_PFLAG_LAST_FRAME` on and + :macro:`SANE_PFLAG_MORE_IMAGES` off is encountered, or an error + other than :macro:`SANE_STATUS_EOF` occurs in a SANE function. + Note that :macro:`SANE_STATUS_NO_DOCS` also is an allowed way for + the backend to indicate the end of a multiple image scan. + + A frontend may choose to skip frames (e.g. because it cannot parse + them), which is accomplished by simply calling :func:`sane_start()` + again, which will get you to the next frame, without having to read + and discard the current one. + + In order to prematurely stop scanning and to reset the backend + state, :func:`sane_cancel()` can be called at any time. This call + is required as well after normal termination of a multiple image + scan as described above. + + When done using the device, the handle should be closed by a call to + :func:`sane_close()`. Finally, before exiting the + application, function :func:`sane_exit()` must be called. It + is important not to forget to call this function since otherwise some + resources (e.g., temporary files or locks) may remain unclaimed. + + The following C sample code implements a reference loop for acquiring + multiple images: + + :: + + SANE_Parameters parms; + SANE_Status status; + + do + { + do + { + /* Now start acquiring the next frame. */ + status=sane_start(handle); + + /* if that failed, we have a problem, and no more frames can be + * read at this time. Due to SANE_PFLAG_MORE_IMAGES still + * being clear, this will break out of _BOTH_ loops. + */ + if (status != SANE_STATUS_GOOD) break; + + /* Now let us see what the next frame brings. */ + status=sane_get_parameters(handle,&parms); + + /* This actually should not fail, but maybe the doc feeder + * jammed or something, so we break as well, if something + * is wrong. + */ + if (status != SANE_STATUS_GOOD) break; + + /* Now we check the announced parameters, if we can make use + * of the frame data. If not, we skip over to the next frame. + */ + if ( do_i_like_that(&parms) == NO ) continue; + + /* Set up for reading the data here. Mangle filenames, + * allocate memory, rewind multiframe files, ask user + * for confirmation, ... + */ + setup_for_transfer(...); + + /* Now we read in the frame data and process it. This should + * return SANE_STATUS_GOOD, until the frame is complete, + * what causes SANE_STATUS_EOF to be returned. + */ + while( SANE_STATUS_GOOD == ( status=sane_read(...) ) ) + read_in_and_process_data_as_required(); + + /* If transfer was broken due to anything but EOF, break out. */ + if (status != SANE_STATUS_EOF) { + break; + } + + /* Now loop until we have all frames of an image. */ + } while(!(parms.flag & SANE_PFLAG_LAST_FRAME)); + + /* O.K. - we now have a complete image. Fit it together, save it, + * flush buffers, transmit it, increment filenames, etc. + */ + /* Now check for more pending images. If we have more, redo from start. + * Some backends might cheat here and send us for an extra round which + * will fail at sane_start, as they were not able to determine if they + * would have more data at the start of the last frame we read. + */ + } while(parms.flags & SANE_PFLAG_MORE_IMAGES); + + /* No more data. Fine. Reset the backend and go back to option-control + * loop. + */ + + sane_cancel(handle); .. index:: well known options Well-Known Options ------------------ -While most backend options are completely self-describing, there are a +While most backend options are completely self-describing, there are cases where a user interface might want to special-case the handling of certain options. For example, the scan area is typically defined by four options that specify the top-left and bottom-right corners of the area. With a graphical user interface, it would be tedious to force the user to type in these four numbers. Instead, most such interfaces will want -to present to the user a preview (low-resolution scan) of the scanner -surface and let the user pick the scan area by dragging a rectangle into +to present to the user a preview (low-resolution scan of the full scanner +surface or a high(er) resolution scan of a subpart of the scanner +surface) and let the user pick the scan area by dragging a rectangle into the desired position. For this reason, the SANE API specifies a small number of option names that have well-defined meanings. @@ -1517,17 +1981,26 @@ of option number 0. .. index:: scan resolution, resolution option -Scan Resolution Option -~~~~~~~~~~~~~~~~~~~~~~ +Scan Resolution Options +~~~~~~~~~~~~~~~~~~~~~~~ -Option ``resolution`` is used to select the resolution -at which an image should be acquired. The type of this option is either -:macro:`SANE_TYPE_INT` or -:macro:`SANE_TYPE_FIXED`. The unit is -:macro:`SANE_UNIT_DPI` (dots/inch). +.. attention:: -This option is not mandatory, but if a backend does support it, it must -implement it in a manner consistent with the above definition. + Option ``resolution`` is used to select the resolution + at which an image should be acquired. + When the backend wants to allow different + values for x- and y-resolution it has to define the options + ``x_resolution`` and ``y_resolution``. Note that only the option + ``resolution`` **or** the options ``x_resolution`` **and** + ``y_resolution`` may be active. + + The type of this option is either + :macro:`SANE_TYPE_INT` or + :macro:`SANE_TYPE_FIXED`. The unit is + :macro:`SANE_UNIT_DPI` (dots/inch). + + This option is not mandatory, but if a backend does support it, it must + implement it in a manner consistent with the above definition. .. index:: preview mode @@ -1548,6 +2021,11 @@ backend is free to override the ``resolution`` value with its own choice for preview mode, but it is advised to leave this choice to the frontend wherever possible. +.. attention:: + + When the ``preview`` option is set the backend should transfer the + image in frame type :macro:`SANE_FRAME_RAW` if possible. + This option is not mandatory, but if a backend does support it, it must implement it in a manner consistent with the above definition. @@ -1618,6 +2096,357 @@ regarding these options: - A frontend must work properly with any or all of these options missing. +.. attention:: + + - A frontend may temporarily set the values in a way that ``tl-x`` + is larger than ``br-x`` and ``tl-y`` is larger than ``br-y``. + +.. index:: bit depth option + +Depth option +~~~~~~~~~~~~ + +.. attention:: + + Option ``depth`` is used to select the image depth in bits/sample + in multi bit mode - (this means for 24 bit RGB mode this value must + be 8). The type of this option is :macro:`SANE_TYPE_INT`. The + unit is :macro:`SANE_UNIT_BIT`. For 1 bit modes (Lineart or + Halftone) this option has to be inactive. For selection of 1 bit + modes (Lineart or Halftone) the backend should use the well-known + option ``mode``. + + This option is not mandatory, but if a backend does support it, it + must implement it in a manner consistent with the above definition. + +.. index:: gamma table options + +Gamma table options +~~~~~~~~~~~~~~~~~~~ + +.. attention:: + + The ``gamma-table`` option defines a :macro:`SANE_CONSTRAINT_RANGE` + of the type :macro:`SANE_TYPE_INT` which represents the gamma + correction table for gray. In color mode the ``gamma-table`` may + be used to set a common gamma correction for red, green and + blue. The options ``red-gamma-table``, ``green-gamma-table`` and + ``blue-gamma-table`` are used in color mode to set a gamma + correction for each color separately. In color mode the backend is + free to use only the ``gamma-table`` option, only the ``red-``, + ``green-`` and ``blue-gamma-table`` or all four options. When all + four options are used then the color tables should do a gamma + correction with the same input and output bit depth and the gray + gamma table should reduce (if necessary) the bit depth from the + scanner internal bit depth to the output bit depth. This should + e.g. look like this: + + :: + + red_value = gamma-table(red-gamma-table(value)) + green_value = gamma-table(green-gamma-table(value)) + blue_value = gamma-table(blue-gamma-table(value)) + + The backend should not use the gamma tables to emulate other + functions or options like highlight, shadow, contrast, brightness, + threshold, analog_gamma. These functions are common for all + backends and should be added to the frontend or a meta-backend. + + This option is not mandatory, but if a backend does support it, it + must implement it in a manner consistent with the above definition. + +.. index:: mode options + +Scan Mode options +~~~~~~~~~~~~~~~~~ + +.. attention:: + + The option ``mode`` defines a :macro:`SANE_CONSTRAINT_STRING_LIST` + of type :macro:`SANE_TYPE_STRING`. + It is used to select the scanmode (e.g. Color or Gray). + Well known modes are: ``Color``, ``Gray``, ``Halftone`` + and ``Lineart``. ``Color`` and ``Gray`` are multi bit + modes (8 or 16 bits/sample), ``Halftone`` and ``Lineart`` + are single bit modes. + + This way a frontend can select e.g the mode ``Gray`` + for scanning a fax. + + This option is not mandatory, but if a backend does support it, it + must implement it in a manner consistent with the above definition. + +.. index:: source options + +Scan Source options +~~~~~~~~~~~~~~~~~~~ + +.. attention:: + + The option ``source`` is used to select the scan source + (e.g. Automatic Document Feeder). It defines a + :macro:`SANE_CONSTRAINT_STRING_LIST` of type + :macro:`SANE_TYPE_STRING`. Well known sources are: ``Flatbed``, + ``Transparancy Adapter`` and ``Automatic Document Feeder``. + + This option is not mandatory, but if a backend does support it, it + must implement it in a manner consistent with the above definition. + +.. index:: threshold option + +Threshold +~~~~~~~~~ + +.. attention:: + + The option ``threshold`` is used to define the threshold for + Lineart and maybe Halftone mode. In multi bit modes this option + should be set inactive. The type of this option is + :macro:`SANE_TYPE_FIXED`. The unit is + :macro:`SANE_UNIT_PERCENT`. The value range should be + :math:`0.0\ldots100.0` if possible. It defines the minimum + intensity to get a white point / full intensity (image data bit = + 0). The backend has to scale the values in the following way: + + A value of 0.0 means all pixels get white /full intensity (all + image data bits are 0). A value of 50.0 means intensities + brighter than medium gray get white / full intensity (bit 0). A + value of 100.0 means all pixels get black (all image data bits + are 1). If the scanner is not able to cover the full range the + backend has to define a reduced value range + (e.g. :math:`30\ldots70` percent). + + This option is not mandatory, but if a backend does support it, it + must implement it in a manner consistent with the above definition. + +.. index:: analog gamma option + +Analog gamma +~~~~~~~~~~~~ + +.. attention:: + + The option ``analog-gamma`` is used to define the gamma value for + an analog gamma function of the scanner in multi bit modes. In 1 + bit modes this option should be set inactive. The type of this + option is :macro:`SANE_TYPE_FIXED`. The unit is + :macro:`SANE_UNIT_NONE`. The value range can be defined by the + backend as supported. The values have to be positive. A gamma value + of 1.0 means that the gamma correction has no effect. A value + larger than 1.0 increases the brightness of the image. In color + mode there also can be options ``analog-gamma-red``, + ``analog-gamma-green`` and ``analog-gamma-blue``. It is not + allowed to emulate an analog gamma function by a digital gamma + table. The backend has to disable (or not define) this option when + the scanner does not support an analog (hardware) gamma function. + + When analog gamma, highlight and shadow functions are available at + the same time then the backend author has to care about the order + in which the functions are implemented in the scanner hardware. + The SANE standard expects that changing the analog gamma value has + no effect on the shadow and highlight function. When the analog + gamma function is executed in the scanner hardware before the + shadow and highlight functions then the backend should do a + compensation. For this the shadow and highlight values have to be + gamma corrected with the relevant analog gamma value. + + This option is not mandatory, but if a backend does support it, it + must implement it in a manner consistent with the above definition. + +.. index:: shadow options + +Shadow +~~~~~~ + +.. attention:: + + The option ``shadow`` is used to define the shadow level / black + point level. The type of this option is :macro:`SANE_TYPE_FIXED`. + The unit is :macro:`SANE_UNIT_PERCENT`. The value range should be + :math:`0.0\ldots100.0` if possible. It is used to define the + maximum intensity level that creates an image data value of 0 + (black). The backend has to scale the values in the following way: + + A value of 0.0 means that the sensitivity range is not reduced, + only the minimum intensity produces an image data value of 0 + (black). A value of 50.0 means that that a medium intensity + and everything that is darker produces an image data value of 0 + (black). A value of 100.0 means the sensitivity range is + reduced to 0, all image data values are 0 (black). If the + scanner is not able to cover the full range the backend has to + define a reduced value range (e.g. :math:`30\ldots70` percent). + In color mode there can be options ``shadow-red``, + ``shadow-green`` and ``shadow-blue``, in this case the + ``shadow`` function has to be disabled. It is not allowed to + emulate a shadow function by a digital gamma table. The backend + has to disable (or not define) this option when the scanner + does not support an analog (hardware) shadow function. + + This option is not mandatory, but if a backend does support it, it + must implement it in a manner consistent with the above definition. + +.. index:: hightlight options + +Highlight +~~~~~~~~~ + +.. attention:: + + The option ``highlight`` is used to define the highlight level / + white point level. The type of this option is + :macro:`SANE_TYPE_FIXED`. The unit is + :macro:`SANE_UNIT_PERCENT`. The value range should be + :math:`0.0\ldots100.0` if possible. It is used to define the + minimum intensity level that creates the maximum possible image + data value (white/full intensity). The backend has to scale the + values in the following way: + + A value of 0.0 means the sensitivity range is reduced to 0, all + image data have maximum value (white / full intensity). A + value of 50.0 means that a medium intensity and everything that + is brighter produces the maximum possible image data value + (white / full intensity). A value of 100.0 means that the + sensitivity range is not reduced, only the maximum intensity + produces an image data with maximum possible value (white / + full intensity). If the scanner is not able to cover the full + range the backend has to define a reduced value range + (e.g. :math:`30\ldots70` percent). In color mode there can be + options ``highlight-red``, ``highlight-green`` and + ``highlight-blue``, in this case ``highlight`` has to be + disabled. It is not allowed to emulate a highlight function by + a digital gamma table. The backend has to disable (or not + define) this option when the scanner does not support an analog + (hardware) highlight function. + + This option is not mandatory, but if a backend does support it, it + must implement it in a manner consistent with the above definition. + +.. index:: lamp-on option +.. index:: lamp-off option + +Turn lamp on and off +~~~~~~~~~~~~~~~~~~~~ + +.. attention:: + + The option ``lamp-on`` is used to turn the lamp of the scanner on. + The type of this option is :macro:`SANE_TYPE_BUTTON`. The unit is + :macro:`SANE_UNIT_NONE`. When the option is set then the lamp of + the scanner is turned on. + + The option ``lamp-off`` is used to turn the lamp of the scanner + off. The type of this option is :macro:`SANE_TYPE_BUTTON`. The + unit is :macro:`SANE_UNIT_NONE`. When the option is set then the + lamp of the scanner is turned off. + + These options are not mandatory, but if a backend does support + them, it must implement them in a manner consistent with the above + definition. + +.. index:: scanner button options + +Scanner buttons +~~~~~~~~~~~~~~~ + +.. attention:: + + Some scanners have buttons which state can be read by the scanner + driver. It is necessary to implement a locking function for the + buttons because it is possible that several frontends try to + connect to the same backend/scanner at the same time. Imagine what + could happen when no locking would be implemented: + + Five people have started a scanning application which is + connected via network to the scanner you want to use. You start + a frontend, put a paper to the scanner and press the + scan-button on the scanner. The scanner does scan three times + (because three frontends asked the button status when you + pressed the button). For three people the image is saved to the + harddisk, but it is not sure that your frontend did scan the + image. + + A backend that does make available the scanner-buttons has to + implement the following options: + + - ``scanner-buttons-lock`` is of type :macro:`SANE_TYPE_BOOL`, + default = :macro:`SANE_FALSE` + - ``scanner-buttons-status`` is of type :macro:`SANE_TYPE_INT`, + default = 0 + - ``scanner-buttons-status-update`` is of type + :macro:`SANE_TYPE_BUTTON` + + When setting these options the backend does not set + :macro:`SANE_INFO_RELOAD_OPTIONS` or + :macro:`SANE_INFO_RELOAD_PARAMS` if not explictly defined. + + A frontend has to disable the usage of the scanner-buttons by + default. This is important because other frontends will not be able + to use the buttons when the button-functions are locked. Another + important thing is that some scanners do not turn off their lamp + when the driver does frequently talk to the scanner (what is done + when reading the button status from the scanner). + + - A frontend that wants to read the button status has to lock the + button functions at first. For this it does set the option + ``scanner-buttons-lock`` to :macro:`SANE_TRUE`. While setting + the value of option ``scanner-buttons-lock`` to + :macro:`SANE_TRUE` the backend does check if a lockfile + (e.g. "backend"-buttons.lock) does exist. The lockfile has to be + placed in a directory where every user has read and write access + to. + + - If the lockfile does not exist then the backend creates the + lockfile and writes the process ID (PID) of the backend to the + file. Button access is allowed: the value of option + ``scanner-buttons-lock`` is set to :macro:`SANE_TRUE` + - If the file does exist and the backend PID is not the file PID + then the backend has to check if the process with the PID + stored in the lockfile still is running. If yes then the button + access is not allowed: the value of option + ``scanner-buttons-lock`` is set to :macro:`SANE_FALSE`. If not + then the lockfile is recreated and the PID of the backend is + stored in the lockfile, button access is allowed: the value of + option ``scanner-buttons-lock`` is set to :macro:`SANE_TRUE` + + - The frontend does read the value of option + ``scanner-buttons-lock``. If it is :macro:`SANE_TRUE` then the + frontend has access to the scanner buttons. If it is + :macro:`SANE_FALSE` then access has been denied. + + - If the button access is allowed the frontend has to do the + following about once per second (while not scanning): + + - The frontend does set option ``scanner-buttons-status-update``. + The backend checks if access to the buttons is allowed by + comparing the backend PID with the lockfile PID. If access is + allowed it does read the button status from the scanner and + stores it in the option ``scanner-buttons-status``, each bit + represents a button, a value of 0 means the button is not + pressed, a value of 1 means that the button is pressed. When + the scanner is busy the backend must not wait, it has to return + immedeatly and the button state keeps unchanged. The backend + has to implement a timeout function. When no button has been + pressed within a predefined time (e.g. 15 minutes) then the + access permission is lost. In this case the backend does set + option ``scanner-buttons-lock`` to :macro:`SANE_FALSE` and does + set :macro:`SANE_INFO_RELOAD_OPTIONS` to inform the frontend + that it has lost permission to access the scanner-button + functions. If access is not allowed it does set the + ``scanner-buttons-status`` to 0. + + - The frontend does read the value of option + ``scanner-buttons-status`` + + - When the frontend does exit or it does not want to use the + buttons it does set option ``scanner-buttons-lock`` to + :macro:`SANE_FALSE`. The backend does check if the backend PID + and the lockfile PID are the same. If this is true then it + removes the lockfile and sets the value of + ``scanner-buttons-lock`` to :macro:`SANE_FALSE`. + + :func:`sane_close()` should do the same as setting option + ``scanner-buttons-lock`` to :macro:`SANE_FALSE`. + .. [1] This is different from ANSI C where any non-zero integer value represents logical TRUE. diff --git a/conf.py b/conf.py index d50dbb4..294665d 100644 --- a/conf.py +++ b/conf.py @@ -20,7 +20,7 @@ import os project = 'SANE Standard' copyright = '' author = '' -version = 'Version 1.03' +version = 'Version 2.0 proposal 0.07 - rauch/beck' release = version # -- General configuration --------------------------------------------------- @@ -53,7 +53,7 @@ numfig_format = { 'section': '%s' } -today_fmt = '2002-10-10' +today_fmt = 'Dec 5, 2002' highlight_language = 'c' @@ -83,5 +83,13 @@ latex_documents = [ latex_elements = { 'papersize': 'a4paper', - 'releasename': '\!' # suppress default with negative thin space + 'releasename': '\!', # suppress default with negative thin space + # Attention directives are abused to inject changebar environments. + 'preamble': r''' +\usepackage{changebar} +\setlength{\changebarwidth}{1pt} +\setcounter{changebargrey}{10} +\renewenvironment{sphinxattention}[1] + {\begin{changebar}}{\end{changebar}} +''' } diff --git a/contact.rst b/contact.rst index 34fe4c2..4d0a426 100644 --- a/contact.rst +++ b/contact.rst @@ -9,7 +9,7 @@ The SANE standard is discussed and evolved via a mailing list. Anybody with email access to the Internet can automatically join and leave the discussion group by sending mail to the following address. - mailto:sane-devel-request@mostang.com + mailto:majordomo@mostang.com To subscribe, send a mail with the body “``subscribe sane-devel``” to the above address. diff --git a/environment.rst b/environment.rst index e06c542..752675a 100644 --- a/environment.rst +++ b/environment.rst @@ -127,17 +127,9 @@ the time this standard was created. A SANE image is a rectangular area. The rectangular area is subdivided into a number of rows and columns. At the intersection of each row and -column is a quadratic pixel. A pixel consists of one or more sample +column is a (preferable quadratic) pixel. A pixel consists of one or more sample values. Each sample value represents one channel (e.g., the red -channel). Each sample value has a certain bit depth. The bit depth is -fixed for the entire image and can be as small as one bit. Valid bit -depths are 1, 8, or 16 bits per sample. If a device’s natural bit depth -is something else, it is up to the driver to scale the sample values -appropriately (e.g., a 4 bit sample could be scaled by a factor of four -to represent a sample value of depth 8). - -Image Transmission -~~~~~~~~~~~~~~~~~~ +channel). The SANE API transmits an image as a sequence of frames. Each frame covers the same rectangular area as the entire image, but may contain @@ -148,13 +140,58 @@ transmitted as a sequence of three frames: the first frame containing the red channel, the second the green channel, and the third the blue channel. -Conceptually, each frame is transmitted a byte at a time. Each byte may +When transmitting an image frame by frame, the frontend needs to know what +part of the image a frame represents (and how many frames it should expect). +For that purpose, the SANE API tags every frame with a type and a format +descriptor. + +.. attention:: + + There are two different types of frames: pixel oriented frames + :macro:`SANE_FRAME_RAW` and arbitrary data frames + :macro:`SANE_FRAME_MIME`. These types are discussed in detail in + the following sections. The frame types used by version 1 of this + standard :macro:`SANE_FRAME_GRAY`, :macro:`SANE_FRAME_RGB`, + :macro:`SANE_FRAME_RED`, :macro:`SANE_FRAME_GREEN`, and + :macro:`SANE_FRAME_BLUE`) are obsolete and superseded by + :macro:`SANE_FRAME_RAW`. + +Pixel oriented frames +~~~~~~~~~~~~~~~~~~~~~ + +.. attention:: + + The type of pixel oriented frames is :macro:`SANE_FRAME_RAW`. The + frame contains one or more channels of data in a + channel-interleaved format, that represents sample values from a + property of the individual pixels that is subject to further + description in the :member:`format_desc` member of the + :type:`SANE_Parameters` structured type. See section + :numref:`sec:sanegetparameters` for details about the format + descriptions. + +Each sample value has a certain bit depth. The bit depth is +fixed for the entire image and can be as small as one bit. Valid bit +depths are 1, 8, or 16 bits per sample. If a device's natural bit depth +is something else, it is up to the driver to scale the sample values +appropriately (e.g., a 4 bit sample could be scaled by a factor of four +to represent a sample value of depth 8). + +.. attention:: + + The complete image may consist of several different channels. The + number of channels is defined by member :member:`channels_per_image` + of :type:`SANE_Parameters`. The image may be transmitted in an + arbitary number of frames which can be determined by watching the + :macro:`SANE_PFLAG_LAST_FRAME` flag in said type (or by counting the + channels). Note: This frame type replaces all frame types of the SANE + standard version 1. + +Conceptually, each pixel oriented frame is transmitted a byte at a time. Each byte may contain 8 sample values (for an image bit depth of 1), one full sample value (for an image bit depth of 8), or a partial sample value (for an image bit depth of 16 or bigger). In the latter case, the bytes of each sample value are transmitted in the machine’s native byte order. -For depth 1, the leftmost pixel is stored in the most significant bit, -and the rightmost pixel in the least significant bit. **Backend Implementation Note** @@ -183,63 +220,44 @@ orientation (as it would be displayed on a screen, for example). If a frame contains multiple channels, then the channels are transmitted in an interleaved fashion. :numref:`fig:pixels` illustrates this for the case where a frame contains a complete -red/green/blue image with a bit-depth of 8. For a bit depth of 1, each -byte contains 8 sample values of a *single* channel. In other words, a -bit depth 1 frame is transmitted in a byte interleaved fashion. +red/green/blue image with a bit-depth of 8. .. figure:: figs/image-data.* :name: fig:pixels :scale: 80% :align: center - Bit and byte order or image data + Bit and byte order of image data -When transmitting an image frame by frame, the frontend needs to know -what part of the image a frame represents (and how many frames it should -expect). For that purpose, the SANE API tags every frame with a type. -This version of the SANE standard supports the following frame types: +For a bit depth of 1, each byte contains 8 sample values of a *single* +channel. In other words, a bit depth 1 frame is transmitted in a byte +interleaved fashion. The first sample of each byte is represented by +the most significant bit. - :macro:`SANE_FRAME_GRAY`: - The frame contains a single channel of data that represents - sample values from a spectral band that covers the human visual - range. The image consists of this frame only. +.. attention:: - :macro:`SANE_FRAME_RGB`: - The frame contains three channels of data that represent sample - values from the red, green, and blue spectral bands. The sample - values are interleaved in the order red, green, and blue. The - image consists of this frame only. + For gray channels at a bit depth of 1 only two sample values are + possible: 1 represents minimum intensity (black) and 0 represents + maximum intensity (white). For all other channel types and bit + depths a sample value of 0 represents minimum intensity and larger + values represent increasing intensity. - :macro:`SANE_FRAME_RED`: - The frame contains one channel of data that represents sample - values from the red spectral band. The complete image consists - of three frames: :macro:`SANE_FRAME_RED`, - :macro:`SANE_FRAME_GREEN`, and - :macro:`SANE_FRAME_BLUE`. The order in which the - frames are transmitted chosen by the backend. +Arbitrary data frames +~~~~~~~~~~~~~~~~~~~~~ - :macro:`SANE_FRAME_GREEN`: - The frame contains one channel of data that represents sample - values from the green spectral band. The complete image consists - of three frames: :macro:`SANE_FRAME_RED`, - :macro:`SANE_FRAME_GREEN`, and - :macro:`SANE_FRAME_BLUE`. The order in which the - frames are transmitted chosen by the backend. +.. attention:: - :macro:`SANE_FRAME_BLUE`: - The frame contains one channel of data that represents sample - values from the blue spectral band. The complete image consists - of three frames: :macro:`SANE_FRAME_RED`, - :macro:`SANE_FRAME_GREEN`, and - :macro:`SANE_FRAME_BLUE`. The order in which the - frames are transmitted chosen by the backend. + It also is possible to transmit arbitrary (not necessaryly pixel + oriented) data. This allows transmission of compressed images like + jpeg, tiff, etc. -In frames of type :macro:`SANE_FRAME_GRAY`, when the bit depth is 1 there are -only two sample values possible, 1 represents minimum intensity -(black) and 0 represents maximum intensity (white). For all other bit -depth and frame type combinations, a sample value of 0 represents -minimum intensity and larger values represent increasing intensity. - -The combination of bit depth 1 and :macro:`SANE_FRAME_RGB (or -:macro:`SANE_FRAME_RED`, :macro:`SANE_FRAME_GREEN`, :macro:`SANE_FRAME_BLUE`) -is rarely used and may not be supported by every frontend. + The type of arbitrary data frames is :macro:`SANE_FRAME_MIME`. The + frame contains arbitrary data of the MIME (see RFC 1521/1522) type + that is given in the :member:`format_desc` member of the + :type:`SANE_Parameters` structured type (see See section + :numref:`sec:sanegetparameters`). As such, it is assumed to be + incomprehensible to the frontend, except for selected types the + frontend is specifically capable of handling internally. The + frontend is free to ignore those frames, or employ any appropriate + means to otherwise handle this data (like saving them to disk or + spawning an external viewer). diff --git a/preface.rst b/preface.rst index 071b14d..ef52f28 100644 --- a/preface.rst +++ b/preface.rst @@ -39,3 +39,8 @@ Typographic Conventions Changes since the last revision of this document are highlighted like this: + +.. attention:: + + Paragraphs that changed since the last revision of the documention + are marked like this paragraph.