@aura3d/rendering 4.0.3 → 4.0.5

package/dist/WebGPUDevice.js

@@ -5,6 +5,8 @@ import { normalizeWebGPUTemporalOptions, WEBGPU_TAA_FRAGMENT, WEBGPU_TAA_OUTPUT_
 import { defaultWebGPUBloomWeights, normalizeWebGPUColorGradeOptions, normalizeWebGPUBloomOptions, webgpuBlurFragment, webgpuBloomCompositeFragment, webgpuBrightExtractFragment, webgpuColorGradeFragment, webgpuFxaaFragment, WEBGPU_POST_VERTEX_WGSL } from "./webgpu/WebGPUPostShaders.js";
 import { DEFAULT_DEPTH_SHADER_MARKER } from "./ShaderLibraryCore.js";
 import { reflectShaderSources } from "./ShaderReflection.js";
+import { recordPostSkipped, recordPostStage } from "./renderer/postSkipped.js";
+import { registeredPostPasses } from "./contracts/post.js";
 import { Texture, bytesPerPixel, isCompressedTextureFormat } from "./Texture.js";
 import { isTextureBinding, TextureBinding } from "./TextureBinding.js";
 import {} from "./VertexFormat.js";
@@ -162,6 +164,13 @@ export class WebGPUDevice {
     drawCalls = 0;
     viewportWidth = 0;
     viewportHeight = 0;
+    /** SC-01: viewport/scissor override (origin bottom-left, three convention) and the target it was set on; applies only while that target is bound. */
+    viewStateTarget = null;
+    viewportOverride = null;
+    scissorOverride = null;
+    scissorTestOn = false;
+    /** XR/SC-01: viewport scoped to the default (canvas) target that survives `beginFrame`. */
+    persistentViewportRect = null;
     clearColor = [0, 0, 0, 1];
     lastError = null;
     nativeSubmissions = 0;
@@ -202,6 +211,14 @@ export class WebGPUDevice {
     shaders = new Set();
     renderTargets = new Set();
     nativeSampledTextures = new Map();
+    /**
+     * threejs-parity ST-03 (L4): `Texture.revision` recorded at the last native
+     * upload. A mismatch on a cached binding re-uploads the texture in place —
+     * the same revision gate WebGL2 has in `webgl2/TextureUpload.ts` — so
+     * canvas/video/data textures bound through `texture.*` handles refresh
+     * on `needsUpdate` instead of staying frozen at the first upload.
+     */
+    nativeSampledTextureRevisions = new Map();
     activeRenderTarget = null;
     canvasDepthTexture = null;
     canvasDepthView = null;
@@ -225,6 +242,10 @@ export class WebGPUDevice {
         }
         return new WebGPUDevice(adapter, device, canvasContext, presentationFormat);
     }
+    /** The native `GPUDevice` this render device owns; used by `createComputeContext` (SH-04). */
+    get nativeGpuDevice() {
+        return this.device;
+    }
     constructor(adapter, device, canvasContext, presentationFormat) {
         this.adapter = adapter;
         this.device = device;
@@ -661,9 +682,65 @@ export class WebGPUDevice {
         this.lastError = null;
         this.viewportWidth = width;
         this.viewportHeight = height;
+        this.viewportOverride = null;
+        this.scissorOverride = null;
+        this.scissorTestOn = false;
+        this.viewStateTarget = null;
         this.releaseDisposedNativeSampledTextures();
         this.ensureCanvasDepthAttachment(width, height);
     }
+    /** threejs-parity L7/SC-01: raster viewport in target pixels, origin bottom-left; converted to WebGPU's top-left origin per draw pass. */
+    setViewport(x, y, width, height, options) {
+        this.assertAlive();
+        if (!(width > 0) || !(height > 0)) {
+            throw new RenderDeviceError("Viewport dimensions must be positive", "INVALID_VIEWPORT", { width, height });
+        }
+        if (options?.persistent) {
+            this.persistentViewportRect = { x, y, width, height };
+            return;
+        }
+        this.viewportOverride = { x, y, width, height };
+        this.viewStateTarget = this.activeRenderTarget;
+    }
+    /** Clears the persistent viewport and the frame-scoped override. */
+    resetViewport() {
+        this.assertAlive();
+        this.persistentViewportRect = null;
+        this.viewportOverride = null;
+        this.viewStateTarget = null;
+    }
+    setScissor(x, y, width, height) {
+        this.assertAlive();
+        if (width < 0 || height < 0) {
+            throw new RenderDeviceError("Scissor dimensions must be non-negative", "INVALID_SCISSOR", { width, height });
+        }
+        this.scissorOverride = { x, y, width, height };
+        this.viewStateTarget = this.activeRenderTarget;
+    }
+    setScissorTest(enabled) {
+        this.assertAlive();
+        this.scissorTestOn = enabled;
+        this.viewStateTarget = this.activeRenderTarget;
+    }
+    /** Applies the live viewport/scissor override (if any) to a draw pass. Clears are full-attachment load ops and are never scissored. */
+    applyViewStateToPass(pass) {
+        const targetHeight = this.activeRenderTarget ? this.activeRenderTarget.height : this.viewportHeight;
+        if (this.viewStateTarget !== this.activeRenderTarget || !this.viewportOverride) {
+            const persistent = this.activeRenderTarget === null ? this.persistentViewportRect : null;
+            if (persistent)
+                pass.setViewport?.(persistent.x, targetHeight - persistent.y - persistent.height, persistent.width, persistent.height, 0, 1);
+        }
+        if (this.viewStateTarget !== this.activeRenderTarget)
+            return;
+        if (this.viewportOverride) {
+            const v = this.viewportOverride;
+            pass.setViewport?.(v.x, targetHeight - v.y - v.height, v.width, v.height, 0, 1);
+        }
+        if (this.scissorTestOn && this.scissorOverride) {
+            const r = this.scissorOverride;
+            pass.setScissorRect?.(r.x, targetHeight - r.y - r.height, r.width, r.height);
+        }
+    }
     clear(color) {
         this.assertFrame();
         this.clearColor = color;
@@ -1027,8 +1104,29 @@ export class WebGPUDevice {
         const owned = [];
         let current = source;
         const track = (target) => { owned.push(target); current = target; };
+        /*
+         * threejs-parity SH-03/SH-06: C-13 custom passes registered via
+         * `registerPostPass` (`app.post.addPostPass` / `effects.shaderPass`) run on
+         * the native WebGPU chain too. Anchor resolution mirrors the v2 graph's
+         * named slots onto this chain's pass order; a registered pass missing its
+         * WGSL fragment is recorded `WGSL_PROGRAM_MISSING:<id>` and skipped — never
+         * silently, never as a GLSL fallback.
+         */
+        const customAt = this.webgpuCustomPassPositions(options.passes);
+        const runCustomsAt = (position) => {
+            const customs = customAt.get(position);
+            if (!customs?.length)
+                return;
+            for (const custom of customs) {
+                const out = this.executeWebGPUCustomPass(custom, current);
+                if (out)
+                    track(out);
+            }
+        };
         try {
-            for (const pass of options.passes) {
+            for (let passIndex = 0; passIndex < options.passes.length; passIndex += 1) {
+                runCustomsAt(passIndex);
+                const pass = options.passes[passIndex];
                 if (pass.name === "bloom")
                     track(this.executeWebGPUBloom(current, pass.options));
                 else if (pass.name === "color-grade")
@@ -1061,6 +1159,7 @@ export class WebGPUDevice {
                     current = target;
                 }
             }
+            runCustomsAt(options.passes.length);
             const target = options.outputTarget ?? null;
             if (target === current)
                 throw new RenderDeviceError("Native WebGPU presentation source/output alias", "INVALID_RESOURCE");
@@ -1108,6 +1207,139 @@ export class WebGPUDevice {
             throw error;
         }
     }
+    /**
+     * SH-03: maps each registered custom pass's `insertAt` anchor onto a position
+     * in this native chain — `position` runs BEFORE `options.passes[position]` and
+     * `options.passes.length` runs after the last pass (before the present copy).
+     * Deterministic fallbacks keep passes attached when their anchor stage is not
+     * in the submitted chain. Passes sharing a position sort by `order` ascending
+     * (stable — registration order preserved for omitted keys).
+     */
+    webgpuCustomPassPositions(passes) {
+        const positions = new Map();
+        const customs = registeredPostPasses();
+        if (!customs.length)
+            return positions;
+        const indexOf = (...names) => passes.findIndex((pass) => names.includes(pass.name));
+        const anchorPosition = (insertAt) => {
+            switch (insertAt) {
+                case "after-depth": return 0;
+                case "before-taa": {
+                    const taa = indexOf("taa");
+                    if (taa >= 0)
+                        return taa;
+                    const bloom = indexOf("bloom");
+                    return bloom >= 0 ? bloom : 0;
+                }
+                case "after-taa": {
+                    const taa = indexOf("taa");
+                    if (taa >= 0)
+                        return taa + 1;
+                    // No TAA: the anchor still precedes bloom (v2 graph order is TAA → after-taa → bloom).
+                    const bloom = indexOf("bloom");
+                    return bloom >= 0 ? bloom : 0;
+                }
+                case "before-tonemap": {
+                    const tone = indexOf("tone-mapping");
+                    return tone >= 0 ? tone : passes.length;
+                }
+                case "after-tonemap": {
+                    const tone = indexOf("tone-mapping");
+                    return tone >= 0 ? tone + 1 : passes.length;
+                }
+                default: return passes.length;
+            }
+        };
+        const orderKey = (pass) => typeof pass.order === "number" && Number.isFinite(pass.order) ? pass.order : Number.MAX_SAFE_INTEGER;
+        for (const pass of [...customs].sort((a, b) => orderKey(a) - orderKey(b))) {
+            const position = anchorPosition(pass.insertAt);
+            const list = positions.get(position) ?? [];
+            list.push(pass);
+            positions.set(position, list);
+        }
+        return positions;
+    }
+    /**
+     * SH-03/SH-06: one C-13 custom pass as a native WGSL fullscreen draw.
+     *
+     * Bind convention (fixed by runWebGPUFullscreenPass): binding 0 = uniform
+     * buffer (`vec4f` array — `values[0]` is `vec4(texelSize, timeSeconds, 0)`,
+     * declared uniforms follow in registration order, one vec4 each), binding 1 =
+     * linear sampler, binding 2 = `u_color`, binding 3 = `u_depthLinear` (only
+     * when `inputs` declares "depth"), binding 4 = `u_velocity` (only for
+     * "velocity"). The authored `fragment.wgsl` is a complete fragment stage;
+     * its `@fragment` entry point is detected or defaults to `fs_main`.
+     *
+     * Returns null when the pass is disabled or has no WGSL (recorded as
+     * `WGSL_PROGRAM_MISSING:<id>` in the post skipped-reasons channel).
+     */
+    executeWebGPUCustomPass(pass, source) {
+        const timeSeconds = typeof performance !== "undefined" ? performance.now() / 1000 : Date.now() / 1000;
+        const frameContext = {
+            device: this,
+            width: source.width,
+            height: source.height,
+            timeSeconds,
+            frameIndex: 0
+        };
+        if (pass.enabled && !pass.enabled(frameContext))
+            return null;
+        const wgsl = pass.fragment.wgsl;
+        if (typeof wgsl !== "string" || !wgsl.trim()) {
+            recordPostSkipped(`WGSL_PROGRAM_MISSING:${pass.id}`);
+            return null;
+        }
+        const src = this.requireRenderTarget(source);
+        const srcView = src.nativeView;
+        if (!srcView) {
+            throw new RenderDeviceError("WebGPU custom pass source target has no native view", "NATIVE_POST_UNSUPPORTED", { label: src.label });
+        }
+        recordPostStage(`custom:${pass.id}@${pass.insertAt}`);
+        const wantsDepth = pass.inputs.includes("depth");
+        const wantsVelocity = pass.inputs.includes("velocity");
+        const target = this.createRenderTarget({
+            width: src.width,
+            height: src.height,
+            format: pass.space === "display" ? "rgba8" : "rgba16f",
+            label: `a3d-webgpu-custom-${pass.id}`
+        });
+        const views = [srcView];
+        if (wantsDepth)
+            views.push(this.requireRenderTarget(this.webgpuPostBlankTarget()).nativeView);
+        if (wantsVelocity)
+            views.push(this.requireRenderTarget(this.webgpuPostBlankTarget()).nativeView);
+        const declared = pass.uniforms?.(frameContext) ?? {};
+        const packed = [1 / src.width, 1 / src.height, timeSeconds, 0];
+        for (const value of Object.values(declared)) {
+            const scalars = Array.isArray(value) ? [...value] : [value];
+            for (let offset = 0; offset < Math.max(1, scalars.length); offset += 4) {
+                for (let lane = 0; lane < 4; lane += 1)
+                    packed.push(Number.isFinite(scalars[offset + lane]) ? scalars[offset + lane] : 0);
+            }
+        }
+        const entryPoint = wgsl.match(/@fragment\s*fn\s+([A-Za-z_]\w*)/)?.[1] ?? "fs_main";
+        try {
+            this.runWebGPUFullscreenPass({
+                label: `webgpu-custom:${pass.id}`,
+                fragment: wgsl,
+                entryPoint,
+                uniforms: new Float32Array(packed),
+                views,
+                target
+            });
+            return target;
+        }
+        catch (error) {
+            target.dispose();
+            throw error;
+        }
+    }
+    /** 1×1 stand-in for declared depth/velocity inputs this chain cannot supply (matches the WebGL2 blankTex fallback). */
+    webgpuPostBlankTarget() {
+        this.webgpuPostBlank ??= this.createRenderTarget({ width: 1, height: 1, format: "rgba8", label: "a3d-webgpu-custom-blank" });
+        return this.webgpuPostBlank;
+    }
+    webgpuPostBlank = null;
     runWebGPUFullscreenPass(args) {
         // No assertFrame here on purpose: these are target-to-target passes with
         // their own encoders, so they run both inside a Renderer frame (scene ->
@@ -1229,6 +1461,7 @@ export class WebGPUDevice {
         for (const resource of this.nativeSampledTextures.values())
             resource.texture.destroy();
         this.nativeSampledTextures.clear();
+        this.nativeSampledTextureRevisions.clear();
         this.canvasDepthTexture?.destroy();
         this.canvasDepthTexture = null;
         this.canvasDepthView = null;
@@ -1476,6 +1709,7 @@ export class WebGPUDevice {
         });
         this.nativeRenderPasses += 1;
         pass.setPipeline(pipeline);
+        this.applyViewStateToPass(pass);
         pass.setVertexBuffer(0, vertexBuffer.handle);
         if (bindGroup)
             pass.setBindGroup?.(0, bindGroup);
@@ -1591,65 +1825,193 @@ export class WebGPUDevice {
                 actual: true
             };
         }
+        // ST-03 (L4): live sources (video) may mark a new frame before the
+        // revision comparison runs.
+        texture.pollContentRevision?.();
         let resource = this.nativeSampledTextures.get(texture);
+        if (resource && this.nativeSampledTextureRevisions.get(texture) !== texture.revision) {
+            // ST-03: revision-bumped content (Texture.update / handle needsUpdate /
+            // a video frame) — re-upload into the same GPUTexture so every binding
+            // built on it refreshes without re-allocating.
+            if (this.uploadNativeSampledTextureRevision(texture, resource.texture)) {
+                this.nativeSampledTextureRevisions.set(texture, texture.revision);
+            }
+        }
         if (!resource) {
-            if (texture.source) {
-                const sourceLevels = nativeTextureSourceLevels(texture);
-                if (sourceLevels.length === 0)
-                    return null;
-                const nativeTexture = this.device.createTexture({
-                    label: texture.label,
-                    size: { width: texture.width, height: texture.height, depthOrArrayLayers: 1 },
-                    format: webgpuSampledTextureFormat(texture, "rgba8"),
-                    usage: TEXTURE_USAGE.TEXTURE_BINDING | TEXTURE_USAGE.COPY_DST,
-                    mipLevelCount: sourceLevels.length
-                });
+            const created = this.createNativeSampledTextureResource(texture);
+            if (!created)
+                return null;
+            resource = created;
+            this.nativeSampledTextures.set(texture, created);
+            this.nativeSampledTextureRevisions.set(texture, texture.revision);
+        }
+        return {
+            view: resource.view,
+            sampler: this.device.createSampler(webgpuSamplerDescriptor(binding.sampler)),
+            actual: true
+        };
+    }
+    /**
+     * threejs-parity ST-01/ST-02/ST-03 (L4): allocate and upload the native
+     * texture for a `Texture`. Source-backed textures prefer
+     * `queue.copyExternalImageToTexture` (the level-0 external-image copy
+     * replaces the draw-to-canvas readback entirely); when a mip chain is
+     * requested — or the queue predates the copy — the canvas readback path
+     * still produces real downsized levels so mipmap samplers stay complete.
+     * `2d-array` textures upload every layer in a single writeTexture and cube
+     * textures write all six faces at `origin.z = face`.
+     */
+    createNativeSampledTextureResource(texture) {
+        if (!this.device.createTexture)
+            return null;
+        if (texture.source) {
+            const copyExternalImageToTexture = this.device.queue.copyExternalImageToTexture;
+            const useExternalCopy = typeof copyExternalImageToTexture === "function" && !texture.generateMipmaps;
+            const sourceLevels = useExternalCopy ? [] : nativeTextureSourceLevels(texture);
+            if (!useExternalCopy && sourceLevels.length === 0)
+                return null;
+            const nativeTexture = this.device.createTexture({
+                label: texture.label,
+                size: { width: texture.width, height: texture.height, depthOrArrayLayers: 1 },
+                format: webgpuSampledTextureFormat(texture, "rgba8"),
+                // copyExternalImageToTexture additionally requires RENDER_ATTACHMENT.
+                usage: TEXTURE_USAGE.TEXTURE_BINDING | TEXTURE_USAGE.COPY_DST | (useExternalCopy ? TEXTURE_USAGE.RENDER_ATTACHMENT : 0),
+                mipLevelCount: useExternalCopy ? 1 : sourceLevels.length
+            });
+            if (useExternalCopy) {
+                copyExternalImageToTexture.call(this.device.queue, { source: texture.source, flipY: texture.flipY }, { texture: nativeTexture }, { width: texture.width, height: texture.height, depthOrArrayLayers: 1 });
+                this.nativeTextureUploads += 1;
+            }
+            else {
                 const writeTexture = this.device.queue.writeTexture;
-                if (!writeTexture)
+                if (!writeTexture) {
+                    nativeTexture.destroy();
                     return null;
+                }
                 sourceLevels.forEach((level, mipLevel) => {
                     writeTexture.call(this.device.queue, { texture: nativeTexture, mipLevel }, level.data, { bytesPerRow: level.bytesPerRow, rowsPerImage: level.height }, { width: level.width, height: level.height, depthOrArrayLayers: 1 });
                     this.nativeTextureUploads += 1;
                 });
-                resource = { texture: nativeTexture, view: nativeTexture.createView() };
             }
-            else {
-                const sampledTexture = nativeSampledTextureLevels(texture);
-                if (!sampledTexture)
-                    return null;
-                const { levels, format } = sampledTexture;
-                const baseLevel = levels[0];
-                if (!baseLevel)
-                    return null;
-                const levelBytesPerPixel = bytesPerPixel(format);
-                if (levels.some((level) => level.data.byteLength < level.width * level.height * levelBytesPerPixel))
-                    return null;
-                const nativeTexture = this.device.createTexture({
-                    label: texture.label,
-                    size: { width: baseLevel.width, height: baseLevel.height, depthOrArrayLayers: 1 },
-                    format: webgpuSampledTextureFormat(texture, format),
-                    usage: TEXTURE_USAGE.TEXTURE_BINDING | TEXTURE_USAGE.COPY_DST,
-                    mipLevelCount: levels.length
-                });
-                for (const [mipLevel, level] of levels.entries()) {
-                    this.device.queue.writeTexture({ texture: nativeTexture, mipLevel }, level.data, { bytesPerRow: level.width * levelBytesPerPixel, rowsPerImage: level.height }, { width: level.width, height: level.height, depthOrArrayLayers: 1 });
-                    this.nativeTextureUploads += 1;
-                }
-                resource = { texture: nativeTexture, view: nativeTexture.createView() };
+            return { texture: nativeTexture, view: nativeTexture.createView() };
+        }
+        if (texture.dimension === "cube") {
+            const faces = texture.cubeFaces;
+            if (faces.length !== 6)
+                return null;
+            const mipLevelCount = faces[0]?.mipLevels.length ?? 0;
+            if (mipLevelCount === 0)
+                return null;
+            const nativeTexture = this.device.createTexture({
+                label: texture.label,
+                size: { width: texture.width, height: texture.height, depthOrArrayLayers: 6 },
+                format: webgpuSampledTextureFormat(texture, texture.format),
+                usage: TEXTURE_USAGE.TEXTURE_BINDING | TEXTURE_USAGE.COPY_DST,
+                mipLevelCount
+            });
+            if (!this.writeNativeCubeFaceLevels(texture, nativeTexture)) {
+                nativeTexture.destroy();
+                return null;
             }
-            this.nativeSampledTextures.set(texture, resource);
+            return { texture: nativeTexture, view: nativeTexture.createView({ dimension: "cube" }) };
         }
-        return {
-            view: resource.view,
-            sampler: this.device.createSampler(webgpuSamplerDescriptor(binding.sampler)),
-            actual: true
-        };
+        const sampledTexture = nativeSampledTextureLevels(texture);
+        if (!sampledTexture)
+            return null;
+        const { levels, format } = sampledTexture;
+        const baseLevel = levels[0];
+        if (!baseLevel)
+            return null;
+        const levelBytesPerPixel = bytesPerPixel(format);
+        if (levels.some((level) => level.data.byteLength < level.width * level.height * levelBytesPerPixel))
+            return null;
+        const depthOrArrayLayers = texture.dimension === "2d-array" ? texture.layers : 1;
+        const nativeTexture = this.device.createTexture({
+            label: texture.label,
+            size: { width: baseLevel.width, height: baseLevel.height, depthOrArrayLayers },
+            format: webgpuSampledTextureFormat(texture, format),
+            usage: TEXTURE_USAGE.TEXTURE_BINDING | TEXTURE_USAGE.COPY_DST,
+            mipLevelCount: levels.length
+        });
+        if (!this.writeNativeTextureLevels(texture, nativeTexture, levels, format)) {
+            nativeTexture.destroy();
+            return null;
+        }
+        return { texture: nativeTexture, view: nativeTexture.createView() };
+    }
+    /**
+     * threejs-parity ST-01/ST-03 (L4): push every mip level of `levels` into
+     * `nativeTexture`; for `2d-array` textures a single writeTexture covers all
+     * `texture.layers` slices (the level data is stored layer-contiguous).
+     */
+    writeNativeTextureLevels(texture, nativeTexture, levels, format) {
+        const writeTexture = this.device.queue.writeTexture;
+        if (!writeTexture)
+            return false;
+        const levelBytesPerPixel = bytesPerPixel(format);
+        for (const [mipLevel, level] of levels.entries()) {
+            writeTexture.call(this.device.queue, { texture: nativeTexture, mipLevel }, level.data, { bytesPerRow: level.width * levelBytesPerPixel, rowsPerImage: level.height }, { width: level.width, height: level.height, depthOrArrayLayers: texture.dimension === "2d-array" ? texture.layers : 1 });
+            this.nativeTextureUploads += 1;
+        }
+        return true;
+    }
+    /** threejs-parity ST-01 (L4): per-face per-level writeTexture for cube textures. */
+    writeNativeCubeFaceLevels(texture, nativeTexture) {
+        if (!this.device.queue.writeTexture)
+            return false;
+        const faceOrder = ["px", "nx", "py", "ny", "pz", "nz"];
+        const levelBytesPerPixel = bytesPerPixel(texture.format);
+        for (const [faceIndex, face] of faceOrder.entries()) {
+            const faceData = texture.cubeFaces.find((candidate) => candidate.face === face);
+            if (!faceData)
+                return false;
+            for (const [mipLevel, level] of faceData.mipLevels.entries()) {
+                this.device.queue.writeTexture({ texture: nativeTexture, mipLevel, origin: { z: faceIndex } }, level.data, { bytesPerRow: level.width * levelBytesPerPixel, rowsPerImage: level.height }, { width: level.width, height: level.height, depthOrArrayLayers: 1 });
+                this.nativeTextureUploads += 1;
+            }
+        }
+        return true;
+    }
+    /**
+     * threejs-parity ST-03 (L4): in-place re-upload for a revision-bumped
+     * texture. Mirrors the create paths — external-image copy for source
+     * textures (the video per-frame path), whole-chain writeTexture otherwise.
+     * Returns false when the queue lacks the needed upload entry point so the
+     * cached binding keeps its last-good content instead of corrupting it.
+     */
+    uploadNativeSampledTextureRevision(texture, nativeTexture) {
+        texture.pendingUpdateRegion = null;
+        texture.needsUpdate = false;
+        if (texture.source) {
+            const copyExternalImageToTexture = this.device.queue.copyExternalImageToTexture;
+            if (typeof copyExternalImageToTexture === "function" && !texture.generateMipmaps) {
+                copyExternalImageToTexture.call(this.device.queue, { source: texture.source, flipY: texture.flipY }, { texture: nativeTexture }, { width: texture.width, height: texture.height, depthOrArrayLayers: 1 });
+                this.nativeTextureUploads += 1;
+                return true;
+            }
+            const sourceLevels = nativeTextureSourceLevels(texture);
+            if (sourceLevels.length === 0 || !this.device.queue.writeTexture)
+                return false;
+            sourceLevels.forEach((level, mipLevel) => {
+                this.device.queue.writeTexture({ texture: nativeTexture, mipLevel }, level.data, { bytesPerRow: level.bytesPerRow, rowsPerImage: level.height }, { width: level.width, height: level.height, depthOrArrayLayers: 1 });
+                this.nativeTextureUploads += 1;
+            });
+            return true;
+        }
+        if (texture.dimension === "cube") {
+            return this.writeNativeCubeFaceLevels(texture, nativeTexture);
+        }
+        const sampledTexture = nativeSampledTextureLevels(texture);
+        if (!sampledTexture)
+            return false;
+        return this.writeNativeTextureLevels(texture, nativeTexture, sampledTexture.levels, sampledTexture.format);
     }
     releaseDisposedNativeSampledTextures() {
         for (const [texture, resource] of this.nativeSampledTextures) {
             if (texture instanceof Texture && texture.disposed) {
                 resource.texture.destroy();
                 this.nativeSampledTextures.delete(texture);
+                this.nativeSampledTextureRevisions.delete(texture);
             }
         }
     }
@@ -2076,7 +2438,18 @@ function nativeTextureSourceLevels(texture) {
         if (!context)
             return levels;
         context.clearRect(0, 0, levelWidth, levelHeight);
-        context.drawImage(source, 0, 0, levelWidth, levelHeight);
+        if (texture.flipY) {
+            // threejs-parity ST-02 (L4): flip the source at draw time so the CPU
+            // readback matches UNPACK_FLIP_Y / copyExternalImageToTexture flipY.
+            context.save();
+            context.translate(0, levelHeight);
+            context.scale(1, -1);
+            context.drawImage(source, 0, 0, levelWidth, levelHeight);
+            context.restore();
+        }
+        else {
+            context.drawImage(source, 0, 0, levelWidth, levelHeight);
+        }
         const pixels = context.getImageData(0, 0, levelWidth, levelHeight).data;
         const sourceBytesPerRow = levelWidth * 4;
         const bytesPerRow = alignTo(sourceBytesPerRow, 256);