Repository navigation
Render to a layer of a 2D texture array - #9689
Conversation
Add the RenderTarget layer option to render to a single layer of a 2D array texture, on WebGL2 and WebGPU. The cubemap face and the array layer share a single internal value. On WebGPU, the mipmaps are regenerated only for the rendered face / layer. Texture#gpuSize now accounts for all layers of a texture array. Add the render-targets examples category with the texture-array-impostors example. Fixed #8327
Public API reportThis PR changes the public API surface (+8 / −7), per the docs' rules (@ignore / @Private / undocumented are excluded). Show API diff-Material.setParameter(name: string, data: number | number[] | Texture | ArrayBufferView<ArrayBufferLike> | StorageBuffer): void
+Material.setParameter(name: string, data: number | number[] | Texture | ArrayBufferView<ArrayBufferLike> | StorageBuffer | TextureView): void
-MeshInstance.setParameter(name: string, data: number | number[] | Float32Array<ArrayBufferLike> | Texture): void
+MeshInstance.setParameter(name: string, data: number | number[] | Float32Array<ArrayBufferLike> | Texture | TextureView): void
-RenderTarget.constructor(options?: { autoResolve: boolean; colorBuffer: Texture; colorBuffers: Texture[]; depth: boolean; depthBuffer: Texture; depthResolveBuffer: Texture; depthResolveMode: string; face: number; mipLevel: number; name: string; origin: string; resolveBuffer: Texture | null; resolveBuffers: Texture | null[]; samples: number; stencil: boolean; transientColor: boolean; transientDepth: boolean })
+RenderTarget.constructor(options?: { autoResolve: boolean; colorBuffer: Texture; colorBuffers: Texture[]; depth: boolean; depthBuffer: Texture; depthResolveBuffer: Texture; depthResolveMode: string; face: number; layer: number; mipLevel: number; name: string; origin: string; resolveBuffer: Texture | null; resolveBuffers: Texture | null[]; samples: number; stencil: boolean; transientColor: boolean; transientDepth: boolean })
+RenderTarget.get layer(): number
-ShaderMaterial.setParameter(name: string, data: number | number[] | Texture | ArrayBufferView<ArrayBufferLike> | StorageBuffer): void
+ShaderMaterial.setParameter(name: string, data: number | number[] | Texture | ArrayBufferView<ArrayBufferLike> | StorageBuffer | TextureView): void
-StandardMaterial.setParameter(name: string, data: number | number[] | Texture | ArrayBufferView<ArrayBufferLike> | StorageBuffer): void
+StandardMaterial.setParameter(name: string, data: number | number[] | Texture | ArrayBufferView<ArrayBufferLike> | StorageBuffer | TextureView): void
-Texture.copy(source: Texture, options?: { destMipLevel: number; destX: number; destY: number; face: number; height: number; sourceMipLevel: number; sourceRenderTarget: RenderTarget; sourceX: number; sourceY: number; width: number }): boolean
+Texture.copy(source: Texture, options?: { destMipLevel: number; destX: number; destY: number; face: number; height: number; layer: number; sourceMipLevel: number; sourceRenderTarget: RenderTarget; sourceX: number; sourceY: number; width: number }): boolean
-Texture.read(x: number, y: number, width: number, height: number, options?: { data: Uint8Array<ArrayBufferLike> | Float32Array<ArrayBufferLike> | Uint32Array<ArrayBufferLike> | Uint16Array<ArrayBufferLike>; face: number; frequent: boolean; immediate: boolean; mipLevel: number; renderTarget: RenderTarget }): Promise<Uint8Array<ArrayBufferLike> | Float32Array<ArrayBufferLike> | Uint32Array<ArrayBufferLike> | Uint16Array<ArrayBufferLike>>
+Texture.read(x: number, y: number, width: number, height: number, options?: { data: Uint8Array<ArrayBufferLike> | Float32Array<ArrayBufferLike> | Uint32Array<ArrayBufferLike> | Uint16Array<ArrayBufferLike>; face: number; frequent: boolean; immediate: boolean; layer: number; mipLevel: number; renderTarget: RenderTarget }): Promise<Uint8Array<ArrayBufferLike> | Float32Array<ArrayBufferLike> | Uint32Array<ArrayBufferLike> | Uint16Array<ArrayBufferLike>>Informational only — this never fails the build. |
Build size reportThis PR changes the size of the minified bundles.
|
mvaligursky
left a comment
There was a problem hiding this comment.
Automated PR review by Codex (OpenAI AI agent).
Reviewed the full diff and affected attachment, mipmap, copy/resolve, resource-accounting, and example paths at 2d360be634ec34aac17c05baf96c9d104e85b1bd.
Found three reproducible P2 issues:
- Different array layers share their implicit MSAA depth storage on both backends.
- WebGPU color copies ignore the source and destination render-target layers.
- WebGPU shader-based depth resolves write to layer 0 rather than the selected destination layer.
Validation:
- Local unit suite: 3,977 passing, 28 pending; declaration build/type tests and debug/release ESM builds passed.
- Changed source/test files pass ESLint. Full local lint only fails to resolve the uninstalled optional native
webgpupackage; current CI, including lint and native WebGPU tests, is green. - Deterministic raw-pixel checks: 126 existing 2D/cubemap captures per backend, across two poses, MSAA and mip configurations. Repeated baselines were byte-exact; head versus base differed in 0 of 79,800 pixels across WebGL2/WebGPU.
- New color-array checks passed for six layers, multiple mip levels, MRT, MSAA, and supplied depth arrays. Separate interleaved-depth and public copy/resolve probes reproduced the findings below.
- The new impostor example loads and renders on both backends at two camera angles without shader/asset errors; sampled baked layers contained the statue, and baking cameras were removed after baking.
The documented WebGL all-layer mipmap cost tracked in #9688 is not reported again. No tracked files were modified.
| gl.framebufferTexture2D(gl.FRAMEBUFFER, attachmentPoint, | ||
| depthBuffer._cubemap ? gl.TEXTURE_CUBE_MAP_POSITIVE_X + target._face : gl.TEXTURE_2D, | ||
| target._depthBuffer.impl._glTexture, target.mipLevel); | ||
| attachTexture(gl, attachmentPoint, depthBuffer, target.layer, target.mipLevel); |
There was a problem hiding this comment.
Automated PR review by Codex (OpenAI AI agent).
[P2] Key cached MSAA depth storage by array layer
The selected layer is attached here, but the implicit MSAA depth cache below still keys only by texture ID, size, sample count and format. WebgpuRenderTarget.initDepthStencil has the same omission. Consequently, two RenderTargets with the same depth-array texture, different layers and samples: 4 reuse the very same multisampled depth object. I reproduced this on both backends by clearing layer 0's depth to 1, clearing layer 1's depth to 0, then loading layer 0's depth while drawing an object: it renders with samples: 1, but is completely occluded with samples: 4, because layer 1 overwrote layer 0's cached depth. Include the selected layer in both cache keys, while retaining sharing for targets addressing the same texture and layer; otherwise interleaved/multipass rendering cannot preserve independent depth per array layer.
| * @type {number} | ||
| */ | ||
| get layer() { | ||
| return this._layer; |
There was a problem hiding this comment.
Automated PR review by Codex (OpenAI AI agent).
[P2] Honor array layers in WebGPU render-target color copies
The new layer selection also needs to reach WebgpuGraphicsDevice.copyRenderTarget: its copySrc and copyDst descriptors omit origin, so both always address layer 0. With source layer 0 red/layer 1 green and destination layer 0 blue/layer 1 yellow, calling destinationRt.copy(sourceRt, true, false) on the two layer-1 targets returns true, but overwrites destination layer 0 with red and leaves layer 1 yellow. The identical probe on WebGL2 correctly leaves layer 0 blue and copies green into layer 1. Set the copy descriptors' Z origins from the source/destination render-target layers so the existing public copy API operates on the surfaces these targets represent.
| * - {@link CUBEFACE_NEGZ} | ||
| * | ||
| * Defaults to {@link CUBEFACE_POSX}. | ||
| * @param {number} [options.layer] - If the colorBuffer or depthBuffer parameter is a 2D array |
There was a problem hiding this comment.
Automated PR review by Codex (OpenAI AI agent).
[P2] Resolve WebGPU MSAA depth into the selected destination layer
The shader depth-resolve paths still discard the target layer: WebgpuResolver.resolveDepth iterates the one-layer implicit MSAA source and uses that source index for the destination view. In a public-API probe, I cleared a 4x-MSAA source depth to 0.625 and copied it with destinationRt.copy(sourceRt, false, true) into layer 1 of an R32F array. The call returns true, but overwrites layer 0 with 0.625 and leaves layer 1 at 0; it also triggers the source/destination array-length assertion. Resolving into a provided R32F depth-array buffer via depthStencilOps.resolveDepth has the same result (0.75 appeared in layer 0 instead of the selected layer 1). Pass the selected destination layer through both resolve callers and use it when constructing the destination view; the implicit MSAA source itself remains layer 0.
…d and copy - Bind a TextureView in materials and mesh instances on WebGPU, which allows a texture array to be sampled in the same render pass that renders to a different layer. On WebGL, the whole texture of a view is bound, with a warning. - Add the layer option to Texture#read and Texture#copy for array textures. The face option selecting an array layer in Texture#copy is deprecated. - Fix Texture#copy into a layer of a texture array on WebGL2. - Document the face / layer options of Texture#read.
…solves - Key the cached multisampled depth buffer by the face / layer, so render targets rendering to different layers of a depth buffer do not share it (WebGL2 and WebGPU). - WebGPU: RenderTarget#copy copies the color and depth of the source and destination faces / layers, instead of layer 0. - WebGPU: shader based depth resolves write to the face / layer of the destination render target, instead of layer 0.
mvaligursky
left a comment
There was a problem hiding this comment.
Automated PR re-review by Codex (OpenAI AI agent).
Re-reviewed the updates through 3d9372db759fb36be932d84d6627d76b751e1b6c, including the new TextureView material bindings and Texture read/copy layer options.
All three previous P2 findings are fixed in the original GPU repros: MSAA depth is independent per array layer on both backends, WebGPU render-target color copies honor both selected layers, and both shader-based depth-resolve paths write to the selected destination layer. One new P2 regression remains in the single-sampled depth-copy path, detailed inline.
Validation:
- Unit suite: 3,981 passing, 28 pending. Declaration build/type tests and debug/release ESM builds passed. Changed source/test files pass ESLint;
git diff --checkpasses. Full local lint is limited by the absent optional nativewebgpupackage intest/webgpu-device.mjs; current CI, including native WebGPU tests and lint, is green. - Repeated deterministic baseline captures were byte-identical on both backends. Existing 2D/cubemap rendering, including MSAA and mip paths at two poses, differs in 0 of 79,800 pixels across WebGL2/WebGPU (126 captures per backend).
- Six-layer array color checks passed for mip levels, MRT, MSAA, and supplied depth arrays. Region copies through
Texture#copypassed for all six array layers and cubemap faces at two mip levels, leaving pixels outside the copied region unchanged. - TextureView selection works through material and mesh-instance overrides, including sampling a different layer while rendering into the same texture on WebGPU. WebGL binds the whole texture and emits the documented warning.
- The new implicit-depth copy failure reproduces for both a nonzero array layer and a nonzero cubemap face. The previous PR revision copies correctly in both cases; the latest revision emits out-of-range depth-layer validation errors and discards the command buffer.
No tracked files were modified.
| texture: sourceTexture, | ||
| mipLevel: sourceMipLevel | ||
| mipLevel: sourceMipLevel, | ||
| origin: [0, 0, sourceRT.layer] |
There was a problem hiding this comment.
Automated PR re-review by Codex (OpenAI AI agent).
[P2] Keep implicit depth copies at source layer zero
sourceRT.layer selects the color attachment, but an internally allocated depth texture (depth: true, no depthBuffer) always has exactly one layer. For a single-sampled array target at layer: 1, copying its depth into a normal 2D depth-stencil target with destination.copy(source, false, true) now returns true while encoding source Z=1 against that one-layer texture. WebGPU reports an out-of-range copy and discards the command buffer; the destination depth remains unchanged. I reproduced the same regression with an existing cubemap target at face 1, and both probes work on the previous PR revision. Use the selected layer only when the actual supplied source depth buffer is an array/cubemap; implicit depth must use Z=0. The render-target's color layer must not be applied unconditionally to its depth attachment.
The internally allocated depth buffer and 2D color / depth buffers have a single layer. Copies, depth resolves, mipmap generation and the cached multisampled depth buffer now use the face / layer only for cubemap and array attachments, matching how the attachments are created. A 2D depth buffer can be shared by render targets rendering to different layers.
mvaligursky
left a comment
There was a problem hiding this comment.
Automated PR re-review by Codex (OpenAI AI agent).
Reviewed the follow-up at 25ce166615d04c99e38dded1c8da9ffd1787c31d. The remaining P2 is fixed, and I found no new actionable issues. The attachment-specific getLayer helper correctly distinguishes array/cubemap attachments from supplied or implicit 2D attachments, and its use in copies, mipmap generation, depth resolves, and MSAA depth-cache keys is consistent.
Verified on real browser GPUs:
- The exact implicit-depth copy repro now succeeds for both array layer 1 and cubemap face 1, with no validation errors. The previous PR commit still fails those same probes, confirming the fix.
- A supplied 2D depth buffer is correctly shared across different color-array layers/cubemap faces, with both single-sampled and 4x-MSAA rendering; the MSAA cache reuses the same depth storage for that shared 2D attachment.
- 2D color targets with layered depth generate mipmaps and copy color at layer 0, while copying depth between the selected array layers. These checks pass on WebGL2 and WebGPU.
- WebGPU resolves MSAA depth into a 2D R32F buffer at layer 0 even when the color target selects a nonzero array layer. The original per-layer MSAA depth, color-copy, and array depth-resolve repros remain fixed.
- Repeated deterministic base captures were byte-exact. Existing 2D/cubemap rendering at two poses, including mip and MSAA configurations, remains unchanged: 0 of 79,800 pixels differ across WebGL2/WebGPU. TextureView material/mesh-instance bindings and six-layer array/mip/region-copy checks still pass; WebGL emits only the documented TextureView fallback warning.
Local checks: 3,982 tests passing, 28 pending; declaration build/type tests, debug/release ESM builds, changed-file lint, and git diff --check pass. Full local lint still only fails to resolve the absent optional native webgpu package. Current PR CI, including native WebGPU tests and lint, is green. No tracked files modified.
…9777) The frame graph skipped the mipmap generation of all but the last of consecutive passes rendering to the faces of a cubemap. #7051 renamed ColorAttachmentOps.mipmaps to genMipmaps and missed this code, so it has set an unused property since. It cannot be fixed instead: since #9689 WebGPU generates the mipmaps of only the rendered face, and skipping the earlier faces would leave them without mipmaps. Remove it, together with the requiresCubemaps property only it read. No change in behavior. The WebGL2 cost of regenerating all faces after each face pass is tracked by #9688. The layered texture test example also verifies the mipmaps generated after rendering to cubemap faces and array layers, and their sRGB filtering. Co-authored-by: Martin Valigursky <mvaligursky@snapchat.com>
Adds support for rendering to a single layer of a 2D texture array, on both WebGL2 and WebGPU. Fixes #8327.
Related: #9442 - rendering each shadow cascade to a layer of a depth texture array would build on this.
Changes:
layeroption onRenderTarget, used to render to one layer of a texture array. To render to several layers, create a render target for each layer, all sharing the same texture.generateMipmapstill regenerates the mipmaps of all layers. This is tracked in WebGL2: generate mipmaps only for the rendered cubemap face / array layer of a render target #9688, and theRenderTargetdocs describe a workaround.TextureViewcan now be bound to materials and mesh instances, not only to compute shaders. On WebGPU, this allows a texture array to be sampled in the same render pass that renders to a different layer of it, which is not possible with the whole texture bound. On WebGL, the whole texture of a view is bound (previously nothing was bound), with a warning.Texture#readandTexture#copytake alayeroption for texture arrays, matchingRenderTarget.faceis for cubemaps only.Texture#copyinto a layer of a texture array on WebGL2.RenderTarget#copyand shader-based depth resolves now use the face / layer of the render targets on WebGPU, instead of always layer 0. This also fixes copies and depth resolves of cubemap faces.Texture#gpuSize(and the VRAM tracking based on it) now counts all layers of a texture array. Previously it reported the size of a single layer.API Changes:
RenderTargetconstructor: newoptions.layer, the layer of a 2D array texture to render to. Defaults to 0.RenderTarget#layergetter.Texture#read: newoptions.layer, the array layer to download.Texture#copy: newoptions.layer, the array layer to copy.Material#setParameterandMeshInstance#setParameteraccept aTextureView(WebGPU only).mipLevel(even to 0) turns off automatic mipmap generation for that render target. This behavior is not new.Deprecations:
Texture#copy: using thefaceoption to select a layer of a texture array is deprecated, uselayerinstead.Examples:
render-targetsexamples category. The existing render-to-texture examples will move into it in a follow-up PR.render-targets/texture-array-impostorsexample: a statue is rendered from 64 directions into the layers of a texture array, and thousands of instanced impostors each show the view closest to the camera direction.