wrote up docs for scan/pane example

jowens · jowens · commit 9189eedc57d7 · 2025-10-18T15:24:31.000-07:00
diff --git a/examples/scan_pane_example.html b/examples/scan_pane_example.html
@@ -3,15 +3,100 @@
 <html>
   <head>
     <meta charset="utf-8" />
-    <title>Standalone WebGPU Scan/Reduce Primitive Test, with Configuration Pane</title>
+    <title>
+      Standalone WebGPU Scan/Reduce Primitive Test, with Configuration Pane
+    </title>
+    <link
+      rel="stylesheet"
+      href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/default.min.css"
+    />
   </head>
 
   <body>
-    <div id="instructions">
-      <p>Set your parameters in the pane and click "Start" to run and validate a WebGPU scan/reduce.</p>
-    </div>
-    <script src="scan_pane_example.mjs" type="module"></script>
-    <div id ="webgpu-results"></div>
+    <p>
+      This example is a self-contained use of the <code>scan</code> and
+      <code>sort</code> primitives. Gridwise's scan encapsulates an exclusive
+      scan, an inclusive scan, and a reduce. (A simpler scan-only example is
+      <a href="scan_example">here</a>.) Set your parameters in the pane and
+      click "Start" to run and validate a WebGPU scan/reduce/sort.
+      <a
+        href="https://github.com/gridwise-webgpu/gridwise/blob/main/examples/scan_pane_example.mjs"
+        >The entire JS source file is in github.</a
+      >
+      While the entire file contains substantial WebGPU and input-output setup
+      boilerplate, the important parts follow.
+    </p>
+    <p>
+      The pane selects several parameters, here listed with default settings:
+    </p>
+    <pre><code class="language-javascript">const params = {
+  /* defaults */
+  primitive: "exclusive",
+  datatype: "u32",
+  binop: "add",
+  direction: "ascending",
+  inputLength: 2 ** 20,
+};</code></pre>
+    <p>
+      Whenever you change a parameter, it triggers a call of
+      <code>buildAndRun</code>. This function initializes an input array and
+      sets up all WebGPU calls necessary to declare and run the primitive.
+      Depending on the selected primitive, we declare <code>primitive</code> as
+      either a sort or scan primitive:
+    </p>
+    <pre><code class="language-javascript">let primitive;
+switch (params.primitive) {
+  case "sort_keys":
+    primitive = new OneSweepSort({
+      device,
+      datatype: params.datatype,
+      direction: params.direction,
+      copyOutputToTemp: true,
+    });
+    break;
+  default:
+    primitive = new DLDFScan({
+      device,
+      binop: makeBinOp({ op: params.binop, datatype: params.datatype }),
+      type: params.primitive,
+      datatype: params.datatype,
+    });
+    break;
+  }</code></pre>
+    <p>
+      We have declared buffers (using WebGPU's
+      <code>device.createBuffer</code>). These are called
+      <code>memsrcBuffer</code> and <code>memdestBuffer</code>. We then call the
+      primitive's <code>execute</code> procedure (note that
+      <code>execute</code> is <code>async</code>, and that the names of the
+      arguments for <code>scan</code> and <code>sort</code> are different):
+    </p>
+    <pre><code class="language-javascript">  /* sort and scan have different arguments */
+switch (params.primitive) {
+  case "sort_keys":
+    await primitive.execute({
+      keysInOut: memsrcBuffer,
+      keysTemp: memdestBuffer,
+    });
+    break;
+  default:
+    await primitive.execute({
+      inputBuffer: memsrcBuffer,
+      outputBuffer: memdestBuffer,
+    });
+    break;
+}</code></pre>
+    <p>
+      We then read back the result from the GPU and validate it. Click "Start"
+      to run the selected primitive and the results should display below. The
+      developer console will show the input and output arrays.
+    </p>
+    <hr />
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
+    <script>
+      hljs.highlightAll();
     </script>
+    <script src="scan_pane_example.mjs" type="module"></script>
+    <div id="webgpu-results"></div>
   </body>
 </html>
