From 63aeff49c1088a8b1b75ecd846ebdf22469250f7 Mon Sep 17 00:00:00 2001
From: Nicolas Silva <nsilva@mozilla.com>
Date: Wed, 28 Feb 2024 08:15:40 +0000
Subject: [PATCH] Bug 1882318 - Add some documentation to quad shaders.
 r=gfx-reviewers,gw

Differential Revision: https://phabricator.services.mozilla.com/D202831
---
 gfx/wr/webrender/res/ps_quad.glsl          | 28 ++++++++++++++++++++++
 gfx/wr/webrender/res/ps_quad_mask.glsl     |  2 ++
 gfx/wr/webrender/res/ps_quad_textured.glsl |  2 ++
 3 files changed, 32 insertions(+)

diff --git a/gfx/wr/webrender/res/ps_quad.glsl b/gfx/wr/webrender/res/ps_quad.glsl
index 0919ec047e8c..94c80a93f70f 100644
--- a/gfx/wr/webrender/res/ps_quad.glsl
+++ b/gfx/wr/webrender/res/ps_quad.glsl
@@ -2,12 +2,40 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+/// The common infrastructure for ps_quad_* shaders.
+///
+/// # Memory layout
+///
+/// The diagram below shows the the various pieces of data fectched in the vertex shader:
+///
+///```ascii
+///                                       (int gpu buffer)
+///                                       +---------------+    (sGpuCache)
+///  (instance-step vertex attr)          |  Int header   |   +-----------+
+/// +-----------------------------+       |               |   | Transform |
+/// |    Quad instance (uvec4)    |  +--> | transform id +--> +-----------+
+/// |                             |  |    | z id          |
+/// | x: int prim address        +---+    +---------------+   (float gpu buffer)
+/// | y: float prim address      +--------------------------> +-----------+--------------+-+-+
+/// | z: quad flags               |      (sGpuCache)          | Quad Prim | Quad Segment | | |
+/// |    edge flags               |   +--------------------+  |           |              | | |
+/// |    part index               |   |     Picture task   |  | bounds    | rect         | | |
+/// |    segment index            |   |                    |  | clip      | uv rect      | | |
+/// | w: picture task address    +--> | task rect          |  | color     |              | | |
+/// +-----------------------------+   | device pixel scale |  +-----------+--------------+-+-+
+///                                   | content origin     |
+///                                   +--------------------+
+///```
+
 #define WR_FEATURE_TEXTURE_2D
 
 #include shared,rect,transform,render_task,gpu_buffer
 
 flat varying mediump vec4 v_color;
 flat varying mediump vec4 v_uv_sample_bounds;
+// x: (in ps_quad_textured) has edge flags
+// y: has uv rect
+// z: (in ps_quad_textured) sample as mask
 flat varying lowp ivec4 v_flags;
 varying highp vec2 v_uv;
 
diff --git a/gfx/wr/webrender/res/ps_quad_mask.glsl b/gfx/wr/webrender/res/ps_quad_mask.glsl
index a8ba032a7021..6b72714efbf1 100644
--- a/gfx/wr/webrender/res/ps_quad_mask.glsl
+++ b/gfx/wr/webrender/res/ps_quad_mask.glsl
@@ -2,6 +2,8 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+/// This shader applies a (rounded) rectangle mask to the content of the framebuffer.
+
 #include ps_quad,ellipse
 
 varying highp vec4 vClipLocalPos;
diff --git a/gfx/wr/webrender/res/ps_quad_textured.glsl b/gfx/wr/webrender/res/ps_quad_textured.glsl
index 48579eb4fe35..2382623cdb9a 100644
--- a/gfx/wr/webrender/res/ps_quad_textured.glsl
+++ b/gfx/wr/webrender/res/ps_quad_textured.glsl
@@ -2,6 +2,8 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+/// This shader renders solid colors or simple images in a color or alpha target.
+
 #include ps_quad
 
 #ifndef SWGL_ANTIALIAS