add example with separate modules

maybe this would be better else where?
webgpu · Aug 22, 2023 · aaa8a7c · aaa8a7c
1 parent 5a2186b
commit aaa8a7c
Show file tree

Hide file tree

Showing 2 changed files with 224 additions and 2 deletions.
diff --git a/webgpu/lessons/webgpu-inter-stage-variables.md b/webgpu/lessons/webgpu-inter-stage-variables.md
@@ -234,13 +234,95 @@ select = (a, b, condition) => condition ? b : a;
 Even if you don't use `@builtin(position)` in a fragment shader, it's convenient
 that it's there because it means we can use the same struct for both a vertex
 shader and a fragment shader. What was important to takeaway is that the `position` struct
-field in the vertex shader vs the fragment shader is entire unrelated. They're
-entirely different variables.
+field in the vertex shader vs the fragment shader is entirely unrelated. They're
+completely different variables.
 
 As pointed out above though, for inter-stage variables, all that matters is the
 `@location(?)`. So, it's not uncommon to declare different structs for a vertex
 shader's output vs a fragment shaders input.
 
+To hopefully make this more clear, the fact that the vertex shader and
+fragment shader are in the same string in our examples it just a convenience.
+We could also split them into separate modules
+
+```js
+-  const module = device.createShaderModule({
+-    label: 'hardcoded checkerboard triangle shaders',
++  const vsModule = device.createShaderModule({
++    label: 'hardcoded triangle',
+    code: `
+      struct OurVertexShaderOutput {
+        @builtin(position) position: vec4f,
+      };
+
+      @vertex fn vs(
+        @builtin(vertex_index) vertexIndex : u32
+      ) -> OurVertexShaderOutput {
+        let pos = array(
+          vec2f( 0.0,  0.5),  // top center
+          vec2f(-0.5, -0.5),  // bottom left
+          vec2f( 0.5, -0.5)   // bottom right
+        );
+
+        var vsOutput: OurVertexShaderOutput;
+        vsOutput.position = vec4f(pos[vertexIndex], 0.0, 1.0);
+        return vsOutput;
+      }
++    `,
++  });
++
++  const fsModule = device.createShaderModule({
++    label: 'checkerboard',
++    code: `
+-      @fragment fn fs(@builtin(position) pixelPosition: vec4f) -> @location(0) vec4f {
++      @fragment fn fs(@builtin(position) pixelPosition: vec4f) -> @location(0) vec4f {
+        let red = vec4f(1, 0, 0, 1);
+        let cyan = vec4f(0, 1, 1, 1);
+
+-        let grid = vec2u(fsInput.position.xy) / 8;
++        let grid = vec2u(pixelPosition.xy) / 8;
+        let checker = (grid.x + grid.y) % 2 == 1;
+
+        return select(red, cyan, checker);
+      }
+    `,
+  });
+```
+
+And we'd have to update our pipeline creation to use these
+
+```js
+  const pipeline = device.createRenderPipeline({
+    label: 'hardcoded checkerboard triangle pipeline',
+    layout: 'auto',
+    vertex: {
+-      module,
++      module: vsModule,
+      entryPoint: 'vs',
+    },
+    fragment: {
+-      module,
++      module: fsModule,
+      entryPoint: 'fs',
+      targets: [{ format: presentationFormat }],
+    },
+  });
+
+```
+
+And this would also work
+
+{{{example url="../webgpu-fragment-shader-builtin-position-separate-modules.html"}}}
+
+The point is, the fact that both shaders are in the same string in most WebGPU
+examples is just a convenience. In reality, first WebGPU parses the WGSL to make
+sure it's syntactically correct. Then, WebGPU looks at the `entryPoint`
+you specify. From that it goes and looks at the parts that entryPoint references
+and nothing else for that entryPoint. It's useful because you don't have to type
+things like structures or binding and group locations twice if two or more shaders
+share bindings or structures or constants or functions. But, from the POV of WebGPU,
+it's as though you did duplicate all of them, once for each entryPoint.
+
 Note: It is not that common to generate a checkerboard using the
 `@builtin(position)`. Checkerboards or other patterns are far more commonly
 implemented [using textures](webgpu-textures.html). In fact you'll see an issue

diff --git a/webgpu/webgpu-fragment-shader-builtin-position-separate-modules.html b/webgpu/webgpu-fragment-shader-builtin-position-separate-modules.html
@@ -0,0 +1,140 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>WebGPU Fragment Shader using @builtin(position)</title>
+    <style>
+      @import url(resources/webgpu-lesson.css);
+html, body {
+  margin: 0;       /* remove the default margin          */
+  height: 100%;    /* make the html,body fill the page   */
+}
+canvas {
+  display: block;  /* make the canvas act like a block   */
+  width: 100%;     /* make the canvas fill its container */
+  height: 100%;
+}
+    </style>
+  </head>
+  <body>
+    <canvas></canvas>
+  </body>
+  <script type="module">
+async function main() {
+  const adapter = await navigator.gpu?.requestAdapter();
+  const device = await adapter?.requestDevice();
+  if (!device) {
+    fail('need a browser that supports WebGPU');
+    return;
+  }
+
+  // Get a WebGPU context from the canvas and configure it
+  const canvas = document.querySelector('canvas');
+  const context = canvas.getContext('webgpu');
+  const presentationFormat = navigator.gpu.getPreferredCanvasFormat();
+  context.configure({
+    device,
+    format: presentationFormat,
+  });
+
+  const vsModule = device.createShaderModule({
+    label: 'hardcoded triangle',
+    code: `
+      struct OurVertexShaderOutput {
+        @builtin(position) position: vec4f,
+      };
+
+      @vertex fn vs(
+        @builtin(vertex_index) vertexIndex : u32
+      ) -> OurVertexShaderOutput {
+        let pos = array(
+          vec2f( 0.0,  0.5),  // top center
+          vec2f(-0.5, -0.5),  // bottom left
+          vec2f( 0.5, -0.5)   // bottom right
+        );
+
+        var vsOutput: OurVertexShaderOutput;
+        vsOutput.position = vec4f(pos[vertexIndex], 0.0, 1.0);
+        return vsOutput;
+      }
+    `,
+  });
+
+  const fsModule = device.createShaderModule({
+    label: 'checkerboard',
+    code: `
+      @fragment fn fs(@builtin(position) pixelPosition: vec4f) -> @location(0) vec4f {
+        let red = vec4f(1, 0, 0, 1);
+        let cyan = vec4f(0, 1, 1, 1);
+
+        let grid = vec2u(pixelPosition.xy) / 8;
+        let checker = (grid.x + grid.y) % 2 == 1;
+
+        return select(red, cyan, checker);
+      }
+    `,
+  });
+
+  const pipeline = device.createRenderPipeline({
+    label: 'hardcoded checkerboard triangle pipeline',
+    layout: 'auto',
+    vertex: {
+      module: vsModule,
+      entryPoint: 'vs',
+    },
+    fragment: {
+      module: fsModule,
+      entryPoint: 'fs',
+      targets: [{ format: presentationFormat }],
+    },
+  });
+
+  const renderPassDescriptor = {
+    label: 'our basic canvas renderPass',
+    colorAttachments: [
+      {
+        // view: <- to be filled out when we render
+        clearValue: [0.3, 0.3, 0.3, 1],
+        loadOp: 'clear',
+        storeOp: 'store',
+      },
+    ],
+  };
+
+  function render() {
+    // Get the current texture from the canvas context and
+    // set it as the texture to render to.
+    renderPassDescriptor.colorAttachments[0].view =
+        context.getCurrentTexture().createView();
+
+    const encoder = device.createCommandEncoder({ label: 'our encoder' });
+    const pass = encoder.beginRenderPass(renderPassDescriptor);
+    pass.setPipeline(pipeline);
+    pass.draw(3);  // call our vertex shader 3 times
+    pass.end();
+
+    const commandBuffer = encoder.finish();
+    device.queue.submit([commandBuffer]);
+  }
+
+  const observer = new ResizeObserver(entries => {
+    for (const entry of entries) {
+      const canvas = entry.target;
+      const width = entry.contentBoxSize[0].inlineSize;
+      const height = entry.contentBoxSize[0].blockSize;
+      canvas.width = Math.max(1, Math.min(width, device.limits.maxTextureDimension2D));
+      canvas.height = Math.max(1, Math.min(height, device.limits.maxTextureDimension2D));
+      // re-render
+      render();
+    }
+  });
+  observer.observe(canvas);
+}
+
+function fail(msg) {
+  // eslint-disable-next-line no-alert
+  alert(msg);
+}
+
+main();
+  </script>
+</html>