Protocol

MTLCommand​Buffer

A transient, single-use buffer that stores encoded commands which 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 MTLCommand​Queue 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 MTLCommand​Queue object’s make​Command​Buffer() method.

After creating a command buffer, you create an encoder object to fill the buffer with commands. The MTLCommand​Buffer protocol has methods to create specific types of command encoders: MTLRender​Command​Encoder, MTLCompute​Command​Encoder, MTLBlit​Command​Encoder, and MTLParallel​Render​Command​Encoder. 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.

Symbols

Creating Command Encoders

func make​Render​Command​Encoder(descriptor:​ MTLRender​Pass​Descriptor)

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

func make​Compute​Command​Encoder()

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

func make​Blit​Command​Encoder()

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

func make​Parallel​Render​Command​Encoder(descriptor:​ MTLRender​Pass​Descriptor)

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

Scheduling and Executing Commands

func enqueue()

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

func commit()

Commits this command buffer for execution as soon as possible.

func add​Scheduled​Handler(MTLCommand​Buffer​Handler)

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

func add​Completed​Handler(MTLCommand​Buffer​Handler)

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

func wait​Until​Scheduled()

Synchronously wait for this command buffer to be scheduled.

func wait​Until​Completed()

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

Presenting a Drawable

func present(MTLDrawable)

Registers a drawable presentation to occur as soon as possible.

func present(MTLDrawable, after​Minimum​Duration:​ CFTime​Interval)

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

Beta
func present(MTLDrawable, at​Time:​ CFTime​Interval)

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

Obtaining Status and Timestamps

var status:​ MTLCommand​Buffer​Status

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

var error:​ Error?

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

var kernel​Start​Time:​ CFTime​Interval

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

var kernel​End​Time:​ CFTime​Interval

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

var gpu​Start​Time:​ CFTime​Interval

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

var gpu​End​Time:​ CFTime​Interval

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

Determining Whether to Keep Strong References to Associated Resource Objects

var retained​References:​ 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.

Identifying the Command Buffer

var device:​ MTLDevice

The device from which this command buffer was created.

var command​Queue:​ MTLCommand​Queue

The command queue that created the command buffer.

var label:​ String?

A string to help identify the command buffer object.

Constants

MTLCommand​Buffer​Handler

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

MTLCommand​Buffer​Status

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

MTLCommand​Buffer​Error.Code

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

MTLCommand​Buffer​Error​Domain

Constant to identify the MTLCommand​Buffer error domain.

Relationships

Inherits From

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