@sadhaka/loom-engine 0.11.0 → 0.12.0

package/dist/renderer/sprite-batcher.js

@@ -0,0 +1,146 @@
+// SpriteBatcher - per-frame instance accumulator for the WebGL2 path.
+//
+// Pure CPU-side: holds a growable Float32Array of per-instance data
+// and tracks the current batch key (atlas + blend mode). submit()
+// appends; if the batch key changes it flushes the current run via
+// a handler the device wires up at construction. flush() also runs
+// from endFrame to drain any pending instances.
+//
+// 12 floats per instance:
+//   [origin.x, origin.y, size.x, size.y,
+//    uv0.x, uv0.y, uv1.x, uv1.y,
+//    tint.r, tint.g, tint.b, tint.a]
+//
+// Why: a single drawArraysInstanced call covers the whole batch with
+// one CPU->GPU upload of the instance buffer. Atlas swap forces a
+// flush because the bound texture changes; blend-mode swap forces a
+// flush because gl.blendFunc state changes.
+//
+// Submission order is preserved within a batch. Higher-level systems
+// (SpriteRenderSystem) sort globally before submitting; the batcher
+// trusts that order. Subsequent atlas batches reset the order chain
+// but never mix across atlases - that is intentional, the cost is
+// borne by the consumer (sort by atlas then by depth if global
+// ordering across atlases matters).
+export const FLOATS_PER_INSTANCE = 12;
+const INITIAL_CAPACITY = 1024;
+export class SpriteBatcher {
+    // Instance data buffer. Grows by doubling when capacity is hit.
+    // Backing typed-array stays referentially stable when count is
+    // below capacity to avoid per-frame allocation.
+    buffer;
+    capacity;
+    // Current run state.
+    count = 0;
+    currentAtlas = null;
+    currentBlend = 'alpha';
+    // Flush statistics. Reset at beginFrame; surfaced by getStats for
+    // tests + diagnostics.
+    flushCount = 0;
+    instanceTotal = 0;
+    flushHandler;
+    constructor(flushHandler, initialCapacity = INITIAL_CAPACITY) {
+        this.flushHandler = flushHandler;
+        this.capacity = Math.max(64, initialCapacity);
+        this.buffer = new Float32Array(this.capacity * FLOATS_PER_INSTANCE);
+    }
+    // Reset for a new frame. Counts go to zero; batch state cleared.
+    // Flushes any pending instances first as a safety net (endFrame
+    // should have done this, but we belt-and-suspenders to keep the
+    // device contract clean).
+    beginFrame() {
+        if (this.count > 0 && this.currentAtlas) {
+            this.flush();
+        }
+        this.count = 0;
+        this.currentAtlas = null;
+        this.currentBlend = 'alpha';
+        this.flushCount = 0;
+        this.instanceTotal = 0;
+    }
+    // Submit one instance to the batcher. Triggers flush if the
+    // (atlas, blendMode) key differs from the current batch.
+    submit(atlas, blendMode, originX, originY, sizeX, sizeY, u0, v0, u1, v1, tintR, tintG, tintB, tintA) {
+        if (atlas.released)
+            return;
+        if (this.currentAtlas !== atlas || this.currentBlend !== blendMode) {
+            // Atlas / blend change forces a batch break. Flush the current
+            // run before installing the new key.
+            if (this.count > 0 && this.currentAtlas) {
+                this.flush();
+            }
+            this.currentAtlas = atlas;
+            this.currentBlend = blendMode;
+        }
+        if (this.count >= this.capacity) {
+            this.grow();
+        }
+        var off = this.count * FLOATS_PER_INSTANCE;
+        var b = this.buffer;
+        b[off + 0] = originX;
+        b[off + 1] = originY;
+        b[off + 2] = sizeX;
+        b[off + 3] = sizeY;
+        b[off + 4] = u0;
+        b[off + 5] = v0;
+        b[off + 6] = u1;
+        b[off + 7] = v1;
+        b[off + 8] = tintR;
+        b[off + 9] = tintG;
+        b[off + 10] = tintB;
+        b[off + 11] = tintA;
+        this.count++;
+    }
+    // Flush the current run via the device-supplied handler. No-op if
+    // nothing pending or no atlas selected.
+    flush() {
+        if (this.count === 0 || !this.currentAtlas)
+            return;
+        var atlas = this.currentAtlas;
+        var blend = this.currentBlend;
+        var n = this.count;
+        this.flushHandler(atlas, blend, this.buffer, n);
+        this.flushCount++;
+        this.instanceTotal += n;
+        this.count = 0;
+    }
+    // Final drain - call from endFrame to push the last partial batch.
+    endFrame() {
+        if (this.count > 0 && this.currentAtlas) {
+            this.flush();
+        }
+    }
+    // Diagnostics. Returned object is owned by the caller; we copy
+    // into it to avoid allocating per-frame.
+    getStats(out) {
+        out.flushCount = this.flushCount;
+        out.instanceTotal = this.instanceTotal;
+        out.capacity = this.capacity;
+    }
+    // Test-only inspection helpers. Not part of the public API but
+    // exported so the test file can assert internal state without
+    // brittle reflection.
+    _peekCount() {
+        return this.count;
+    }
+    _peekCurrentAtlas() {
+        return this.currentAtlas;
+    }
+    _peekCurrentBlend() {
+        return this.currentBlend;
+    }
+    _peekBuffer() {
+        return this.buffer;
+    }
+    // Grow by doubling. Float32Array does not resize in place; we
+    // allocate a new buffer and copy the live prefix. Triggered when
+    // submit overruns capacity.
+    grow() {
+        var next = this.capacity * 2;
+        var b = new Float32Array(next * FLOATS_PER_INSTANCE);
+        b.set(this.buffer.subarray(0, this.count * FLOATS_PER_INSTANCE));
+        this.buffer = b;
+        this.capacity = next;
+    }
+}
+//# sourceMappingURL=sprite-batcher.js.map

package/dist/renderer/sprite-batcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sprite-batcher.js","sourceRoot":"","sources":["../../src/renderer/sprite-batcher.ts"],"names":[],"mappings":"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"}

package/dist/renderer/texture-atlas.d.ts

@@ -0,0 +1,24 @@
+import type { AtlasDescriptor } from './graphics-device.js';
+export declare class TextureAtlas {
+    texture: WebGLTexture | null;
+    readonly width: number;
+    readonly height: number;
+    readonly uvRects: Float32Array;
+    readonly frameSizes: Float32Array;
+    readonly frameCount: number;
+    readonly name: string;
+    private sourceImage;
+    released: boolean;
+    constructor(gl: WebGL2RenderingContext | null, desc: AtlasDescriptor);
+    upload(gl: WebGL2RenderingContext): void;
+    bind(gl: WebGL2RenderingContext): void;
+    handleContextLoss(): void;
+    dispose(gl: WebGL2RenderingContext | null): void;
+    lookupUVRect(frame: number, out: Float32Array, offset: number): boolean;
+    lookupFrameSize(frame: number, out: {
+        w: number;
+        h: number;
+    }): boolean;
+}
+export declare function makeParticleDiscAtlas(gl: WebGL2RenderingContext | null): TextureAtlas | null;
+//# sourceMappingURL=texture-atlas.d.ts.map

package/dist/renderer/texture-atlas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"texture-atlas.d.ts","sourceRoot":"","sources":["../../src/renderer/texture-atlas.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,qBAAa,YAAY;IAGvB,OAAO,EAAE,YAAY,GAAG,IAAI,CAAQ;IAKpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAMxB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAI/B,QAAQ,CAAC,UAAU,EAAE,YAAY,CAAC;IAElC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAG5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAItB,OAAO,CAAC,WAAW,CAAqD;IAIxE,QAAQ,EAAE,OAAO,CAAS;gBAEd,EAAE,EAAE,sBAAsB,GAAG,IAAI,EAAE,IAAI,EAAE,eAAe;IAmCpE,MAAM,CAAC,EAAE,EAAE,sBAAsB,GAAG,IAAI;IAkCxC,IAAI,CAAC,EAAE,EAAE,sBAAsB,GAAG,IAAI;IAMtC,iBAAiB,IAAI,IAAI;IAIzB,OAAO,CAAC,EAAE,EAAE,sBAAsB,GAAG,IAAI,GAAG,IAAI;IAWhD,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO;IAWvE,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO;CAOvE;AASD,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,sBAAsB,GAAG,IAAI,GAChC,YAAY,GAAG,IAAI,CAqBrB"}

package/dist/renderer/texture-atlas.js

@@ -0,0 +1,173 @@
+// TextureAtlas - GL texture wrapper for the WebGL2 backend.
+//
+// Wraps a single GL texture plus a frame-rect lookup table. The
+// device passes an AtlasDescriptor at registerAtlas time; we upload
+// the source image as a texture and pre-compute UV rects per frame
+// so drawSprite/drawTile can look up by frame index without a divide
+// in the hot path.
+//
+// Texture coordinates use UNPACK_FLIP_Y_WEBGL=true on upload so frame
+// (x, y) - which the AtlasDescriptor specifies in top-left source
+// pixel coords - maps directly to UVs of (x/W, y/H, (x+w)/W, (y+h)/H)
+// in the GL texture. The shader uses the unit-quad vertex (0..1) as
+// the mix factor between (u0, v0) and (u1, v1).
+//
+// Context-loss handling: the device watches the canvas for
+// 'webglcontextlost' and calls handleContextLoss() on every atlas
+// to mark them invalid. On 'webglcontextrestored' the device calls
+// rehydrate(gl) which re-uploads the cached source image.
+export class TextureAtlas {
+    // GL texture object. Null while the context is lost or before
+    // upload. drawSprite paths must check before binding.
+    texture = null;
+    // Atlas dimensions in pixels - cached because the descriptor's
+    // image may be reclaimed from layout flow but the dims do not
+    // change.
+    width;
+    height;
+    // Pre-computed UV rects. Layout: 4 floats per frame
+    // [u0, v0, u1, v1]. Indexed by frame number * 4. Storing as a
+    // single Float32Array keeps lookup branchless and cache-friendly
+    // when the batcher iterates many sprites.
+    uvRects;
+    // Pre-computed frame sizes in pixels. Layout: 2 floats per frame
+    // [w, h]. drawSprite multiplies by camera zoom.
+    frameSizes;
+    frameCount;
+    // Optional debug name for logging.
+    name;
+    // Source image kept for context-restore rehydrate. AtlasDescriptor
+    // owns the image lifetime; we hold a reference but never mutate.
+    sourceImage;
+    // Marker to skip use-after-release. releaseAtlas sets this; the
+    // device's draw paths bail out on released atlases.
+    released = false;
+    constructor(gl, desc) {
+        this.sourceImage = desc.image;
+        this.name = desc.name ?? 'unnamed';
+        // Image dimensions vary by source type; ImageBitmap, HTMLImage-
+        // Element and HTMLCanvasElement all expose width/height the same
+        // way.
+        this.width = desc.image.width;
+        this.height = desc.image.height;
+        this.frameCount = desc.frames.length;
+        this.uvRects = new Float32Array(this.frameCount * 4);
+        this.frameSizes = new Float32Array(this.frameCount * 2);
+        var W = this.width || 1;
+        var H = this.height || 1;
+        for (var i = 0; i < this.frameCount; i++) {
+            var f = desc.frames[i];
+            if (!f)
+                continue;
+            var base4 = i * 4;
+            var base2 = i * 2;
+            this.uvRects[base4 + 0] = f.x / W;
+            this.uvRects[base4 + 1] = f.y / H;
+            this.uvRects[base4 + 2] = (f.x + f.w) / W;
+            this.uvRects[base4 + 3] = (f.y + f.h) / H;
+            this.frameSizes[base2 + 0] = f.w;
+            this.frameSizes[base2 + 1] = f.h;
+        }
+        if (gl) {
+            this.upload(gl);
+        }
+    }
+    // Upload source image to a GL texture. Used at construction and on
+    // context-restore. Idempotent: deletes any prior texture first.
+    upload(gl) {
+        if (this.released)
+            return;
+        if (this.texture) {
+            gl.deleteTexture(this.texture);
+            this.texture = null;
+        }
+        var tex = gl.createTexture();
+        if (!tex) {
+            // createTexture returns null only on context-lost; bail and
+            // leave this.texture null. The device will retry on restore.
+            return;
+        }
+        gl.bindTexture(gl.TEXTURE_2D, tex);
+        gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
+        gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, false);
+        // Pixel-art friendly defaults to match Canvas2DDevice's
+        // imageSmoothingEnabled = false. Consumers can override after
+        // registerAtlas via the returned handle if they need bilinear.
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+        gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, this.sourceImage);
+        this.texture = tex;
+    }
+    // Bind for sampling. Caller has the active texture unit set.
+    bind(gl) {
+        gl.bindTexture(gl.TEXTURE_2D, this.texture);
+    }
+    // Mark texture invalid - context lost. The GL object is already
+    // gone; we just clear the JS reference so subsequent draws skip.
+    handleContextLoss() {
+        this.texture = null;
+    }
+    dispose(gl) {
+        this.released = true;
+        if (gl && this.texture) {
+            gl.deleteTexture(this.texture);
+        }
+        this.texture = null;
+    }
+    // Look up the UV rect for a frame index. Returns false if the
+    // frame is out of range so the caller can skip the draw safely.
+    // out is filled with [u0, v0, u1, v1].
+    lookupUVRect(frame, out, offset) {
+        if (frame < 0 || frame >= this.frameCount)
+            return false;
+        var base = frame * 4;
+        out[offset + 0] = this.uvRects[base + 0] ?? 0;
+        out[offset + 1] = this.uvRects[base + 1] ?? 0;
+        out[offset + 2] = this.uvRects[base + 2] ?? 0;
+        out[offset + 3] = this.uvRects[base + 3] ?? 0;
+        return true;
+    }
+    // Look up the frame width/height in pixels.
+    lookupFrameSize(frame, out) {
+        if (frame < 0 || frame >= this.frameCount)
+            return false;
+        var base = frame * 2;
+        out.w = this.frameSizes[base + 0] ?? 0;
+        out.h = this.frameSizes[base + 1] ?? 0;
+        return true;
+    }
+}
+// Build a tiny built-in atlas containing a single soft-disc frame
+// for drawParticle. 64 x 64 RGBA, white center fading to transparent
+// edge. Returned wrapped in a TextureAtlas with one frame at index 0.
+//
+// Lazy-built on first drawParticle call. Headless / Node tests pass
+// gl=null; the descriptor is still valid and the GL upload happens
+// later when (if) the context is provided.
+export function makeParticleDiscAtlas(gl) {
+    if (typeof document === 'undefined')
+        return null;
+    var size = 64;
+    var c = document.createElement('canvas');
+    c.width = size;
+    c.height = size;
+    var ctx = c.getContext('2d');
+    if (!ctx)
+        return null;
+    var center = size / 2;
+    var grad = ctx.createRadialGradient(center, center, 0, center, center, center);
+    grad.addColorStop(0, 'rgba(255,255,255,1)');
+    grad.addColorStop(1, 'rgba(255,255,255,0)');
+    ctx.fillStyle = grad;
+    ctx.beginPath();
+    ctx.arc(center, center, center, 0, Math.PI * 2);
+    ctx.fill();
+    return new TextureAtlas(gl, {
+        image: c,
+        frames: [{ x: 0, y: 0, w: size, h: size }],
+        name: 'particle-disc',
+    });
+}
+//# sourceMappingURL=texture-atlas.js.map

package/dist/renderer/texture-atlas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"texture-atlas.js","sourceRoot":"","sources":["../../src/renderer/texture-atlas.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAC5D,EAAE;AACF,gEAAgE;AAChE,oEAAoE;AACpE,mEAAmE;AACnE,qEAAqE;AACrE,mBAAmB;AACnB,EAAE;AACF,sEAAsE;AACtE,kEAAkE;AAClE,sEAAsE;AACtE,oEAAoE;AACpE,gDAAgD;AAChD,EAAE;AACF,2DAA2D;AAC3D,kEAAkE;AAClE,mEAAmE;AACnE,0DAA0D;AAI1D,MAAM,OAAO,YAAY;IACvB,8DAA8D;IAC9D,sDAAsD;IACtD,OAAO,GAAwB,IAAI,CAAC;IAEpC,+DAA+D;IAC/D,8DAA8D;IAC9D,UAAU;IACD,KAAK,CAAS;IACd,MAAM,CAAS;IAExB,oDAAoD;IACpD,8DAA8D;IAC9D,iEAAiE;IACjE,0CAA0C;IACjC,OAAO,CAAe;IAE/B,iEAAiE;IACjE,gDAAgD;IACvC,UAAU,CAAe;IAEzB,UAAU,CAAS;IAE5B,mCAAmC;IAC1B,IAAI,CAAS;IAEtB,mEAAmE;IACnE,iEAAiE;IACzD,WAAW,CAAqD;IAExE,gEAAgE;IAChE,oDAAoD;IACpD,QAAQ,GAAY,KAAK,CAAC;IAE1B,YAAY,EAAiC,EAAE,IAAqB;QAClE,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,SAAS,CAAC;QACnC,gEAAgE;QAChE,iEAAiE;QACjE,OAAO;QACP,IAAI,CAAC,KAAK,GAAI,IAAI,CAAC,KAA2B,CAAC,KAAK,CAAC;QACrD,IAAI,CAAC,MAAM,GAAI,IAAI,CAAC,KAA4B,CAAC,MAAM,CAAC;QAExD,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;QACrC,IAAI,CAAC,OAAO,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC;QACrD,IAAI,CAAC,UAAU,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC;QAExD,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC;QACxB,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;QACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC,EAAE,EAAE,CAAC;YACzC,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YACvB,IAAI,CAAC,CAAC;gBAAE,SAAS;YACjB,IAAI,KAAK,GAAG,CAAC,GAAG,CAAC,CAAC;YAClB,IAAI,KAAK,GAAG,CAAC,GAAG,CAAC,CAAC;YAClB,IAAI,CAAC,OAAO,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YAClC,IAAI,CAAC,OAAO,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YAClC,IAAI,CAAC,OAAO,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YAC1C,IAAI,CAAC,OAAO,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YAC1C,IAAI,CAAC,UAAU,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACjC,IAAI,CAAC,UAAU,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACnC,CAAC;QAED,IAAI,EAAE,EAAE,CAAC;YACP,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IAED,mEAAmE;IACnE,gEAAgE;IAChE,MAAM,CAAC,EAA0B;QAC/B,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO;QAC1B,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC/B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACtB,CAAC;QACD,IAAI,GAAG,GAAG,EAAE,CAAC,aAAa,EAAE,CAAC;QAC7B,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,4DAA4D;YAC5D,6DAA6D;YAC7D,OAAO;QACT,CAAC;QACD,EAAE,CAAC,WAAW,CAAC,EAAE,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;QACnC,EAAE,CAAC,WAAW,CAAC,EAAE,CAAC,mBAAmB,EAAE,IAAI,CAAC,CAAC;QAC7C,EAAE,CAAC,WAAW,CAAC,EAAE,CAAC,8BAA8B,EAAE,KAAK,CAAC,CAAC;QACzD,wDAAwD;QACxD,8DAA8D;QAC9D,+DAA+D;QAC/D,EAAE,CAAC,aAAa,CAAC,EAAE,CAAC,UAAU,EAAE,EAAE,CAAC,kBAAkB,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC;QACnE,EAAE,CAAC,aAAa,CAAC,EAAE,CAAC,UAAU,EAAE,EAAE,CAAC,kBAAkB,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC;QACnE,EAAE,CAAC,aAAa,CAAC,EAAE,CAAC,UAAU,EAAE,EAAE,CAAC,cAAc,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC;QACrE,EAAE,CAAC,aAAa,CAAC,EAAE,CAAC,UAAU,EAAE,EAAE,CAAC,cAAc,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC;QACrE,EAAE,CAAC,UAAU,CACX,EAAE,CAAC,UAAU,EACb,CAAC,EACD,EAAE,CAAC,IAAI,EACP,EAAE,CAAC,IAAI,EACP,EAAE,CAAC,aAAa,EAChB,IAAI,CAAC,WAA6B,CACnC,CAAC;QACF,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC;IACrB,CAAC;IAED,6DAA6D;IAC7D,IAAI,CAAC,EAA0B;QAC7B,EAAE,CAAC,WAAW,CAAC,EAAE,CAAC,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAC9C,CAAC;IAED,gEAAgE;IAChE,iEAAiE;IACjE,iBAAiB;QACf,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;IACtB,CAAC;IAED,OAAO,CAAC,EAAiC;QACvC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,IAAI,EAAE,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACvB,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACjC,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;IACtB,CAAC;IAED,8DAA8D;IAC9D,gEAAgE;IAChE,uCAAuC;IACvC,YAAY,CAAC,KAAa,EAAE,GAAiB,EAAE,MAAc;QAC3D,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,UAAU;YAAE,OAAO,KAAK,CAAC;QACxD,IAAI,IAAI,GAAG,KAAK,GAAG,CAAC,CAAC;QACrB,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;QAC9C,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;QAC9C,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;QAC9C,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;QAC9C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,4CAA4C;IAC5C,eAAe,CAAC,KAAa,EAAE,GAA6B;QAC1D,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,UAAU;YAAE,OAAO,KAAK,CAAC;QACxD,IAAI,IAAI,GAAG,KAAK,GAAG,CAAC,CAAC;QACrB,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;QACvC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;QACvC,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAED,kEAAkE;AAClE,qEAAqE;AACrE,sEAAsE;AACtE,EAAE;AACF,oEAAoE;AACpE,mEAAmE;AACnE,2CAA2C;AAC3C,MAAM,UAAU,qBAAqB,CACnC,EAAiC;IAEjC,IAAI,OAAO,QAAQ,KAAK,WAAW;QAAE,OAAO,IAAI,CAAC;IACjD,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,IAAI,CAAC,GAAG,QAAQ,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;IACzC,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC;IACf,CAAC,CAAC,MAAM,GAAG,IAAI,CAAC;IAChB,IAAI,GAAG,GAAG,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,IAAI,MAAM,GAAG,IAAI,GAAG,CAAC,CAAC;IACtB,IAAI,IAAI,GAAG,GAAG,CAAC,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/E,IAAI,CAAC,YAAY,CAAC,CAAC,EAAE,qBAAqB,CAAC,CAAC;IAC5C,IAAI,CAAC,YAAY,CAAC,CAAC,EAAE,qBAAqB,CAAC,CAAC;IAC5C,GAAG,CAAC,SAAS,GAAG,IAAI,CAAC;IACrB,GAAG,CAAC,SAAS,EAAE,CAAC;IAChB,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IAChD,GAAG,CAAC,IAAI,EAAE,CAAC;IACX,OAAO,IAAI,YAAY,CAAC,EAAE,EAAE;QAC1B,KAAK,EAAE,CAAC;QACR,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC;QAC1C,IAAI,EAAE,eAAe;KACtB,CAAC,CAAC;AACL,CAAC"}

package/dist/renderer/webgl2-device.d.ts

@@ -0,0 +1,53 @@
+import type { ColorRGBA } from '../util/color.js';
+import { type IGraphicsDevice, type AtlasHandle, type AtlasDescriptor, type TextStyle } from './graphics-device.js';
+import { type CameraView } from './camera.js';
+export declare class WebGL2Device implements IGraphicsDevice {
+    readonly canvas: HTMLCanvasElement;
+    readonly viewportWidth: number;
+    readonly viewportHeight: number;
+    private gl;
+    private program;
+    private vao;
+    private quadVBO;
+    private instanceVBO;
+    private instanceVBOBytes;
+    private atlases;
+    private nextAtlasHandle;
+    private camera;
+    private drawCallCount;
+    private batcher;
+    private particleAtlas;
+    private textCache;
+    private contextLost;
+    private boundOnLost;
+    private boundOnRestored;
+    private lastUpload;
+    constructor(canvas: HTMLCanvasElement, gl?: WebGL2RenderingContext);
+    private initGLResources;
+    private compileProgram;
+    private handleContextLoss;
+    private handleContextRestored;
+    beginFrame(): void;
+    endFrame(): void;
+    setCamera(cam: Readonly<CameraView>): void;
+    registerAtlas(desc: AtlasDescriptor): AtlasHandle;
+    releaseAtlas(handle: AtlasHandle): void;
+    drawSprite(worldX: number, worldY: number, worldZ: number, atlas: AtlasHandle, frame: number, tint?: Readonly<ColorRGBA>): void;
+    drawTile(tileX: number, tileY: number, atlas: AtlasHandle, frame: number): void;
+    drawText(worldX: number, worldY: number, text: string, style: TextStyle): void;
+    drawParticle(worldX: number, worldY: number, worldZ: number, size: number, color: Readonly<ColorRGBA>, additive: boolean): void;
+    getDrawCallCount(): number;
+    dispose(): void;
+    getBatcherStats(): {
+        flushCount: number;
+        instanceTotal: number;
+        capacity: number;
+    };
+    _peekLastUpload(): {
+        count: number;
+        floats: number;
+    };
+    private executeFlush;
+    private getOrBakeText;
+}
+//# sourceMappingURL=webgl2-device.d.ts.map

package/dist/renderer/webgl2-device.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webgl2-device.d.ts","sourceRoot":"","sources":["../../src/renderer/webgl2-device.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,SAAS,EACf,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,UAAU,EAEhB,MAAM,aAAa,CAAC;AAkDrB,qBAAa,YAAa,YAAW,eAAe;IAClD,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC,OAAO,CAAC,EAAE,CAAyB;IACnC,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,GAAG,CAAuC;IAClD,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,WAAW,CAA4B;IAG/C,OAAO,CAAC,gBAAgB,CAAa;IAErC,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,eAAe,CAAa;IAEpC,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,aAAa,CAAa;IAElC,OAAO,CAAC,OAAO,CAAgB;IAG/B,OAAO,CAAC,aAAa,CAA6B;IAKlD,OAAO,CAAC,SAAS,CAAwC;IAIzD,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,WAAW,CAAqC;IACxD,OAAO,CAAC,eAAe,CAA6B;IAGpD,OAAO,CAAC,UAAU,CAA8D;gBAEpE,MAAM,EAAE,iBAAiB,EAAE,EAAE,CAAC,EAAE,sBAAsB;IAgDlE,OAAO,CAAC,eAAe;IAqDvB,OAAO,CAAC,cAAc;IA6CtB,OAAO,CAAC,iBAAiB;IAiBzB,OAAO,CAAC,qBAAqB;IAa7B,UAAU,IAAI,IAAI;IA0BlB,QAAQ,IAAI,IAAI;IAOhB,SAAS,CAAC,GAAG,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,IAAI;IAI1C,aAAa,CAAC,IAAI,EAAE,eAAe,GAAG,WAAW;IAOjD,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAOvC,UAAU,CACR,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,QAAQ,CAAC,SAAS,CAAC,GACzB,IAAI;IAqCP,QAAQ,CACN,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,MAAM,GACZ,IAAI;IA+BP,QAAQ,CACN,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,SAAS,GACf,IAAI;IA4CP,YAAY,CACV,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,QAAQ,CAAC,SAAS,CAAC,EAC1B,QAAQ,EAAE,OAAO,GAChB,IAAI;IAkCP,gBAAgB,IAAI,MAAM;IAO1B,OAAO,IAAI,IAAI;IAkCf,eAAe,IAAI;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE;IAWlF,eAAe,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE;IAMpD,OAAO,CAAC,YAAY;IAoDpB,OAAO,CAAC,aAAa;CAiEtB"}