@footgun/cobalt 0.1.0

package/src/fb-texture/fb-texture.js

@@ -0,0 +1,56 @@
+import createTexture from '../create-texture.js'
+
+
+// Frame buffer textures automatically resize to match the cobalt viewport.
+
+export default {
+    type: 'fbTexture',
+    refs: [ ],
+
+    // @params Object cobalt renderer world object
+    // @params Object options optional data passed when initing this node
+    onInit: async function (cobalt, options={}) {
+        return init(cobalt, options)
+    },
+
+    onRun: function (cobalt, node, webGpuCommandEncoder) {
+        // do whatever you need for this node. webgpu renderpasses, etc.
+    },
+
+    onDestroy: function (cobalt, node) {
+        // any cleanup for your node should go here (releasing textures, etc.)
+        destroy(data)
+    },
+
+    onResize: function (cobalt, node) {
+        // do whatever you need when the dimensions of the renderer change (resize textures, etc.)
+        resize(cobalt, node)
+    },
+
+    onViewportPosition: function (cobalt, node) { },
+}
+
+
+async function init (cobalt, node) {
+    const { device } = cobalt
+
+    const { label, mip_count, format, usage, viewportScale } = node.options
+
+    return createTexture(device, label, cobalt.viewport.width * viewportScale, cobalt.viewport.height * viewportScale, mip_count, format, usage)
+}
+
+
+function destroy (node) {
+    // destroy the existing texture before we re-create it to avoid leaking memory
+    node.data.texture.destroy()
+}
+
+
+function resize (cobalt, node) {
+    const { device } = cobalt
+	destroy(node)
+    const { width, height } = cobalt.viewport
+    const { options } = node
+    const scale = node.options.viewportScale
+    node.data = createTexture(device, options.label, width * scale, height * scale, options.mip_count, options.format, options.usage)
+}

package/src/light/README.md

@@ -0,0 +1,61 @@
+## Lighting system
+Cobalt uses a deferred lighting system, where the `Light` node receives as input the albedo texture and combines it with the computed illumination to build the output.
+
+![Screenshot](readme/01_illumination.webp)
+
+ _On the left, the input albedo texture. On the right the output composition result._
+
+### Algorithm
+
+The lights are computed in 2 renderpasses:
+- first renderpass: for each light we compute their illumination and shadows. We store the results in a texture called the "lights texture", where each lights has their data stored independently. This pass is handled by the `LightsTexture` class.
+- second renderpass: composition time. For each pixel, we determine which lights might affect it. Then we check these lights contribution by sampling the lights texture. We sum all contributions to get a total illumination for the pixel. We then multiply it by the color sampled from the albedo texture. This pass is handled by the `LightsRenderer` class.
+
+We must perform the composition for every frame. However, the lights texture only needs to be recomputed when either the lights (movement, intensity, color etc.) or the shadow-casting objects changed.
+
+#### Lighting equation
+We use a lighting equation that is not physically accurate, but is flexible and gives good enough results. You can find it in the `LightsTextureInitializer` shader
+
+#### Lights texture
+The lights texture stores the computed illumination of each light. This illumination is a combination of the light intensity and the cast shadows. It is a one-dimensional value because the light color is applied at composition-time. Here is an example of what the lights texture looks like:
+
+![Screenshot](readme/02_lights_texture.webp)
+
+For technical reasons, we store all lights into a  single texture:
+- each light is assigned a square area in the texture. The center of the area is the center of the light. In the example above, there are two areas. All lights have the same resolution, which means that there is a maximum light radius. If a light's radius is above this limit, it means that light is too big to be stored in its area, which will result in visual artifacts. If we stored lights with floating resolution (= the biggest lights are lower resolution than the small ones), we could remove this max radius limit.
+- each light is stored into a single texture channel. This is possible because the light intensity is a simple float. This allows us to store 4 lights in a single texel, one per channel (Red, Green, Blue, Alpha). The above texture has two areas and four channels, which means it can store up to 8 lights.
+
+![Screenshot](readme/03_lights_texture_decomposed.webp)
+
+_Illustration of a single area storing the data of 3 lights_
+
+The lights texture stores normalized lights intensity (between 0 and 1). At composition-time we multiply the intensity sampled from texture by the maximum intensity of the light, which allows us to have lights brighter than 1.
+
+Here is how the lights texture is computed by the `LightsTexture` class (illustrated with a single light for clarity):
+- first we compute the base lights intensity (class `LightsTextureInitializer`)
+- then we add the cast shadows as a mask (class `LightsTextureMask`)
+
+![Screenshot](readme/04_lights_texture_mask.webp)
+
+_One the left, the base light intensity. On the right, the base light intensity with the cast shadows_
+
+##### Cast shadows computing
+All lights in Cobalt are point-lights.
+
+The shadow-casting objects are decomposed as a series of segments.
+
+![Screenshot](readme/05_lights_obstacle_decomposition.webp)
+
+_On the left, the base obstacle. On the right, its decomposition into segments P0-P1, P1-P2, P2-P3, P3-P0._
+
+Then, the key is to observe that the cast shadow is a quad, where two points are the obstacle segments, and two points are their projection relatively to the point light.
+
+![Screenshot](readme/06_lights_hard_cast_shadows.webp)
+
+_P0' and P3' are the projection of P0 and P3 respectively_
+
+This projection is performed in the vertex shader. When the CPU declares an obstacle composed of `vec2` vertices P0 and P1, in the GPU buffer it creates 4 `vec3` vertices where the `z` components indicates whether the vertice will be projected:
+- [P0x, P0y, 0] and [P1x, P1y, 0] will remain at the position of P0 and P1
+- [P0x, P0, 1] and [P1x, P1y, 1] will be their projection
+
+And then we draw the quad P0, P0', P1', P1 which covers the cast shadow.

package/src/light/light.js

@@ -0,0 +1,148 @@
+import * as publicAPI from './public-api.js'
+import { Viewport } from "./viewport";
+import { LightsRenderer } from './lights-renderer.js';
+import { LightsBuffer } from './lights-buffer.js';
+
+
+/**
+ * 2D lighting and Shadows
+ */
+
+export default {
+    type: 'cobalt:light',
+
+    // the inputs and outputs to this node
+    refs: [
+        { name: 'in', type: 'textureView', format: 'rgba16float', access: 'read' },
+        { name: 'out', type: 'textureView', format: 'rgba16float', access: 'write' },
+    ],
+
+    // cobalt event handling functions
+
+    // @params Object cobalt renderer world object
+    // @params Object options optional data passed when initing this node
+    onInit: async function (cobalt, options = {}) {
+        return init(cobalt, options)
+    },
+
+    onRun: function (cobalt, node, webGpuCommandEncoder) {
+        // do whatever you need for this node. webgpu renderpasses, etc.
+        draw(cobalt, node, webGpuCommandEncoder)
+    },
+
+    onDestroy: function (cobalt, node) {
+        // any cleanup for your node should go here (releasing textures, etc.)
+        destroy(node)
+    },
+
+    onResize: function (cobalt, node) {
+        // runs when the viewport size changes (handle resizing textures, etc.)
+        resize(cobalt, node)
+    },
+
+    onViewportPosition: function (cobalt, node) {
+        // runs when the viewport position changes
+        node.data.viewport.setTopLeft(...cobalt.viewport.position);
+    },
+
+    // optional
+    customFunctions: {
+        ...publicAPI,
+    },
+}
+
+
+async function init(cobalt, node) {
+
+    const { device } = cobalt
+
+    // a 2048x2048 light texture with 4 channels (rgba) with each light lighting a 256x256 region can hold 256 lights
+    const MAX_LIGHT_COUNT = 256;
+    const MAX_LIGHT_SIZE = 256;
+    const lightsBuffer = new LightsBuffer(device, MAX_LIGHT_COUNT);
+
+    const viewport = new Viewport({
+        viewportSize: {
+            width: cobalt.viewport.width,
+            height: cobalt.viewport.height,
+        },
+        center: cobalt.viewport.position,
+        zoom: cobalt.viewport.zoom,
+    });
+
+    const lightsRenderer = new LightsRenderer({
+        device,
+        albedo: {
+            view: node.refs.in.data.view,
+            sampler: node.refs.in.data.sampler
+        },
+        targetTexture: node.refs.out.data.texture,
+        lightsBuffer,
+        lightsTextureProperties: {
+            resolutionPerLight: MAX_LIGHT_SIZE,
+            maxLightSize: MAX_LIGHT_SIZE,
+            antialiased: false,
+            filtering: "nearest",
+        },
+    });
+
+    return {
+        lightsBuffer,
+        lightsBufferNeedsUpdate: true,
+
+        lightsTextureNeedsUpdate: true,
+        lightsRenderer,
+
+        viewport,
+
+        lights: [],
+    }
+}
+
+
+function draw(cobalt, node, commandEncoder) {
+    if (node.data.lightsBufferNeedsUpdate) {
+        const lightsBuffer = node.data.lightsBuffer;
+        lightsBuffer.setLights(node.data.lights);
+        node.data.lightsBufferNeedsUpdate = false;
+        node.data.lightsTextureNeedsUpdate = true;
+    }
+
+    const lightsRenderer = node.data.lightsRenderer;
+
+    if (node.data.lightsTextureNeedsUpdate) {
+        lightsRenderer.computeLightsTexture(commandEncoder);
+        node.data.lightsTextureNeedsUpdate = false;
+    }
+
+    const renderpass = commandEncoder.beginRenderPass({
+        colorAttachments: [
+            {
+                view: node.refs.out.data.view,
+                clearValue: cobalt.clearValue,
+                loadOp: 'load',
+                storeOp: 'store'
+            }
+        ]
+    })
+
+    node.data.viewport.setZoom(cobalt.viewport.zoom);
+    const invertVpMatrix = node.data.viewport.invertViewProjectionMatrix;
+    lightsRenderer.render(renderpass, invertVpMatrix);
+
+    renderpass.end()
+}
+
+function destroy(node) {
+    node.data.lightsBuffer.destroy();
+    node.data.lightsRenderer.destroy();
+}
+
+function resize(cobalt, node) {
+    node.data.lightsRenderer.setAlbedo({
+        view: node.refs.in.data.view,
+        sampler: node.refs.in.data.sampler
+    });
+
+    node.data.viewport.setViewportSize(cobalt.viewport.width, cobalt.viewport.height);
+}

package/src/light/lights-buffer.ts

@@ -0,0 +1,98 @@
+/// <reference types="@webgpu/types"/>
+
+import { type Light } from "./types";
+
+class LightsBuffer {
+    public static readonly structs = {
+        definition: `
+struct Light {                //             align(16) size(48)
+    color: vec3<f32>,         // offset(0)   align(16) size(12)
+    radius: f32,              // offset(12)  align(4)  size(4)
+    position: vec2<f32>,      // offset(16)  align(8)  size(8)
+    intensity: f32,           // offset(24)  align(4)  size(4)
+    attenuationLinear: f32,   // offset(28)  align(4)  size(4)
+    attenuationExp: f32,      // offset(32)  align(4)  size(4)
+};
+
+struct LightsBuffer {         //             align(16)
+    count: u32,               // offset(0)   align(4)  size(4)
+    // padding
+    lights: array<Light>,     // offset(16)  align(16)
+};
+`,
+        light: {
+            radius: { offset: 12 },
+            position: { offset: 16 },
+        },
+        lightsBuffer: {
+            lights: { offset: 16, stride: 48 },
+        },
+    };
+
+    private readonly device: GPUDevice;
+
+    public readonly maxLightsCount: number;
+    private currentLightsCount: number = 0;
+
+    private readonly buffer: {
+        readonly bufferCpu: ArrayBuffer;
+        readonly bufferGpu: GPUBuffer;
+    };
+    public get gpuBuffer(): GPUBuffer {
+        return this.buffer.bufferGpu;
+    }
+
+    public constructor(device: GPUDevice, maxLightsCount: number) {
+        this.device = device;
+        this.maxLightsCount = maxLightsCount;
+
+        const bufferCpu = new ArrayBuffer(LightsBuffer.computeBufferBytesLength(maxLightsCount));
+        const bufferGpu = device.createBuffer({
+            label: "LightsBuffer buffer",
+            size: bufferCpu.byteLength,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.VERTEX,
+        });
+        this.buffer = { bufferCpu, bufferGpu };
+
+        this.setLights([]);
+    }
+
+    public setLights(lights: ReadonlyArray<Light>): void {
+        if (lights.length > this.maxLightsCount) {
+            throw new Error(`Too many lights "${lights.length}", max is "${this.maxLightsCount}".`);
+        }
+
+        const newBufferLength = LightsBuffer.computeBufferBytesLength(lights.length);
+        new Uint32Array(this.buffer.bufferCpu, 0, 1).set([lights.length]);
+
+        lights.forEach((light: Light, index: number) => {
+            new Float32Array(this.buffer.bufferCpu, LightsBuffer.structs.lightsBuffer.lights.offset + LightsBuffer.structs.lightsBuffer.lights.stride * index, 9).set([
+                ...light.color,
+                light.radius,
+                ...light.position,
+                light.intensity,
+                light.attenuationLinear,
+                light.attenuationExp
+            ]);
+        });
+
+        this.device.queue.writeBuffer(this.buffer.bufferGpu, 0, this.buffer.bufferCpu, 0, newBufferLength);
+        this.currentLightsCount = lights.length;
+    }
+
+    public get lightsCount(): number {
+        return this.currentLightsCount;
+    }
+
+    public destroy(): void {
+        this.buffer.bufferGpu.destroy();
+    }
+
+    private static computeBufferBytesLength(lightsCount: number): number {
+        return LightsBuffer.structs.lightsBuffer.lights.offset + LightsBuffer.structs.lightsBuffer.lights.stride * lightsCount;
+    }
+}
+
+export {
+    LightsBuffer
+};

package/src/light/lights-renderer.ts

@@ -0,0 +1,278 @@
+/// <reference types="@webgpu/types"/>
+
+import * as wgpuMatrix from "wgpu-matrix";
+import { LightsBuffer } from "./lights-buffer";
+import { LightsTexture, type LightsTextureProperties } from "./texture/lights-texture";
+import { type LightObstacleSegment } from "./texture/lights-texture-mask";
+
+type TextureSamplable = {
+    readonly view: GPUTextureView;
+    readonly sampler: GPUSampler;
+};
+
+type TextureRenderable = {
+    readonly format: GPUTextureFormat;
+};
+
+type Parameters = {
+    readonly device: GPUDevice;
+    readonly albedo: TextureSamplable;
+    readonly targetTexture: TextureRenderable;
+    readonly lightsBuffer: LightsBuffer;
+    readonly lightsTextureProperties: LightsTextureProperties;
+};
+
+class LightsRenderer {
+    private readonly device: GPUDevice;
+
+    private ambientLight: [number, number, number] = [0.2, 0.2, 0.2];
+
+    private readonly targetTexture: TextureRenderable;
+
+    private readonly renderPipeline: GPURenderPipeline;
+    private readonly uniformsBufferGpu: GPUBuffer;
+    private readonly bindgroup0: GPUBindGroup;
+    private bindgroup1: GPUBindGroup;
+    private renderBundle: GPURenderBundle;
+
+    private readonly lightsBuffer: LightsBuffer;
+    private readonly lightsTexture: LightsTexture;
+
+    public constructor(params: Parameters) {
+        this.device = params.device;
+
+        this.targetTexture = params.targetTexture;
+        this.lightsBuffer = params.lightsBuffer;
+
+        this.lightsTexture = new LightsTexture(params.device, params.lightsBuffer, params.lightsTextureProperties);
+
+        this.uniformsBufferGpu = params.device.createBuffer({
+            label: "LightsRenderer uniforms buffer",
+            size: 80,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+
+        const shaderModule = params.device.createShaderModule({
+            label: "LightsRenderer shader module",
+            code: `
+struct Uniforms {                  //            align(16) size(80)
+    invertViewMatrix: mat4x4<f32>, // offset(0)  align(16) size(64)
+    ambientLight: vec3<f32>,       // offset(64) align(16) size(12)
+};
+
+${LightsBuffer.structs.definition}
+
+@group(0) @binding(0) var<uniform> uniforms: Uniforms;
+@group(0) @binding(1) var<storage,read> lightsBuffer: LightsBuffer;
+@group(0) @binding(2) var lightsTexture: texture_2d<f32>;
+@group(0) @binding(3) var lightsTextureSampler: sampler;
+
+@group(1) @binding(0) var albedoTexture: texture_2d<f32>;
+@group(1) @binding(1) var albedoSampler: sampler;
+
+struct VertexIn {
+    @builtin(vertex_index) vertexIndex: u32,
+};
+
+struct VertexOut {
+    @builtin(position) position: vec4<f32>,
+    @location(0) worldPosition: vec2<f32>,
+    @location(1) uv: vec2<f32>,
+};
+
+@vertex
+fn main_vertex(in: VertexIn) -> VertexOut {
+    const corners = array<vec2<f32>, 4>(
+        vec2<f32>(-1, -1),
+        vec2<f32>(1, -1),
+        vec2<f32>(-1, 1),
+        vec2<f32>(1, 1),
+    );
+    let screenPosition = corners[in.vertexIndex];
+
+    var out: VertexOut;
+    out.position = vec4<f32>(screenPosition, 0.0, 1.0);
+    out.worldPosition = (uniforms.invertViewMatrix * out.position).xy;
+    out.uv = 0.5 + 0.5 * screenPosition * vec2<f32>(1.0, -1.0);
+    return out;
+}
+
+struct FragmentOut {
+    @location(0) color: vec4<f32>,
+};
+
+const cellsGridSizeU = vec2<u32>(${this.lightsTexture.gridSize.x}, ${this.lightsTexture.gridSize.y});
+const cellsGridSizeF = vec2<f32>(${this.lightsTexture.gridSize.x}, ${this.lightsTexture.gridSize.y});
+
+fn sampleLightBaseIntensity(lightId: u32, localUv: vec2<f32>) -> f32 {
+    let cellIndex = lightId / 4u;
+    let indexInCell = lightId % 4u;
+
+    let cellIdU = vec2<u32>(
+        cellIndex % cellsGridSizeU.x,
+        cellIndex / cellsGridSizeU.x,
+    );
+    let cellIdF = vec2<f32>(cellIdU);
+    let uv = (cellIdF + localUv) / cellsGridSizeF;
+    let uvYInverted = vec2<f32>(uv.x, 1.0 - uv.y);
+    let sample = textureSampleLevel(lightsTexture, lightsTextureSampler, uvYInverted, 0.0);
+    let channel = vec4<f32>(
+        vec4<u32>(indexInCell) == vec4<u32>(0u, 1u, 2u, 3u),
+    );
+    return dot(sample, channel);
+}
+    
+fn compute_lights(worldPosition: vec2<f32>) -> vec3<f32> {
+    var color = vec3<f32>(uniforms.ambientLight);
+
+    const maxUvDistance = f32(${1 - 2 / params.lightsTextureProperties.resolutionPerLight});
+
+    let lightsCount = lightsBuffer.count;
+    for (var iLight = 0u; iLight < lightsCount; iLight++) {
+        let light = lightsBuffer.lights[iLight];
+        let lightSize = f32(${params.lightsTextureProperties.resolutionPerLight});
+        let relativePosition = (worldPosition - light.position) / lightSize;
+        if (max(abs(relativePosition.x), abs(relativePosition.y)) < maxUvDistance) {
+            let localUv = 0.5 + 0.5 * relativePosition;    
+            let lightIntensity = light.intensity * sampleLightBaseIntensity(iLight, localUv);
+            color += lightIntensity * light.color;
+        }
+    }
+
+    return color;
+}
+
+@fragment
+fn main_fragment(in: VertexOut) -> FragmentOut {
+    let light = compute_lights(in.worldPosition);
+    let albedo = textureSample(albedoTexture, albedoSampler, in.uv);
+    let color = albedo.rgb * light;
+
+    var out: FragmentOut;
+    out.color = vec4<f32>(color, 1.0);
+    return out;
+}
+            `,
+        });
+
+        this.renderPipeline = params.device.createRenderPipeline({
+            label: "LightsRenderer renderpipeline",
+            layout: "auto",
+            vertex: {
+                module: shaderModule,
+                entryPoint: "main_vertex",
+            },
+            fragment: {
+                module: shaderModule,
+                entryPoint: "main_fragment",
+                targets: [{
+                    format: this.targetTexture.format,
+                }],
+            },
+            primitive: {
+                cullMode: "none",
+                topology: "triangle-strip",
+            },
+        });
+
+        const bindgroupLayout = this.renderPipeline.getBindGroupLayout(0);
+
+        this.bindgroup0 = params.device.createBindGroup({
+            label: "LightsRenderer bindgroup 0",
+            layout: bindgroupLayout,
+            entries: [
+                {
+                    binding: 0,
+                    resource: { buffer: this.uniformsBufferGpu },
+                },
+                {
+                    binding: 1,
+                    resource: { buffer: this.lightsBuffer.gpuBuffer },
+                },
+                {
+                    binding: 2,
+                    resource: this.lightsTexture.texture.createView({ label: "LightsRenderer lightsTexture view" }),
+                },
+                {
+                    binding: 3,
+                    resource: params.device.createSampler({
+                        label: "LightsRenderer sampler",
+                        addressModeU: "clamp-to-edge",
+                        addressModeV: "clamp-to-edge",
+                        magFilter: params.lightsTextureProperties.filtering,
+                        minFilter: params.lightsTextureProperties.filtering,
+                    }),
+                },
+            ]
+        });
+
+        this.bindgroup1 = this.buildBindgroup1(params.albedo);
+        this.renderBundle = this.buildRenderBundle();
+    }
+
+    public computeLightsTexture(commandEncoder: GPUCommandEncoder): void {
+        this.lightsTexture.update(commandEncoder);
+    }
+
+    public render(renderpassEncoder: GPURenderPassEncoder, invertVpMatrix: wgpuMatrix.Mat4Arg): void {
+        const uniformsBufferCpu = new ArrayBuffer(80);
+        new Float32Array(uniformsBufferCpu, 0, 16).set(invertVpMatrix);
+        new Float32Array(uniformsBufferCpu, 64, 3).set(this.ambientLight);
+        this.device.queue.writeBuffer(this.uniformsBufferGpu, 0, uniformsBufferCpu);
+
+        renderpassEncoder.executeBundles([this.renderBundle]);
+    }
+
+    public setAlbedo(albedo: TextureSamplable): void {
+        this.bindgroup1 = this.buildBindgroup1(albedo);
+        this.renderBundle = this.buildRenderBundle();
+    }
+
+    public setAmbientLight(color: [number, number, number]): void {
+        this.ambientLight = [...color];
+    }
+
+    public setObstacles(segments: ReadonlyArray<LightObstacleSegment>): void {
+        this.lightsTexture.setObstacles(segments);
+    }
+
+    public destroy(): void {
+        this.uniformsBufferGpu.destroy();
+
+        this.lightsTexture.destroy();
+    }
+
+    private buildBindgroup1(albedo: TextureSamplable): GPUBindGroup {
+        return this.device.createBindGroup({
+            label: "LightsRenderer bindgroup 1",
+            layout: this.renderPipeline.getBindGroupLayout(1),
+            entries: [
+                {
+                    binding: 0,
+                    resource: albedo.view,
+                },
+                {
+                    binding: 1,
+                    resource: albedo.sampler,
+                },
+            ]
+        });
+    }
+
+    private buildRenderBundle(): GPURenderBundle {
+        const renderBundleEncoder = this.device.createRenderBundleEncoder({
+            label: "LightsRenderer renderbundle encoder",
+            colorFormats: [this.targetTexture.format],
+        });
+        renderBundleEncoder.setPipeline(this.renderPipeline);
+        renderBundleEncoder.setBindGroup(0, this.bindgroup0);
+        renderBundleEncoder.setBindGroup(1, this.bindgroup1);
+        renderBundleEncoder.draw(4);
+        return renderBundleEncoder.finish({ label: "LightsRenderer renderbundle" });
+    }
+}
+
+export {
+    LightsRenderer
+};
+

package/src/light/public-api.js

@@ -0,0 +1,20 @@
+import uuid     from '../uuid.js'
+import { vec2 } from '../deps.js'
+
+
+// public API to interact with a lighting/shadows node.
+
+export function setLights(cobalt, node, lights) {
+	node.data.lights = lights;
+	node.data.lightsBufferNeedsUpdate = true;
+}
+
+export function setAmbientLight(cobalt, node, color) {
+	node.data.lightsRenderer.setAmbientLight(color);
+}
+
+export function setOccluders(cobalt, node, segmentsList) {
+	node.data.lightsRenderer.setObstacles(segmentsList);
+	node.data.lightsTextureNeedsUpdate = true;
+}
+