[sane-devel] Byte ordering

Sat Jun 7 20:04:00 BST 2025

Hi,

On Sat, Jun 7, 2025 at 11:58 AM Kelly Price <strredwolf at gmail.com> wrote:

> I would recommend referencing said document in the relevant API
> documents.  Something along the lines of "Bytes in each sample value are
> transmitted in the machine's native byte order per the 'SANE Environment'
> document."  That way if someone skips that document initially, they'll go
> back to it.
>
>
> Both sections are in the same document. There *is* a reference to the
Image Format section in the description of the sane_get_parameters()
function. It might be useful to also add a reference to the sane_read()
function definition as well.

Cheers,
Ralph

>
> On Sat, Jun 7, 2025 at 2:54 PM Ralph Little <skelband at gmail.com> wrote:
>
>> Hi,
>> So I was looking through the SANE API specification and there *is* some
>> guidance on byte order. It is just separated from the function definitions.
>> In the section "The SANE Environment":
>> https://sane-project.gitlab.io/standard/environment.html#sec-imageformat
>>
>> "In the latter case, the bytes of each sample value are transmitted in
>> the machine’s native byte order."
>>
>> So I guess that settles that.
>>
>> Cheers,
>> Ralph
>>
>> On Wed, Jun 4, 2025 at 9:28 AM Ralph Little <skelband at gmail.com> wrote:
>>
>>> Hi,
>>> Thanks, I will check that out.
>>>
>>> Cheers,
>>> Ralph
>>>
>>> On Wed, Jun 4, 2025 at 9:25 AM m. allan noah <kitno455 at gmail.com> wrote:
>>>
>>>> A quote from fujitsu.c that seems relevant:
>>>>
>>>> *
>>>>  * @@ Section 5 - SANE cleanup functions
>>>>  */
>>>> /*
>>>>  * Cancels a scan.
>>>>  *
>>>>  * It has been said on the mailing list that sane_cancel is a bit of a
>>>>  * misnomer because it is routinely called to signal the end of a
>>>>  * batch - quoting David Mosberger-Tang:
>>>>  *
>>>>  * > In other words, the idea is to have sane_start() be called, and
>>>>  * > collect as many images as the frontend wants (which could in turn
>>>>  * > consist of multiple frames each as indicated by frame-type) and
>>>>  * > when the frontend is done, it should call sane_cancel().
>>>>  * > Sometimes it's better to think of sane_cancel() as "sane_stop()"
>>>>  * > but that name would have had some misleading connotations as
>>>>  * > well, that's why we stuck with "cancel".
>>>>  *
>>>>  * The current consensus regarding duplex and ADF scans seems to be
>>>>  * the following call sequence: sane_start; sane_read (repeat until
>>>>  * EOF); sane_start; sane_read...  and then call sane_cancel if the
>>>>  * batch is at an end. I.e. do not call sane_cancel during the run but
>>>>  * as soon as you get a SANE_STATUS_NO_DOCS.
>>>>  *
>>>>  * From the SANE spec:
>>>>  * This function is used to immediately or as quickly as possible
>>>>  * cancel the currently pending operation of the device represented by
>>>>  * handle h.  This function can be called at any time (as long as
>>>>  * handle h is a valid handle) but usually affects long-running
>>>>  * operations only (such as image is acquisition). It is safe to call
>>>>  * this function asynchronously (e.g., from within a signal handler).
>>>>  * It is important to note that completion of this operaton does not
>>>>  * imply that the currently pending operation has been cancelled. It
>>>>  * only guarantees that cancellation has been initiated. Cancellation
>>>>  * completes only when the cancelled call returns (typically with a
>>>>  * status value of SANE_STATUS_CANCELLED).  Since the SANE API does
>>>>  * not require any other operations to be re-entrant, this implies
>>>>  * that a frontend must not call any other operation until the
>>>>  * cancelled operation has returned.
>>>>  */
>>>>
>>>>
>>>> On Wed, Jun 4, 2025 at 12:06 PM Ralph Little <skelband at gmail.com>
>>>> wrote:
>>>>
>>>>> Hi,
>>>>> BTW, just on that note, something that has bothered me is that the
>>>>> SANE API specification doesn't make the ADF multi-page scanning process
>>>>> super clear in terms of result codes, sequence etc. I will perhaps also
>>>>> review that section to see if additional detail could be added to make it
>>>>> more concrete.
>>>>>
>>>>> Any changes I propose, I will offer them up here for review before
>>>>> updating the document.
>>>>>
>>>>> Cheers,
>>>>> Ralph
>>>>>
>>>>> On Wed, Jun 4, 2025 at 9:02 AM Ralph Little <skelband at gmail.com>
>>>>> wrote:
>>>>>
>>>>>> Hi,
>>>>>> OK, I will draft something up for the standard.
>>>>>>
>>>>>> If there is anything else to update the standard with, perhaps people
>>>>>> could let me know.
>>>>>> Just to be clear, I am not changing the interface with this update,
>>>>>> just adding come clarification, so if anybody feels that there is anything
>>>>>> else unclear in the standard, they should possibly raise it now.
>>>>>>
>>>>>> I will add address this on the weekend.
>>>>>>
>>>>>> Cheers,
>>>>>> Ralph
>>>>>>
>>>>>> On Wed, Jun 4, 2025 at 8:57 AM m. allan noah <kitno455 at gmail.com>
>>>>>> wrote:
>>>>>>
>>>>>>> Makes sense to me.
>>>>>>>
>>>>>>> On Wed, Jun 4, 2025 at 10:12 AM Ralph Little <skelband at gmail.com>
>>>>>>> wrote:
>>>>>>>
>>>>>>>> Hi,
>>>>>>>>
>>>>>>>> On Tue, Jun 3, 2025 at 11:36 PM <sane-devel at symme.link> wrote:
>>>>>>>>
>>>>>>>>> On Tue, Jun 03, 2025 at 10:00:45PM -0700, Ralph Little wrote:
>>>>>>>>> > On Tue, Jun 3, 2025 at 9:54 PM James Ring <sjr at jdns.org> wrote:
>>>>>>>>> > > On Tue, Jun 3, 2025 at 9:46 PM Ralph Little <
>>>>>>>>> skelband at gmail.com> wrote:
>>>>>>>>> > >> Someone has asked the question about byte order in multi-byte
>>>>>>>>> image data
>>>>>>>>> > >> that we might get from a SANE backend.
>>>>>>>>>
>>>>>>>>> Hi, it's me, I had the question.
>>>>>>>>>
>>>>>>>>> > >> It is not enough to assume the local machine byte order since
>>>>>>>>> we may get
>>>>>>>>> > >> data through the net backend from a remote machine with a
>>>>>>>>> different byte
>>>>>>>>> > >> order.
>>>>>>>>>
>>>>>>>>> The `net` backend explicitly swaps to local machine byte order:
>>>>>>>>>
>>>>>>>>> https://gitlab.com/sane-project/backends/-/blob/master/backend/net.c?ref_type=heads#L2356-2362
>>>>>>>>>
>>>>>>>>> So, it does seem like the de facto standard is that backends
>>>>>>>>> produce
>>>>>>>>> data in local machine byte order.
>>>>>>>>>
>>>>>>>>> (The protocol documentation reinforces this as a standard:
>>>>>>>>>
>>>>>>>>
>>>>>>>> Agreed. Perhaps this is something we should add to the SANE API
>>>>>>>> specification?
>>>>>>>> Allan, do you concur?
>>>>>>>>
>>>>>>>> Cheers,
>>>>>>>> Ralph
>>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> --
>>>>>>> "well, I stand up next to a mountain- and I chop it down with the
>>>>>>> edge of my hand"
>>>>>>>
>>>>>>
>>>>
>>>> --
>>>> "well, I stand up next to a mountain- and I chop it down with the edge
>>>> of my hand"
>>>>
>>>
>
> --
> Kelly "STrRedWolf" Price
> http://redwolf.ws
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://alioth-lists.debian.net/pipermail/sane-devel/attachments/20250607/3bdaf83b/attachment-0001.htm>