GPUCommandEncoder: copyTextureToTexture() method
Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.
The copyTextureToTexture()
method of the
GPUCommandEncoder
interface encodes a command that copies data from one GPUTexture
to another.
Syntax
js
copyTextureToTexture(source, destination, copySize)
Parameters
source
-
An object (see Copy texture object structure) defining the texture to copy the data from. Combined with
copySize
, this defines the region of the source texture subresource. destination
-
An object (see Copy texture object structure) defining the texture to write the data to. Combined with
copySize
, this defines the region of the destination texture subresource. 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 }
Copy texture object structure
A copy texture object has the following structure:
aspect
Optional-
An enumerated value defining which aspects of the texture to copy the data from/to. Possible values are:
"all"
-
All available aspects of the texture format will be copied from/to, 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/to.
"stencil-only"
-
Only the stencil aspect of a depth-or-stencil format will be copied from/to.
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/to. If omitted,
mipLevel
defaults to 0. origin
Optional-
An object or array specifying the origin of the copy/destination — the minimum corner of the texture region to copy the data from/to. Together with
size
, this defines the full extent of the region to copy from/to. 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/to.
Return value
None (Undefined
).
Validation
The following criteria must be met when calling copyTextureToTexture()
, otherwise a GPUValidationError
is generated and the GPUCommandEncoder
becomes invalid.
For the source
:
- The
source
'sGPUTexture.usage
includes theGPUTextureUsage.COPY_SRC
flag.
For the destination
:
- The
source
'sGPUTexture.usage
includes theGPUTextureUsage.COPY_DST
flag.
For source
and destination
:
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
.- The source and destination
texture
GPUTexture.format
s are copy-compatible. - The source and destination
texture
GPUTexture.sampleCount
s are equal. - If the
GPUTexture.format
is a depth-or-stencil format orGPUTexture.sampleCount
is more than 1, the subresource size is equal tosize
. - The
texture
'sGPUTexture.sampleCount
is 1. aspect
refers to a single aspect of theGPUTexture.format
.- That aspect is a valid image copy source/destination according to depth-or-stencil formats.
- The
texture
is compatible with thecopySize
.
Examples
js
commandEncoder.copyTextureToTexture(
{
texture: sourceTexture,
},
{
texture: destinationTexture,
},
{
width: 16,
height: 16,
depthOrArrayLayers: 2,
}
);
Specifications
Specification |
---|
WebGPU # dom-gpucommandencoder-copytexturetotexture |
Browser compatibility
BCD tables only load in the browser
See also
- The WebGPU API