Merge branch 'master' into pipe-format-simplify

Conflicts:
	src/gallium/auxiliary/draw/draw_pipe_aaline.c
	src/gallium/auxiliary/draw/draw_pipe_pstipple.c
	src/gallium/auxiliary/util/u_blit.c
	src/gallium/auxiliary/util/u_gen_mipmap.c
	src/gallium/auxiliary/util/u_surface.c
	src/gallium/auxiliary/vl/vl_mpeg12_mc_renderer.c
	src/gallium/drivers/cell/ppu/cell_texture.c
	src/gallium/drivers/llvmpipe/lp_texture.c
	src/gallium/drivers/r300/r300_emit.c
	src/gallium/drivers/r300/r300_texture.c
	src/gallium/drivers/softpipe/sp_texture.c
	src/gallium/drivers/softpipe/sp_tile_cache.c
	src/gallium/drivers/svga/svga_state_vs.c
	src/gallium/include/pipe/p_format.h
	src/gallium/state_trackers/dri/dri_drawable.c
	src/gallium/state_trackers/egl/egl_surface.c
	src/gallium/state_trackers/python/p_device.i
	src/gallium/state_trackers/python/st_softpipe_winsys.c
	src/gallium/state_trackers/vega/api_filters.c
	src/gallium/state_trackers/vega/image.c
	src/gallium/state_trackers/vega/mask.c
	src/gallium/state_trackers/vega/paint.c
	src/gallium/state_trackers/vega/renderer.c
	src/gallium/state_trackers/vega/vg_tracker.c
	src/gallium/state_trackers/xorg/xorg_crtc.c
	src/gallium/state_trackers/xorg/xorg_dri2.c
	src/gallium/state_trackers/xorg/xorg_exa.c
	src/gallium/state_trackers/xorg/xorg_renderer.c
	src/gallium/state_trackers/xorg/xorg_xv.c
	src/gallium/state_trackers/xorg/xvmc/surface.c
	src/gallium/winsys/drm/nouveau/drm/nouveau_drm_api.c
	src/gallium/winsys/drm/radeon/core/radeon_buffer.c
	src/gallium/winsys/egl_xlib/sw_winsys.c
	src/gallium/winsys/g3dvl/xlib/xsp_winsys.c
	src/gallium/winsys/gdi/gdi_llvmpipe_winsys.c
	src/gallium/winsys/gdi/gdi_softpipe_winsys.c
	src/gallium/winsys/xlib/xlib_cell.c
	src/gallium/winsys/xlib/xlib_llvmpipe.c
	src/gallium/winsys/xlib/xlib_softpipe.c
	src/mesa/state_tracker/st_cb_fbo.c
	src/mesa/state_tracker/st_cb_texture.c
	src/mesa/state_tracker/st_texture.c

1 files changed, 36 insertions, 0 deletions

diff --git a/src/gallium/auxiliary/util/u_format.h b/src/gallium/auxiliary/util/u_format.h
index db1297fa1ec..f5e8eec0450 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
 };