GPUCommandEncoder: copyTextureToTexture() method
MDN Web Docs · نسخهٔ df622a2a1c1e · CC BY-SA 2.5 و مجوز جداگانهٔ ناشر برای نمونهکد
{{APIRef("WebGPU API")}}{{SecureContext_Header}}
The **copyTextureToTexture()** method of the {{domxref("GPUCommandEncoder")}} interface encodes a command that copies data from one {{domxref("GPUTexture")}} to another.
Syntax
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.
For example, you can pass an array [16, 16, 2], or its equivalent object { width: 16, height: 16, depthOrArrayLayers: 2 }.
Copy texture object structure
A copy texture object has the following structure:
aspect{{optional_inline}}- : 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_inline}}- : A number representing the mip-map level of the texture to copy the data from/to. If omitted,
mipLeveldefaults to 0. origin{{optional_inline}}- : 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, andzvalues default to 0 if any of all oforiginis omitted.
For example, you can pass an array like [0, 0, 0], or its equivalent object { x: 0, y: 0, z: 0 }.
texture- : A {{domxref("GPUTexture")}} object representing the texture to copy the data from/to.
Return value
None ({{jsxref("undefined")}}).
Validation
The following criteria must be met when calling **copyTextureToTexture()**, otherwise a {{domxref("GPUValidationError")}} is generated and the {{domxref("GPUCommandEncoder")}} becomes invalid.
For the source:
- The
source's {{domxref("GPUTexture.usage")}} includes theGPUTextureUsage.COPY_SRCflag.
For the destination:
- The
destination's {{domxref("GPUTexture.usage")}} includes theGPUTextureUsage.COPY_DSTflag.
For source and destination:
mipLevelis less than the {{domxref("GPUTexture.mipLevelCount")}}.origin.xis a multiple of the texel block width of the {{domxref("GPUTexture.format")}}.origin.yis a multiple of the texel block height of the {{domxref("GPUTexture.format")}}.- The source and destination
texture{{domxref("GPUTexture.format")}}s are copy-compatible. - The source and destination
texture{{domxref("GPUTexture.sampleCount")}}s are equal. - If the {{domxref("GPUTexture.format")}} is a depth-or-stencil format or {{domxref("GPUTexture.sampleCount")}} is more than 1, the subresource size is equal to
size. - If the {{domxref("GPUTexture.format")}} is a depth-or-stencil format, the
sourceanddestinationaspects both refer to all aspects of their respective textures' {{domxref("GPUTexture.format")}}s. - The
textureis compatible with thecopySize. - The sets of subresources defined by
sourcecombined withcopySize, anddestinationcombined withcopySize, are disjoint.
Examples
commandEncoder.copyTextureToTexture(
{
texture: sourceTexture,
},
{
texture: destinationTexture,
},
{
width: 16,
height: 16,
depthOrArrayLayers: 2,
},
);Specifications
{{Specifications}}
Browser compatibility
{{Compat}}
See also
- The WebGPU API