pelican-engine 0.0.0-stage → 0.3.1

package/lib/renderer/texture-pixels.js

@@ -0,0 +1,207 @@
+import * as THREE from "three";
+import { embeddedImagePixels } from "./embedded-image-pixels.js";
+/** Private, synchronous reader. It borrows images and owns only its canvas/cache. */
+export function createTexturePixelProvider() {
+    const sources = new Map();
+    const textures = new Map();
+    const diagnostics = new Map();
+    let canvas;
+    let context;
+    let disposed = false, requests = 0, reads = 0, hits = 0, delegated = 0;
+    const report = (texture, code, message) => {
+        diagnostics.set(texture.uuid, { code, textureUuid: texture.uuid, message });
+        return undefined;
+    };
+    const clear = () => {
+        sources.clear();
+        textures.clear();
+        diagnostics.clear();
+        if (canvas) {
+            canvas.width = 0;
+            canvas.height = 0;
+        }
+        context = undefined;
+        canvas = undefined;
+        requests = reads = hits = delegated = 0;
+    };
+    return {
+        decode(texture) {
+            requests++;
+            if (disposed)
+                return report(texture, "TC_TEXTURE_PROVIDER_DISPOSED", "Create a new pixel provider after dispose().");
+            // Surface handles native DataTexture data, including float32, without DOM.
+            if (texture.isDataTexture) {
+                delegated++;
+                diagnostics.delete(texture.uuid);
+                return undefined;
+            }
+            const flags = texture;
+            if (texture.type !== THREE.UnsignedByteType ||
+                texture.format !== THREE.RGBAFormat ||
+                texture.premultiplyAlpha ||
+                texture.mipmaps.length ||
+                texture.isRenderTargetTexture ||
+                flags.isCompressedTexture ||
+                flags.isDataArrayTexture ||
+                flags.isData3DTexture ||
+                flags.isVideoTexture ||
+                flags.isFramebufferTexture)
+                return report(texture, "TC_TEXTURE_TYPE_UNSUPPORTED", "Use an unsigned-byte RGBA image without custom mips, premultiplication, or dynamic/compressed/array/render-target storage.");
+            try {
+                const embedded = embeddedImagePixels(texture);
+                if (embedded) {
+                    diagnostics.delete(texture.uuid);
+                    return Object.freeze({ ...embedded, data: embedded.data.slice() });
+                }
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                report(texture, message.split(":")[0], message);
+                throw error;
+            }
+            if (typeof OffscreenCanvas === "undefined" &&
+                typeof document === "undefined")
+                return report(texture, "TC_TEXTURE_DOM_UNAVAILABLE", "Decode browser images in a realm with Canvas2D; native DataTexture needs no DOM.");
+            const image = texture.image;
+            const bitmap = typeof ImageBitmap !== "undefined" && image instanceof ImageBitmap;
+            const html = typeof HTMLImageElement !== "undefined" &&
+                image instanceof HTMLImageElement;
+            if (!bitmap && !html)
+                return report(texture, "TC_TEXTURE_IMAGE_UNSUPPORTED", "Supply an ImageBitmap or a decoded HTMLImageElement from this realm.");
+            const input = image;
+            const width = html
+                ? input.naturalWidth
+                : input.width;
+            const height = html
+                ? input.naturalHeight
+                : input.height;
+            if (bitmap && (!width || !height))
+                return report(texture, "TC_TEXTURE_BITMAP_CLOSED", "The borrowed ImageBitmap is closed; retain it until extraction completes.");
+            if (html && (!input.complete || !width || !height))
+                return report(texture, "TC_TEXTURE_IMAGE_NOT_DECODED", "Await image.decode() before synchronous extraction.");
+            const url = html
+                ? input.currentSrc ||
+                    input.src
+                : "";
+            const previous = textures.get(texture);
+            const source = texture.source;
+            // A texture-only revision also invalidates shared pixels, even if a caller
+            // changed version without incrementing source.version.
+            if (previous &&
+                previous.source === source &&
+                previous.version !== texture.version)
+                sources.delete(source);
+            textures.set(texture, {
+                version: texture.version,
+                source,
+                sourceVersion: source.version,
+                image,
+            });
+            let cached = sources.get(source);
+            if (cached &&
+                cached.image === input &&
+                cached.version === source.version &&
+                cached.width === width &&
+                cached.height === height &&
+                cached.url === url) {
+                hits++;
+            }
+            else {
+                sources.delete(source);
+                try {
+                    if (!Number.isSafeInteger(width * height * 4) ||
+                        width <= 0 ||
+                        height <= 0)
+                        return report(texture, "TC_TEXTURE_CAPACITY", "Image dimensions exceed addressable RGBA8 storage.");
+                    if (!canvas) {
+                        canvas =
+                            typeof OffscreenCanvas !== "undefined"
+                                ? new OffscreenCanvas(width, height)
+                                : document.createElement("canvas");
+                    }
+                    canvas.width = width;
+                    canvas.height = height;
+                    // Resizing resets origin cleanliness, transforms and compositing.
+                    context = canvas.getContext("2d", {
+                        willReadFrequently: true,
+                        colorSpace: "srgb",
+                    });
+                    if (!context)
+                        return report(texture, "TC_TEXTURE_CANVAS_UNAVAILABLE", "Canvas2D is unavailable in this realm.");
+                    context.drawImage(input, 0, 0, width, height);
+                    const pixels = context.getImageData(0, 0, width, height, {
+                        colorSpace: "srgb",
+                    });
+                    if (pixels.data.length !== width * height * 4)
+                        return report(texture, "TC_TEXTURE_CAPACITY", "Canvas2D could not allocate the requested RGBA8 image.");
+                    reads++;
+                    cached = {
+                        image: input,
+                        version: source.version,
+                        width,
+                        height,
+                        url,
+                        data: pixels.data,
+                    };
+                    sources.set(source, cached);
+                }
+                catch (error) {
+                    const name = error instanceof Error ? error.name : "";
+                    // A failed read never leaves a tainted or partially initialized canvas.
+                    if (canvas) {
+                        canvas.width = 0;
+                        canvas.height = 0;
+                    }
+                    canvas = undefined;
+                    context = undefined;
+                    return report(texture, name === "SecurityError"
+                        ? "TC_TEXTURE_CROSS_ORIGIN"
+                        : name === "RangeError" || name === "IndexSizeError"
+                            ? "TC_TEXTURE_CAPACITY"
+                            : "TC_TEXTURE_READ_FAILED", name === "SecurityError"
+                        ? "Serve the image with CORS permission and set crossOrigin before src."
+                        : "Canvas2D could not read this image; check decoding, image lifetime and host memory/canvas capacity.");
+                }
+            }
+            diagnostics.delete(texture.uuid);
+            // Typed arrays cannot be frozen. Never expose the cached buffer to callers.
+            try {
+                return Object.freeze({
+                    width,
+                    height,
+                    data: cached.data.slice(),
+                    channels: 4,
+                    encoding: "unorm8",
+                    origin: "image",
+                });
+            }
+            catch {
+                return report(texture, "TC_TEXTURE_CAPACITY", "The host could not allocate an independent RGBA8 result.");
+            }
+        },
+        inspect() {
+            return {
+                disposed,
+                requests,
+                canvasReads: reads,
+                cacheHits: hits,
+                nativeDelegations: delegated,
+                textures: textures.size,
+                sources: sources.size,
+                capacity: {
+                    policy: "host",
+                    maxBytes: null,
+                    retainedBytes: Array.from(sources.values()).reduce((n, p) => n + p.data.byteLength, 0),
+                    canvasBytes: canvas ? canvas.width * canvas.height * 4 : 0,
+                    unknownResources: diagnostics.size,
+                },
+                diagnostics: Array.from(diagnostics.values(), (d) => ({ ...d })),
+            };
+        },
+        clear,
+        dispose() {
+            clear();
+            disposed = true;
+        },
+    };
+}

package/lib/renderer/traversal-nodes.js

@@ -0,0 +1,54 @@
+/** GPU-only depth-first escape layout; CPU acceleration ABI stays unchanged. */
+export function packTraversalNodes(nodes) {
+    if (nodes.length % 8)
+        throw new Error("TC_TRACE_NODE_LAYOUT: Expected eight-float nodes.");
+    const output = nodes.slice(), visited = new Set();
+    const count = nodes.length / 8;
+    const visit = (index) => {
+        if (!Number.isSafeInteger(index) ||
+            index < 0 ||
+            index >= count ||
+            visited.has(index))
+            throw new Error("TC_TRACE_NODE_LAYOUT: Invalid or cyclic node pointer.");
+        visited.add(index);
+        const offset = index * 8;
+        if (nodes[offset + 7] > 0) {
+            return index + 1;
+        }
+        const left = nodes[offset + 3], right = -nodes[offset + 7];
+        if (left !== index + 1)
+            throw new Error("TC_TRACE_NODE_LAYOUT: Threading requires the validated depth-first node order.");
+        const endLeft = visit(left);
+        if (endLeft !== right)
+            throw new Error("TC_TRACE_NODE_LAYOUT: Sibling ranges overlap.");
+        const end = visit(right);
+        output[offset + 3] = end;
+        output[offset + 7] = 0;
+        return end;
+    };
+    if (count) {
+        const end = visit(0);
+        if (end !== count || visited.size !== count)
+            throw new Error("TC_TRACE_NODE_LAYOUT: Unreachable acceleration nodes.");
+    }
+    return output;
+}
+/** Positions/material/orientation occupy compact cache lines beside the node tree. */
+export function packTraversalData(nodes, geometry) {
+    if (geometry.length % 72)
+        throw new Error("TC_TRACE_TRIANGLE_LAYOUT: Expected surface ABI triangles.");
+    const count = geometry.length / 72, output = new Float32Array(nodes.length + count * 12);
+    output.set(packTraversalNodes(nodes));
+    for (let index = 0; index < count; index++) {
+        const source = index * 72, target = nodes.length + index * 12;
+        output.set(geometry.subarray(source, source + 4), target);
+        output.set([
+            geometry[source + 4],
+            geometry[source + 5],
+            geometry[source + 6],
+            geometry[source + 63],
+        ], target + 4);
+        output.set([geometry[source + 8], geometry[source + 9], geometry[source + 10], 0], target + 8);
+    }
+    return output;
+}