Protocol

MTLCommandBuffer

A container that stores encoded commands that are committed to and executed by the GPU.

Overview

Your app does not define classes that implement this protocol. Command buffer objects are created by a MTLCommandQueue object and 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. In most cases, you create a command buffer by calling a MTLCommandQueue object’s makeCommandBuffer() method.

After creating a command buffer, you create an encoder object 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, you 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)

Creates an encoder object that can encode graphics rendering commands into this command buffer.

Required.

func makeComputeCommandEncoder()

Creates an encoder object that can encode data-parallel compute commands into this command buffer.

Required.

func makeBlitCommandEncoder()

Creates an encoder object that can encode memory operation (blit) commands into this command buffer.

Required.

func makeParallelRenderCommandEncoder(descriptor: MTLRenderPassDescriptor)

Creates an object that encodes commands into this command buffer that breaks up a single rendering pass into multiple units of work.

Required.

Scheduling and Executing Commands

func enqueue()

Reserves a place for this command buffer on its associated command queue.

Required.

func commit()

Commits this command buffer for execution as soon as possible.

Required.

func addScheduledHandler(MTLCommandBufferHandler)

Registers a block of code that is called immediately after the command buffer has been scheduled for execution on the device.

Required.

func addCompletedHandler(MTLCommandBufferHandler)

Registers a block of code that is called immediately after the device has completed the execution of the command buffer.

Required.

func waitUntilScheduled()

Synchronously wait for this command buffer to be scheduled.

Required.

func waitUntilCompleted()

Synchronously wait for the execution of this command buffer to complete.

Required.

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

Reports the current stage in the lifetime of the command buffer, as it proceeds from enqueued to committed to scheduled to completed.

Required.

var error: Error?

Contains details about an error that may have occurred during command buffer execution.

Required.

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.

Determining Whether to Keep Strong References to Associated Resource Objects

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.

Identifying the Command Buffer

var device: MTLDevice

The device from which this command buffer was created.

Required.

var commandQueue: MTLCommandQueue

The command queue that created the command buffer.

Required.

var label: String?

A string to help identify the command buffer object.

Required.

Constants

typealias MTLCommandBufferHandler

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

enum MTLCommandBufferStatus

The current stage in the lifetime of the command buffer, as it proceeds from enqueued to committed to scheduled to completed.

enum MTLCommandBufferError.Code

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

let MTLCommandBufferErrorDomain: String

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

Debugging

func pushDebugGroup(String)

Pushes a named string onto a stack of string labels.

Required.

Beta
func popDebugGroup()

Pops the latest named string off a stack of string labels.

Required.

Beta

Relationships

Inherits From

See Also

Commands

protocol MTLCommandQueue

A queue that organizes the order in which command buffers are executed by the GPU.

protocol MTLCommandEncoder

An encoder that writes sequential GPU commands into a command buffer.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software