1// Copyright (c) 2020-2024 Huawei Technologies Co. Ltd.
2//
3// SPDX-License-Identifier: CC-BY-4.0
4
5[[cluster-culling]]
6= Cluster Culling Shading
7
8This shader type has an execution environment similar to that of a compute
9shader, where a collection of shader invocations form a workgroup and
10cooperate to perform coarse level geometry culling and LOD selection.
11A shader invocation can emit a set of built-in output variables via a new
12built-in function.
13The cluster culling shader organizes these emitted variables into a drawing
14command used by the subsequent rendering pipeline.
15
16
17[[cluster-culling-input]]
18== Cluster Culling Shader Input
19
20The only inputs available to the cluster culling shader are variables
21identifying the specific workgroup and invocation.
22
23
24[[cluster-culling-output]]
25== Cluster Culling Shader Output
26
27If a cluster survives after culling in a cluster culling shader invocation,
28a drawing command to draw this cluster should be emitted by this shader
29invocation for further rendering processing.
30There are two types of drawing command, indexed mode and non-indexed mode.
31Both type of drawing commands consist of a set of built-in output variables
32which have a similar definition to slink:VkDrawIndexedIndirectCommand and
33slink:VkDrawIndirectCommand members.
34
35Cluster culling shaders have the following built-in output variables:
36
37  * <<interfaces-builtin-variables,built-in variable>> code:IndexCountHUAWEI
38    is the number of vertices to draw.
39  * <<interfaces-builtin-variables,built-in variable>>
40    code:VertexCountHUAWEI is the number of vertices to draw.
41  * <<interfaces-builtin-variables,built-in variable>>
42    code:InstanceCountHUAWEI is the number of instances to draw.
43  * <<interfaces-builtin-variables,built-in variable>> code:FirstIndexHUAWEI
44    is the base index within the index buffer.
45  * <<interfaces-builtin-variables,built-in variable>>
46    code:FirstVertexHUAWEI is the index of the first vertex to draw
47  * <<interfaces-builtin-variables,built-in variable>>
48    code:VertexOffsetHUAWEI is the value added to the vertex index before
49    indexing into the vertex buffer.
50  * <<interfaces-builtin-variables,built-in variable>>
51    code:FirstInstanceHUAWEI is the instance ID of the first instance to
52    draw.
53  * <<interfaces-builtin-variables,built-in variable>> code:ClusterIDHUAWEI
54    is the index of cluster being rendered by this drawing command.
55    When cluster culling shader is enabled, code:ClusterIDHUAWEI will
56    replace code:gl_DrawID pass to vertex shader.
57
58
59[[cluster-culling-cluster-ordering]]
60== Cluster Culling Shader Cluster Ordering
61
62  * When a cluster culling shader is used, all output clusters generated by
63    code:DispatchClusterHUAWEI() in a given workgroup are passed to
64    subsequent pipeline stage before any cluster generated from subsequent
65    workgroup.
66  * In a workgroup, the order of output clusters generated by
67    code:DispatchClusterHUAWEI() is specified by the local invocation id,
68    from lower to higher values.
69  * If any cluster culling invocation in the workgroup does not call
70    code:DispatchClusterHUAWEI(), no cluster will be sent to the subsequent
71    rendering pipeline.
72  * Any cluster culling shader invocation may also call
73    code:DispatchClusterHUAWEI() many times as shown below:
74
75[source,c]
76----
77// Cluster Culling Shader sample code:
78        ......
79    DispatchClusterHUAWEI();  // dispatch 0
80        ......
81    DispatchClusterHUAWEI();  // dispatch 1
82        ......
83    DispatchClusterHUAWEI();  // dispatch 2
84        ......
85----
86
87In this case, the output sequence of clusters in a workgroup are specified
88as shown below ( in case of 32 shader invocations in a workgroup):
89
90[source,c]
91----
921. shader invocation0.dispatch0
932. shader invocation1.dispatch0,
94            ..........
9532. shader invocation31.dispatch0
9633. shader invocation0.dispatch1
9734. shader invocation1.dispatch1
98            ..........
9964. shader invocation31.dispatch1
10065. shader invocation0.dispatch2
10166. shader invocation1.dispatch2
102            ..........
10396. shader Invocation31.dispatch2
104----
105
106
107[[cluster-culling-primitive-ordering]]
108== Cluster Culling Shader Primitive Ordering
109
110Following guarantees are provided for the relative ordering of primitives
111produced by a cluster culling shader, as they pertain to
112<<drawing-primitive-order,primitive order>>.
113
114  * Limited guarantees are provided for the relative ordering of primitives
115    produced by a cluster culling shader, as they pertain to primitive
116    order.
117  * The order of primitives in a given cluster is specified by the content
118    of
119  ** code:DispatchClusterHUAWEI() with indexed output built-in variables,
120     vertices sourced from a lower index buffer addresses to higher
121     addresses.
122  ** code:DispatchClusterHUAWEI() with non-indexed output built-in
123     variables, from vertices with a lower numbered vertexIndex to a higher
124     numbered vertexIndex.
125