Instance Method


Encodes a command to copy image data from a slice of a source texture into a destination buffer.



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



The source texture for the copy operation. The value must not be a isFramebufferOnly texture and must not have a PVRTC pixel format.


A zero-based value that specifies which texture slice is the source.

For a cube texture, slice is a value between 0 and 5, inclusive, that defines which cube face is the source.

For a texture array, slice is the index for the array element.

For a cube texture array, slice is a value that defines both a cube face and an array index. The general equation for determining the correct value of slice is:


For example, the third face of a fifth cube is equal to (3-1) + (5-1)*6 = 26.

If the texture type is neither an array nor a cube, use 0.


The mipmap level of the source texture.


The origin of the portion of the source texture where the copying starts.


The number of source pixels, in width, height, and depth, to copy to the destination buffer. When you copy from a 1D texture, height and depth must be 1. When you copy from a 2D texture, depth must be 1.


The destination buffer for the copy operation.


The byte offset within the destination buffer to copy the first row into. The value must be a multiple of the source texture's pixel size, in bytes.


The stride in bytes between rows of the source texture memory. The value must be a multiple of the source texture's pixel size, in bytes. The value must be less than or equal to 32,767 multiplied by the source texture’s pixel size.


For 3D textures and 2D array textures, the stride in bytes between 2D images of the source buffer memory. The value must be a multiple of the source texture's pixel size, in bytes.


Use sourceSlice and sourceLevel to select a single image of the source texture.

If the texture’s pixel format is a compressed format, then sourceSize must be a multiple of the pixel format’s block size or be clamped to the edge of the texture if the block extends outside the bounds of a texture. For a compressed format, destinationBytesPerRow is the number of bytes from the start of one row of blocks to the start of the next row of blocks.

This method cannot be used if the source texture has a PVRTC pixel format.

This method is equivalent to copy(from:sourceSlice:sourceLevel:sourceOrigin:sourceSize:to:destinationOffset:destinationBytesPerRow:destinationBytesPerImage:options:) with options set to none.