[Mesa-dev] [PATCH 7/8] util: Expand the comment above the channel[] array

[Richard Sandiford]

Michel Dänzer <michel at daenzer.net> writes:
> On Die, 2013-06-11 at 16:26 +0100, Richard Sandiford wrote:
>> Signed-off-by: Richard Sandiford <rsandifo at linux.vnet.ibm.com>
>> ---
>>  src/gallium/auxiliary/util/u_format.h | 42 ++++++++++++++++++++++++++++++++++-
>>  1 file changed, 41 insertions(+), 1 deletion(-)
>> 
>> diff --git a/src/gallium/auxiliary/util/u_format.h b/src/gallium/auxiliary/util/u_format.h
>> index e4b9c36..db6c290 100644
>> --- a/src/gallium/auxiliary/util/u_format.h
>> +++ b/src/gallium/auxiliary/util/u_format.h
>> @@ -178,9 +178,49 @@ struct util_format_description
>>     unsigned is_mixed:1;
>>  
>>     /**
>> -    * Input channel description.
>> +    * Input channel description, in the order XYZW.
>>      *
>>      * Only valid for UTIL_FORMAT_LAYOUT_PLAIN formats.
>> +    *
>> +    * The general rule is that the order and layout of the channels is the
>> +    * same as they would be in a C struct:
>> +    *
>> +    * struct {
>> +    *    ...X...;
>> +    *    ...Y...;
>> +    *    ...Z...;
>> +    *    ...W...;
>> +    * };
>> +    *
>> +    * with bitfields being used for all integer channels.
>
> I'd advise against using the term 'bitfield', as the semantics of C
> bitfields are mostly up to the specific C implementation, and it will
> lure people into implicitly thinking of the semantics of bitfields in
> the C implementation they're using.

I got the impression that the bit order was fairly consistent in practice,
since there's usually a strong expectation that the first structure member
should be in the first byte.  But you're right of course.  How does this
look instead:

   /**
    * Input channel description, in the order XYZW.
    *
    * Only valid for UTIL_FORMAT_LAYOUT_PLAIN formats.
    *
    * Suppose the pixel value is treated as a single integer P.
    * The order of the channels within P depends on endianness:
    *
    * - On big-endian targets, the channels are ordered from the most
    *   significant end to the least significant end.  The most significant
    *   bit of P is the most significant bit of the first channel.  The least
    *   significant bit of P is the least significant bit of the last channel.
    *
    * - On little-endian targets, the channels are ordered from the least
    *   significant end to the most significant end.  The least significant
    *   bit of P is the least significant bit of the first channel.  The most
    *   significant bit of P is the most significant bit of the last channel.
    *
    * (This is the same as C bitfield layout on most ABIs.)
    *
    * This means that if some channels can be accessed as individual N-byte
    * values, the order of those channels in this array matches their order
    * in memory.  Each N-byte value has native endianness.
    *
    * If instead a group of channels is accessed as a single N-byte value,
    * the order of the channels within that value depends on endianness.
    * For big-endian targets, the first channel in the group will be
    * the most significant, otherwise it will be the least significant.
    *
    * For example, if X, Y, Z and W are all 8 bits, the memory order is:
    *
    * 0 1 2 3
    * X Y Z W
    *
    * regardless of endianness.  If instead the channels are 16 bits,
    * the memory order is:
    *
    *                 0  1  2  3  4  5  6  7
    *  little-endian: Xl Xu Yl Yu Zl Zu Wl Wu   (l = lower, u = upper)
    *  big-endian:    Xu Xl Yu Yl Zu Zl Wu Wl
    *
    * If X is 8 bits and Y is 24 bits, the memory order is:
    *
    *                 0  1  2  3
    *  little-endian: X  Yl Ym Yu    (l = lower, m = middle, u = upper)
    *  big-endian:    X  Yu Ym Yl
    *
    * If X is 5 bits, Y is 5 bits, Z is 5 bits and W is 1 bit, the layout is:
    *
    *                        0        1
    *                 msb  lsb msb  lsb
    *  little-endian: YYYXXXXX WZZZZZYY
    *  big-endian:    XXXXXYYY YYZZZZZW
    */

(Each version grows a new example :-))

Thanks,
Richard