| METAL-PIPELINES-SCRIPT(5) | Metal | METAL-PIPELINES-SCRIPT(5) |
metal-pipelines-script - Metal pipelines script JSON file format
A Metal pipelines script is used to specify a collection of Metal libraries and pipeline descriptors. metal-nt consumes this information to determine which input file to read and which GPU binaries must be generated and stored in a GPU binaries archive.
A Metal pipelines script has a JSON based textual representation. Its canonical file extension is .mtlp-json. The script itself is a single object that can have the members:
The object describing the collection of Metal libraries can have the members:
A named function constant values object can define the members:
A function constant value object can define the members:
If id_type is FunctionConstantName then id must be a string whose value represent the name of function constant variable.
The object describing the collection of Metal pipelines can have the members:
This is the equivalent structure of MTLComputePipelineDescriptor in the Metal API. A Metal compute pipeline descriptor object can have the members:
This is the equivalent structure of MTLRenderPipelineDescriptor in the Metal API. A Metal render pipeline descriptor object can have the members:
This is the equivalent structure of MTLTileRenderPipelineDescriptor in the Metal API. A Metal tile render pipeline descriptor object can have the members:
This is the equivalent structure of MTLStageInputOutputDescriptor in the Metal API. A Metal stage/output descriptor object can have the members:
This is the equivalent structure of MTLVertexDescriptor in the Metal API. A Metal vertex descriptor object can have the members:
This is the equivalent structure of MTLPipelineBufferDescriptor in the Metal API. A Metal pipeline buffer descriptor can define the members:
This is the equivalent of MTLVertexFormat and MTLAttributeFormat in the Metal API. It must be one of the following string values:
This is the equivalent of MTLPixelFormat in the Metal API. It must be one of the following string values:
This is the equivalent of MTLBlendOperation in the Metal API. It must be one of the following string values:
This is the equivalent of MTLBlendFactor in the Metal API. It must be one of the following string values:
Referencing functions in Metal libraries can be done in different ways based on the kind of library being referenced.
The function name shall be used in the case the desired function is part of the input library specified as a command line argument to metal-nt.
{
"pipelines": {
"compute_pipelines": [
{
"compute_function": "my_kernel_function"
}
]
}
}
The syntax alias:<library-identifier>#<function-name> shall be used in the case the desired function is part of a library defined in the libraries object of the Metal script.
{
"libraries": {
"paths": [
{
"label": "lib1",
"path": "path/to/lib1.metallib"
}
]
}
"pipelines": {
"compute_pipelines": [
{
"compute_function": "alias:lib1#my_kernel_function"
}
]
}
}
The syntax file:<path-to-library-file>#<function-name> shall be used in the case the desired function is part of a library file on disk.
Paths can either be absolute or relative. Relative paths are always resolved using the library search paths provided with the option -L to metal-nt.
{
"pipelines": {
"compute_pipelines": [
{
"compute_function": "file:path/to/lib1.metallib#my_kernel_function"
}
]
}
}
A predicate expression is an arbitrary boolean expression combining builtin predicates and user defined named predicates with the operator && (logical AND), || (logical OR), and ! (logical NOT).
It is possible to define named predicates in a Metal pipelines script. Each object describing a named predicate can define the members:
A named predicate can be referenced in an expression with the syntax $<predicate-name>().
{
"named_predicates": [
{
"name": "myPredicate1",
"predicate": "supportsFamily(apple6) || supports(mac2)"
},
{
"name": "myPredicate2",
"predicate": "$myPredicate1() && !supportsFamily(common1)"
}
],
"pipelines": {
"compute_pipelines": [
{
"compute_function": "my_kernel_basic"
},
{
"enable": "$myPredicate1()",
"compute_function": "my_kernel_advanced"
},
{
"enable": "$myPredicate2() || supportsFamily(apple8) || supportsFamily(metal3)",
"compute_function": "my_kernel_more_advanced"
}
]
}
}
This example shows a Metal pipelines script with two compute pipelines and three render pipelines. All the functions are from the input library provided as a command line argument to metal-nt.
{
"pipelines": {
"compute_pipelines": [
{
"compute_function": "my_kernel_1"
},
{
"compute_function": "my_kernel_2"
}
],
"render_pipelines": [
{
"vertex_function": "my_vertex",
"fragment_function": "my_fragment_1",
"color_attachments": [
{
"pixel_format": "BGRA8Unorm"
}
]
},
{
"vertex_function": "my_vertex",
"fragment_function": "my_fragment_2",
"color_attachments": [
{
"pixel_format": "BGRA8Unorm"
}
]
},
{
"vertex_function": "my_vertex_side_effects",
"rasterization_enabled": false
}
]
}
}
This example shows a Metal pipelines script with two render pipelines. The fragment functions used in these render pipelines are specialized functions, hence the script contains a description of the specialization process. Since the only way to reference the specialized function libraries is via the library unique identifier, the ALIAS URI syntax is used to reference the specialized functions.
{
"named_function_constant_values": [
{
"name": "my_common_fc_values",
"constant_values": [
{
"id_type": "FunctionConstantIndex",
"id": {
"data": 0
},
"value_type": "ConstantUInt",
"value": {
"data": 42
}
},
{
"id_type": "FunctionConstantName",
"id": "base_color",
"value_type": "ConstantFloat4",
"value": {
"data": [0.5, 0.22, 0.25, 1.0]
}
}
]
}
],
"libraries": {
"specialized_functions": [
{
"label": "fragment_1_lib",
"function": "my_fragment",
"named_constant_values": "my_common_fc_values",
"constant_values": [
{
"id_type": "FunctionConstantName",
"id": "base_color",
"value_type": "ConstantFloat4",
"value": {
"data": [0.25, 0.25, 0.5, 1.0]
}
},
]
},
{
"label": "fragment_2_lib",
"function": "my_fragment",
"named_constant_values": "my_common_fc_values",
"constant_values": [
{
"id_type": "FunctionConstantIndex",
"id": {
"data": 0
},
"value_type": "ConstantUInt",
"value": {
"data": 23
}
}
]
}
]
},
"pipelines": {
"render_pipelines": [
{
"vertex_function": "my_vertex",
"fragment_function": "alias:fragment_1_lib#my_fragment",
"color_attachments": [
{
"pixel_format": "BGRA8Unorm"
}
]
},
{
"vertex_function": "my_vertex",
"fragment_function": "alias:fragment_2_lib#my_fragment",
"color_attachments": [
{
"pixel_format": "BGRA8Unorm"
}
]
}
]
}
}
Note that in fragment_1_lib the function constant value for the variable base_color provided by my_common_fc_values is overriden locally. Similarly in fragment_2_lib the function constant value for the variable with index 0 provided by my_common_fc_values is overridden locally.
This example shows a Metal pipelines script with three compute pipelines where functions are from libraries either defined as input libraries on disk in the Metal script (see paths), or directly referenced using the FILE URI syntax, or from specialized function libraries using the ALIAS URI syntax.
{
"libraries": {
"paths": [
{
"label": "lib1",
"path": "libraries/lib1.metallib"
}
],
"specialized_functions": [
{
"label": "kernel_42_lib",
"function": "alias:lib1#my_kernel",
"specialized_name": "my_specialized_kernel",
"constant_values": [
{
"id_type": "FunctionConstantIndex",
"id": {
"data": 0
},
"value_type": "ConstantUInt",
"value": {
"data": 42
}
}
]
}
]
},
"pipelines": {
"compute_pipelines": [
{
"compute_function": "alias:kernel_42_lib#my_specialized_kernel"
},
{
"compute_function": "file:/path/to/custom/lib.metallib#custom_kernel"
},
{
"compute_function": "alias:lib1#base_kernel"
}
]
}
}
2014-2023, The Metal Team
| July 5, 2023 | 15 |