@woosh/meep-engine 3.11.2 → 3.12.0

package/src/shade/renderer/water/shader_water.js

@@ -1,246 +1,246 @@
-import { GPUShaderStage } from "../../descriptor/GPUShaderStage.js";
-import { ColorTargetState } from "../../descriptor/pipeline/render/ColorTargetState.js";
-import { RenderPipelineDescriptor } from "../../descriptor/pipeline/render/RenderPipelineDescriptor.js";
-import { CAMERA_UNIFORM_STRUCT } from "../camera/CAMERA_UNIFORM_STRUCT.js";
-import { chunk_get_view_space_depth } from "../shader/chunk/depth/chunk_get_view_space_depth.js";
-import { CodeChunk } from "../shader/compiler/CodeChunk.js";
-import { ShaderResourceSetDescriptor } from "../shader/resource/ShaderResourceSetDescriptor.js";
-import { ShaderDescriptor } from "../shader/ShaderDescriptor.js";
-import { f32, vec2f, vec3f, vec4f } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUStruct } from "../shader/type/WebGPUStruct.js";
-
-/**
- * One water surface. Small, and rewritten per surface per frame rather than tabled — a level has a
- * handful of these, not thousands.
- */
-export const WATER_DRAW_STRUCT = WebGPUStruct.from({
-    /**
-     * World-space extent of the surface, `x0, z0, x1, z1`. The quad is generated from this rather
-     * than from a vertex buffer: the surface is a rectangle at a constant height, and the waves
-     * displace nothing — they only move where the shore line falls.
-     */
-    extent: vec4f,
-
-    /**
-     * Where the water's UV lands in the terrain height map, `offset.xy, scale.xy`.
-     */
-    height_uv: vec4f,
-
-    color_deep: vec3f,
-    color_shore: vec3f,
-
-    /**
-     * The surface's world height.
-     */
-    level: f32,
-
-    /**
-     * Seconds. Waves are a function of it, so it is the only field that must change every frame.
-     */
-    time: f32,
-
-    wave_amplitude: f32,
-    wave_speed: f32,
-    wave_frequency: f32,
-
-    /**
-     * How fast the water goes opaque with the depth of scene behind it.
-     */
-    scattering: f32,
-
-    /**
-     * Water depth over which the shore colour gives way to the deep colour.
-     */
-    shore_transition: vec2f,
-}, "WaterDraw").pack();
-
-const resources = new ShaderResourceSetDescriptor();
-
-resources.createGroup()
-    .addUniform("camera", CAMERA_UNIFORM_STRUCT)
-    .addUniform("water", WATER_DRAW_STRUCT)
-    // Bound as an unfilterable float rather than as `depth`, which is how every other pass in the
-    // engine reads the depth buffer — GTAO, TAA and the volumetrics all declare it this way and take
-    // `.r`. Declaring it `depth` yields a `texture_depth_2d` binding, and the depth this pass sampled
-    // through one did not come back as the scene's.
-    .addTexture("scene_depth")
-    .addTexture("terrain_height", "float")
-    .addSampler("height_sampler");
-
-const body = CodeChunk.from(
-    //language=WGSL
-    `
-struct WaterVertexOut {
-    @builtin(position) clip : vec4<f32>,
-    @location(0) world : vec3<f32>,
-    @location(1) uv : vec2<f32>,
-}
-
-/*
- Two triangles from the vertex index alone. The surface is a rectangle at a constant height, so
- there is no geometry worth uploading, and nothing about it changes between frames except the
- uniform.
-*/
-@vertex
-fn vs_main(@builtin(vertex_index) vi : u32) -> WaterVertexOut {
-    var CORNERS = array<vec2<f32>, 6>(
-        vec2<f32>(0.0, 0.0),
-        vec2<f32>(1.0, 0.0),
-        vec2<f32>(0.0, 1.0),
-        vec2<f32>(1.0, 0.0),
-        vec2<f32>(1.0, 1.0),
-        vec2<f32>(0.0, 1.0),
-    );
-
-    let corner = CORNERS[vi];
-
-    let world = vec3<f32>(
-        mix(water.extent.x, water.extent.z, corner.x),
-        water.level,
-        mix(water.extent.y, water.extent.w, corner.y)
-    );
-
-    var out : WaterVertexOut;
-
-    out.clip = camera.view_projection_matrix * vec4<f32>(world, 1.0);
-    out.world = world;
-    out.uv = corner;
-
-    return out;
-}
-
-/**
- * The terrain under the water, softened. A hard heightmap read makes the shore line crawl along
- * texel edges; the legacy shader blurred it for the same reason, and the softness is the look
- * rather than an approximation of one.
- */
-fn sample_terrain_height(uv : vec2<f32>) -> f32 {
-    let dimensions = vec2<f32>(textureDimensions(terrain_height, 0));
-    let texel = 1.0 / dimensions;
-
-    var total = 0.0;
-
-    for (var y = -1; y <= 1; y = y + 1) {
-        for (var x = -1; x <= 1; x = x + 1) {
-            let offset = vec2<f32>(f32(x), f32(y)) * texel;
-
-            total = total + textureSampleLevel(terrain_height, height_sampler, uv + offset, 0.0).r;
-        }
-    }
-
-    return total / 9.0;
-}
-
-@fragment
-fn fs_main(in : WaterVertexOut) -> @location(0) vec4<f32> {
-    let coord = vec2<i32>(in.clip.xy);
-
-    /*
-     How much scene sits behind the water at this pixel. Both depths go through the camera's own
-     device-to-view parameters, so this is correct under the reverse-Z infinite-far projection Shade
-     draws with — the legacy shader's near/far reconstruction is not, and reproducing its arithmetic
-     here would have put the shore line in the wrong place everywhere.
-    */
-    let scene_view_depth = get_view_space_depth(
-        textureLoad(scene_depth, coord, 0).r,
-        camera
-    );
-
-    let surface_view_depth = get_view_space_depth(in.clip.z, camera);
-
-    let behind = scene_view_depth - surface_view_depth;
-
-    if (!(behind > 0.0)) {
-        // the water surface is behind something opaque — written as a positive test so a depth that
-        // arrives as NaN discards too rather than drawing over the scene
-        discard;
-    }
-
-    let height_uv = in.uv * water.height_uv.zw + water.height_uv.xy;
-
-    let terrain = sample_terrain_height(height_uv);
-
-    let depth = water.level - terrain;
-
-    let hash = (in.world.x + in.world.z) * water.wave_frequency;
-
-    const INVERSE_PI = 0.3183098861837907;
-
-    let wave = sin(hash + water.time * water.wave_speed) * INVERSE_PI;
-
-    let wave_depth = depth + water.wave_amplitude * wave;
-
-    let deep = smoothstep(water.shore_transition.x, water.shore_transition.y, wave_depth);
-
-    var color = mix(
-        vec4<f32>(water.color_shore, 0.8),
-        vec4<f32>(water.color_deep, 1.0),
-        deep
-    );
-
-    // scattering: the more scene there is behind the water, the less of it comes back through
-    color.a = color.a * (1.0 - exp(-behind * water.scattering));
-
-    return color;
-}
-    `, [
-        chunk_get_view_space_depth
-    ]
-);
-
-export const water_shader = ShaderDescriptor.from({
-    label: "Water",
-    resources,
-    body
-});
-
-const WATER_BLEND = {
-    color: {
-        srcFactor: "src-alpha",
-        dstFactor: "one-minus-src-alpha",
-        operation: "add",
-    },
-    alpha: {
-        srcFactor: "one",
-        dstFactor: "one-minus-src-alpha",
-        operation: "add",
-    },
-};
-
-/**
- * Build the water pipeline.
- *
- * **It has no depth attachment, and that is forced rather than chosen.** The shader *samples* scene
- * depth to know how much water the view looks through, and a texture may not be a sampled source
- * and a render attachment in the same pass. So the depth test the hardware would have done is done
- * in the shader instead — which is also why the fragment `discard` there is load-bearing rather
- * than a guard: without it, water would draw over the things standing in it.
- *
- * @param {object} [options]
- * @param {string} [options.color_format]
- * @returns {RenderPipelineDescriptor}
- */
-export function create_water_pipeline({ color_format = "rgba16float" } = {}) {
-    const code = water_shader.compile();
-
-    return RenderPipelineDescriptor.from({
-        label: "Water",
-        layout: resources.generatePipelineLayout(GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT),
-        vertex: { module: { code }, entryPoint: "vs_main" },
-        fragment: {
-            module: { code },
-            entryPoint: "fs_main",
-            targets: [ColorTargetState.from({ format: color_format, blend: WATER_BLEND })],
-        },
-        // the surface is a rectangle seen from above or below — the legacy plane was BackSide for
-        // the same reason, and neither side of it should vanish
-        primitive: { topology: "triangle-list", cullMode: "none" },
-    });
-}
-
-/**
- * The pipeline's resource set, for building bind groups.
- *
- * @type {ShaderResourceSetDescriptor}
- */
-export const WATER_RESOURCES = resources;
+import { GPUShaderStage } from "../../descriptor/GPUShaderStage.js";
+import { ColorTargetState } from "../../descriptor/pipeline/render/ColorTargetState.js";
+import { RenderPipelineDescriptor } from "../../descriptor/pipeline/render/RenderPipelineDescriptor.js";
+import { CAMERA_UNIFORM_STRUCT } from "../camera/CAMERA_UNIFORM_STRUCT.js";
+import { chunk_get_view_space_depth } from "../shader/chunk/depth/chunk_get_view_space_depth.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../shader/resource/ShaderResourceSetDescriptor.js";
+import { ShaderDescriptor } from "../shader/ShaderDescriptor.js";
+import { f32, vec2f, vec3f, vec4f } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../shader/type/WebGPUStruct.js";
+
+/**
+ * One water surface. Small, and rewritten per surface per frame rather than tabled — a level has a
+ * handful of these, not thousands.
+ */
+export const WATER_DRAW_STRUCT = WebGPUStruct.from({
+    /**
+     * World-space extent of the surface, `x0, z0, x1, z1`. The quad is generated from this rather
+     * than from a vertex buffer: the surface is a rectangle at a constant height, and the waves
+     * displace nothing — they only move where the shore line falls.
+     */
+    extent: vec4f,
+
+    /**
+     * Where the water's UV lands in the terrain height map, `offset.xy, scale.xy`.
+     */
+    height_uv: vec4f,
+
+    color_deep: vec3f,
+    color_shore: vec3f,
+
+    /**
+     * The surface's world height.
+     */
+    level: f32,
+
+    /**
+     * Seconds. Waves are a function of it, so it is the only field that must change every frame.
+     */
+    time: f32,
+
+    wave_amplitude: f32,
+    wave_speed: f32,
+    wave_frequency: f32,
+
+    /**
+     * How fast the water goes opaque with the depth of scene behind it.
+     */
+    scattering: f32,
+
+    /**
+     * Water depth over which the shore colour gives way to the deep colour.
+     */
+    shore_transition: vec2f,
+}, "WaterDraw").pack();
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addUniform("camera", CAMERA_UNIFORM_STRUCT)
+    .addUniform("water", WATER_DRAW_STRUCT)
+    // Bound as an unfilterable float rather than as `depth`, which is how every other pass in the
+    // engine reads the depth buffer — GTAO, TAA and the volumetrics all declare it this way and take
+    // `.r`. Declaring it `depth` yields a `texture_depth_2d` binding, and the depth this pass sampled
+    // through one did not come back as the scene's.
+    .addTexture("scene_depth")
+    .addTexture("terrain_height", "float")
+    .addSampler("height_sampler");
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+struct WaterVertexOut {
+    @builtin(position) clip : vec4<f32>,
+    @location(0) world : vec3<f32>,
+    @location(1) uv : vec2<f32>,
+}
+
+/*
+ Two triangles from the vertex index alone. The surface is a rectangle at a constant height, so
+ there is no geometry worth uploading, and nothing about it changes between frames except the
+ uniform.
+*/
+@vertex
+fn vs_main(@builtin(vertex_index) vi : u32) -> WaterVertexOut {
+    var CORNERS = array<vec2<f32>, 6>(
+        vec2<f32>(0.0, 0.0),
+        vec2<f32>(1.0, 0.0),
+        vec2<f32>(0.0, 1.0),
+        vec2<f32>(1.0, 0.0),
+        vec2<f32>(1.0, 1.0),
+        vec2<f32>(0.0, 1.0),
+    );
+
+    let corner = CORNERS[vi];
+
+    let world = vec3<f32>(
+        mix(water.extent.x, water.extent.z, corner.x),
+        water.level,
+        mix(water.extent.y, water.extent.w, corner.y)
+    );
+
+    var out : WaterVertexOut;
+
+    out.clip = camera.view_projection_matrix * vec4<f32>(world, 1.0);
+    out.world = world;
+    out.uv = corner;
+
+    return out;
+}
+
+/**
+ * The terrain under the water, softened. A hard heightmap read makes the shore line crawl along
+ * texel edges; the legacy shader blurred it for the same reason, and the softness is the look
+ * rather than an approximation of one.
+ */
+fn sample_terrain_height(uv : vec2<f32>) -> f32 {
+    let dimensions = vec2<f32>(textureDimensions(terrain_height, 0));
+    let texel = 1.0 / dimensions;
+
+    var total = 0.0;
+
+    for (var y = -1; y <= 1; y = y + 1) {
+        for (var x = -1; x <= 1; x = x + 1) {
+            let offset = vec2<f32>(f32(x), f32(y)) * texel;
+
+            total = total + textureSampleLevel(terrain_height, height_sampler, uv + offset, 0.0).r;
+        }
+    }
+
+    return total / 9.0;
+}
+
+@fragment
+fn fs_main(in : WaterVertexOut) -> @location(0) vec4<f32> {
+    let coord = vec2<i32>(in.clip.xy);
+
+    /*
+     How much scene sits behind the water at this pixel. Both depths go through the camera's own
+     device-to-view parameters, so this is correct under the reverse-Z infinite-far projection Shade
+     draws with — the legacy shader's near/far reconstruction is not, and reproducing its arithmetic
+     here would have put the shore line in the wrong place everywhere.
+    */
+    let scene_view_depth = get_view_space_depth(
+        textureLoad(scene_depth, coord, 0).r,
+        camera
+    );
+
+    let surface_view_depth = get_view_space_depth(in.clip.z, camera);
+
+    let behind = scene_view_depth - surface_view_depth;
+
+    if (!(behind > 0.0)) {
+        // the water surface is behind something opaque — written as a positive test so a depth that
+        // arrives as NaN discards too rather than drawing over the scene
+        discard;
+    }
+
+    let height_uv = in.uv * water.height_uv.zw + water.height_uv.xy;
+
+    let terrain = sample_terrain_height(height_uv);
+
+    let depth = water.level - terrain;
+
+    let hash = (in.world.x + in.world.z) * water.wave_frequency;
+
+    const INVERSE_PI = 0.3183098861837907;
+
+    let wave = sin(hash + water.time * water.wave_speed) * INVERSE_PI;
+
+    let wave_depth = depth + water.wave_amplitude * wave;
+
+    let deep = smoothstep(water.shore_transition.x, water.shore_transition.y, wave_depth);
+
+    var color = mix(
+        vec4<f32>(water.color_shore, 0.8),
+        vec4<f32>(water.color_deep, 1.0),
+        deep
+    );
+
+    // scattering: the more scene there is behind the water, the less of it comes back through
+    color.a = color.a * (1.0 - exp(-behind * water.scattering));
+
+    return color;
+}
+    `, [
+        chunk_get_view_space_depth
+    ]
+);
+
+export const water_shader = ShaderDescriptor.from({
+    label: "Water",
+    resources,
+    body
+});
+
+const WATER_BLEND = {
+    color: {
+        srcFactor: "src-alpha",
+        dstFactor: "one-minus-src-alpha",
+        operation: "add",
+    },
+    alpha: {
+        srcFactor: "one",
+        dstFactor: "one-minus-src-alpha",
+        operation: "add",
+    },
+};
+
+/**
+ * Build the water pipeline.
+ *
+ * **It has no depth attachment, and that is forced rather than chosen.** The shader *samples* scene
+ * depth to know how much water the view looks through, and a texture may not be a sampled source
+ * and a render attachment in the same pass. So the depth test the hardware would have done is done
+ * in the shader instead — which is also why the fragment `discard` there is load-bearing rather
+ * than a guard: without it, water would draw over the things standing in it.
+ *
+ * @param {object} [options]
+ * @param {string} [options.color_format]
+ * @returns {RenderPipelineDescriptor}
+ */
+export function create_water_pipeline({ color_format = "rgba16float" } = {}) {
+    const code = water_shader.source;
+
+    return RenderPipelineDescriptor.from({
+        label: "Water",
+        layout: resources.generatePipelineLayout(GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT),
+        vertex: { module: { code }, entryPoint: "vs_main" },
+        fragment: {
+            module: { code },
+            entryPoint: "fs_main",
+            targets: [ColorTargetState.from({ format: color_format, blend: WATER_BLEND })],
+        },
+        // the surface is a rectangle seen from above or below — the legacy plane was BackSide for
+        // the same reason, and neither side of it should vanish
+        primitive: { topology: "triangle-list", cullMode: "none" },
+    });
+}
+
+/**
+ * The pipeline's resource set, for building bind groups.
+ *
+ * @type {ShaderResourceSetDescriptor}
+ */
+export const WATER_RESOURCES = resources;

package/src/shade/vitest.setup.mjs

@@ -1,4 +1,4 @@
-// Vendored with Shade (MEEP3 Phase 1b). Vitest setup: stub WebGPU globals that production modules reference at load time. In a real
+// Vendored with Shade (see ../../SHADE_ORIGIN.md). Vitest setup: stub WebGPU globals that production modules reference at load time. In a real
 // WebGPU environment these are provided by the platform; under Node these are absent and reading
 // them throws a ReferenceError, which trips any `import` of a production shader module that
 // constructs an ImageShader / ComputeShader at top level.