copy(from:sourceSlice:sourceLevel:sourceOrigin:sourceSize:to:destinationOffset:destinationBytesPerRow:destinationBytesPerImage:options:)

Declaration

func copy(from sourceTexture: any MTLTexture, sourceSlice: Int, sourceLevel: Int, sourceOrigin: MTLOrigin, sourceSize: MTLSize, to destinationBuffer: any MTLBuffer, destinationOffset: Int, destinationBytesPerRow: Int, destinationBytesPerImage: Int, options: MTLBlitOption)

Parameters

• sourceTexture:

  A texture with an Isframebufferonly property value of False that the command copies data from.

• sourceSlice:

  A slice within sourceTexture.

  For textures that use a combined depth/stencil pixel format, configure the options parameter appropriately.

• sourceLevel:

  A mipmap level within sourceTexture.

• sourceOrigin:

  A location within sourceTexture that the command begins copying data from.

  Assign 0 to each dimension that’s not relevant to sourceTexture. For example:

  • If the source texture is a 2D texture, set the origin’s Z property to 0.

  • If the source texture is a 1D texture, set the origin’s Y and Z properties to 0.

• sourceSize:

  An Mtlsize instance, which can represent a 3D region, that instructs the command how many pixels to copy from sourceTexture, starting at sourceOrigin.

  Assign 1 to each dimension that’s not relevant to sourceTexture. For example:

  • If the source texture is a 2D texture, set the size’s Depth property to 1.

  • If the source texture is a 1D texture, set the size’s Height and Depth properties to 1.

  If sourceTexture uses a compressed pixel format, set sourceSize to a multiple of the pixel format’s block size. If the block extends outside the bounds of the texture, clamp sourceSize to the edge of the texture.

• destinationBuffer:

  A buffer the command copies data to.

• destinationOffset:

  A byte offset within destinationBuffer the command copies to, which needs to be a multiple of the source texture’s pixel size, in bytes.

• destinationBytesPerRow:

  The number of bytes between adjacent rows of pixels in the destination buffer’s memory, which needs to be:

  • A multiple of the source texture’s pixel size, in bytes

  • Less than or equal to the product of the source texture’s pixel size, in bytes, and the largest pixel width the source texture’s type allows

  If sourceTexture uses a compressed pixel format, set destinationBytesPerRow to the number of bytes between the starts of two row blocks.

• destinationBytesPerImage:

  The number of bytes between each 2D image of a 3D texture. This value needs to be a multiple of the source texture’s pixel size, in bytes.

  Set this value to 0 for 2D textures, which means sourceSize.Depth is equal to 1.

• options:

  An option set that applies to textures with applicable pixel formats, such as combined depth/stencil or PVRTC formats.

  If the texture’s pixel format is a combined depth/stencil format, set options to either Depthfromdepthstencil or Stencilfromdepthstencil, but not both.

  If the texture’s pixel format is a PVRTC format, set options to Rowlinearpvrtc.

Discussion

Passing an empty OptionSet to the options parameter is the equivalent of calling copy(from:sourceSlice:sourceLevel:sourceOrigin:sourceSize:to:destinationOffset:destinationBytesPerRow:destinationBytesPerImage:). In Swift, pass [] to represent an empty option set, and in Objective-C, pass MTLBlitOptionNone.

See Also

Copying texture data to a buffer

• copy(from:sourceSlice:sourceLevel:sourceOrigin:sourceSize:to:destinationOffset:destinationBytesPerRow:destinationBytesPerImage:)