Protocol

MTLComputeCommandEncoder

An object used to encode commands in a compute pass.

Declaration

protocol MTLComputeCommandEncoder

Overview

Don't implement this protocol yourself; instead, create compute command encoders by calling the makeComputeCommandEncoder(dispatchType:) method of the MTLCommandBuffer object into which you want to encode compute commands. You can encode multiple commands in a single compute pass.

To encode a compute command:

  1. Call the setComputePipelineState(_:) method with the MTLComputePipelineState object that contains the compute function to be executed.

  2. Call one or more other functions on the encoder to specify parameters for the compute function.

  3. Call the dispatchThreadgroups(_:threadsPerThreadgroup:) method to encode a compute command.

After repeating these steps as many times as necessary, call endEncoding() to finish the compute pass. You must always call endEncoding() before the encoder is released or before creating another encoder.

Topics

Specifying the Compute Pipeline State

func setComputePipelineState(MTLComputePipelineState)

Sets the current compute pipeline state object.

Required.

Specifying Parameters for a Compute Function

func setBuffer(MTLBuffer?, offset: Int, index: Int)

Sets a buffer for the compute function.

Required.

func setBuffers([MTLBuffer?], offsets: [Int], range: Range<Int>)

Sets an array of buffers for the vertex function.

func setBufferOffset(Int, index: Int)

Sets where the data begins in a buffer already bound to the compute shader.

Required.

func setBytes(UnsafeRawPointer, length: Int, index: Int)

Sets a block of data for the compute shader.

Required.

func setSamplerState(MTLSamplerState?, index: Int)

Sets a sampler for the compute function.

Required.

func setSamplerState(MTLSamplerState?, lodMinClamp: Float, lodMaxClamp: Float, index: Int)

Sets a sampler for the compute function, specifying clamp values for the level of detail.

Required.

func setSamplerStates([MTLSamplerState?], range: Range<Int>)

Sets an array of sampler states in a range of indices in the sampler state argument table.

func setSamplerStates([MTLSamplerState?], lodMinClamps: [Float], lodMaxClamps: [Float], range: Range<Int>)

Sets multiple samplers for the compute function, specifying clamp values for the level of detail of each sampler.

func setTexture(MTLTexture?, index: Int)

Sets a texture for the compute function.

Required.

func setTextures([MTLTexture?], range: Range<Int>)

Sets an array of textures for the compute function.

func setThreadgroupMemoryLength(Int, index: Int)

Sets the size of a block of threadgroup memory.

Required.

Executing a Compute Function Directly

func dispatchThreadgroups(MTLSize, threadsPerThreadgroup: MTLSize)

Encodes a compute command using a grid aligned to threadgroup boundaries.

Required.

func dispatchThreads(MTLSize, threadsPerThreadgroup: MTLSize)

Encodes a compute command using an arbitrarily sized grid.

Required.

Executing a Compute Function Indirectly

func dispatchThreadgroups(indirectBuffer: MTLBuffer, indirectBufferOffset: Int, threadsPerThreadgroup: MTLSize)

Encodes a dispatch call for a compute pass, using an indirect buffer that defines the size of a grid aligned to threadgroup boundaries.

Required.

struct MTLDispatchThreadgroupsIndirectArguments

The data layout required for the arguments needed to specify the size of threadgroups.

Specifying Resource Usage for Argument Buffers

func useResource(MTLResource, usage: MTLResourceUsage)

Specifies that a resource in an argument buffer can be safely used by a compute pass.

Required.

func useResources([MTLResource], usage: MTLResourceUsage)

Specifies that an array of resources in an argument buffer can be safely used by a compute pass.

func useHeap(MTLHeap)

Specifies that a heap containing resources in an argument buffer can be safely used by a compute pass.

Required.

func useHeaps([MTLHeap])

Specifies that an array of heaps containing resources in an argument buffer can be safely used by a compute pass.

struct MTLResourceUsage

The options that describe how a resource within an argument buffer will be used in a graphics or compute function.

Specifying Imageblock Size

func setImageblockWidth(Int, height: Int)

Sets the size, in pixels, of the imageblock.

Required.

Specifying the Stage-In Region

func setStageInRegion(MTLRegion)

Sets the region of the stage-in attributes to apply to the compute kernel.

Required.

func setStageInRegionWithIndirectBuffer(MTLBuffer, indirectBufferOffset: Int)

Sets the region of the stage-in attributes to apply to the compute kernel using an indirect buffer.

Required.

struct MTLStageInRegionIndirectArguments

The data layout required for the arguments needed to specify the stage-in region.

Executing Commands Concurrently or Serially

Define whether the encoder's commands should execute in parallel or in succession.

var dispatchType: MTLDispatchType

The strategy to use when dispatching commands encoded by the compute command encoder.

Required.

enum MTLDispatchType

Constants indicating how the compute command encoder's commands are dispatched.

func memoryBarrier(scope: MTLBarrierScope)

Encodes a barrier so that changes to a set of resource types made by commands encoded before the barrier are completed before further commands are executed.

Required.

func memoryBarrier(resources: [MTLResource])

Encodes a barrier so that changes to a set of resources made by commands encoded before the barrier are completed before further commands are executed.

Synchronizing Command Execution for Untracked Resources

func updateFence(MTLFence)

Tells the GPU to update the fence after all commands encoded by the compute command encoder have finished executing.

Required.

func waitForFence(MTLFence)

Tells the GPU to wait until the fence is updated before executing any commands encoded by the compute command encoder.

Required.

Instance Methods

func executeCommands(in: MTLIndirectCommandBuffer, indirectBuffer: MTLBuffer, indirectBufferOffset: Int)

Encodes a command to execute commands in an indirect command buffer, specifying the range indirectly.

Required.

Beta
func executeCommands(in: MTLIndirectCommandBuffer, with: NSRange)

Encodes a command to execute commands in an indirect command buffer.

Required.

Beta
func sampleCounters(sampleBuffer: MTLCounterSampleBuffer, sampleIndex: Int, barrier: Bool)

Encodes a command to sample hardware counters at this point in the compute pass and store the samples into a counter sample buffer.

Required.

Beta

Relationships

Inherits From

See Also

Parallel Computation

Hello Compute

Demonstrates how to perform data-parallel computations using the GPU.

About Threads and Threadgroups

Learn how Metal organizes compute-processing workloads.

Calculating Threadgroup and Grid Sizes

Calculate the optimum sizes for threadgroups and grids when dispatching compute-processing workloads.

class MTLComputePipelineDescriptor

An object used to customize how a new compute pipeline state object is compiled.

protocol MTLComputePipelineState

An object that contains a compiled compute pipeline.

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