@codexo/exojs 0.9.0 → 0.11.0

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

@@ -0,0 +1,86 @@
+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` (the 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;
+/**
+ * Whether a draw command's renderer reads the shared {@link TransformBuffer} /
+ * transform storage. The render-group upload boundary packs each command's
+ * world transform (+ tint) keyed by its `nodeIndex`; only renderers that fetch
+ * those rows back from the buffer need a record written.
+ *
+ * Sprite and Mesh (and their subclasses — {@link AnimatedSprite}, Video,
+ * Graphics' meshes) fetch the transform via `nodeIndex` and therefore consume
+ * it. Text/BitmapText and particle renderers pack their own per-node data into
+ * a private data texture / uniforms and never touch the shared buffer, so they
+ * opt out via `_consumesSharedTransform === false` and their writes are skipped.
+ *
+ * Anything else — a custom renderer, or a drawable with no registered renderer
+ * (resolve throws) — defaults to writing, so behaviour is unchanged for any
+ * path that might still rely on the shared transform.
+ *
+ * @internal
+ */
+export declare const drawCommandUsesSharedTransform: (command: DrawCommand, backend: RenderBackend) => boolean;

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

@@ -0,0 +1,127 @@
+/** @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,
+    };
+};
+/**
+ * Whether a draw command's renderer reads the shared {@link TransformBuffer} /
+ * transform storage. The render-group upload boundary packs each command's
+ * world transform (+ tint) keyed by its `nodeIndex`; only renderers that fetch
+ * those rows back from the buffer need a record written.
+ *
+ * Sprite and Mesh (and their subclasses — {@link AnimatedSprite}, Video,
+ * Graphics' meshes) fetch the transform via `nodeIndex` and therefore consume
+ * it. Text/BitmapText and particle renderers pack their own per-node data into
+ * a private data texture / uniforms and never touch the shared buffer, so they
+ * opt out via `_consumesSharedTransform === false` and their writes are skipped.
+ *
+ * Anything else — a custom renderer, or a drawable with no registered renderer
+ * (resolve throws) — defaults to writing, so behaviour is unchanged for any
+ * path that might still rely on the shared transform.
+ *
+ * @internal
+ */
+const drawCommandUsesSharedTransform = (command, backend) => {
+    const registry = backend.rendererRegistry;
+    if (!registry || typeof registry.resolve !== 'function') {
+        return true;
+    }
+    try {
+        const renderer = registry.resolve(command.drawable);
+        return renderer._consumesSharedTransform !== false;
+    }
+    catch {
+        // No renderer registered for a custom drawable: keep the conservative
+        // write so any consumer of the shared transform keeps working.
+        return true;
+    }
+};
+
+export { RenderEntryKind, drawCommandUsesSharedTransform, 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":"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"}

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

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

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

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

@@ -0,0 +1,51 @@
+import { type DrawCommand, type MaterialKey } from './RenderCommand';
+import type { GroupScope } from './RenderScope';
+/**
+ * The canonical, reorderable unit of work in a render plan: a single draw
+ * that the plan player submits to the backend.
+ *
+ * Today a render instruction is exactly a {@link DrawCommand}; the alias
+ * names the concept the plan player consumes and that the batching layer
+ * reorders, independent of how the draw happens to be stored in the scope
+ * tree. Future {@link TransformBuffer} slotting keys on each instruction's
+ * stable {@link DrawCommand.nodeIndex} (within the `[0, plan.nodeCount)`
+ * slot space).
+ *
+ * @internal
+ */
+export type RenderInstruction = DrawCommand;
+/**
+ * A materialized batch unit: a maximal run of consecutive
+ * {@link RenderInstruction}s within a single {@link GroupScope} that share a
+ * GPU pipeline/bind state and may therefore be submitted together.
+ *
+ * The optimizer ({@link RenderPlanOptimizer}) already stamps this grouping
+ * implicitly onto each {@link DrawCommand.groupIndex}; a `RenderGroup` makes
+ * that batch unit explicit as a value without altering playback. The mesh
+ * renderers continue to detect batches by comparing adjacent `groupIndex`es,
+ * so this representation is purely additive.
+ *
+ * @internal
+ */
+export interface RenderGroup {
+    /** Optimizer-assigned batch identity shared by every instruction in the run. */
+    readonly groupIndex: number;
+    /** Pipeline/bind state shared by the run; taken from its first instruction. */
+    readonly material: MaterialKey;
+    /** Draw instructions in submit order. */
+    readonly instructions: readonly RenderInstruction[];
+}
+/**
+ * Materialize the {@link RenderGroup} batch units contained directly in
+ * `scope`. Consecutive draw instructions that share a defined `groupIndex`
+ * coalesce into one group; any non-draw entry (a nested group or barrier)
+ * breaks the run, and a draw whose `groupIndex` is still `undefined` (i.e.
+ * the plan has not been optimized) forms its own singleton group — mirroring
+ * the adjacency semantics the mesh renderers already rely on.
+ *
+ * This is a read-only view over an (optimized) scope; it does not mutate the
+ * plan or affect playback order.
+ *
+ * @internal
+ */
+export declare function collectRenderGroups(scope: GroupScope): RenderGroup[];

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

@@ -0,0 +1,45 @@
+import { RenderEntryKind } from './RenderCommand.js';
+
+/**
+ * Materialize the {@link RenderGroup} batch units contained directly in
+ * `scope`. Consecutive draw instructions that share a defined `groupIndex`
+ * coalesce into one group; any non-draw entry (a nested group or barrier)
+ * breaks the run, and a draw whose `groupIndex` is still `undefined` (i.e.
+ * the plan has not been optimized) forms its own singleton group — mirroring
+ * the adjacency semantics the mesh renderers already rely on.
+ *
+ * This is a read-only view over an (optimized) scope; it does not mutate the
+ * plan or affect playback order.
+ *
+ * @internal
+ */
+function collectRenderGroups(scope) {
+    const groups = [];
+    let current = null;
+    for (const entry of scope.entries) {
+        if (entry.kind !== RenderEntryKind.Draw) {
+            current = null;
+            continue;
+        }
+        const command = entry.command;
+        const groupIndex = command.groupIndex;
+        if (current !== null && groupIndex !== undefined && groupIndex === current.groupIndex) {
+            current.instructions.push(command);
+            continue;
+        }
+        current = {
+            groupIndex: groupIndex ?? 0,
+            material: command.material,
+            instructions: [command],
+        };
+        groups.push(current);
+        if (groupIndex === undefined) {
+            // Unoptimized / non-batchable draw: never coalesce with the next one.
+            current = null;
+        }
+    }
+    return groups;
+}
+
+export { collectRenderGroups };
+//# sourceMappingURL=RenderInstruction.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RenderInstruction.js","sources":["../../../../../src/rendering/plan/RenderInstruction.ts"],"sourcesContent":[null],"names":[],"mappings":";;AA8CA;;;;;;;;;;;;AAYG;AACG,SAAU,mBAAmB,CAAC,KAAiB,EAAA;IACnD,MAAM,MAAM,GAAkB,EAAE;IAChC,IAAI,OAAO,GAA8B,IAAI;AAE7C,IAAA,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,OAAO,EAAE;QACjC,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,CAAC,IAAI,EAAE;YACvC,OAAO,GAAG,IAAI;YAEd;QACF;AAEA,QAAA,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO;AAC7B,QAAA,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU;AAErC,QAAA,IAAI,OAAO,KAAK,IAAI,IAAI,UAAU,KAAK,SAAS,IAAI,UAAU,KAAK,OAAO,CAAC,UAAU,EAAE;AACrF,YAAA,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC;YAElC;QACF;AAEA,QAAA,OAAO,GAAG;YACR,UAAU,EAAE,UAAU,IAAI,CAAC;YAC3B,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,YAAY,EAAE,CAAC,OAAO,CAAC;SACxB;AACD,QAAA,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC;AAEpB,QAAA,IAAI,UAAU,KAAK,SAAS,EAAE;;YAE5B,OAAO,GAAG,IAAI;QAChB;IACF;AAEA,IAAA,OAAO,MAAM;AACf;;;;"}

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

@@ -0,0 +1,23 @@
+import type { Color } from '@/core/Color';
+import type { RenderTarget } from '@/rendering/RenderTarget';
+import type { View } from '@/rendering/View';
+import type { GroupScope } from './RenderScope';
+/** @internal */
+export interface RenderPassScope {
+    target: RenderTarget | null;
+    view: View;
+    clearColor: Color | null;
+    root: GroupScope;
+}
+/** @internal */
+export interface RenderPlan {
+    passes: RenderPassScope[];
+    nodeCount: number;
+    reset(): void;
+}
+/** @internal */
+export declare class MutableRenderPlan implements RenderPlan {
+    readonly passes: RenderPassScope[];
+    nodeCount: number;
+    reset(): void;
+}

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

@@ -0,0 +1,12 @@
+/** @internal */
+class MutableRenderPlan {
+    passes = [];
+    nodeCount = 0;
+    reset() {
+        this.passes.length = 0;
+        this.nodeCount = 0;
+    }
+}
+
+export { MutableRenderPlan };
+//# sourceMappingURL=RenderPlan.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RenderPlan.js","sources":["../../../../../src/rendering/plan/RenderPlan.ts"],"sourcesContent":[null],"names":[],"mappings":"AAqBA;MACa,iBAAiB,CAAA;IACZ,MAAM,GAAsB,EAAE;IACvC,SAAS,GAAG,CAAC;IAEb,KAAK,GAAA;AACV,QAAA,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;AACtB,QAAA,IAAI,CAAC,SAAS,GAAG,CAAC;IACpB;AACD;;;;"}

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

@@ -0,0 +1,31 @@
+import type { Drawable } from '@/rendering/Drawable';
+import type { RenderBackend } from '@/rendering/RenderBackend';
+import type { RenderNode } from '@/rendering/RenderNode';
+import type { View } from '@/rendering/View';
+import { type RenderPlan } from './RenderPlan';
+/** @internal */
+export declare class RenderPlanBuilder {
+    private static readonly _available;
+    private static readonly _active;
+    static acquire(): RenderPlanBuilder;
+    static release(builder: RenderPlanBuilder): void;
+    backend: RenderBackend;
+    private _view;
+    private readonly _plan;
+    private readonly _groupPool;
+    private readonly _scopeStack;
+    private _groupPoolCursor;
+    private _pendingEntryPlacement;
+    private _nodeIndex;
+    build(root: RenderNode, backend: RenderBackend): RenderPlan;
+    get view(): View;
+    emitNode(node: RenderNode, seq?: number): void;
+    emitDraw(drawable: Drawable, seq?: number): void;
+    private _resetRuntimeState;
+    private _acquireGroupScope;
+    private _reserveEntryPlacement;
+    private _pushEntry;
+    private _currentScope;
+    private _resolvePreserveDrawOrder;
+    private _createEffectDescriptor;
+}