Expand description
Backend for MSL (Metal Shading Language).
This backend does not support the SHADER_INT64_ATOMIC_ALL_OPS
capability.
§Binding model
Metal’s bindings are flat per resource. Since there isn’t an obvious mapping from SPIR-V’s descriptor sets, we require a separate mapping provided in the options. This mapping may have one or more resource end points for each descriptor set + index pair.
§Entry points
Even though MSL and our IR appear to be similar in that the entry points in both can
accept arguments and return values, the restrictions are different.
MSL allows the varyings to be either in separate arguments, or inside a single
[[stage_in]]
struct. We gather input varyings and form this artificial structure.
We also add all the (non-Private) globals into the arguments.
At the beginning of the entry point, we assign the local constants and re-compose the arguments as they are declared on IR side, so that the rest of the logic can pretend that MSL doesn’t have all the restrictions it has.
For the result type, if it’s a structure, we re-compose it with a temporary value holding the result.
§Pointer-typed bounds-checked expressions and OOB locals
MSL (unlike HLSL and GLSL) has native support for pointer-typed function
arguments. When the BoundsCheckPolicy
is ReadZeroSkipWrite
and an
out-of-bounds index expression is used for such an argument, our strategy is to
pass a pointer to a dummy variable. These dummy variables are called “OOB
locals”. We emit at most one OOB local per function for each type, since all
expressions producing a result of that type can share the same OOB local. (Note
that the OOB local mechanism is not actually implementing “skip write”, nor even
“read zero” in some cases of read-after-write, but doing so would require
additional effort and the difference is unlikely to matter.)
§External textures
Support for crate::ImageClass::External
textures is implemented by lowering
each external texture global variable to 3 texture2d<float, sample>
s, and a
constant buffer of type NagaExternalTextureParams
. This provides up to 3
planes of texture data (for example single planar RGBA, or separate Y, Cb, and
Cr planes), and the parameters buffer containing information describing how to
handle these correctly. The bind target to use for each of these globals is
specified via the BindTarget::external_texture
field of the relevant
entries in EntryPointResources::resources
.
External textures are supported by WGSL’s textureDimensions()
,
textureLoad()
, and textureSampleBaseClampToEdge()
built-in functions. These
are implemented using helper functions. See the following functions for how
these are generated:
Writer::write_wrapped_image_query
Writer::write_wrapped_image_load
Writer::write_wrapped_image_sample
The lowered global variables for each external texture global are passed to the
entry point as separate arguments (see “Entry points” above). However, they are
then wrapped in a struct to allow them to be conveniently passed to user
defined and helper functions. See writer::EXTERNAL_TEXTURE_WRAPPER_STRUCT
.
Modules§
Structs§
- Attribute
Mapping - A mapping of vertex buffers and their attributes to shader locations.
- Bind
External Texture Target - Binding information for a Naga
External
image global variable. - Bind
Target - Binding
MapSerialization 🔒 - Entry
Point Resources - Options
- Pipeline
Options - A subset of options that are meant to be changed per pipeline.
- Translation
Info - Information about a translated module that is required for the use of the result.
- Vertex
Buffer Mapping - A description of a vertex buffer with all the information we need to address the attributes within it.
- Writer
Enums§
- Bind
Sampler Target - Entry
Point Error - Error
- Location
Mode 🔒 - Points in the MSL code where we might emit a pipeline input or output.
- Resolved
Binding 🔒 - Resolved
Interpolation 🔒 - Vertex
Format - Corresponds to WebGPU
GPUVertexFormat
.