MTLCommandBuffer
A container that stores a sequence of GPU commands that you encode into it.
Declaration
protocol MTLCommandBuffer : NSObjectProtocolMentioned in
Overview
A command buffer represents a chunk of work for the GPU that stores the commands you encode to it, as well as any resources those commands need. You primarily use a command buffer to:
Create command encoders and call their methods to add commands to the buffer
Optionally reserve a place for the command buffer in its command queue by enqueuing the command buffer, even before you encode any commands into it
Submit, or commit_,_ the contents of the command buffer to the command queue that creates it to run on the GPU device the queue represents
Create a command encoder from an MTLCommandQueue instance by calling its makeCommandBuffer() method. Typically, you create one or more command queues when your app launches and then keep them throughout your app’s lifetime.
To add commands to an MTLCommandBuffer instance, create an encoder from one of its factory methods, including:
An MTLRenderCommandEncoder instance by calling makeRenderCommandEncoder(descriptor:)
An MTLComputeCommandEncoder instance by calling makeComputeCommandEncoder(dispatchType:)
An MTLBlitCommandEncoder instance by calling makeBlitCommandEncoder() or makeBlitCommandEncoder(descriptor:)
An MTLParallelRenderCommandEncoder instance by calling makeParallelRenderCommandEncoder(descriptor:)
You can use only a single encoder at a time to add commands to a command buffer. To start using a different command encoder, first signal that you’re done with the current encoder by calling its endEncoding() method. Then create another command encoder from the command buffer and continue adding commands to the buffer with the new encoder.
Repeat the process until you finish encoding commands to the command buffer and are ready to run the buffer’s contents on the GPU. Then submit the command buffer to the command queue that you used to create it by calling the command buffer’s commit() method. After an app commits a command buffer, you check its status property or block a thread by calling its waitUntilScheduled() or waitUntilCompleted() methods.
You also have the option to reserve a place for the command buffer in its command queue by calling the command buffer’s enqueue() method. You can call this method exactly once at any time before you commit the buffer to the queue. If you don’t enqueue a command buffer, it implicitly enqueues itself when you commit it. Each command queue ensures the order that you enqueue its command buffers is the same order the queue schedules them to run on the GPU.
For example, a multithreaded app might set the GPU’s execution order for a sequence of related subtasks by:
Creating a command buffer for each subtask
Enqueuing the command buffers in the proper order on a single thread
Encoding commands to each buffer on a separate thread and then committing it