GPUCommandEncoder: copyTextureToBuffer() method
Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.
The copyTextureToBuffer()
method of the
GPUCommandEncoder
interface encodes a command that copies data from a GPUTexture
to a GPUBuffer
.
Syntax
js
copyTextureToBuffer(source, destination, copySize)
Parameters
source
-
An object defining the texture to copy the data from. Combined with
copySize
, defines the region of the source texture subresource.source
can take the following properties:aspect
Optional-
An enumerated value defining which aspects of the texture to copy the data from. Possible values are:
"all"
-
All available aspects of the texture format will be copied from, which can mean all or any of color, depth, and stencil, depending on what kind of format you are dealing with.
"depth-only"
-
Only the depth aspect of a depth-or-stencil format will be copied from.
"stencil-only"
-
Only the stencil aspect of a depth-or-stencil format will be copied from.
If omitted,
aspect
takes a value of"all"
. mipLevel
Optional-
A number representing the mip-map level of the texture to copy the data from. If omitted,
mipLevel
defaults to 0. origin
Optional-
An object or array specifying the origin of the copy — the minimum corner of the texture region to copy the data from. Together with
size
, this defines the full extent of the region to copy from. Thex
,y
, andz
values default to 0 if any of all oforigin
is omitted.What follows is a sample array:
js
[0, 0, 0];
The object equivalent would look like this:
js
{ x: 0, y: 0, z: 0 }
texture
-
A
GPUTexture
object representing the texture to copy the data from.
destination
-
An object that defines the buffer to write to, plus the layout of the data to write to the buffer. Combined with
copySize
, it defines the region of the destination buffer.source
can take the following properties:buffer
-
The
GPUBuffer
to write to. offset
Optional-
The offset, in bytes, from the beginning of
data
to the start position to write the copied data to. If omitted,offset
defaults to 0. bytesPerRow
Optional-
A number representing the stride, in bytes, between the start of each block row (i.e. a row of complete texel blocks) and the subsequent block row. This is required if there are multiple block rows (i.e. the copy height or depth is more than one block).
rowsPerImage
Optional-
The number of block rows per single image inside the data.
bytesPerRow
×rowsPerImage
will give you the stride, in bytes, between the start of each complete image. This is required if there are multiple images to copy.
copySize
-
An object or array specifying the width, height, and depth/array layer count of the copied data. The width value must always be specified, while the height and depth/array layer count values are optional and will default to 1 if omitted.
What follows is a sample
copySize
array:js
[16, 16, 2];
The object equivalent would look like this:
js
{ width: 16, height: 16, depthOrArrayLayers: 2 }
Return value
None (Undefined
).
Validation
The following criteria must be met when calling copyTextureToBuffer()
, otherwise a GPUValidationError
is generated and the GPUCommandEncoder
becomes invalid.
For the source
:
mipLevel
is less than theGPUTexture.mipLevelCount
.origin.x
is a multiple of the texel block width of theGPUTexture.format
.origin.y
is a multiple of the texel block height of theGPUTexture.format
.- If the
GPUTexture.format
is a depth-or-stencil format orGPUTexture.sampleCount
is more than 1, the subresource size is equal tosize
. - The
source
'sGPUTexture.usage
includes theGPUTextureUsage.COPY_SRC
flag. - The
source
'sGPUTexture.sampleCount
is 1. source.aspect
refers to a single aspect of theGPUTexture.format
.- That aspect is a valid image copy source according to depth-or-stencil formats.
- The
source
is compatible with thecopySize
.
For the destination
:
destination.bytesPerRow
is a multiple of 256.- The
destination.buffer
'sGPUBuffer.usage
includes theGPUBufferUsage.COPY_DST
flag.
Examples
js
commandEncoder.copyTextureToBuffer(
{
texture: sourceTexture,
},
{
buffer: destinationBuffer,
},
{
width: 16,
height: 16,
depthOrArrayLayers: 2,
}
);
Specifications
Specification |
---|
WebGPU # dom-gpucommandencoder-copytexturetobuffer |
Browser compatibility
BCD tables only load in the browser
See also
- The WebGPU API