@codexo/exojs 0.8.4 → 0.10.0

package/dist/esm/rendering/mesh/Mesh.js

@@ -33,11 +33,40 @@ class Mesh extends Drawable {
     indices;
     uvs;
     colors;
-    shader;
+    /** Custom material attached to this mesh, or `null` for the default mesh path. */
+    material;
+    /** Source geometry when constructed from the geometry form, otherwise `null`. */
+    geometry;
     _texture;
     constructor(options) {
         super();
-        const { vertices, indices = null, uvs = null, colors = null, texture = null, shader = null } = options;
+        const { texture = null, material = null } = options;
+        let vertices;
+        let indices;
+        let uvs;
+        let colors;
+        let geometry;
+        if (options.geometry !== undefined) {
+            if (options.vertices !== undefined) {
+                throw new Error('Mesh accepts either `vertices` or `geometry`, not both.');
+            }
+            geometry = options.geometry;
+            const data = readGeometry(geometry);
+            vertices = data.vertices;
+            uvs = data.uvs;
+            colors = data.colors;
+            indices = data.indices;
+        }
+        else {
+            if (options.vertices === undefined) {
+                throw new Error('Mesh requires either `vertices` or `geometry`.');
+            }
+            geometry = null;
+            vertices = options.vertices;
+            indices = options.indices ?? null;
+            uvs = options.uvs ?? null;
+            colors = options.colors ?? null;
+        }
         if (vertices.length === 0 || vertices.length % 2 !== 0) {
             throw new Error(`Mesh vertices must be a non-empty flat array of (x,y) pairs (got length ${vertices.length}).`);
         }
@@ -68,7 +97,8 @@ class Mesh extends Drawable {
         this.indices = indices;
         this.uvs = uvs;
         this.colors = colors;
-        this.shader = shader;
+        this.material = material;
+        this.geometry = geometry;
         this._texture = texture;
         this.recomputeLocalBounds();
     }
@@ -109,11 +139,100 @@ class Mesh extends Drawable {
             if (y > maxY)
                 maxY = y;
         }
-        this.localBounds.set(minX, minY, maxX - minX, maxY - minY);
+        this.getLocalBounds().set(minX, minY, maxX - minX, maxY - minY);
         this._invalidateBoundsCascade();
         return this;
     }
 }
+const positionAttributeNames = new Set(['a_position', 'position']);
+const texcoordAttributeNames = new Set(['a_texcoord', 'texcoord', 'a_uv', 'uv']);
+const colorAttributeNames = new Set(['a_color', 'color']);
+const findAttribute = (attributes, names) => attributes.find(attribute => names.has(attribute.name));
+/**
+ * Read a {@link Geometry}'s standard mesh attributes into the flat
+ * `vertices`/`uvs`/`colors` arrays the mesh renderers consume. Only the
+ * `triangle-list` topology and the canonical attribute layout (`f32` position
+ * and texcoord, `u8`/`u32`/`f32` color) are supported — this is the immediate
+ * (non-batched) bridge; shared GPU buffers and instancing arrive later.
+ */
+function readGeometry(geometry) {
+    if (geometry.topology !== 'triangle-list') {
+        throw new Error(`Mesh only supports triangle-list geometry (got "${geometry.topology}").`);
+    }
+    const position = findAttribute(geometry.attributes, positionAttributeNames);
+    if (position === undefined) {
+        throw new Error('Mesh geometry requires a position attribute named `a_position` or `position`.');
+    }
+    if (position.type !== 'f32' || position.size < 2) {
+        throw new Error('Mesh geometry position attribute must be a float vector with at least 2 components.');
+    }
+    const texcoord = findAttribute(geometry.attributes, texcoordAttributeNames);
+    if (texcoord !== undefined && (texcoord.type !== 'f32' || texcoord.size < 2)) {
+        throw new Error('Mesh geometry texcoord attribute must be a float vector with at least 2 components.');
+    }
+    const color = findAttribute(geometry.attributes, colorAttributeNames);
+    const vertexCount = geometry.vertexCount;
+    const { stride } = geometry;
+    const source = geometry.vertexData;
+    const view = source instanceof Float32Array ? new DataView(source.buffer, source.byteOffset, source.byteLength) : new DataView(source);
+    const vertices = new Float32Array(vertexCount * 2);
+    const uvs = texcoord !== undefined ? new Float32Array(vertexCount * 2) : null;
+    const colors = color !== undefined ? new Uint32Array(vertexCount) : null;
+    for (let i = 0; i < vertexCount; i++) {
+        const base = i * stride;
+        vertices[i * 2] = view.getFloat32(base + position.offset, true);
+        vertices[i * 2 + 1] = view.getFloat32(base + position.offset + 4, true);
+        if (uvs !== null && texcoord !== undefined) {
+            uvs[i * 2] = view.getFloat32(base + texcoord.offset, true);
+            uvs[i * 2 + 1] = view.getFloat32(base + texcoord.offset + 4, true);
+        }
+        if (colors !== null && color !== undefined) {
+            colors[i] = readPackedColor(view, base + color.offset, color);
+        }
+    }
+    const indices = readIndices(geometry.indices, vertexCount);
+    return { vertices, uvs, colors, indices };
+}
+/** Pack a geometry color attribute into the mesh's RGBA8 u32 representation. */
+function readPackedColor(view, offset, attribute) {
+    if (attribute.type === 'u32' && attribute.size === 1) {
+        return view.getUint32(offset, true) >>> 0;
+    }
+    if (attribute.type === 'u8' && attribute.size === 4) {
+        const r = view.getUint8(offset);
+        const g = view.getUint8(offset + 1);
+        const b = view.getUint8(offset + 2);
+        const a = view.getUint8(offset + 3);
+        return (r | (g << 8) | (b << 16) | (a << 24)) >>> 0;
+    }
+    if (attribute.type === 'f32' && attribute.size === 4) {
+        const r = Math.round(clamp01(view.getFloat32(offset, true)) * 255);
+        const g = Math.round(clamp01(view.getFloat32(offset + 4, true)) * 255);
+        const b = Math.round(clamp01(view.getFloat32(offset + 8, true)) * 255);
+        const a = Math.round(clamp01(view.getFloat32(offset + 12, true)) * 255);
+        return (r | (g << 8) | (b << 16) | (a << 24)) >>> 0;
+    }
+    throw new Error('Mesh geometry color attribute must be u8x4, u32x1, or f32x4.');
+}
+function readIndices(indices, vertexCount) {
+    if (indices === null) {
+        return null;
+    }
+    if (indices instanceof Uint16Array) {
+        return indices;
+    }
+    if (vertexCount > 0xffff) {
+        throw new Error(`Mesh geometry with ${vertexCount} vertices exceeds the 16-bit index limit.`);
+    }
+    return Uint16Array.from(indices);
+}
+function clamp01(value) {
+    if (value < 0)
+        return 0;
+    if (value > 1)
+        return 1;
+    return value;
+}
 
 export { Mesh };
 //# sourceMappingURL=Mesh.js.map

package/dist/esm/rendering/mesh/Mesh.js.map

@@ -1 +1 @@
-{"version":3,"file":"Mesh.js","sources":["../../../../../src/rendering/mesh/Mesh.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}
+{"version":3,"file":"Mesh.js","sources":["../../../../../src/rendering/mesh/Mesh.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/esm/rendering/pass/RenderPassCoordinator.d.ts

@@ -0,0 +1,63 @@
+import type { Matrix } from '@/math/Matrix';
+import type { Rectangle } from '@/math/Rectangle';
+import type { Geometry } from '../geometry/Geometry';
+import type { RenderTarget } from '../RenderTarget';
+import type { View } from '../View';
+import type { RenderPassDescriptor, RenderPassLoad } from './RenderPassDescriptor';
+/**
+ * Internal, backend-owned owner of render-pass lifecycle: target / view / clear
+ * orchestration, the scissor and stencil-clip stacks, and — on WebGPU, from
+ * phase 12D — the active `GPURenderPassEncoder`.
+ *
+ * There is no public RenderPass API. This abstraction exists so the WebGL2 and
+ * WebGPU backends can share the orchestration shape that geometric stencil
+ * clipping needs, while each maps it onto its own state model: WebGL2 onto
+ * ambient GL state (bound framebuffer, viewport, scissor, stencil), WebGPU onto
+ * explicit render passes built up front with their attachments.
+ * @internal
+ */
+export interface RenderPassCoordinator {
+    /** The target the active pass draws into (the backend root when idle). */
+    readonly activeTarget: RenderTarget;
+    /** The view the active pass renders with. */
+    readonly activeView: View;
+    /** Whether a pass is currently open. */
+    readonly hasActivePass: boolean;
+    /** Open a pass for `descriptor`, applying its target / view / clear / stencil state. */
+    beginPass(descriptor: RenderPassDescriptor): void;
+    /** Close the active pass, flushing any pending draws into it. */
+    endPass(): void;
+    /**
+     * Run `body` inside a child pass described by `descriptor`, restoring the
+     * previous target and view afterwards — even if `body` throws. Preserves the
+     * save / restore semantics of {@link RenderTargetPass}.
+     */
+    withChildPass(descriptor: RenderPassDescriptor, body: () => void): void;
+    /** Push an axis-aligned scissor rectangle; nested rectangles intersect. */
+    pushScissorRect(bounds: Rectangle): void;
+    /** Pop the most recently pushed scissor rectangle. */
+    popScissorRect(): void;
+    /** Push a geometric stencil clip — the `shape` silhouette under `transform`. */
+    pushStencilClip(shape: Geometry, transform: Matrix): void;
+    /** Pop the most recently pushed stencil clip. */
+    popStencilClip(): void;
+    /**
+     * Decide whether `target` should be cleared or loaded given an explicit clear
+     * request. Centralizes the clear-vs-load / content-preservation decision so a
+     * render texture's contents survive across multiple passes in one frame.
+     */
+    resolveLoad(target: RenderTarget, clearRequested: boolean): RenderPassLoad;
+}
+/**
+ * Duck-typing host for backends that own a {@link RenderPassCoordinator}.
+ *
+ * Generic, `RenderBackend`-typed orchestration code ({@link RenderTargetPass},
+ * {@link RenderingContext.renderTo}) reaches the coordinator through this
+ * optional accessor and falls back to a legacy inline target/view save-restore
+ * when it is absent (e.g. test stub backends), mirroring the `_beginDrawPlan?`
+ * hook pattern used by `RenderPlanPlayer`.
+ * @internal
+ */
+export interface RenderPassCoordinatorHost {
+    readonly _passCoordinator: RenderPassCoordinator;
+}

package/dist/esm/rendering/pass/RenderPassDescriptor.d.ts

@@ -0,0 +1,48 @@
+import type { Color } from '@/core/Color';
+import type { RenderTarget } from '../RenderTarget';
+import type { View } from '../View';
+/**
+ * Whether a render pass carries a stencil attachment.
+ *
+ * WebGL2 stencil is ambient per-target GL state, so this flag is largely
+ * informational there; the WebGPU backend (from phase 12D onwards) uses it to
+ * decide whether a pass descriptor needs a `depthStencilAttachment`.
+ * @internal
+ */
+export declare enum StencilAttachmentMode {
+    None = 0,
+    Enabled = 1
+}
+/** Load behaviour for a pass's colour attachment. @internal */
+export type RenderPassLoad = 'clear' | 'load';
+/**
+ * Backend-agnostic description of a single render pass: which target and view
+ * it draws into, whether it clears or loads its colour attachment, and whether
+ * it carries a stencil attachment.
+ *
+ * WebGL2 maps this onto ambient framebuffer / viewport / scissor / stencil
+ * state; WebGPU (phase 12D onwards) maps it onto a `GPURenderPassEncoder`.
+ * @internal
+ */
+export interface RenderPassDescriptor {
+    /** Target to draw into. `null` selects the backend's root (canvas) target. */
+    readonly target: RenderTarget | null;
+    /** View to render with. `null` inherits the target's current view. */
+    readonly view: View | null;
+    /** Whether the colour attachment is cleared or preserved when the pass begins. */
+    readonly load: RenderPassLoad;
+    /** Clear colour used when `load === 'clear'`. `null` keeps the backend's current clear colour. */
+    readonly clearColor: Color | null;
+    /** Whether this pass carries a stencil attachment. */
+    readonly stencil: StencilAttachmentMode;
+}
+/**
+ * Snapshot of the pass currently open on a {@link RenderPassCoordinator}. The
+ * WebGPU coordinator exposes the live encoder alongside these fields from phase
+ * 12D; the shared shape lives here so both backends agree on it.
+ * @internal
+ */
+export interface ActiveRenderPass {
+    readonly view: View;
+    readonly stencilEnabled: boolean;
+}

package/dist/esm/rendering/pass/RenderPassDescriptor.js

@@ -0,0 +1,16 @@
+/**
+ * Whether a render pass carries a stencil attachment.
+ *
+ * WebGL2 stencil is ambient per-target GL state, so this flag is largely
+ * informational there; the WebGPU backend (from phase 12D onwards) uses it to
+ * decide whether a pass descriptor needs a `depthStencilAttachment`.
+ * @internal
+ */
+var StencilAttachmentMode;
+(function (StencilAttachmentMode) {
+    StencilAttachmentMode[StencilAttachmentMode["None"] = 0] = "None";
+    StencilAttachmentMode[StencilAttachmentMode["Enabled"] = 1] = "Enabled";
+})(StencilAttachmentMode || (StencilAttachmentMode = {}));
+
+export { StencilAttachmentMode };
+//# sourceMappingURL=RenderPassDescriptor.js.map

package/dist/esm/rendering/pass/RenderPassDescriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RenderPassDescriptor.js","sources":["../../../../../src/rendering/pass/RenderPassDescriptor.ts"],"sourcesContent":[null],"names":[],"mappings":"AAKA;;;;;;;AAOG;IACS;AAAZ,CAAA,UAAY,qBAAqB,EAAA;AAC/B,IAAA,qBAAA,CAAA,qBAAA,CAAA,MAAA,CAAA,GAAA,CAAA,CAAA,GAAA,MAAQ;AACR,IAAA,qBAAA,CAAA,qBAAA,CAAA,SAAA,CAAA,GAAA,CAAA,CAAA,GAAA,SAAW;AACb,CAAC,EAHW,qBAAqB,KAArB,qBAAqB,GAAA,EAAA,CAAA,CAAA;;;;"}

package/dist/esm/rendering/plan/RenderCommand.d.ts

@@ -0,0 +1,67 @@
+import type { Drawable } from '@/rendering/Drawable';
+import type { RenderBackend } from '@/rendering/RenderBackend';
+import type { BlendModes } from '@/rendering/types';
+/** @internal */
+export declare const enum RenderEntryKind {
+    Draw = 0,
+    Group = 1,
+    Barrier = 2
+}
+/**
+ * @internal
+ *
+ * Stable material identity used for safe draw-command grouping and
+ * eventual instanced batching.
+ *
+ * - {@link pipelineKey} drives pipeline/program reuse: identical key ⇒
+ *   identical GPU pipeline state (shader + blend + sampler). Two draws
+ *   with the same pipeline key can be issued with a single pipeline bind.
+ * - {@link bindKey} drives texture-bind reuse: identical key ⇒ identical
+ *   texture bindings. Two draws with the same bind key can share a bind
+ *   group / texture-slot state.
+ *
+ * When the drawable carries a {@link Material}, both keys are taken
+ * directly from `material.pipelineKey` and `material.bindKey` (Phase 4+
+ * Material system). When the drawable uses its default path (no material),
+ * the keys are derived conservatively from renderer identity, blend mode,
+ * and texture identity so grouping never accidentally merges draws with
+ * incompatible state.
+ */
+export interface MaterialKey {
+    readonly rendererId: number;
+    readonly blendMode: BlendModes;
+    readonly textureId: number;
+    readonly shaderId: number;
+    readonly pipelineKey: number;
+    readonly bindKey: number;
+}
+/** @internal */
+export interface DrawCommand {
+    readonly kind: RenderEntryKind.Draw;
+    readonly drawable: Drawable;
+    nodeIndex: number;
+    seq: number;
+    zIndex: number;
+    material: MaterialKey;
+    /** Assigned by the optimizer; consecutive draws with the same groupIndex
+     *  form a batch-safe unit.  Undefined before optimisation. */
+    groupIndex?: number;
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}
+/**
+ * Derive a stable material key from the drawable.
+ *
+ * When the drawable carries a {@link Material} (e.g. a {@link MeshMaterial}
+ * or {@link SpriteMaterial}), the pipeline and bind keys are taken directly
+ * from the material so identically configured materials group together.
+ * When the drawable uses its default rendering path, both keys fall back
+ * to a conservative derivation from renderer identity, blend mode, and
+ * texture identity — keeping grouping safe but still enabling adjacency
+ * coalescing for default-pipeline draws of the same type.
+ *
+ * @internal
+ */
+export declare const makeMaterialKey: (drawable: Drawable, backend: RenderBackend | null) => MaterialKey;

package/dist/esm/rendering/plan/RenderCommand.js

@@ -0,0 +1,94 @@
+/** @internal */
+var RenderEntryKind;
+(function (RenderEntryKind) {
+    RenderEntryKind[RenderEntryKind["Draw"] = 0] = "Draw";
+    RenderEntryKind[RenderEntryKind["Group"] = 1] = "Group";
+    RenderEntryKind[RenderEntryKind["Barrier"] = 2] = "Barrier";
+})(RenderEntryKind || (RenderEntryKind = {}));
+const rendererIds = new WeakMap();
+const constructorRendererIds = new WeakMap();
+const textureIds = new WeakMap();
+const shaderIds = new WeakMap();
+let nextRendererId = 1;
+let nextTextureId = 1;
+let nextShaderId = 1;
+const getOrCreateId = (map, target, allocate) => {
+    const cached = map.get(target);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const id = allocate();
+    map.set(target, id);
+    return id;
+};
+const getRendererId = (drawable, backend) => {
+    const registry = backend?.rendererRegistry;
+    if (registry && typeof registry.resolve === 'function') {
+        try {
+            const renderer = registry.resolve(drawable);
+            if (renderer && typeof renderer === 'object') {
+                return getOrCreateId(rendererIds, renderer, () => nextRendererId++);
+            }
+        }
+        catch {
+            // Resolve can throw if no renderer is registered for a custom drawable.
+            // Fall back to a conservative constructor-based id.
+        }
+    }
+    const ctor = drawable.constructor;
+    if (ctor && typeof ctor === 'function') {
+        return getOrCreateId(constructorRendererIds, ctor, () => nextRendererId++);
+    }
+    return 0;
+};
+const getTextureId = (drawable) => {
+    const texture = drawable.texture;
+    if (texture && typeof texture === 'object') {
+        return getOrCreateId(textureIds, texture, () => nextTextureId++);
+    }
+    return -1;
+};
+const getShaderId = (drawable) => {
+    const shader = drawable.shader;
+    if (shader && typeof shader === 'object') {
+        return getOrCreateId(shaderIds, shader, () => nextShaderId++);
+    }
+    return -1;
+};
+const getMaterial = (drawable) => {
+    const material = drawable.material;
+    return material ?? null;
+};
+/**
+ * Derive a stable material key from the drawable.
+ *
+ * When the drawable carries a {@link Material} (e.g. a {@link MeshMaterial}
+ * or {@link SpriteMaterial}), the pipeline and bind keys are taken directly
+ * from the material so identically configured materials group together.
+ * When the drawable uses its default rendering path, both keys fall back
+ * to a conservative derivation from renderer identity, blend mode, and
+ * texture identity — keeping grouping safe but still enabling adjacency
+ * coalescing for default-pipeline draws of the same type.
+ *
+ * @internal
+ */
+const makeMaterialKey = (drawable, backend) => {
+    const rendererId = getRendererId(drawable, backend);
+    const blendMode = drawable.blendMode;
+    const textureId = getTextureId(drawable);
+    const shaderId = getShaderId(drawable);
+    const material = getMaterial(drawable);
+    const pipelineKey = material !== null ? material.pipelineKey : rendererId * 31 + blendMode;
+    const bindKey = material !== null ? material.bindKey : rendererId * 31 + (textureId > 0 ? textureId : 0);
+    return {
+        rendererId,
+        blendMode,
+        textureId,
+        shaderId,
+        pipelineKey,
+        bindKey,
+    };
+};
+
+export { RenderEntryKind, makeMaterialKey };
+//# sourceMappingURL=RenderCommand.js.map

package/dist/esm/rendering/plan/RenderCommand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RenderCommand.js","sources":["../../../../../src/rendering/plan/RenderCommand.ts"],"sourcesContent":[null],"names":[],"mappings":"AAOA;IACkB;AAAlB,CAAA,UAAkB,eAAe,EAAA;AAC/B,IAAA,eAAA,CAAA,eAAA,CAAA,MAAA,CAAA,GAAA,CAAA,CAAA,GAAA,MAAI;AACJ,IAAA,eAAA,CAAA,eAAA,CAAA,OAAA,CAAA,GAAA,CAAA,CAAA,GAAA,OAAK;AACL,IAAA,eAAA,CAAA,eAAA,CAAA,SAAA,CAAA,GAAA,CAAA,CAAA,GAAA,SAAO;AACT,CAAC,EAJiB,eAAe,KAAf,eAAe,GAAA,EAAA,CAAA,CAAA;AAsEjC,MAAM,WAAW,GAAG,IAAI,OAAO,EAAkB;AACjD,MAAM,sBAAsB,GAAG,IAAI,OAAO,EAAkB;AAC5D,MAAM,UAAU,GAAG,IAAI,OAAO,EAAkB;AAChD,MAAM,SAAS,GAAG,IAAI,OAAO,EAAkB;AAE/C,IAAI,cAAc,GAAG,CAAC;AACtB,IAAI,aAAa,GAAG,CAAC;AACrB,IAAI,YAAY,GAAG,CAAC;AAEpB,MAAM,aAAa,GAAG,CAAC,GAA4B,EAAE,MAAc,EAAE,QAAsB,KAAY;IACrG,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC;AAE9B,IAAA,IAAI,MAAM,KAAK,SAAS,EAAE;AACxB,QAAA,OAAO,MAAM;IACf;AAEA,IAAA,MAAM,EAAE,GAAG,QAAQ,EAAE;AACrB,IAAA,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC;AAEnB,IAAA,OAAO,EAAE;AACX,CAAC;AAED,MAAM,aAAa,GAAG,CAAC,QAAkB,EAAE,OAA6B,KAAY;AAClF,IAAA,MAAM,QAAQ,GAAI,OAA8C,EAAE,gBAAgB;IAElF,IAAI,QAAQ,IAAI,OAAO,QAAQ,CAAC,OAAO,KAAK,UAAU,EAAE;AACtD,QAAA,IAAI;YACF,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC;AAE3C,YAAA,IAAI,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE;AAC5C,gBAAA,OAAO,aAAa,CAAC,WAAW,EAAE,QAAQ,EAAE,MAAM,cAAc,EAAE,CAAC;YACrE;QACF;AAAE,QAAA,MAAM;;;QAGR;IACF;AAEA,IAAA,MAAM,IAAI,GAAG,QAAQ,CAAC,WAAW;AAEjC,IAAA,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,UAAU,EAAE;AACtC,QAAA,OAAO,aAAa,CAAC,sBAAsB,EAAE,IAAI,EAAE,MAAM,cAAc,EAAE,CAAC;IAC5E;AAEA,IAAA,OAAO,CAAC;AACV,CAAC;AAED,MAAM,YAAY,GAAG,CAAC,QAAkB,KAAY;AAClD,IAAA,MAAM,OAAO,GAAI,QAA2B,CAAC,OAAO;AAEpD,IAAA,IAAI,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE;AAC1C,QAAA,OAAO,aAAa,CAAC,UAAU,EAAE,OAAO,EAAE,MAAM,aAAa,EAAE,CAAC;IAClE;IAEA,OAAO,EAAE;AACX,CAAC;AAED,MAAM,WAAW,GAAG,CAAC,QAAkB,KAAY;AACjD,IAAA,MAAM,MAAM,GAAI,QAA0B,CAAC,MAAM;AAEjD,IAAA,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE;AACxC,QAAA,OAAO,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,YAAY,EAAE,CAAC;IAC/D;IAEA,OAAO,EAAE;AACX,CAAC;AAED,MAAM,WAAW,GAAG,CAAC,QAAkB,KAAqB;AAC1D,IAAA,MAAM,QAAQ,GAAI,QAA4B,CAAC,QAAQ;IAEvD,OAAO,QAAQ,IAAI,IAAI;AACzB,CAAC;AAED;;;;;;;;;;;;AAYG;MACU,eAAe,GAAG,CAAC,QAAkB,EAAE,OAA6B,KAAiB;IAChG,MAAM,UAAU,GAAG,aAAa,CAAC,QAAQ,EAAE,OAAO,CAAC;AACnD,IAAA,MAAM,SAAS,GAAG,QAAQ,CAAC,SAAS;AACpC,IAAA,MAAM,SAAS,GAAG,YAAY,CAAC,QAAQ,CAAC;AACxC,IAAA,MAAM,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC;AACtC,IAAA,MAAM,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC;AAEtC,IAAA,MAAM,WAAW,GAAG,QAAQ,KAAK,IAAI,GAAG,QAAQ,CAAC,WAAW,GAAG,UAAU,GAAG,EAAE,GAAG,SAAS;AAC1F,IAAA,MAAM,OAAO,GAAG,QAAQ,KAAK,IAAI,GAAG,QAAQ,CAAC,OAAO,GAAG,UAAU,GAAG,EAAE,IAAI,SAAS,GAAG,CAAC,GAAG,SAAS,GAAG,CAAC,CAAC;IAExG,OAAO;QACL,UAAU;QACV,SAAS;QACT,SAAS;QACT,QAAQ;QACR,WAAW;QACX,OAAO;KACR;AACH;;;;"}

package/dist/esm/rendering/plan/RenderEffectExecutor.d.ts

@@ -0,0 +1,10 @@
+import type { RenderBackend } from '@/rendering/RenderBackend';
+import { type BarrierScope, type GroupScope } from './RenderScope';
+/** @internal */
+export declare class RenderEffectExecutor {
+    static play(barrier: BarrierScope, backend: RenderBackend, playScope: (scope: GroupScope) => void): void;
+    private static _withClip;
+    private static _withRectClip;
+    private static _withMask;
+    private static _resolveMaskTexture;
+}

package/dist/esm/rendering/plan/RenderEffectExecutor.js

@@ -0,0 +1,159 @@
+import { Rectangle } from '../../math/Rectangle.js';
+import { RenderTexture } from '../texture/RenderTexture.js';
+import { Texture } from '../texture/Texture.js';
+import { ClipKind } from './RenderScope.js';
+
+/** @internal */
+class RenderEffectExecutor {
+    static play(barrier, backend, playScope) {
+        const { node, effect } = barrier;
+        const hasFilters = effect.filters.length > 0;
+        const needsBitmapCache = effect.cacheAsBitmap;
+        const { left, top, width, height } = barrier;
+        if (!hasFilters && !needsBitmapCache) {
+            this._withClip(node, backend, barrier, () => {
+                if (barrier.childPlan !== null) {
+                    playScope(barrier.childPlan);
+                }
+            });
+            return;
+        }
+        if (needsBitmapCache && barrier.childPlan === null) {
+            const cachedTexture = node._renderPlanGetCacheTexture();
+            if (cachedTexture !== null) {
+                this._withClip(node, backend, barrier, () => {
+                    node._renderPlanDrawTexture(backend, cachedTexture, left, top, width, height, effect.blendMode);
+                });
+            }
+            return;
+        }
+        const cacheTexture = needsBitmapCache ? node._renderPlanEnsureCacheTexture(width, height) : null;
+        let pooledTexture = null;
+        try {
+            const sourceTexture = needsBitmapCache && !hasFilters ? cacheTexture : backend.acquireRenderTexture(width, height);
+            if (sourceTexture !== cacheTexture) {
+                pooledTexture = sourceTexture;
+            }
+            node._renderPlanRenderToTexture(backend, sourceTexture, left, top, width, height, () => {
+                if (barrier.childPlan !== null) {
+                    playScope(barrier.childPlan);
+                }
+            });
+            let finalTexture = sourceTexture;
+            if (hasFilters) {
+                for (let index = 0; index < effect.filters.length; index++) {
+                    const isLast = index === effect.filters.length - 1;
+                    const output = isLast && needsBitmapCache ? cacheTexture : backend.acquireRenderTexture(width, height);
+                    try {
+                        effect.filters[index].apply(backend, finalTexture, output);
+                    }
+                    catch (error) {
+                        if (output !== cacheTexture) {
+                            backend.releaseRenderTexture(output);
+                        }
+                        throw error;
+                    }
+                    if (pooledTexture !== null) {
+                        backend.releaseRenderTexture(pooledTexture);
+                        pooledTexture = null;
+                    }
+                    finalTexture = output;
+                    if (output !== cacheTexture) {
+                        pooledTexture = output;
+                    }
+                }
+            }
+            if (needsBitmapCache) {
+                node._renderPlanStoreCacheTexture(cacheTexture, left, top, width, height);
+            }
+            this._withClip(node, backend, barrier, () => {
+                node._renderPlanDrawTexture(backend, finalTexture, left, top, width, height, effect.blendMode);
+            });
+        }
+        finally {
+            if (pooledTexture !== null) {
+                backend.releaseRenderTexture(pooledTexture);
+            }
+        }
+    }
+    // Clip wraps the mask block as the outermost effect boundary, so it acts on
+    // the final filtered/masked output. Stencil (Geometry) is outermost; the Rect
+    // scissor sits between it and the alpha-mask machinery; both compose with any
+    // existing mask scissor since scissors/stencil are all restrictive.
+    static _withClip(node, backend, barrier, callback) {
+        if (barrier.effect.clip === ClipKind.Stencil) {
+            backend.pushStencilClip(barrier.effect.clipShape, node.getGlobalTransform());
+            try {
+                this._withRectClip(node, backend, barrier, callback);
+            }
+            finally {
+                backend.popStencilClip();
+            }
+            return;
+        }
+        this._withRectClip(node, backend, barrier, callback);
+    }
+    static _withRectClip(node, backend, barrier, callback) {
+        if (barrier.effect.clip === ClipKind.Rect) {
+            const rect = barrier.effect.clipShape ?? node.getBounds();
+            if (rect.width <= 0 || rect.height <= 0) {
+                return;
+            }
+            backend.pushScissorRect(rect);
+            try {
+                this._withMask(node, backend, barrier, callback);
+            }
+            finally {
+                backend.popScissorRect();
+            }
+            return;
+        }
+        this._withMask(node, backend, barrier, callback);
+    }
+    static _withMask(node, backend, barrier, callback) {
+        const mask = barrier.effect.maskSource;
+        if (mask === null) {
+            callback();
+            return;
+        }
+        if (mask instanceof Rectangle) {
+            if (mask.width <= 0 || mask.height <= 0) {
+                return;
+            }
+            backend.pushScissorRect(mask);
+            try {
+                callback();
+            }
+            finally {
+                backend.popScissorRect();
+            }
+            return;
+        }
+        const contentTexture = backend.acquireRenderTexture(barrier.width, barrier.height);
+        const releasePool = [contentTexture];
+        try {
+            node._renderPlanRenderToTexture(backend, contentTexture, barrier.left, barrier.top, barrier.width, barrier.height, callback);
+            const maskTexture = this._resolveMaskTexture(node, backend, mask, barrier, releasePool);
+            backend.composeWithAlphaMask(contentTexture, maskTexture, barrier.left, barrier.top, barrier.width, barrier.height, barrier.effect.blendMode);
+        }
+        finally {
+            for (const texture of releasePool) {
+                backend.releaseRenderTexture(texture);
+            }
+        }
+    }
+    static _resolveMaskTexture(node, backend, mask, barrier, releasePool) {
+        if (!(mask instanceof Texture) && !(mask instanceof RenderTexture)) {
+            const maskTexture = backend.acquireRenderTexture(barrier.width, barrier.height);
+            releasePool.push(maskTexture);
+            node._renderPlanRenderToTexture(backend, maskTexture, barrier.left, barrier.top, barrier.width, barrier.height, () => {
+                mask.render(backend);
+            });
+            return maskTexture;
+        }
+        return mask;
+    }
+}
+
+export { RenderEffectExecutor };
+//# sourceMappingURL=RenderEffectExecutor.js.map