MTLBlitCommandEncoder

Declaration

protocol MTLBlitCommandEncoder : MTLCommandEncoder

Mentioned in

• Copying data into or out of mipmaps
• Understanding the Metal 4 core API
• Converting a GPU’s counter data into a readable format
• Sampling GPU data into counter sample buffers
• Transferring data between connected GPUs

Overview

Create a blit encoder by calling one of the factory methods on an MTLCommandBuffer instance, such as makeBlitCommandEncoder().

A blit command encoder adds commands to a command buffer that modify resources in various ways, including:

• Filling buffers with repeating bytes

• Generating mipmaps for textures

• Copying data between buffers

• Copying data between textures

• Copying data between a texture and a buffer

• Managing the contents of indirect command buffers

• Synchronizing buffers, textures, and other resources between the CPU and GPU

• Improving runtime performance for resources by optimizing their memory layout for the GPU or CPU

You typically use these commands to move data between a resource that uses private storage and another resource that uses CPU-accessible storage. Some apps also use them to apply image-processing and texture effects, such as blurring or reflections, or to render and work with offscreen image data.

When you finish encoding blit commands, finalize the blit pass into the command buffer by calling the encoder’s endEncoding() method.

Command stages

Most blit commands apply to one stage within a pass. The following table shows which stages apply to each command:

For more information about stages and synchronization, see MTLStages and Resource synchronization.

Topics

Filling buffers

• fill(buffer:range:value:)

Generating texture mipmaps

• generateMipmaps(for:)

Copying buffer data to another buffer

• copy(from:sourceOffset:to:destinationOffset:size:)

Copying texture data to another texture

• copy(from:to:)
• copy(from:sourceSlice:sourceLevel:to:destinationSlice:destinationLevel:sliceCount:levelCount:)
• copy(from:sourceSlice:sourceLevel:sourceOrigin:sourceSize:to:destinationSlice:destinationLevel:destinationOrigin:)
• copy(from:sourceOrigin:sourceDimensions:to:destinationOrigin:destinationDimensions:)

Copying buffer data to a texture

• copy(from:sourceOffset:sourceBytesPerRow:sourceBytesPerImage:sourceSize:to:destinationSlice:destinationLevel:destinationOrigin:)
• copy(from:sourceOffset:sourceBytesPerRow:sourceBytesPerImage:sourceSize:to:destinationSlice:destinationLevel:destinationOrigin:options:)

Copying texture data to a buffer

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

Optimizing textures for GPU access

• optimizeContentsForGPUAccess(texture:)
• optimizeContentsForGPUAccess(texture:slice:level:)

Optimizing textures for CPU access

• optimizeContentsForCPUAccess(texture:)
• optimizeContentsForCPUAccess(texture:slice:level:)

Synchronizing managed resources

• synchronize(resource:)
• synchronize(texture:slice:level:)

Preventing resource access conflicts

• waitForFence(_:)
• updateFence(_:)

Managing indirect command buffers

• copyIndirectCommandBuffer(_:sourceRange:destination:destinationIndex:)
• resetCommandsInBuffer(_:range:)
• optimizeIndirectCommandBuffer(_:range:)

Sampling counters

• sampleCounters(sampleBuffer:sampleIndex:barrier:)
• resolveCounters(_:range:destinationBuffer:destinationOffset:)

Managing sparse texture access counters

• getTextureAccessCounters(_:region:mipLevel:slice:resetCounters:countersBuffer:countersBufferOffset:)
• resetTextureAccessCounters(_:region:mipLevel:slice:)

Relationships

Inherits From

• MTLCommandEncoder
• NSObjectProtocol

See Also

Encoding a blit pass

• MTLBlitOption