[Mesa-dev] [PATCH 1/4] i965/guardband: Improve comments for guardband clipping

[Ben Widawsky]

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.
---
 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;
-- 
2.0.3