i965: Document brw_context.state.depth_region

Reviewed-by: Kenneth Graunke <[email protected]>
Signed-off-by: Chad Versace <[email protected]>

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 f3312360213..4b4dfbafb1a 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 92eba8fe173..74e911b4ddb 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,