Skip to main content

naga/back/hlsl/
mesh_shader.rs

1use core::fmt;
2
3use alloc::{
4    format,
5    string::{String, ToString},
6    vec::Vec,
7};
8
9use crate::{
10    back::{
11        self,
12        hlsl::{
13            writer::{EntryPointBinding, EpStructMember, Io, NestedEntryPointArgs},
14            BackendResult, Error,
15        },
16    },
17    proc::NameKey,
18    Handle, Module, ShaderStage, TypeInner,
19};
20
21impl NestedEntryPointArgs {
22    pub fn write_call_args(&self, out: &mut impl fmt::Write) -> fmt::Result {
23        let all_args = self
24            .user_args
25            .iter()
26            .map(String::as_str)
27            .chain(self.task_payload.as_deref())
28            .chain(core::iter::once(self.local_invocation_index.as_str()));
29        for (i, arg) in all_args.enumerate() {
30            if i != 0 {
31                write!(out, ", ")?;
32            }
33            write!(out, "{arg}")?;
34        }
35        Ok(())
36    }
37}
38
39impl<W: fmt::Write> super::Writer<'_, W> {
40    #[expect(clippy::too_many_arguments)]
41    fn write_mesh_shader_wrapper(
42        &mut self,
43        module: &Module,
44        func_ctx: &back::FunctionCtx,
45        need_workgroup_variables_initialization: bool,
46        nested_name: &str,
47        entry_point: &crate::EntryPoint,
48        args: NestedEntryPointArgs,
49        mut separator_if_needed: impl FnMut() -> &'static str,
50    ) -> BackendResult {
51        let Some(ref mesh_info) = entry_point.mesh_info else {
52            unreachable!()
53        };
54        let back::FunctionType::EntryPoint(ep_index) = func_ctx.ty else {
55            unreachable!()
56        };
57        // Mesh shader wrapper
58        let mesh_interface = self.entry_point_io.get(&(ep_index as usize)).unwrap();
59        let vert_info = mesh_interface.mesh_vertices.as_ref().unwrap();
60        let prim_info = mesh_interface.mesh_primitives.as_ref().unwrap();
61        let indices_info = mesh_interface.mesh_indices.as_ref().unwrap();
62        // Write something of the form `out indices uint3 indices_var[num_primitives]`
63        write!(
64            self.out,
65            "{}out indices {} {}[{}]",
66            separator_if_needed(),
67            indices_info.ty_name,
68            indices_info.arg_name,
69            mesh_info.max_primitives
70        )?;
71        // Write something of the form `out vertices VertexType vertices_var[num_vertices]`
72        write!(
73            self.out,
74            ", out vertices {} {}[{}]",
75            vert_info.ty_name, vert_info.arg_name, mesh_info.max_vertices
76        )?;
77        // Write something of the form `out primitives PrimitiveType} primitives_var[num_primitives]`
78        write!(
79            self.out,
80            ", out primitives {} {}[{}]",
81            prim_info.ty_name, prim_info.arg_name, mesh_info.max_primitives
82        )?;
83        if let Some(task_payload) = entry_point.task_payload {
84            // Write the outer-function `in payload` arg.  The name is already in
85            // args.task_payload, having been collected when the inner function
86            // signature was written in write_function (writer.rs).
87            write!(self.out, ", in payload ")?;
88            let var = &module.global_variables[task_payload];
89            self.write_type(module, var.ty)?;
90            let name = &self.names[&NameKey::GlobalVariable(task_payload)];
91            write!(self.out, " {name}")?;
92            if let TypeInner::Array { base, size, .. } = module.types[var.ty].inner {
93                self.write_array_size(module, base, size)?;
94            }
95        }
96        writeln!(self.out, ") {{")?;
97        if need_workgroup_variables_initialization {
98            self.write_workgroup_variables_initialization(
99                func_ctx,
100                module,
101                &args.local_invocation_index,
102            )?;
103        }
104        write!(self.out, "{}{nested_name}(", back::INDENT)?;
105        args.write_call_args(&mut self.out)?;
106        writeln!(self.out, ");")?;
107        writeln!(
108            self.out,
109            "{}GroupMemoryBarrierWithGroupSync();",
110            back::INDENT
111        )?;
112
113        let ep = &module.entry_points[ep_index as usize];
114        let mesh_info = ep.mesh_info.as_ref().unwrap();
115        let io = self.entry_point_io.get(&(ep_index as usize)).unwrap();
116
117        let var_name = &self.names[&NameKey::GlobalVariable(mesh_info.output_variable)];
118        let var_type = module.global_variables[mesh_info.output_variable].ty;
119        let wg_size: u32 = ep.workgroup_size.iter().product();
120
121        let get_var_member_name = |bi, var_type| {
122            // The mesh shader output type must be a struct with exactly 4 members.
123            let TypeInner::Struct { ref members, .. } = module.types[var_type].inner else {
124                unreachable!()
125            };
126            let idx = members
127                .iter()
128                .position(|f| f.binding == Some(crate::Binding::BuiltIn(bi)))
129                .unwrap();
130            self.names[&NameKey::StructMember(var_type, idx as u32)].clone()
131        };
132
133        let vert_count = format!(
134            "{var_name}.{}",
135            get_var_member_name(crate::BuiltIn::VertexCount, var_type),
136        );
137        let prim_count = format!(
138            "{var_name}.{}",
139            get_var_member_name(crate::BuiltIn::PrimitiveCount, var_type),
140        );
141
142        let level = back::Level(1);
143
144        writeln!(
145            self.out,
146            "{level}SetMeshOutputCounts({vert_count}, {prim_count});"
147        )?;
148
149        // We need separate loops for vertices and primitives writing
150        struct OutputArray<'a> {
151            array_bi: crate::BuiltIn,
152            count: String,
153            io_interface: &'a EntryPointBinding,
154            is_primitive: bool,
155            index_name: &'static str,
156            ty: Handle<crate::Type>,
157        }
158        let output_arrays = [
159            OutputArray {
160                array_bi: crate::BuiltIn::Vertices,
161                count: vert_count,
162                io_interface: io.mesh_vertices.as_ref().unwrap(),
163                is_primitive: false,
164                index_name: "vertIndex",
165                ty: mesh_info.vertex_output_type,
166            },
167            OutputArray {
168                array_bi: crate::BuiltIn::Primitives,
169                count: prim_count,
170                io_interface: io.mesh_primitives.as_ref().unwrap(),
171                is_primitive: true,
172                index_name: "primIndex",
173                ty: mesh_info.primitive_output_type,
174            },
175        ];
176
177        for output in output_arrays {
178            let OutputArray {
179                array_bi,
180                count,
181                io_interface,
182                is_primitive,
183                index_name,
184                ty,
185            } = output;
186            let out_var_name = &io_interface.arg_name;
187            let index_name = self.namer.call(index_name);
188            let array_name = get_var_member_name(array_bi, var_type);
189            let item_name = format!("{var_name}.{array_name}[{index_name}]");
190            writeln!(
191                self.out,
192                "{level}for (int {index_name} = {}; {index_name} < {count}; {index_name} += {}) {{",
193                args.local_invocation_index, wg_size
194            )?;
195
196            // Loop body, uses more indentation
197            {
198                let level = level.next();
199                for member in &io_interface.members {
200                    let out_member_name = &member.name;
201                    let in_member_name = &self.names[&NameKey::StructMember(ty, member.index)];
202                    writeln!(self.out, "{level}{out_var_name}[{index_name}].{out_member_name} = {item_name}.{in_member_name};",)?;
203                }
204                if is_primitive {
205                    let indices_member_name = get_var_member_name(
206                        mesh_info.topology.to_builtin(),
207                        mesh_info.primitive_output_type,
208                    );
209                    let indices_var_name = &io.mesh_indices.as_ref().unwrap().arg_name;
210                    writeln!(
211                                self.out,
212                                "{level}{indices_var_name}[{index_name}] = {item_name}.{indices_member_name};",
213                            )?;
214                }
215            }
216
217            writeln!(self.out, "{level}}}")?;
218        }
219        Ok(())
220    }
221
222    fn write_task_shader_wrapper(
223        &mut self,
224        module: &Module,
225        func_ctx: &back::FunctionCtx,
226        need_workgroup_variables_initialization: bool,
227        nested_name: &str,
228        entry_point: &crate::EntryPoint,
229        args: NestedEntryPointArgs,
230    ) -> BackendResult {
231        // Task shader wrapper
232        writeln!(self.out, ") {{")?;
233        if need_workgroup_variables_initialization {
234            self.write_workgroup_variables_initialization(
235                func_ctx,
236                module,
237                &args.local_invocation_index,
238            )?;
239        }
240        let grid_size = self.namer.call("gridSize");
241        write!(
242            self.out,
243            "{}uint3 {grid_size} = {nested_name}(",
244            back::INDENT
245        )?;
246        args.write_call_args(&mut self.out)?;
247        writeln!(self.out, ");")?;
248        writeln!(
249            self.out,
250            "{}GroupMemoryBarrierWithGroupSync();",
251            back::INDENT
252        )?;
253        if let Some(limits) = self.options.task_dispatch_limits {
254            let level = back::Level(2);
255            writeln!(self.out, "{}if (", back::INDENT)?;
256
257            let max_per_dim = limits.max_mesh_workgroups_per_dim.min(2 << 21);
258            let max_total = limits.max_mesh_workgroups_total;
259            for i in 0..3 {
260                writeln!(
261                    self.out,
262                    "{level}{grid_size}.{} > {max_per_dim} ||",
263                    back::COMPONENTS[i],
264                )?;
265            }
266            writeln!(
267                self.out,
268                "{level}((uint64_t){grid_size}.x) * ((uint64_t){grid_size}.y) > {max_total} ||"
269            )?;
270            writeln!(
271                    self.out,
272                    "{level}((uint64_t){grid_size}.x) * ((uint64_t){grid_size}.y) * ((uint64_t){grid_size}.z) > {max_total}",
273                )?;
274
275            writeln!(self.out, "{}) {{", back::INDENT)?;
276            writeln!(self.out, "{level}{grid_size} = uint3(0, 0, 0);")?;
277            writeln!(self.out, "{}}}", back::INDENT)?;
278        }
279        writeln!(
280            self.out,
281            "{}DispatchMesh({grid_size}.x, {grid_size}.y, {grid_size}.z, {});",
282            back::INDENT,
283            self.names[&NameKey::GlobalVariable(entry_point.task_payload.unwrap())]
284        )?;
285        Ok(())
286    }
287    /// Mesh and task entry points must all return at the same `return` statement,
288    /// so we have a nested function that can return wherever. This writes the caller,
289    /// or the actual entry point.
290    #[expect(clippy::too_many_arguments)]
291    pub(super) fn write_nested_function_outer(
292        &mut self,
293        module: &Module,
294        func_ctx: &back::FunctionCtx,
295        header: &str,
296        name: &str,
297        need_workgroup_variables_initialization: bool,
298        nested_name: &str,
299        entry_point: &crate::EntryPoint,
300        // Built in write_function alongside the inner function signature, so the
301        // call-site argument order is guaranteed to match the declaration order.
302        args: NestedEntryPointArgs,
303    ) -> BackendResult {
304        let mut any_args_written = false;
305        let mut separator_if_needed = || {
306            if any_args_written {
307                ", "
308            } else {
309                any_args_written = true;
310                ""
311            }
312        };
313
314        let back::FunctionType::EntryPoint(ep_index) = func_ctx.ty else {
315            unreachable!();
316        };
317        let stage = module.entry_points[ep_index as usize].stage;
318        write!(self.out, "{header}")?;
319        write!(self.out, "void {name}(")?;
320        // Write the outer function's argument list with full type annotations and
321        // semantics.  Arg names come from self.names and are the same names that
322        // were collected into `args` when writing the inner function signature.
323        if let Some(ref ep_input) = self.entry_point_io.get(&(ep_index as usize)).unwrap().input {
324            write!(self.out, "{} {}", ep_input.ty_name, ep_input.arg_name)?;
325        } else {
326            for (index, arg) in entry_point.function.arguments.iter().enumerate() {
327                write!(self.out, "{}", separator_if_needed())?;
328                self.write_type(module, arg.ty)?;
329
330                let argument_name =
331                    &self.names[&NameKey::EntryPointArgument(ep_index, index as u32)];
332
333                write!(self.out, " {argument_name}")?;
334                if let TypeInner::Array { base, size, .. } = module.types[arg.ty].inner {
335                    self.write_array_size(module, base, size)?;
336                }
337
338                self.write_semantic(&arg.binding, Some((stage, Io::Input)))?;
339            }
340        }
341        if need_workgroup_variables_initialization || stage == ShaderStage::Mesh {
342            write!(
343                self.out,
344                "{}uint {} : SV_GroupIndex",
345                separator_if_needed(),
346                args.local_invocation_index,
347            )?;
348        }
349        if entry_point.stage == ShaderStage::Mesh {
350            self.write_mesh_shader_wrapper(
351                module,
352                func_ctx,
353                need_workgroup_variables_initialization,
354                nested_name,
355                entry_point,
356                args,
357                separator_if_needed,
358            )?;
359        } else {
360            self.write_task_shader_wrapper(
361                module,
362                func_ctx,
363                need_workgroup_variables_initialization,
364                nested_name,
365                entry_point,
366                args,
367            )?;
368        }
369
370        writeln!(self.out, "}}")?;
371        Ok(())
372    }
373
374    pub(super) fn write_ep_mesh_output_struct(
375        &mut self,
376        module: &Module,
377        entry_point_name: &str,
378        is_primitive: bool,
379        mesh_info: &crate::MeshStageInfo,
380    ) -> Result<EntryPointBinding, Error> {
381        let (in_type, io, var_prefix, arg_name) = if is_primitive {
382            (
383                mesh_info.primitive_output_type,
384                Io::MeshPrimitives,
385                "Primitive",
386                "primitives",
387            )
388        } else {
389            (
390                mesh_info.vertex_output_type,
391                Io::MeshVertices,
392                "Vertex",
393                "vertices",
394            )
395        };
396        let struct_name = format!("Mesh{var_prefix}Output_{entry_point_name}",);
397
398        // Mesh shader output types must be structs; this is validated by naga
399        let members = match module.types[in_type].inner {
400            TypeInner::Struct { ref members, .. } => members,
401            _ => unreachable!(),
402        };
403        let mut out_members = Vec::new();
404        for (index, member) in members.iter().enumerate() {
405            if matches!(
406                member.binding,
407                Some(crate::Binding::BuiltIn(
408                    crate::BuiltIn::PointIndex
409                        | crate::BuiltIn::LineIndices
410                        | crate::BuiltIn::TriangleIndices
411                ))
412            ) {
413                continue;
414            }
415            let member_name = self.namer.call_or(&member.name, "member");
416            out_members.push(EpStructMember {
417                name: member_name,
418                ty: member.ty,
419                binding: member.binding.clone(),
420                index: index as u32,
421            })
422        }
423        self.write_interface_struct(
424            module,
425            (ShaderStage::Mesh, io),
426            struct_name,
427            Some(arg_name),
428            out_members,
429        )
430    }
431
432    pub(super) fn write_ep_mesh_output_indices(
433        &mut self,
434        topology: crate::MeshOutputTopology,
435    ) -> Result<EntryPointBinding, Error> {
436        let (indices_name, indices_type) = match topology {
437            // Points require a capability that isn't supported in the HLSL writer
438            crate::MeshOutputTopology::Points => unreachable!(),
439            crate::MeshOutputTopology::Lines => (self.namer.call("lineIndices"), "uint2"),
440            crate::MeshOutputTopology::Triangles => (self.namer.call("triangleIndices"), "uint3"),
441        };
442        Ok(EntryPointBinding {
443            ty_name: indices_type.to_string(),
444            arg_name: indices_name,
445            members: Vec::new(),
446            local_invocation_index_name: None,
447        })
448    }
449}