[Mesa-dev] [PATCH 2/4] i965: Document brw_context.state.depth_region

[chad at chad-versace.us]

From: Chad Versace <chad at chad-versace.us>

Signed-off-by: Chad Versace <chad at chad-versace.us>
---
 src/mesa/drivers/dri/i965/brw_context.h    |   21 ++++++++++++++++++++-
 src/mesa/drivers/dri/i965/brw_misc_state.c |    3 +++
 2 files changed, 23 insertions(+), 1 deletions(-)

diff --git a/src/mesa/drivers/dri/i965/brw_context.h b/src/mesa/drivers/dri/i965/brw_context.h
index ab0c78f..9af97b5 100644
--- a/src/mesa/drivers/dri/i965/brw_context.h
+++ b/src/mesa/drivers/dri/i965/brw_context.h
@@ -139,7 +139,7 @@ struct brw_context;
  * by any 3D rendering.
  */
 #define BRW_NEW_BATCH			0x10000
-/** brw->depth_region updated */
+/** \see brw.state.depth_region */
 #define BRW_NEW_DEPTH_BUFFER		0x20000
 #define BRW_NEW_NR_WM_SURFACES		0x40000
 #define BRW_NEW_NR_VS_SURFACES		0x80000
@@ -464,8 +464,27 @@ struct brw_context
    struct {
       struct brw_state_flags dirty;
 
+      /**
+       * \name Cached region pointers
+       *
+       * When the draw buffer is updated, often the depth buffer is not
+       * changed. Caching the pointer to the buffer's region allows us to
+       * detect when the buffer has in fact changed, and allows us to avoid
+       * updating the buffer's GPU state when it has not.
+       *
+       * The original of each cached pointer is an instance of
+       * \c intel_renderbuffer.region.
+       *
+       * \see brw_set_draw_region()
+       *
+       * \{
+       */
+
+      /** \see struct brw_tracked_state brw_depthbuffer */
       struct intel_region *depth_region;
 
+      /** \} */
+
       /**
        * List of buffers accumulated in brw_validate_state to receive
        * drm_intel_bo_check_aperture treatment before exec, so we can
diff --git a/src/mesa/drivers/dri/i965/brw_misc_state.c b/src/mesa/drivers/dri/i965/brw_misc_state.c
index 92eba8f..74e911b 100644
--- a/src/mesa/drivers/dri/i965/brw_misc_state.c
+++ b/src/mesa/drivers/dri/i965/brw_misc_state.c
@@ -284,6 +284,9 @@ static void emit_depthbuffer(struct brw_context *brw)
    }
 }
 
+/**
+ * \see brw_context.state.depth_region
+ */
 const struct brw_tracked_state brw_depthbuffer = {
    .dirty = {
       .mesa = 0,
-- 
1.7.4.2