pixi-effects 0.45.0 → 0.46.0

package/dist/three.d.cts

@@ -1,11 +1,66 @@
-import { b as SpaceNow, c as SequenceCommon, d as PropValue, e as Sequence, f as PathRouters, S as SequenceSpec } from './types-C5xo0fzb.cjs';
-import { Scene, Camera, WebGLRenderer, Object3D, Group, Vector3, PerspectiveCamera } from 'three';
+import { b as Sequence, c as SpaceNow, d as SequenceCommon, e as PropValue, f as PathRouters, S as SequenceSpec } from './types-CTSrPvY3.cjs';
+import { Renderer } from 'pixi.js';
+import { Material, Texture, Scene, Camera, WebGLRenderer, Object3D, Group, Vector3, PerspectiveCamera } from 'three';
 import { WebGPURenderer } from 'three/webgpu';
-import 'pixi.js';
 
 /** The page-level default renderer of the three layers: `registerThree({ renderer })` sets it, a layer's own `renderer` wins. */
 type ThreeRendererKind = 'webgl' | 'webgpu';
 
+/**
+ * `threeLayerTexture(ctx, 'screen')`: a live 2D layer (a `composition`) as the picture on a mesh of a `three` layer (a phone's screen, a television, a billboard, a label).
+ *
+ * The 2D layer stays a layer of the movie: the timeline drives it, its own `at` / `duration` / keyframes / filters apply. It is not drawn on the stage any more: just before the three layer draws,
+ * PixiJS draws it into a texture, and the mesh shows that texture. Two routes, chosen by what the layer has:
+ *   - the three layer draws on PixiJS's own GPU device (`renderer: 'webgpu'` in a WebGPU movie, the default): the texture is PixiJS's GPUTexture itself, used through three's `ExternalTexture`
+ *     (no copy; 0.3 ms a frame measured). It is not decoded from sRGB by three (the texture is plain rgba8), so the material decodes it in its shader and the picture is flipped by its UV.
+ *   - otherwise (the layer has a canvas of its own, or PixiJS is on WebGL): the pixels are read back into a canvas (1.6 ms a frame at 480 x 270, 4 ms at 1280 x 720) and three treats it as an ordinary
+ *     sRGB canvas texture.
+ * Both give the 2D layer's colours exactly (tests/films/three-layer-texture).
+ */
+
+interface ThreeLayerTextureOptions {
+    /** Pixels of the texture per pixel of the 2D layer: 2 for a screen that is seen large. Default 1. */
+    resolution?: number;
+    /**
+     * The 2D layer's empty and half-transparent parts let what is behind the mesh show through (a sticker, a label with rounded corners, a hologram). Default `false`: an opaque screen, empty parts black,
+     * which is cheaper and never has the sorting trouble of transparent meshes (give the composition a background rect and use that). With `true` the material blends and does not write depth.
+     */
+    transparent?: boolean;
+}
+interface ThreeLayerTexture {
+    /** An unlit material that shows the 2D layer: put it on a mesh (or on one face of a box: an array of materials). A screen shines by itself, so scene lights do not shade it. */
+    material: Material;
+    /** The three texture behind the material (colours are only right through `material`, which decodes them). */
+    texture: Texture;
+    /** The size of the texture in pixels. */
+    width: number;
+    height: number;
+    /** Stop showing the layer (it is drawn on the stage again). Called when the three layer is destroyed. */
+    dispose(): void;
+}
+/** What a three layer lends to `threeLayerTexture` (set on `ctx._host` by the layer itself). */
+interface ThreeLayerHost {
+    /** A layer of the same composition by its name, among those built before this one. */
+    findLayer(name: string): Sequence | null;
+    /** The names of those layers, for the message when the name is wrong. */
+    layerNames(): string[];
+    pixiRenderer: Renderer | null;
+    /** The three layer draws on PixiJS's GPU device (no copy is needed). */
+    shared: boolean;
+    /** Run `fn` just before every draw of the three layer; returns the function that stops it. */
+    beforeDraw(fn: () => void): () => void;
+    /** Remember a handle: a rebuild that keeps the three layer gives it the new tree's layer (`rebind`). */
+    track(handle: Rebindable): void;
+}
+/** What a rebuild that keeps the three layer needs: show the layer of the new tree with the same name. */
+interface Rebindable {
+    material: Material;
+    source(): Sequence;
+    rebind(host: ThreeLayerHost): void;
+    dispose(): void;
+}
+declare function threeLayerTexture(ctx: ThreeContext, name: string, options?: ThreeLayerTextureOptions): Promise<ThreeLayerTexture>;
+
 /** Handed to setup / update / dispose. One per three sequence. */
 interface ThreeContext {
     scene: Scene;
@@ -18,6 +73,8 @@ interface ThreeContext {
     height: number;
     /** The composition's camera and the lights alive at this moment, set before every `update` when the layer has `followCamera` or `followLights`; undefined otherwise. */
     space?: SpaceNow;
+    /** Internal: what `threeLayerTexture` needs from the layer that owns this context. */
+    _host?: ThreeLayerHost;
 }
 interface ThreeSetupResult {
     /** Objects addressable from keyframes as `three.<name>.<path>`. `camera` is added implicitly unless present. */
@@ -111,6 +168,9 @@ declare class ThreeSequence extends Sequence {
     private _borrowed;
     /** True once another layer owns this layer's state: destroying this one must not let it go. */
     private _donated;
+    /** Things to do just before every draw (the 2D layers shown on meshes: `threeLayerTexture`), and those layers' handles. Both go with the state to a layer that takes it over. */
+    private _drawHooks;
+    private _layerTextures;
     private _scene;
     private _camera;
     private _ctx;
@@ -128,6 +188,12 @@ declare class ThreeSequence extends Sequence {
     protected pathRouters(): PathRouters;
     build(): Promise<void>;
     private _makeSprite;
+    /** The 2D layer that a material shows (`threeLayerTexture`), for a click on the mesh to reach it (movie.pick); null for any other material. */
+    screenOf(material: unknown): {
+        source: Sequence;
+    } | null;
+    /** What `threeLayerTexture` asks of this layer: the layers listed before it, PixiJS's renderer, whether the GPU device is shared, and a place to hook in before every draw. */
+    private _makeHost;
     /** Reuse (core/reuse.ts): the key this layer is matched by, while it can still lend its state. */
     reuseKey(): string | null;
     private _lendable;
@@ -151,6 +217,11 @@ declare class ThreeSequence extends Sequence {
         point: [number, number, number];
         distance: number;
         object3d: Object3D;
+        uv?: {
+            u: number;
+            v: number;
+        };
+        material?: unknown;
     } | null;
     /**
      * `hit.three.grab(plane)`: drag a grabbed point of the scene. Returns a function of a point (u, v) of the layer's picture (0..1, v down) that gives where the pointer's ray through the layer's
@@ -268,4 +339,4 @@ declare function registerThree(options?: {
  */
 declare function three(spec: ThreeSequenceSpec): SequenceSpec;
 
-export { type ThreeContext, type ThreeFrameCameraOptions, type ThreeGltfModel, type ThreeGltfOptions, type ThreeRendererKind, ThreeSequence, type ThreeSequenceSpec, type ThreeSetupResult, registerThree, three, threeFrameCamera, threeGltf };
+export { type ThreeContext, type ThreeFrameCameraOptions, type ThreeGltfModel, type ThreeGltfOptions, type ThreeLayerTexture, type ThreeLayerTextureOptions, type ThreeRendererKind, ThreeSequence, type ThreeSequenceSpec, type ThreeSetupResult, registerThree, three, threeFrameCamera, threeGltf, threeLayerTexture };

package/dist/three.d.ts

@@ -1,11 +1,66 @@
-import { b as SpaceNow, c as SequenceCommon, d as PropValue, e as Sequence, f as PathRouters, S as SequenceSpec } from './types-C5xo0fzb.js';
-import { Scene, Camera, WebGLRenderer, Object3D, Group, Vector3, PerspectiveCamera } from 'three';
+import { b as Sequence, c as SpaceNow, d as SequenceCommon, e as PropValue, f as PathRouters, S as SequenceSpec } from './types-CTSrPvY3.js';
+import { Renderer } from 'pixi.js';
+import { Material, Texture, Scene, Camera, WebGLRenderer, Object3D, Group, Vector3, PerspectiveCamera } from 'three';
 import { WebGPURenderer } from 'three/webgpu';
-import 'pixi.js';
 
 /** The page-level default renderer of the three layers: `registerThree({ renderer })` sets it, a layer's own `renderer` wins. */
 type ThreeRendererKind = 'webgl' | 'webgpu';
 
+/**
+ * `threeLayerTexture(ctx, 'screen')`: a live 2D layer (a `composition`) as the picture on a mesh of a `three` layer (a phone's screen, a television, a billboard, a label).
+ *
+ * The 2D layer stays a layer of the movie: the timeline drives it, its own `at` / `duration` / keyframes / filters apply. It is not drawn on the stage any more: just before the three layer draws,
+ * PixiJS draws it into a texture, and the mesh shows that texture. Two routes, chosen by what the layer has:
+ *   - the three layer draws on PixiJS's own GPU device (`renderer: 'webgpu'` in a WebGPU movie, the default): the texture is PixiJS's GPUTexture itself, used through three's `ExternalTexture`
+ *     (no copy; 0.3 ms a frame measured). It is not decoded from sRGB by three (the texture is plain rgba8), so the material decodes it in its shader and the picture is flipped by its UV.
+ *   - otherwise (the layer has a canvas of its own, or PixiJS is on WebGL): the pixels are read back into a canvas (1.6 ms a frame at 480 x 270, 4 ms at 1280 x 720) and three treats it as an ordinary
+ *     sRGB canvas texture.
+ * Both give the 2D layer's colours exactly (tests/films/three-layer-texture).
+ */
+
+interface ThreeLayerTextureOptions {
+    /** Pixels of the texture per pixel of the 2D layer: 2 for a screen that is seen large. Default 1. */
+    resolution?: number;
+    /**
+     * The 2D layer's empty and half-transparent parts let what is behind the mesh show through (a sticker, a label with rounded corners, a hologram). Default `false`: an opaque screen, empty parts black,
+     * which is cheaper and never has the sorting trouble of transparent meshes (give the composition a background rect and use that). With `true` the material blends and does not write depth.
+     */
+    transparent?: boolean;
+}
+interface ThreeLayerTexture {
+    /** An unlit material that shows the 2D layer: put it on a mesh (or on one face of a box: an array of materials). A screen shines by itself, so scene lights do not shade it. */
+    material: Material;
+    /** The three texture behind the material (colours are only right through `material`, which decodes them). */
+    texture: Texture;
+    /** The size of the texture in pixels. */
+    width: number;
+    height: number;
+    /** Stop showing the layer (it is drawn on the stage again). Called when the three layer is destroyed. */
+    dispose(): void;
+}
+/** What a three layer lends to `threeLayerTexture` (set on `ctx._host` by the layer itself). */
+interface ThreeLayerHost {
+    /** A layer of the same composition by its name, among those built before this one. */
+    findLayer(name: string): Sequence | null;
+    /** The names of those layers, for the message when the name is wrong. */
+    layerNames(): string[];
+    pixiRenderer: Renderer | null;
+    /** The three layer draws on PixiJS's GPU device (no copy is needed). */
+    shared: boolean;
+    /** Run `fn` just before every draw of the three layer; returns the function that stops it. */
+    beforeDraw(fn: () => void): () => void;
+    /** Remember a handle: a rebuild that keeps the three layer gives it the new tree's layer (`rebind`). */
+    track(handle: Rebindable): void;
+}
+/** What a rebuild that keeps the three layer needs: show the layer of the new tree with the same name. */
+interface Rebindable {
+    material: Material;
+    source(): Sequence;
+    rebind(host: ThreeLayerHost): void;
+    dispose(): void;
+}
+declare function threeLayerTexture(ctx: ThreeContext, name: string, options?: ThreeLayerTextureOptions): Promise<ThreeLayerTexture>;
+
 /** Handed to setup / update / dispose. One per three sequence. */
 interface ThreeContext {
     scene: Scene;
@@ -18,6 +73,8 @@ interface ThreeContext {
     height: number;
     /** The composition's camera and the lights alive at this moment, set before every `update` when the layer has `followCamera` or `followLights`; undefined otherwise. */
     space?: SpaceNow;
+    /** Internal: what `threeLayerTexture` needs from the layer that owns this context. */
+    _host?: ThreeLayerHost;
 }
 interface ThreeSetupResult {
     /** Objects addressable from keyframes as `three.<name>.<path>`. `camera` is added implicitly unless present. */
@@ -111,6 +168,9 @@ declare class ThreeSequence extends Sequence {
     private _borrowed;
     /** True once another layer owns this layer's state: destroying this one must not let it go. */
     private _donated;
+    /** Things to do just before every draw (the 2D layers shown on meshes: `threeLayerTexture`), and those layers' handles. Both go with the state to a layer that takes it over. */
+    private _drawHooks;
+    private _layerTextures;
     private _scene;
     private _camera;
     private _ctx;
@@ -128,6 +188,12 @@ declare class ThreeSequence extends Sequence {
     protected pathRouters(): PathRouters;
     build(): Promise<void>;
     private _makeSprite;
+    /** The 2D layer that a material shows (`threeLayerTexture`), for a click on the mesh to reach it (movie.pick); null for any other material. */
+    screenOf(material: unknown): {
+        source: Sequence;
+    } | null;
+    /** What `threeLayerTexture` asks of this layer: the layers listed before it, PixiJS's renderer, whether the GPU device is shared, and a place to hook in before every draw. */
+    private _makeHost;
     /** Reuse (core/reuse.ts): the key this layer is matched by, while it can still lend its state. */
     reuseKey(): string | null;
     private _lendable;
@@ -151,6 +217,11 @@ declare class ThreeSequence extends Sequence {
         point: [number, number, number];
         distance: number;
         object3d: Object3D;
+        uv?: {
+            u: number;
+            v: number;
+        };
+        material?: unknown;
     } | null;
     /**
      * `hit.three.grab(plane)`: drag a grabbed point of the scene. Returns a function of a point (u, v) of the layer's picture (0..1, v down) that gives where the pointer's ray through the layer's
@@ -268,4 +339,4 @@ declare function registerThree(options?: {
  */
 declare function three(spec: ThreeSequenceSpec): SequenceSpec;
 
-export { type ThreeContext, type ThreeFrameCameraOptions, type ThreeGltfModel, type ThreeGltfOptions, type ThreeRendererKind, ThreeSequence, type ThreeSequenceSpec, type ThreeSetupResult, registerThree, three, threeFrameCamera, threeGltf };
+export { type ThreeContext, type ThreeFrameCameraOptions, type ThreeGltfModel, type ThreeGltfOptions, type ThreeLayerTexture, type ThreeLayerTextureOptions, type ThreeRendererKind, ThreeSequence, type ThreeSequenceSpec, type ThreeSetupResult, registerThree, three, threeFrameCamera, threeGltf, threeLayerTexture };

package/dist/three.js

@@ -1,7 +1,7 @@
-import { Sequence, buildScope, evaluateExpr, registerSequenceType } from './chunk-4QVQ5UJJ.js';
+import { Sequence, buildScope, evaluateExpr, registerSequenceType } from './chunk-DM2OLQOJ.js';
 import './chunk-32MMNDDN.js';
 import './chunk-BXOCEZ4U.js';
-import { Texture, Sprite, TextureSource } from 'pixi.js';
+import { Texture, Sprite, TextureSource, RenderTexture, Matrix } from 'pixi.js';
 import { WebGLRenderer, Scene, PerspectiveCamera, Raycaster, Vector2, Vector3, Quaternion, Plane, Box3, RenderTarget, Group, AnimationMixer, LoopOnce, LoopRepeat, AmbientLight, DirectionalLight, SpotLight, PointLight, Color, SRGBColorSpace, Fog } from 'three';
 
 // src/three/defaults.ts
@@ -189,6 +189,9 @@ var ThreeSequence = class extends Sequence {
   _borrowed = null;
   /** True once another layer owns this layer's state: destroying this one must not let it go. */
   _donated = false;
+  /** Things to do just before every draw (the 2D layers shown on meshes: `threeLayerTexture`), and those layers' handles. Both go with the state to a layer that takes it over. */
+  _drawHooks = /* @__PURE__ */ new Set();
+  _layerTextures = [];
   _scene = null;
   _camera = null;
   _ctx = null;
@@ -287,7 +290,7 @@ var ThreeSequence = class extends Sequence {
       renderer.setClearColor(0, 0);
       const scene = new Scene();
       const camera = new PerspectiveCamera(50, width / height, 0.1, 2e3);
-      const ctx = { scene, camera, renderer, width, height };
+      const ctx = { scene, camera, renderer, width, height, _host: this._makeHost() };
       if (spec.followCamera) this._checkFollowShape(width, height, spec.name);
       let result;
       try {
@@ -320,6 +323,29 @@ var ThreeSequence = class extends Sequence {
     this.intrinsicHeight = height;
     this.buildFilters();
   }
+  /** The 2D layer that a material shows (`threeLayerTexture`), for a click on the mesh to reach it (movie.pick); null for any other material. */
+  screenOf(material) {
+    const handle = this._layerTextures.find((h) => h.material === material);
+    return handle ? { source: handle.source() } : null;
+  }
+  /** What `threeLayerTexture` asks of this layer: the layers listed before it, PixiJS's renderer, whether the GPU device is shared, and a place to hook in before every draw. */
+  _makeHost() {
+    return {
+      findLayer: (name) => this.parent?.findLayer?.(name) ?? null,
+      layerNames: () => this.parent?.layerNames?.() ?? [],
+      pixiRenderer: this.root.pixiRenderer ?? null,
+      shared: this.sharedGpu,
+      beforeDraw: (fn) => {
+        this._drawHooks.add(fn);
+        return () => {
+          this._drawHooks.delete(fn);
+        };
+      },
+      track: (handle) => {
+        this._layerTextures.push(handle);
+      }
+    };
+  }
   /** Reuse (core/reuse.ts): the key this layer is matched by, while it can still lend its state. */
   reuseKey() {
     return this._renderer && !this._donated && !this._closing ? this._key : null;
@@ -345,6 +371,10 @@ var ThreeSequence = class extends Sequence {
     this._fogMirror = d._fogMirror;
     this._tracked = d._tracked;
     this._borrowed = d;
+    this._drawHooks = d._drawHooks;
+    this._layerTextures = d._layerTextures;
+    const host = this._makeHost();
+    for (const h of this._layerTextures) h.rebind(host);
     if (this.spec && this._threeSpec.followCamera) this._checkFollowShape(width, height, name);
     this._makeSprite(this._texture, width, height, name);
   }
@@ -402,7 +432,9 @@ var ThreeSequence = class extends Sequence {
         name = n.name;
         break;
       }
-      return { object: name, point: hit.point.toArray(), distance: hit.distance, object3d: hit.object };
+      const m = hit.object.material;
+      const material = Array.isArray(m) ? m[hit.face?.materialIndex ?? 0] : m;
+      return { object: name, point: hit.point.toArray(), distance: hit.distance, object3d: hit.object, ...hit.uv ? { uv: { u: hit.uv.x, v: hit.uv.y } } : {}, material };
     }
     return null;
   }
@@ -573,6 +605,7 @@ var ThreeSequence = class extends Sequence {
    */
   _draw(t, toCanvas = false) {
     if (!this._renderer || !this._scene || !this._camera) return;
+    for (const hook of this._drawHooks) hook();
     if (this._gpu) this._advanceNodeFrame(t);
     if (!this._rt || toCanvas) {
       this._renderer.render(this._scene, this._camera);
@@ -623,9 +656,9 @@ var ThreeSequence = class extends Sequence {
       if (!m || typeof m !== "object" || seen.has(m)) return;
       seen.add(m);
       const mat = m;
-      const label = `${mat.name ? `"${mat.name}" ` : ""}${mat.type ?? "material"}`;
-      if (mat.isShaderMaterial || mat.isRawShaderMaterial) bad.push(`${label} is a ShaderMaterial (it cannot run on the WebGPU renderer)`);
-      else if (Object.prototype.hasOwnProperty.call(mat, "onBeforeCompile")) bad.push(`${label} sets onBeforeCompile (the WebGPU renderer ignores it)`);
+      const label2 = `${mat.name ? `"${mat.name}" ` : ""}${mat.type ?? "material"}`;
+      if (mat.isShaderMaterial || mat.isRawShaderMaterial) bad.push(`${label2} is a ShaderMaterial (it cannot run on the WebGPU renderer)`);
+      else if (Object.prototype.hasOwnProperty.call(mat, "onBeforeCompile")) bad.push(`${label2} sets onBeforeCompile (the WebGPU renderer ignores it)`);
     };
     scene.traverse?.((o) => {
       const mats = o.material;
@@ -722,6 +755,12 @@ var ThreeSequence = class extends Sequence {
     }
     const texture = this._texture;
     if (!kept) {
+      for (const h of this._layerTextures) {
+        try {
+          h.dispose();
+        } catch {
+        }
+      }
       this._lightMirror?.dispose();
       this._fogMirror?.dispose();
       this._disposeRenderer();
@@ -757,19 +796,19 @@ function idOf(fn) {
   return id;
 }
 async function threeGltf(url, options = {}) {
-  const label = "pixi-effects: threeGltf";
-  if (typeof url !== "string" || !url) throw new Error(`${label}: the first argument is the URL of a .glb or .gltf file`);
+  const label2 = "pixi-effects: threeGltf";
+  if (typeof url !== "string" || !url) throw new Error(`${label2}: the first argument is the URL of a .glb or .gltf file`);
   let GLTFLoader;
   try {
     ({ GLTFLoader } = await import('three/addons/loaders/GLTFLoader.js'));
   } catch (err) {
-    throw new Error(`${label}: needs "three/addons/" in the import map next to "three" (${err instanceof Error ? err.message : err})`);
+    throw new Error(`${label2}: needs "three/addons/" in the import map next to "three" (${err instanceof Error ? err.message : err})`);
   }
   let gltf;
   try {
     gltf = await new GLTFLoader().loadAsync(url);
   } catch (err) {
-    throw new Error(`${label}: could not load "${url}" (${err instanceof Error ? err.message : err})`, { cause: err });
+    throw new Error(`${label2}: could not load "${url}" (${err instanceof Error ? err.message : err})`, { cause: err });
   }
   const clips = gltf.animations ?? [];
   let clip;
@@ -778,7 +817,7 @@ async function threeGltf(url, options = {}) {
   else if (wanted === void 0) clip = clips[0];
   else {
     clip = typeof wanted === "number" ? clips[wanted] : clips.find((c) => c.name === wanted);
-    if (!clip) throw new Error(`${label}: "${url}" has no animation ${JSON.stringify(wanted)}; its clips: ${clips.length ? clips.map((c, i) => `${i}: "${c.name}"`).join(", ") : "(none)"}`);
+    if (!clip) throw new Error(`${label2}: "${url}" has no animation ${JSON.stringify(wanted)}; its clips: ${clips.length ? clips.map((c, i) => `${i}: "${c.name}"`).join(", ") : "(none)"}`);
   }
   const root = gltf.scene;
   root.traverse((o) => {
@@ -840,6 +879,145 @@ function threeFrameCamera(camera, object, options = {}) {
   cam.lookAt(centre);
   cam.updateProjectionMatrix();
 }
+var label = "pixi-effects: threeLayerTexture";
+async function threeLayerTexture(ctx, name, options = {}) {
+  const host = ctx._host;
+  if (!host) throw new Error(`${label}: call it from the setup of a three layer: const screen = await threeLayerTexture(ctx, 'screen')`);
+  if (typeof name !== "string" || !name) throw new Error(`${label}: the second argument is the name of a 2D layer: threeLayerTexture(ctx, 'screen')`);
+  const resolution = options.resolution ?? 1;
+  const transparent = options.transparent === true;
+  if (!(Number.isFinite(resolution) && resolution > 0 && resolution <= 4)) throw new Error(`${label}: resolution is a number from above 0 to 4 (2 = twice the pixels), got ${JSON.stringify(options.resolution)}`);
+  const pixi = host.pixiRenderer;
+  if (!pixi) throw new Error(`${label}: PixiJS's renderer is not available here (the movie is not ready)`);
+  const source = host.findLayer(name);
+  if (!source) {
+    const names = host.layerNames();
+    throw new Error(`${label}: no layer named "${name}" before this three layer${names.length ? ` (the layers built before it: ${names.map((n) => `"${n}"`).join(", ")})` : ""}. A layer shown on a mesh must be listed BEFORE the three layer, in the same composition, and have that name.`);
+  }
+  if (source.spec.type !== "composition") {
+    throw new Error(`${label}: "${name}" is a ${source.spec.type} layer: a layer shown on a mesh must be a composition (wrap it: { type: 'composition', name: '${name}', width: 480, height: 270, sequences: [ \u2026 ] })`);
+  }
+  const width = Math.max(1, Math.round(source.intrinsicWidth * resolution)), height = Math.max(1, Math.round(source.intrinsicHeight * resolution));
+  const sharedRoute = host.shared && pixi.name === "webgpu";
+  const rt = RenderTexture.create({ width, height, resolution: 1, ...sharedRoute ? { autoGenerateMipmaps: true } : {} });
+  const gpuTexture = sharedRoute ? pixi.texture.getGpuSource?.(rt.source) : void 0;
+  let texture, material, readCanvas = null;
+  if (gpuTexture) {
+    let webgpu, tsl;
+    try {
+      [webgpu, tsl] = await Promise.all([import('three/webgpu'), import('three/tsl')]);
+    } catch (err) {
+      throw new Error(`${label}: needs "three/webgpu" and "three/tsl" in the import map (${err instanceof Error ? err.message : err})`);
+    }
+    const ext = new webgpu.ExternalTexture(gpuTexture);
+    ext.colorSpace = webgpu.NoColorSpace;
+    ext.minFilter = webgpu.LinearMipmapLinearFilter;
+    ext.magFilter = webgpu.LinearFilter;
+    ext.generateMipmaps = false;
+    ext.anisotropy = 4;
+    ext.repeat.set(1, -1);
+    ext.offset.set(0, 1);
+    const m = new webgpu.MeshBasicNodeMaterial();
+    const t = tsl.texture(ext);
+    const tex = t, vec4 = tsl.vec4, eotf = tsl.sRGBTransferEOTF, max = tsl.max;
+    const straight = eotf(vec4(tex.rgb.div(max(tex.a, 1e-4)), 1));
+    m.colorNode = transparent ? vec4(straight.rgb, tex.a) : vec4(eotf(vec4(tex.rgb, 1)).rgb, 1);
+    m.toneMapped = false;
+    if (transparent) {
+      m.transparent = true;
+      m.depthWrite = false;
+    }
+    texture = ext;
+    material = m;
+  } else {
+    const three2 = await import('three');
+    readCanvas = document.createElement("canvas");
+    readCanvas.width = width;
+    readCanvas.height = height;
+    const ct = new three2.CanvasTexture(readCanvas);
+    ct.colorSpace = three2.SRGBColorSpace;
+    texture = ct;
+    material = new three2.MeshBasicMaterial({ map: ct, toneMapped: false, ...transparent ? { transparent: true, depthWrite: false } : {} });
+  }
+  let current = source;
+  let display = source.target;
+  let sx = width / source.intrinsicWidth, sy = height / source.intrinsicHeight;
+  let hidden = false;
+  const hide = () => {
+    display.visible = false;
+    hidden = true;
+  };
+  hide();
+  const uncull = (c) => {
+    if (c.culled) c.culled = false;
+    for (const k of c.children) uncull(k);
+  };
+  const refresh = () => {
+    const m = new Matrix().scale(sx, sy);
+    display.visible = true;
+    uncull(display);
+    try {
+      pixi.render({ container: display, target: rt, transform: m, clear: true, clearColor: [0, 0, 0, 0] });
+    } finally {
+      display.visible = false;
+    }
+    if (gpuTexture) rt.source.updateMipmaps();
+    if (readCanvas) {
+      const g = readCanvas.getContext("2d");
+      if (transparent) {
+        const { pixels, width: w, height: h } = pixi.extract.pixels(rt);
+        for (let i = 0; i < pixels.length; i += 4) {
+          const a = pixels[i + 3];
+          if (a > 0 && a < 255) {
+            const k = 255 / a;
+            pixels[i] = pixels[i] * k;
+            pixels[i + 1] = pixels[i + 1] * k;
+            pixels[i + 2] = pixels[i + 2] * k;
+          }
+        }
+        g.putImageData(new ImageData(pixels, w, h), 0, 0);
+      } else {
+        g.clearRect(0, 0, width, height);
+        g.drawImage(pixi.extract.canvas(rt), 0, 0);
+      }
+      texture.needsUpdate = true;
+    }
+  };
+  const stop = host.beforeDraw(refresh);
+  refresh();
+  const handle = {
+    material,
+    texture,
+    width,
+    height,
+    source: () => current,
+    rebind(next) {
+      const again = next.findLayer(name);
+      if (!again) throw new Error(`${label}: after a rebuild there is no layer "${name}" before the three layer any more`);
+      current = again;
+      display = again.target;
+      sx = width / again.intrinsicWidth;
+      sy = height / again.intrinsicHeight;
+      hide();
+      refresh();
+    },
+    dispose() {
+      stop();
+      if (hidden) {
+        display.visible = true;
+        hidden = false;
+      }
+      try {
+        rt.destroy(true);
+      } catch {
+      }
+      texture.dispose?.();
+      material.dispose?.();
+    }
+  };
+  host.track(handle);
+  return handle;
+}
 
 // src/three/index.ts
 function registerThree(options = {}) {
@@ -852,6 +1030,6 @@ function three(spec) {
   return spec;
 }
 
-export { ThreeSequence, registerThree, three, threeFrameCamera, threeGltf };
+export { ThreeSequence, registerThree, three, threeFrameCamera, threeGltf, threeLayerTexture };
 //# sourceMappingURL=three.js.map
 //# sourceMappingURL=three.js.map