Copies texture's texels — or region's rectangle of them — into a
tightly packed RGBA8 ArrayBuffer, rows bottom-to-top (module header):
width * height * 4 bytes for the whole texture,
region.width * region.height * 4 with a region.
region is measured in texels from the texture's bottom-left corner
(§7a, the space the result's rows are defined in) and must already be
validated against width × height — validateReadbackRegion in
@fourjs/render is the shared §85 check, and WebgpuRenderer.readPixels
runs it before calling here. The conversion to WebGPU's top-first origin
happens in exactly one place, below.
Resolves null when the device surface does not carry the readback entry
points (copyTextureToBuffer, mapAsync — optional members whose presence
is the capability); the caller turns that into UNSUPPORTED_GPU_FEATURE.
The staging buffer is created per call and destroyed before resolving: a
readback is a diagnostic-tier operation (§92's visual tier, RFC 0005's
fallback path), and pooling a buffer that is mapped across an await would
trade a transient allocation for a reentrancy hazard.
Copies
texture's texels — orregion's rectangle of them — into a tightly packed RGBA8ArrayBuffer, rows bottom-to-top (module header):width * height * 4bytes for the whole texture,region.width * region.height * 4with a region.regionis measured in texels from the texture's bottom-left corner (§7a, the space the result's rows are defined in) and must already be validated againstwidth×height—validateReadbackRegionin@fourjs/renderis the shared §85 check, andWebgpuRenderer.readPixelsruns it before calling here. The conversion to WebGPU's top-firstoriginhappens in exactly one place, below.Resolves
nullwhen the device surface does not carry the readback entry points (copyTextureToBuffer,mapAsync— optional members whose presence is the capability); the caller turns that intoUNSUPPORTED_GPU_FEATURE. The staging buffer is created per call and destroyed before resolving: a readback is a diagnostic-tier operation (§92's visual tier, RFC 0005's fallback path), and pooling a buffer that is mapped across anawaitwould trade a transient allocation for a reentrancy hazard.