Protocol

MTLCommandBuffer

A container that stores encoded commands for the GPU to execute.

Declaration

protocol MTLCommandBuffer

Overview

Don't implement this protocol yourself; instead, create command buffer objects by calling a MTLCommandQueue object’s makeCommandBuffer() method. The command buffer can only be committed for execution on the command queue that created it. All command buffers sent to a single command queue are guaranteed to execute in the order in which the command buffers were enqueued.

After creating a command buffer, you create encoder objects to fill the buffer with commands. The MTLCommandBuffer protocol has methods to create specific types of command encoders: MTLRenderCommandEncoder, MTLComputeCommandEncoder, MTLBlitCommandEncoder, and MTLParallelRenderCommandEncoder. At any given time, only a single encoder may be active for a particular command buffer. You create an encoder, use it to add commands to the buffer, and then end the encoding process. After you finish with an encoder, you can create another encoder and continue to add commands to the same buffer. When you are ready to execute the set of encoded commands, call the command buffer’s commit() method to schedule the buffer for execution.

After a command buffer has been committed for execution, the only valid operations on the command buffer are to wait for it to be scheduled or completed (using synchronous calls or handler blocks) and to check the status of the command buffer execution. When used, scheduled and completed handlers are blocks that are invoked in execution order. These handlers should perform quickly; if expensive or blocking work needs to be scheduled, defer that work to another thread.

In a multithreaded app, it’s advisable to break your overall task into subtasks that can be encoded separately. Create a command buffer for each chunk of work, then call the enqueue() method on these command buffer objects to establish the order of execution. Fill each buffer object (using multiple threads) and commit them. The command queue automatically schedules and executes these command buffers as they become available.

Topics

Creating Command Encoders

func makeRenderCommandEncoder(descriptor: MTLRenderPassDescriptor) -> MTLRenderCommandEncoder?

Creates an object to encode a rendering pass into the command buffer.

Required.

func makeParallelRenderCommandEncoder(descriptor: MTLRenderPassDescriptor) -> MTLParallelRenderCommandEncoder?

Creates an object that can split the work of encoding commands for a single render pass.

Required.

func makeComputeCommandEncoder(dispatchType: MTLDispatchType) -> MTLComputeCommandEncoder?

Creates an object to encode a compute pass into the command buffer.

Required.

func makeComputeCommandEncoder() -> MTLComputeCommandEncoder?

Creates an object to encode a sequential compute pass into the command buffer.

Required.

func makeBlitCommandEncoder() -> MTLBlitCommandEncoder?

Creates an object to encode a block information transfer (blit) pass into the command buffer.

Required.

func makeResourceStateCommandEncoder() -> MTLResourceStateCommandEncoder?

Required.

enum MTLDispatchType

Constants indicating how the compute command encoder's commands are dispatched.

Scheduling and Executing Commands

func enqueue()

Reserves a place for the command buffer on the associated command queue.

Required.

func commit()

Commits the command buffer for execution.

Required.

func addScheduledHandler(MTLCommandBufferHandler)

Registers a block of code that Metal calls immediately after it schedules the command buffer for execution on the GPU.

Required.

func addCompletedHandler(MTLCommandBufferHandler)

Registers a block of code that Metal calls immediately after the GPU finishes executing the commands in the command buffer.

Required.

func waitUntilScheduled()

Blocks execution of the current thread until the command buffer is scheduled.

Required.

func waitUntilCompleted()

Blocks execution of the current thread until execution of the command buffer is completed.

Required.

typealias MTLCommandBufferHandler

A block of code invoked when a command buffer is scheduled for execution or has completed execution.

Presenting a Drawable

func present(MTLDrawable)

Registers a drawable presentation to occur as soon as possible.

Required.

func present(MTLDrawable, afterMinimumDuration: CFTimeInterval)

Registers a drawable presentation to occur after waiting for the previous drawable to meet the minimum display time.

Required.

func present(MTLDrawable, atTime: CFTimeInterval)

Registers a drawable presentation to occur at a specific host time.

Required.

Obtaining Status and Timestamps

var status: MTLCommandBufferStatus

The current stage in the lifetime of the command buffer.

Required.

enum MTLCommandBufferStatus

The stages in the lifetime of the command buffer.

var error: Error?

The error that occurred when the command buffer was executed.

Required.

struct MTLCommandBufferError

Error codes that indicate why the execution of the command buffer has failed.

let MTLCommandBufferErrorDomain: String

The error domain used by MTLCommandBuffer when returning command buffer execution errors.

enum MTLCommandBufferError.Code

Error codes that indicate why the execution of the command buffer has failed. The error property contains the error code.

var kernelStartTime: CFTimeInterval

The host time, in seconds, when the CPU began scheduling this command buffer for execution.

Required.

var kernelEndTime: CFTimeInterval

The host time, in seconds, when the CPU finished scheduling this command buffer for execution.

Required.

var gpuStartTime: CFTimeInterval

The host time, in seconds, when the GPU began executing this command buffer.

Required.

var gpuEndTime: CFTimeInterval

The host time, in seconds, when the GPU finished executing this command buffer.

Required.

Synchronizing Events

func encodeSignalEvent(MTLEvent, value: UInt64)

Encodes a command that signals the given event, updating it to a new value.

Required.

func encodeWaitForEvent(MTLEvent, value: UInt64)

Encodes a command that blocks the execution of the command buffer until the given event reaches the given value.

Required.

Determining Whether to Keep Strong References

var retainedReferences: Bool

A Boolean value that indicates whether the command buffer maintains strong references to associated resource objects (textures, buffers) necessary to complete execution of any encoded commands.

Required.