Contents

MTLFunctionStitchingGraph

A description of a new stitched function.

Declaration

class MTLFunctionStitchingGraph

Overview

An MTLFunctionStitchingGraph instance describes the function graph for a stitched function. A stitched function is a visible function you create by composing other Metal shader functions together in a function graph. A function stitching graph contains nodes for the function’s arguments and any functions it calls in the implementation. Data flows from the arguments to the end of the graph until the stitched function evaluates all of the graph’s nodes.

The graph in the figure below constructs a new function that adds numbers from two source arrays, storing the result in a third array. The function’s parameters are pointers to the source and destination arrays, and an index for performing the array lookup. The graph uses three separate MSL functions to construct the stitched function: a function to look up a value from an array, a function that adds two numbers together, and a function that stores a value to an array.

[Image]

Create an MTLFunctionStitchingGraph instance for each stitched function you want to create. Configure its properties to describe the new function and the nodes that define its behavior, as described below. To create a new library with these stitched functions, see MTLStitchedLibraryDescriptor.

Configuring a function stitching graph

To create a valid stitched function, the function stitching graph and shader code need to meet some requirements:

  • Implement the MSL functions that you use to create the new function, adding the stitchable attribute to each. Stitchable functions are visible functions that you can also use in a function graph. Stitchable functions may require the compiler to do additional work or emit larger instance code, so mark functions as stitchable only when necessary.

  • Declare the stitched function’s name and signature in a header file to include in any shader code that calls the new function. Alternatively, you can add the function to a function table with a matching type and pass the function table as an argument.

  • Create an MTLFunctionStitchingInputNode node for each of the function’s arguments, specifying which parameter each node references. The output type of each input node is the type of that parameter in your function signature.

  • Create an MTLFunctionStitchingFunctionNode for each function the implementation calls. A function node’s output type is the return type of the MSL function.

  • Make sure the output types of each node match the types of the node they pass to. For example, if a function takes a float parameter, the node that provides that data need to output a float value. If you don’t match the types correctly, Metal doesn’t define the behavior of the resulting function.

  • Create an array from the node instances and assign it to the nodes property.

  • If the function produces an output, create another node and assign it to the outputNode property. The output type of this node needs to match the function’s return type. Don’t include this node in the array of nodes you assign to the nodes property.

The MSL code below implements the functions in the example graph above, as well as the function’s signature:

[[stitchable]] float add(float a, float b)
{
    return a + b;
}

[[stitchable]] float lookup(const constant float *a, uint index)
{
    return a[index];
}

[[stitchable]] float store(float value, device float *a, uint index)
{
    a[index] = value;
}

// The output function declaration.
[[visible]] void add_arrays(constant float *a, constant float *b, device float*c, uint tid);

The following code creates the graph above:

Topics

Initializing a function graph

Configuring a function graph

See Also

Stitched function libraries