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

[Richard Sandiford]

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.
+    *
+    * 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 channel 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 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
     */
    struct util_format_channel_description channel[4];
 
-- 
1.7.11.7