A container that stores encoded commands for the GPU to execute.
SDKs
- iOS 8.0+
- macOS 10.11+
- Mac Catalyst 13.0+
- tvOS 9.0+
Framework
- Metal
Declaration
protocol MTLCommandBuffer
Overview
Don't implement this protocol yourself; instead, create command buffer objects by calling a MTLCommand
object’s make
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 MTLCommand
protocol has methods to create specific types of command encoders: MTLRender
, MTLCompute
, MTLBlit
, and MTLParallel
. 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.