From 59f6af51b858340139fe2139e2698fef8a5ad62f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Fonseca?= Date: Wed, 9 Dec 2009 10:59:38 +0000 Subject: [PATCH] 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! --- src/gallium/auxiliary/util/u_format.h | 36 +++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/src/gallium/auxiliary/util/u_format.h b/src/gallium/auxiliary/util/u_format.h index 6740683a618..19b902db983 100644 --- 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 };