Protocol

MTLCommandEncoder

An encoder that writes GPU commands into a command buffer.

Declaration

protocol MTLCommandEncoder

Overview

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

Protocol

Task

MTLRenderCommandEncoder

Graphics rendering

MTLComputeCommandEncoder

Computation

MTLBlitCommandEncoder

Memory management

MTLParallelRenderCommandEncoder

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.

Topics

Ending Encoded Commands

func endEncoding()

Declares that all command generation from the encoder is completed.

Required.

Annotating the Command Buffer with Debug Information

func insertDebugSignpost(String)

Inserts a debug string into the captured frame data.

Required.

func pushDebugGroup(String)

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

Required.

func popDebugGroup()

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

Required.

Identifying Properties

var device: MTLDevice

The Metal device from which the command encoder was created.

Required.

var label: String?

A string that labels the command encoder.

Required.

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.

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.

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