Buffer and Texture Operations: Blit Command Encoder

MTLBlitCommandEncoder provides methods for copying data between resources (buffers and textures). Data copying operations may be necessary for image processing and texture effects, such as blurring or reflections. They may be used to access image data that is rendered off-screen.

To perform data copying operations, first create a MTLBlitCommandEncoder object by calling the blitCommandEncoder method of MTLCommandBuffer. Then call the MTLBlitCommandEncoder methods described below to encode commands onto the command buffer.

Copying Data in GPU Memory Between Resource Objects

The following MTLBlitCommandEncoder methods copy image data between resource objects: between two buffer objects, between two texture objects, and between a buffer and a texture.

Copying Data Between Two Buffers

The method copyFromBuffer:sourceOffset:toBuffer:destinationOffset:size: copies data between two buffers: from the source buffer into the destination buffer toBuffer. If the source and destination are the same buffer, and the range being copied overlaps, the results are undefined.

Copying Data from a Buffer to a Texture

The method copyFromBuffer:sourceOffset:sourceBytesPerRow:sourceBytesPerImage:sourceSize:toTexture:destinationSlice:destinationLevel:destinationOrigin: copies image data from a source buffer into the destination texture toTexture.

Copying Data Between Two Textures

The method copyFromTexture:sourceSlice:sourceLevel:sourceOrigin:sourceSize:toTexture:destinationSlice:destinationLevel:destinationOrigin: copies a region of image data between two textures: from a single cube slice and mipmap level of the source texture to the destination texture toTexture.

Copying Data from a Texture to a Buffer

The method copyFromTexture:sourceSlice:sourceLevel:sourceOrigin:sourceSize:toBuffer:destinationOffset:destinationBytesPerRow:destinationBytesPerImage: copies a region of image data from a single cube slice and mipmap level of a source texture into the destination buffer toBuffer.

Generating Mipmaps

The generateMipmapsForTexture: method of MTLBlitCommandEncoder automatically generate mipmaps for the given texture, starting from the base level texture image. generateMipmapsForTexture: creates scaled images for all mipmap levels up to the maximum level.

For details on how the number of mipmaps and the size of each mipmap are determined, see Slices.

Filling the Contents of a Buffer

The fillBuffer:range:value: method of MTLBlitCommandEncoder stores the 8-bit constant value in every byte over the specified range of the given buffer.

Ending Encoding for the Blit Command Encoder

To end encoding commands for a blit command encoder, call endEncoding. After ending the previous command encoder, you can create a new command encoder of any type to encode additional commands into the command buffer.