Mesa (master): i965/guardband: Improve comments for guardband clipping

[Ben Widawsky]

Module: Mesa
Branch: master
Commit: 109d420f42b66224366f4604d1235204101abb37
URL:    http://cgit.freedesktop.org/mesa/mesa/commit/?id=109d420f42b66224366f4604d1235204101abb37

Author: Ben Widawsky <benjamin.widawsky at intel.com>
Date:   Fri Aug  1 20:28:07 2014 -0700

i965/guardband: Improve comments for guardband clipping

While working in this part of the code I had a great deal of trouble
understanding what it was trying to do, and matching it with the spec.
(mostly due bad wording in the PRM). To help future people, I've cleaned
up the wording and provided some ascii art.

Reviewed-by: Kenneth Graunke <kenneth at whitecape.org>
Reviewed-by: Chris Forbes <chrisf at ijw.co.nz>

---

 src/mesa/drivers/dri/i965/gen8_viewport_state.c |   22 ++++++++++++++++++----
 1 file changed, 18 insertions(+), 4 deletions(-)

diff --git a/src/mesa/drivers/dri/i965/gen8_viewport_state.c b/src/mesa/drivers/dri/i965/gen8_viewport_state.c
index b366246..b5171e0 100644
--- a/src/mesa/drivers/dri/i965/gen8_viewport_state.c
+++ b/src/mesa/drivers/dri/i965/gen8_viewport_state.c
@@ -71,10 +71,24 @@ gen8_upload_sf_clip_viewport(struct brw_context *brw)
        * maximum screen space coordinates of a small object may larger, but we
        * have no way to enforce the object size other than through clipping.
        *
-       * If you're surprised that we set clip to -gbx to +gbx and it seems like
-       * we'll end up with 16384 wide, note that for a 8192-wide render target,
-       * we'll end up with a normal (-1, 1) clip volume that just covers the
-       * drawable.
+       * The goal is to create the maximum sized guardband (8K x 8K) with the
+       * viewport rectangle in the center of the guardband. This looks weird
+       * because the hardware wants coordinates that are scaled to the viewport
+       * in NDC. In other words, an 8K x 8K viewport would have [-1,1] for X and Y.
+       * A 4K viewport would be [-2,2], 2K := [-4,4] etc.
+       *
+       * --------------------------------
+       * |Guardband                     |
+       * |                              |
+       * |         ------------         |
+       * |         |viewport  |         |
+       * |         |          |         |
+       * |         |          |         |
+       * |         |__________|         |
+       * |                              |
+       * |                              |
+       * |______________________________|
+       *
        */
       const float maximum_guardband_extent = 8192;
       float gbx = maximum_guardband_extent / ctx->ViewportArray[i].Width;