Instance Method


Copies pixel data from a texture to memory.



func getBytes(_ pixelBytes: UnsafeMutableRawPointer, bytesPerRow: Int, bytesPerImage: Int, from region: MTLRegion, mipmapLevel level: Int, slice: Int)



A pointer to the memory where you want the texture to write its data.


For an ordinary or packed pixel format, the stride, in bytes, between rows of destination data. For a compressed pixel format, the stride is the number of bytes from the beginning of one row of blocks to the beginning of the next.

Specify a nonzero value when you copy pixels from texture types other than MTLTextureType.type1D or MTLTextureType.type1DArray. Specify a value greater than or equal to the width of one row (the size of one pixel, in bytes, multiplied by the pixel width of one row) and less than or equal to 32767 multiplied by the size of one pixel. For an ordinary or packed pixel format, use a multiple of the size of one pixel. For a compressed pixel format, use a multiple of the compressed block size. If you specify a nonzero value that is smaller than the width of the texture or is not a multiple of the size of the pixel format or compressed block size, an error occurs.

When you copy pixels from a MTLTextureType.type1D or MTLTextureType.type1DArray texture, use 0.


bytesPerImage is the stride, in bytes, between images in the destination texture data.


The location of a block of pixels in the texture slice. The region must be within the dimensions of the slice.


A zero-based value that specifies which mipmap level is the source. If the texture doesn't have mipmaps, use 0.


A zero-based value that specofies 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 destination.

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.


If the texture is a multisample texture, each sample within a pixel is located consecutively in memory and are all treated as part of one row.

If you are a copying a texture in the PowerVR Texture Compression (PVRTC) pixel format, you must copy the entire texture.

Don't use this method for textures with a private storage mode. To copy data from a private texture, use a MTLBlitCommandEncoder to copy the data from the private texture to another texture that has a non-private storage mode and then copy the data from that texture.

See Also

Copying Data from a Texture Image

func getBytes(UnsafeMutableRawPointer, bytesPerRow: Int, from: MTLRegion, mipmapLevel: Int)

Copies pixel data from slice 0 of a texture to memory.