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 Command Encoding

func endEncoding()

Declares that all command generation from the encoder is completed.


Annotating the Command Buffer with Debug Information

func insertDebugSignpost(String)

Inserts a debug string into the captured frame data.


func pushDebugGroup(String)

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


func popDebugGroup()

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


Identifying the Command Encoder

var device: MTLDevice

The Metal device from which the command encoder was created.


var label: String?

A string that labels the command encoder.


See Also

Command Setup

Setting Up a Command Structure

Discover how Metal executes commands on a GPU.

Preparing Your Metal App to Run in the Background

Prepare your app to move into the background by pausing future GPU use and ensuring previous work is scheduled.

protocol MTLCommandQueue

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

protocol MTLCommandBuffer

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

Counter Sampling

Retrieve information about how the GPU executed your commands.