An encoder that writes GPU commands into a command buffer.


@protocol MTLCommandEncoder


Don't implement this protocol yourself; instead you call methods on a MTLCommandBuffer object to create command encoders. Command encoder objects are lightweight objects that you re-create every time you need to send commands to the GPU.

There are many different kinds of command encoders, each providing a different set of commands that can be encoded into the buffer. A command encoder implements the MTLCommandEncoder protocol and an additional protocol specific to the kind of encoder being created. Table 1 lists command encoders and the protocols they implement.

Table 1

Command encoder protocols




Graphics rendering




Memory management


Multiple graphics rendering tasks encoded in parallel.

While a command encoder is active, it has the exclusive right to append commands to its command buffer. Once you finish encoding commands, call the endEncoding method to finish encoding the commands. To write further commands into the same command buffer, create a new command encoder.

You can call the insertDebugSignpost:, pushDebugGroup:, and popDebugGroup methods to put debug strings into the command buffer and to push or pop string labels used to identify groups of encoded commands. These methods don't change the rendering or compute behavior of your app; the Xcode debugger uses them to organize your app’s rendering commands in a format that may provide insight into how your app works.


Ending Encoded Commands

- endEncoding

Declares that all command generation from the encoder is completed.


Annotating the Command Buffer with Debug Information

- insertDebugSignpost:

Inserts a debug string into the captured frame data.


- pushDebugGroup:

Pushes a specific string onto a stack of debug group strings for the command encoder.


- popDebugGroup

Pops the latest string off of a stack of debug group strings for the command encoder.


Identifying Properties


The Metal device from which the command encoder was created.



A string that labels the command encoder.


See Also

Command Setup

Setting Up a Command Structure

Discover how Metal executes commands on a GPU.

Devices and Commands

Demonstrates how to access and interact with the GPU.

Enhancing Frame Capture by Using Labels

Assign meaningful labels to your Metal objects and commands so you can easily identify them in the call list of a captured frame.


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


A container that stores encoded commands for the GPU to execute.

Advanced Command Setup

Organize your commands for maximum concurrency and minimal dependencies.

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