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 commandBuffer 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

- renderCommandEncoderWithDescriptor:

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

Required.

- parallelRenderCommandEncoderWithDescriptor:

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

Required.

- computeCommandEncoderWithDispatchType:

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

Required.

- computeCommandEncoder

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

Required.

- blitCommandEncoder

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

Required.

MTLDispatchType

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

Scheduling and Executing Commands

- enqueue

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

Required.

- commit

Commits the command buffer for execution.

Required.

- addScheduledHandler:

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

Required.

- addCompletedHandler:

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

Required.

- waitUntilScheduled

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

Required.

- waitUntilCompleted

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

Required.

MTLCommandBufferHandler

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

Presenting a Drawable

- presentDrawable:

Registers a drawable presentation to occur as soon as possible.

Required.

- presentDrawable:afterMinimumDuration:

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

Required.

- presentDrawable:atTime:

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

Required.

Obtaining Status and Timestamps

status

The current stage in the lifetime of the command buffer.

Required.

MTLCommandBufferStatus

The stages in the lifetime of the command buffer.

error

The error that occurred when the command buffer was executed.

Required.

MTLCommandBufferErrorDomain

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

MTLCommandBufferError

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

kernelStartTime

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

Required.

kernelEndTime

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

Required.

GPUStartTime

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

Required.

GPUEndTime

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

Required.

Synchronizing Events

- encodeSignalEvent:value:

Encodes a command that signals the given event with the given value.

Required.

- encodeWaitForEvent:value:

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

retainedReferences

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.

Identifying the Command Buffer

device

The device from which this command buffer was created.

Required.

commandQueue

The command queue that created the command buffer.

Required.

label

A string that identifies this object.

Required.

Grouping Commands in a GPU Frame Capture

- pushDebugGroup:

A string that identifies this object.

Required.

- popDebugGroup

A string that identifies this object.

Required.

Relationships

Inherits From

Conforming Types

See Also

Command Setup

Setting Up a Command Structure

Discover how Metal executes commands on a GPU.

MTLCommandQueue

A queue that organizes command buffers to be executed by a GPU.

MTLCommandEncoder

An encoder that writes GPU commands into a command buffer.

Counter Sampling

Retrieve information about how the GPU executed your commands.