@footgun/cobalt 0.6.14 → 0.7.0

package/src/sprite/sprite.js

@@ -1,262 +1,386 @@
-import * as publicAPI          from '../sprite/public-api.js'
-import { FLOAT32S_PER_SPRITE } from './constants.js'
+import getPreferredFormat from '../get-preferred-format.js'
+import * as publicAPI from './public-api.js'
+import spriteWGSL     from './sprite.wgsl'
+import round          from 'round-half-up-symmetric'
+import { mat4, vec3 } from 'wgpu-matrix'
 
 
-// an emissive sprite renderer
+// temporary variables, allocated once to avoid garbage collection
+const _tmpVec3 = vec3.create(0, 0, 0)
 
+// Packed instance layout: 48 bytes (aligned for vec4 fetch)
+const INSTANCE_STRIDE = 64;
 
-/*
-Sprites are typically dynamic; they can move, they are animated, they can be colored, rotated etc.
+// Offsets inside one instance (bytes)
+const OFF_POS = 0; // float32x2 (8B)
+const OFF_SIZE = 8; // float32x2 (8B)
+const OFF_SCALE = 16;    // float32x2 (8B)
+const OFF_TINT = 24; // float32x4 (16B)
+const OFF_SPRITEID = 40; // uint32 (4B)
+const OFF_OPACITY = 44; // float32 (4B)
+const OFF_ROT = 48; // float32 (4B)
 
-These use a `SpriteRenderPass` data structure which allows for dynamically adding/removing/updating sprites at run time.
-
-Internally, `SpriteRenderPass` objects are rendered as instanced triangles.
-Adding and removing sprites pre-sorts all triangles based on they layer they're on + the type of sprite they are.
-This lines up the data nicely for WebGpu such that they don't require any work in the render loop.
-
-Each type of sprite is rendered as 2 triangles, with a number instances for each sprite.
-This instance data is transfered to the GPU, which is then calculated in the shaders (position, rotation, scale, tinting, opacity, etc.)
-
-All of the matrix math for these sprites is done in a vertex shader, so they are fairly efficient to move, color and rotate, but it's not free.
-There is still some CPU required as the number of sprites increases.
-*/
 
 export default {
-    type: 'cobalt:sprite',
+    type: "cobalt:sprite",
     refs: [
-        { name: 'spritesheet', type: 'customResource', access: 'read' },
-        { name: 'hdr', type: 'textureView', format: 'rgba16float', access: 'write' },
-        { name: 'emissive', type: 'textureView', format: 'rgba16float', access: 'write' },
+        { name: "spritesheet", type: "customResource", access: "read" },
+        {
+            name: "color",
+            type: "textureView",
+            format: "rgba8unorm",
+            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)
+    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)
+        draw(cobalt, node, webGpuCommandEncoder);
     },
 
+    // Clean up GPU resources. Most WebGPU objects are GC-managed and don't
+    // expose destroy(); buffers/textures/query-sets do.
     onDestroy: function (cobalt, node) {
-        // any cleanup for your node should go here (releasing textures, etc.)
-        destroy(node)
+        // Explicitly destroy GPU resources that have a destroy() method
+        try { node.data.instanceBuf?.destroy(); } catch {}
+        try { node.data.spriteBuf?.destroy(); } catch {}
+        try { node.data.uniformBuffer?.destroy(); } catch {}
+
+        // These do not have destroy(); drop references to let GC reclaim
+        node.data.pipeline = null; // GPURenderPipeline
+        node.data.bindGroup = null; // GPUBindGroup
+        node.data.bindGroupLayout = null;// GPUBindGroupLayout
+
+        // CPU-side allocations
+        node.data.instanceStaging = null;
+        node.data.instanceView = null;
+        node.data.sprites.length = 0;
+        node.data.visible.length = 0;
     },
 
     onResize: function (cobalt, node) {
-        // do whatever you need when the dimensions of the renderer change (resize textures, etc.)
+        _writeSpriteBuffer(cobalt, node)
     },
 
     onViewportPosition: function (cobalt, node) {
+        _writeSpriteBuffer(cobalt, node)
     },
 
     // optional
     customFunctions: {
         ...publicAPI,
     },
-}
-
-
-// This corresponds to a WebGPU render pass.  It handles 1 sprite layer.
-async function init (cobalt, nodeData) {
-    const { device } = cobalt
-    
-    const MAX_SPRITE_COUNT = 16192  // max number of sprites in a single sprite render pass
-
-    const numInstances = MAX_SPRITE_COUNT
+};
 
-    const translateFloatCount = 2 // vec2
-    const translateSize = Float32Array.BYTES_PER_ELEMENT * translateFloatCount  // in bytes
+async function init(cobalt, nodeData) {
+    const { device } = cobalt;
 
-    const scaleFloatCount = 2 // vec2
-    const scaleSize = Float32Array.BYTES_PER_ELEMENT * scaleFloatCount  // in bytes
+    const { descs, names } = nodeData.refs.spritesheet.data.spritesheet
 
-    const tintFloatCount = 4 // vec4
-    const tintSize = Float32Array.BYTES_PER_ELEMENT * tintFloatCount // in bytes
-
-    const opacityFloatCount = 4 // vec4. technically we only need 3 floats (opacity, rotation, emissiveIntensity) but that screws up data alignment in the shader
-    const opacitySize = Float32Array.BYTES_PER_ELEMENT * opacityFloatCount  // in bytes
-
-    // instanced sprite data (scale, translation, tint, opacity, rotation, emissiveIntensity)
-    const spriteBuffer = device.createBuffer({
-        size: (translateSize + scaleSize + tintSize + opacitySize) * numInstances, // 4x4 matrix with 4 bytes per float32, per instance
-        usage: GPUBufferUsage.VERTEX | GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
-        //mappedAtCreation: true,
+    const uniformBuffer = device.createBuffer({
+        size: 64 * 2, // 4x4 matrix with 4 bytes per float32, times 2 matrices (view, projection)
+        usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
     })
 
-    const spritesheet = nodeData.refs.spritesheet.data
+    // Pack into std430-like struct (4*float*? + vec2 + vec2 → 32 bytes). We'll just write tightly as 8 floats.
+    const BYTES_PER_DESC = 8 * 4; // 8 float32s
+    const buf = new ArrayBuffer(BYTES_PER_DESC * descs.length);
+    const f32 = new Float32Array(buf);
+    for (let i=0;i<descs.length;i++){
+        const d = descs[i];
+        const base = i * 8;
+        f32[base+0] = d.UvOrigin[0];
+        f32[base+1] = d.UvOrigin[1];
+        f32[base+2] = d.UvSpan[0];
+        f32[base+3] = d.UvSpan[1];
+        f32[base+4] = d.FrameSize[0];
+        f32[base+5] = d.FrameSize[1];
+        f32[base+6] = d.CenterOffset[0];
+        f32[base+7] = d.CenterOffset[1];
+    }
 
-    const bindGroup = device.createBindGroup({
-        layout: nodeData.refs.spritesheet.data.bindGroupLayout,
+    // create buffer for sprite uv lookup
+    const spriteBuf = device.createBuffer({
+        label: "sprite desc table",
+        size: Math.max(16, buf.byteLength),
+        usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+    });
+
+    device.queue.writeBuffer(spriteBuf, 0, buf);
+
+    // --- Instance buffer (growable) ---
+    const instanceCap = 1024;
+    const instanceBuf = device.createBuffer({
+        label: "sprite instances",
+        size: INSTANCE_STRIDE * instanceCap,
+        usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+    });
+    const instanceStaging = new ArrayBuffer(INSTANCE_STRIDE * instanceCap);
+    const instanceView = new DataView(instanceStaging);
+
+    // --- Pipeline ---
+    const shader = device.createShaderModule({ code: spriteWGSL });
+    const bgl = device.createBindGroupLayout({
         entries: [
             {
                 binding: 0,
-                resource: {
-                    buffer: spritesheet.uniformBuffer
-                }
+                visibility: GPUShaderStage.VERTEX,
+                buffer: { type: "uniform" },
             },
             {
                 binding: 1,
-                resource: spritesheet.colorTexture.view
+                visibility: GPUShaderStage.FRAGMENT,
+                sampler: { type: "filtering" },
             },
             {
                 binding: 2,
-                resource: spritesheet.colorTexture.sampler
+                visibility: GPUShaderStage.FRAGMENT,
+                texture: { sampleType: "float" },
             },
             {
                 binding: 3,
-                resource: {
-                    buffer: spriteBuffer
-                }
+                visibility: GPUShaderStage.VERTEX,
+                buffer: { type: "read-only-storage" },
             },
-            {
-                binding: 4,
-                resource: spritesheet.emissiveTexture.view
-            },
-        ]
-    })
+        ],
+    });
+    const pipelineLayout = device.createPipelineLayout({
+        bindGroupLayouts: [bgl],
+    });
+
+    const instLayout = {
+        arrayStride: INSTANCE_STRIDE,
+        stepMode: "instance",
+        attributes: [
+            { shaderLocation: 0, offset: OFF_POS, format: "float32x2" },
+            { shaderLocation: 1, offset: OFF_SIZE, format: "float32x2" },
+            { shaderLocation: 2, offset: OFF_SCALE, format: "float32x2" },
+            { shaderLocation: 3, offset: OFF_TINT, format: "float32x4" },
+            { shaderLocation: 4, offset: OFF_SPRITEID, format: "uint32" },
+            { shaderLocation: 5, offset: OFF_OPACITY, format: "float32" },
+            { shaderLocation: 6, offset: OFF_ROT, format: "float32" },
+        ],
+    };
+
+    const pipeline = device.createRenderPipeline({
+        layout: pipelineLayout,
+        vertex: {
+            module: shader,
+            entryPoint: "vs_main",
+            buffers: [instLayout],
+        },
+        fragment: {
+            module: shader,
+            entryPoint: "fs_main",
+            targets: [
+                // color
+                {
+                    format: getPreferredFormat(cobalt),
+                    blend: {
+                        color: {
+                            srcFactor: 'src-alpha',
+                            dstFactor: 'one-minus-src-alpha',
+                        },
+                        alpha: {
+                            srcFactor: 'zero',
+                            dstFactor: 'one'
+                        }
+                    }
+                },
+            ],
+        },
+        primitive: { topology: "triangle-strip", cullMode: "none" },
+        multisample: { count: 1 },
+    });
+
+    const bindGroupLayout = bgl;
 
-    return {
-        // instancedDrawCalls is used to actually perform draw calls within the render pass
-        // layout is interleaved with baseVtxIdx (the sprite type), and instanceCount (how many sprites)
-        // [
-        //    baseVtxIdx0, instanceCount0,
-        //    baseVtxIdx1, instanceCount1,
-        //    ...
-        // ]
-        instancedDrawCalls: new Uint32Array(MAX_SPRITE_COUNT * 2),
-        instancedDrawCallCount: 0,
+    const bindGroup = device.createBindGroup({
+        layout: bgl,
+        entries: [
+            // Uniform buffer (view + proj matrices)
+            { binding: 0, resource: { buffer: uniformBuffer } },
 
-        bindGroup,
-        spriteBuffer,
+            { binding: 1, resource: nodeData.refs.spritesheet.data.colorTexture.sampler },
+            { binding: 2, resource: nodeData.refs.spritesheet.data.colorTexture.view },
+            { binding: 3, resource: { buffer: spriteBuf } },
+        ],
+    });
 
-        // actual sprite instance data. ordered by layer, then sprite type
-        // this is used to update the spriteBuffer.
-        spriteData: new Float32Array(MAX_SPRITE_COUNT * FLOAT32S_PER_SPRITE), 
-        spriteCount: 0,
+    return {
+        sprites: [ ],
+        visible: [ ],
+        visibleCount: 0,
+        viewRect: { x: 0, y: 0, w: 0, h: 0 },
+
+        spriteBuf,
+        uniformBuffer,
 
-        spriteIndices: new Map(), // key is spriteId, value is insert index of the sprite. e.g., 0 means 1st sprite , 1 means 2nd sprite, etc.
+        instanceCap,
+        instanceView,
+        instanceBuf,
+        instanceStaging,
 
-        // when a sprite is changed the renderpass is dirty, and should have it's instance data copied to the gpu
-        dirty: false,
+        pipeline,
+        bindGroup,
     }
 }
 
 
-function draw (cobalt, node, commandEncoder) {
-    const { device } = cobalt
+function ensureCapacity (cobalt, node, nInstances) {
 
-    // on the first render, we should clear the color attachment.
-    // otherwise load it, so multiple sprite passes can build up data in the color and emissive textures
-	const loadOp = node.options.loadOp || 'load'
+    const { instanceCap } = node.data
 
-    if (node.data.dirty) {
-        _rebuildSpriteDrawCalls(node.data)
-        node.data.dirty = false
-    }
+    if (nInstances <= instanceCap)
+        return;
 
-    // TODO: somehow spriteCount can be come negative?! for now just guard against this
-    if (node.data.spriteCount > 0) {
-        const writeLength = node.data.spriteCount * FLOAT32S_PER_SPRITE * Float32Array.BYTES_PER_ELEMENT
-        device.queue.writeBuffer(node.data.spriteBuffer, 0, node.data.spriteData.buffer, 0, writeLength)
-    }
+    let newCap = instanceCap
+    if (newCap === 0)
+        newCap = 1024;
 
-    const renderpass = commandEncoder.beginRenderPass({
-        label: 'sprite',
-        colorAttachments: [
-            // color
-            {
-                view: node.refs.hdr.data.view,
-                clearValue: cobalt.clearValue,
-                loadOp,
-                storeOp: 'store'
-            },
+    while (newCap < nInstances)
+        newCap *= 2;
 
-            // emissive
-            {
-                view: node.refs.emissive.data.view,
-                clearValue: cobalt.clearValue,
-                loadOp: 'clear',
-                storeOp: 'store'
-            }
-        ]
-    })
+    node.data.instanceBuf.destroy();
+    node.data.instanceBuf = cobalt.device.createBuffer({
+        size: INSTANCE_STRIDE * newCap,
+        usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+    });
 
-    renderpass.setPipeline(node.refs.spritesheet.data.pipeline)
-    renderpass.setBindGroup(0, node.data.bindGroup)
-    renderpass.setVertexBuffer(0, node.refs.spritesheet.data.quads.buffer)
-
-    // write sprite instance data into the storage buffer, sorted by sprite type. e.g.,
-    //      renderpass.draw(6,  1,  0, 0)  //  1 hero instance
-    //      renderpass.draw(6, 14,  6, 1)  // 14 bat instances
-    //      renderpass.draw(6,  5, 12, 15) //  5 bullet instances
-
-    // render each sprite type's instances
-    const vertexCount = 6
-    let baseInstanceIdx = 0
-
-    for (let i=0; i < node.data.instancedDrawCallCount; i++) {
-        // [
-        //    baseVtxIdx0, instanceCount0,
-        //    baseVtxIdx1, instanceCount1,
-        //    ...
-        // ]
-        const baseVertexIdx = node.data.instancedDrawCalls[i*2  ] * vertexCount
-        const instanceCount = node.data.instancedDrawCalls[i*2+1]
-        renderpass.draw(vertexCount, instanceCount, baseVertexIdx, baseInstanceIdx)
-        baseInstanceIdx += instanceCount
-    }
-
-    renderpass.end()
+    node.data.instanceStaging = new ArrayBuffer(INSTANCE_STRIDE * newCap);
+    node.data.instanceView = new DataView(node.data.instanceStaging);
+    node.data.instanceCap = newCap;
 }
 
 
-// build instancedDrawCalls
-function _rebuildSpriteDrawCalls (renderPass) {
-    let currentSpriteType = -1
-    let instanceCount = 0
-    renderPass.instancedDrawCallCount = 0
+function draw (cobalt, node, commandEncoder) {
+
+    const { device, context } = cobalt;
+
+    const { instanceView, instanceBuf, instanceStaging, pipeline, bindGroup } = node.data
 
-    for (let i=0; i < renderPass.spriteCount; i++) {
+    const { descs } = node.refs.spritesheet.data.spritesheet
 
-        // 12th float is order. lower bits 0-15 are spriteType, bits 16-23 are sprite Z index
-        const spriteType = renderPass.spriteData[i * FLOAT32S_PER_SPRITE + 11] & 0xFFFF
+    const viewRect = node.data.viewRect
 
-        if (spriteType !== currentSpriteType) {
-            if (instanceCount > 0) {
-                renderPass.instancedDrawCalls[renderPass.instancedDrawCallCount * 2]     = currentSpriteType
-                renderPass.instancedDrawCalls[renderPass.instancedDrawCallCount * 2 + 1] = instanceCount
-                renderPass.instancedDrawCallCount++
-            }
+    viewRect.x = cobalt.viewport.position[0]
+    viewRect.y = cobalt.viewport.position[1]
+    viewRect.w = cobalt.viewport.width
+    viewRect.h = cobalt.viewport.height
+ 
+    node.data.visibleCount = 0
 
-            currentSpriteType = spriteType
-            instanceCount = 0
+    for (const s of node.data.sprites) {
+        const d = descs[s.spriteID];
+        if (!d)
+            continue;
+
+        // avoid sprite viewport culling when drawing in screenspace mode (typically ui/hud layers)
+        if (!node.options.isScreenSpace) {
+            const sx = (d.FrameSize[0] * (s.sizeX) * s.scale[0]) * 0.5;
+            const sy = (d.FrameSize[1] * (s.sizeY) * s.scale[1]) * 0.5;
+            const rad = Math.hypot(sx, sy);
+            const x = s.position[0], y = s.position[1];
+            if (x + rad < viewRect.x || x - rad > viewRect.x + viewRect.w || y + rad < viewRect.y || y - rad > viewRect.y + viewRect.h)
+                continue
         }
 
-        instanceCount++
+        node.data.visible[node.data.visibleCount] = s
+        node.data.visibleCount++
     }
 
-    if (instanceCount > 0) {
-        renderPass.instancedDrawCalls[renderPass.instancedDrawCallCount * 2]     = currentSpriteType
-        renderPass.instancedDrawCalls[renderPass.instancedDrawCallCount * 2 + 1] = instanceCount
-        renderPass.instancedDrawCallCount++
+    ensureCapacity(cobalt, node, node.data.visibleCount)
+
+    // Pack instances into staging buffer
+    for (let i=0; i < node.data.visibleCount; i++){
+        const base = i * INSTANCE_STRIDE;
+        const s = node.data.visible[i];
+        const tint = s.tint;
+
+        instanceView.setFloat32(base + OFF_POS + 0, s.position[0], true);
+        instanceView.setFloat32(base + OFF_POS + 4, s.position[1], true);
+        
+        instanceView.setFloat32(base + OFF_SIZE + 0, s.sizeX, true);
+        instanceView.setFloat32(base + OFF_SIZE + 4, s.sizeY, true);
+
+        instanceView.setFloat32(base + OFF_SCALE + 0, s.scale[0], true);
+        instanceView.setFloat32(base + OFF_SCALE + 4, s.scale[1], true);
+
+        instanceView.setFloat32(base + OFF_TINT + 0, tint[0], true);
+        instanceView.setFloat32(base + OFF_TINT + 4, tint[1], true);
+        instanceView.setFloat32(base + OFF_TINT + 8, tint[2], true);
+        instanceView.setFloat32(base + OFF_TINT + 12, tint[3], true);
+       
+        instanceView.setUint32(base + OFF_SPRITEID, s.spriteID >>> 0, true);
+
+        instanceView.setFloat32(base + OFF_OPACITY, s.opacity, true);
+
+        instanceView.setFloat32(base + OFF_ROT, s.rotation, true);
     }
+
+    device.queue.writeBuffer(instanceBuf, 0, instanceStaging, 0, node.data.visibleCount * INSTANCE_STRIDE);
+
+    const loadOp = node.options.loadOp || 'load'
+
+    const pass = commandEncoder.beginRenderPass({
+        label: "sprite renderpass",
+        colorAttachments: [
+            // color
+            {
+                view: node.refs.color,
+                clearValue: cobalt.clearValue,
+                loadOp: loadOp,
+                storeOp: 'store',
+            },
+        ],
+    });
+
+    pass.setPipeline(pipeline);
+    pass.setBindGroup(0, bindGroup);
+    pass.setVertexBuffer(0, instanceBuf);
+    if (node.data.visibleCount)
+        pass.draw(4, node.data.visibleCount, 0, 0); // triangle strip, 4 verts per instance
+    pass.end();
 }
 
 
-function destroy (node) {
-    node.data.instancedDrawCalls = null
-    
-    node.data.bindGroup = null
+function _writeSpriteBuffer (cobalt, node) {
 
-    node.data.spriteBuffer.destroy()
-    node.data.spriteBuffer = null
+    const { device, viewport } = cobalt
 
-    node.data.spriteData = null
-    node.data.spriteIndices.clear()
-    node.data.spriteIndices = null
+    const GAME_WIDTH = viewport.width / viewport.zoom
+    const GAME_HEIGHT = viewport.height / viewport.zoom
+
+    //                         left          right    bottom        top     near     far
+    const projection = mat4.ortho(0,    GAME_WIDTH,   GAME_HEIGHT,    0,   -10.0,   10.0)
+
+    // set 3d camera position
+    if (!!node.options.isScreenSpace) {
+        vec3.set(0, 0, 0, _tmpVec3)
+    }
+    else {
+        // TODO: if this doesn't introduce jitter into the crossroads render, remove this disabled code entirely.
+        //
+        // I'm disabling the rounding because I think it fails in cases where units are not expressed in pixels
+        // e.g., most physics engines operate on meters, not pixels, so we don't want to round to the nearest integer as that 
+        // probably isn't high enough resolution. That would mean the camera could be snapped by up to 0.5 meters
+        // in that case. I think the better solution for expressing camera position in pixels is to round before calling
+        // cobalt.setViewportPosition(...)
+        //
+        vec3.set(-round(viewport.position[0]), -round(viewport.position[1]), 0, _tmpVec3)
+        //vec3.set(-viewport.position[0], -viewport.position[1], 0, _tmpVec3)
+    }  
+
+    const view = mat4.translation(_tmpVec3)
+
+    device.queue.writeBuffer(node.data.uniformBuffer, 0, view.buffer)
+    device.queue.writeBuffer(node.data.uniformBuffer, 64, projection.buffer)
 }