util: Document the meaning of util_format_layout.

The util_format_layout name was unfortunate and there
are  as been a lot of confusion due to this. Hopefully
this will shed some light on what it was meant for.

Bottom line is: do not rely on these values unless
you're automatically code generating pixel
packing/unpacking routines.

Suggestions for better names than util_format_layout
are welcome!

diff --git a/src/gallium/auxiliary/util/u_format.h b/src/gallium/auxiliary/util/u_format.h
index 6740683a618405eefaf4f2eef70fc1f398f82fa1..19b902db98332190a74824b605d51c188e1c5c6e 100644 (file)
--- a/src/gallium/auxiliary/util/u_format.h
+++ b/src/gallium/auxiliary/util/u_format.h
@@ -33,10 +33,46 @@
 #include "pipe/p_format.h"
 
 
+/**
+ * Describe how to best pack/unpack pixels into/from the prescribed format.
+ *
+ * These are used for automatic code generation of pixel packing and unpacking
+ * routines (in compile time, e.g., u_format_access.py, or in runtime, like
+ * llvmpipe does).
+ *
+ * Thumb rule is: if you're not code generating pixel packing/unpacking then
+ * these are irrelevant for you.
+ *
+ * Note that this can be deduced from other values in util_format_description
+ * structure. This is by design, to make code generation of pixel
+ * packing/unpacking/sampling routines simple and efficient.
+ *
+ * XXX: This should be renamed to something like util_format_pack.
+ */
 enum util_format_layout {
+   /**
+    * Single scalar component.
+    */
    UTIL_FORMAT_LAYOUT_SCALAR = 0,
+
+   /**
+    * One or more components of mixed integer formats, arithmetically encoded
+    * in a word up to 32bits.
+    */
    UTIL_FORMAT_LAYOUT_ARITH = 1,
+
+   /**
+    * One or more components, no mixed formats, each with equal power of two
+    * number of bytes.
+    */
    UTIL_FORMAT_LAYOUT_ARRAY = 2,
+
+   /**
+    * XXX: Not used yet. These might go away and be replaced by a single entry,
+    * for formats where multiple pixels have to be
+    * read in order to determine a single pixel value (i.e., block.width > 1
+    * || block.height > 1)
+    */
    UTIL_FORMAT_LAYOUT_YUV = 3,
    UTIL_FORMAT_LAYOUT_DXT = 4
 };