1 /*
2 * Copyright (C) 2023 Huawei Device Co., Ltd.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16 #ifndef API_RENDER_IRENDER_COMMAND_LIST_H
17 #define API_RENDER_IRENDER_COMMAND_LIST_H
18
19 #include <cstdint>
20
21 #include <base/containers/array_view.h>
22 #include <base/util/uid.h>
23 #include <render/device/pipeline_layout_desc.h>
24 #include <render/device/pipeline_state_desc.h>
25 #include <render/namespace.h>
26 #include <render/nodecontext/intf_render_node_interface.h>
27 #include <render/render_data_structures.h>
28 #include <render/resource_handle.h>
29
RENDER_BEGIN_NAMESPACE()30 RENDER_BEGIN_NAMESPACE()
31 /** @ingroup group_render_irendercommandlist */
32 /** Call methods to add render commands to a render command list.
33 * Render command list is unique for every render node.
34 * Most of the methods and their inputs are familiar from different graphics APIs.
35 *
36 * RenderCommandList does not do heavy processing on unnecessary state changes etc.
37 * Prefer setting data, bindings etc. only once and do not add empty draw and/or dispatches.
38 */
39 class IRenderCommandList : public IRenderNodeInterface {
40 public:
41 static constexpr auto UID = BASE_NS::Uid("59d9798e-7fff-4eb5-8fb9-3ffa48e9ff34");
42
43 /** Can only be called inside of a render pass.
44 * @param vertexCount Vertex count
45 * @param instanceCount Instance count
46 * @param firstVertex First vertex
47 * @param firstInstance First instance
48 */
49 virtual void Draw(const uint32_t vertexCount, const uint32_t instanceCount, const uint32_t firstVertex,
50 const uint32_t firstInstance) = 0;
51
52 /** Can only be called inside of a render pass.
53 * @param indexCount Index count
54 * @param instanceCount Instance count
55 * @param firstIndex First index
56 * @param vertexOffset Vertex offset
57 * @param firstInstance First instance
58 */
59 virtual void DrawIndexed(const uint32_t indexCount, const uint32_t instanceCount, const uint32_t firstIndex,
60 const int32_t vertexOffset, const uint32_t firstInstance) = 0;
61
62 /** Draw with indirect arguments.
63 * Can only be called inside of a render pass.
64 * @param bufferHandle Buffer handle
65 * @param offset Offset
66 * @param drawCount Draw count
67 * @param stride Stride
68 */
69 virtual void DrawIndirect(
70 const RenderHandle bufferHandle, const uint32_t offset, const uint32_t drawCount, const uint32_t stride) = 0;
71
72 /** Can only be called inside of a render pass.
73 * @param bufferHandle Buffer handle
74 * @param offset Offset
75 * @param drawCount Draw count
76 * @param stride Stride
77 */
78 virtual void DrawIndexedIndirect(
79 const RenderHandle bufferHandle, const uint32_t offset, const uint32_t drawCount, const uint32_t stride) = 0;
80
81 /** Dispatch a compute program.
82 * @param groupCountX Group count x
83 * @param aGroupCountY Group count y
84 * @param groupCountZ Group count z
85 */
86 virtual void Dispatch(const uint32_t groupCountX, const uint32_t groupCountY, const uint32_t groupCountZ) = 0;
87
88 /** Dispatch a compute program with indirect arguments.
89 * @param bufferHandle Buffer handle
90 * @param offset Offset
91 */
92 virtual void DispatchIndirect(const RenderHandle bufferHandle, const uint32_t offset) = 0;
93
94 /** Bind pipeline
95 * @param psoHandle PSO handle
96 */
97 virtual void BindPipeline(const RenderHandle psoHandle) = 0;
98
99 /** Push constant
100 * @param pushConstant Push constant
101 * @param data Data
102 */
103 virtual void PushConstant(const PushConstant& pushConstant, const uint8_t* data) = 0;
104
105 /** Bind vertex buffers
106 * @param vertexBuffers Vertex buffers
107 */
108 virtual void BindVertexBuffers(const BASE_NS::array_view<const VertexBuffer> vertexBuffers) = 0;
109
110 /** Bind index buffer
111 * @param indexBuffer Index buffer
112 */
113 virtual void BindIndexBuffer(const IndexBuffer& indexBuffer) = 0;
114
115 /** Draw-calls can only be made inside of a render pass.
116 * A render pass definition without content. Render pass needs to have
117 * SubpassContents::CORE_SUBPASS_CONTENTS_INLINE set.
118 * All subpasses given with subpassDescs.
119 * @param renderPassDesc Render pass descriptor
120 * @param subpassDescs Subpass descriptors
121 */
122 virtual void BeginRenderPass(
123 const RenderPassDesc& renderPassDesc, const BASE_NS::array_view<const RenderPassSubpassDesc> subpassDescs) = 0;
124
125 /** Draw-calls can only be made inside of a render pass.
126 * A render pass definition without content. Render pass needs to have
127 * SubpassContents::CORE_SUBPASS_CONTENTS_INLINE set.
128 * Subpasses are patched to this render pass from other render command lists, if renderPassDesc.subpassCount > 1.
129 * There cannot be multiple "open" render passes from other render command lists.
130 * @param renderPassDesc Render pass descriptor
131 * @param subpassStartIndex Subpass start index
132 * @param subpassDesc Subpass descriptor
133 */
134 virtual void BeginRenderPass(const RenderPassDesc& renderPassDesc, const uint32_t subpassStartIndex,
135 const RenderPassSubpassDesc& subpassDesc) = 0;
136
137 /** Must be called when a render pass ends. */
138 virtual void EndRenderPass() = 0;
139
140 /** Next subpass
141 * @param subpassContents subpass contents
142 */
143 virtual void NextSubpass(const SubpassContents& subpassContents) = 0;
144
145 /** This will disable automatic barriers until EndExecuteAutomaticBarriers is called.
146 * This will add a barrier point for current pending barriers.
147 * Use when manually adding barriers and executing them in a single spot.
148 * In addition, disables initial image layouts in render passes and uses undefined layouts.
149 */
150 virtual void BeginDisableAutomaticBarrierPoints() = 0;
151
152 /** Re-enable automatic barriers.
153 * Needs to be called after BeginDisableAutomaticBarrierPoints to re-enable automatic barriers.
154 */
155 virtual void EndDisableAutomaticBarrierPoints() = 0;
156
157 /** This will add custom barrier point where all pending (custom) barriers will be executed.
158 */
159 virtual void AddCustomBarrierPoint() = 0;
160
161 /** Add custom memory barrier.
162 * Can be used for a memory barrier.
163 * @param src General barrier source state
164 * @param dst General barrier destination state
165 */
166 virtual void CustomMemoryBarrier(const GeneralBarrier& src, const GeneralBarrier& dst) = 0;
167
168 /** Add custom barriers for a GPU buffer.
169 * Can only be called outside of render pass.
170 * @param handle Handle to resource
171 * @param src Source buffer resource barrier
172 * @param dst Destination buffer resource barrier
173 * @param byteOffset Byte offset
174 * @param byteSize Byte size (use PipelineStateConstants::GPU_BUFFER_WHOLE_SIZE for the whole buffer)
175 */
176 virtual void CustomBufferBarrier(const RenderHandle handle, const BufferResourceBarrier& src,
177 const BufferResourceBarrier& dst, const uint32_t byteOffset, const uint32_t byteSize) = 0;
178
179 /** Add custom barriers for a GPU image.
180 * Can only be called outside of render pass.
181 * Checks the current/correct state and layout, and updates to new given dst state.
182 * @param handle Handle to resource
183 * @param dst Destination image resource barrier
184 * @param imageSubresourceRange ImageSubresourceRange
185 */
186 virtual void CustomImageBarrier(const RenderHandle handle, const ImageResourceBarrier& dst,
187 const ImageSubresourceRange& imageSubresourceRange) = 0;
188 /** Add custom barriers for a GPU image.
189 * Can only be called outside of render pass.
190 * Does not check the current/correct state and layout. Can be used e.g. as a barrier from undefined state.
191 * @param handle Handle to resource
192 * @param src Source image resource barrier
193 * @param dst Destination image resource barrier
194 * @param imageSubresourceRange ImageSubresourceRange
195 */
196 virtual void CustomImageBarrier(const RenderHandle handle, const ImageResourceBarrier& src,
197 const ImageResourceBarrier& dst, const ImageSubresourceRange& imageSubresourceRange) = 0;
198
199 /** Copy buffer to buffer
200 * @param srcHandle Source handle
201 * @param dstHandle Destination handle
202 * @param bufferCopy Buffer copy
203 */
204 virtual void CopyBufferToBuffer(
205 const RenderHandle srcHandle, const RenderHandle dstHandle, const BufferCopy& bufferCopy) = 0;
206
207 /** Copy buffer to image
208 * @param srcHandle Source handle
209 * @param dstHandle Destination handle
210 * @param bufferImageCopy Buffer image copy
211 */
212 virtual void CopyBufferToImage(
213 const RenderHandle srcHandle, const RenderHandle dstHandle, const BufferImageCopy& bufferImageCopy) = 0;
214
215 /** Copy image to buffer
216 * @param srcHandle Source handle
217 * @param dstHandle Destination handle
218 * @param bufferImageCopy Buffer image copy
219 */
220 virtual void CopyImageToBuffer(
221 const RenderHandle srcHandle, const RenderHandle dstHandle, const BufferImageCopy& bufferImageCopy) = 0;
222
223 /** Copy image to image
224 * @param srcHandle Source handle
225 * @param dstHandle Destination handle
226 * @param imageCopy Image copy
227 */
228 virtual void CopyImageToImage(
229 const RenderHandle srcHandle, const RenderHandle dstHandle, const ImageCopy& imageCopy) = 0;
230
231 /** Blit source image to destination image.
232 * Can only be called outside of render pass.
233 * @param srcImageHandle Source handle
234 * @param dstImageHandle Destination handle
235 * @param imageBlit Image blit
236 * @param filter Filtering mode
237 */
238 virtual void BlitImage(const RenderHandle srcImageHandle, const RenderHandle dstImageHandle,
239 const ImageBlit& imageBlit, const Filter filter) = 0;
240
241 /** Update a single descriptor set with given bindings.
242 * @param handle Handle used in update
243 * @param bindingResources Binding resources
244 */
245 virtual void UpdateDescriptorSet(
246 const RenderHandle handle, const DescriptorSetLayoutBindingResources& bindingResources) = 0;
247
248 /** Bind a single descriptor set to pipeline.
249 * There can be maximum of 4 sets. I.e. the maximum set index is 3.
250 * @param set Set to bind
251 * @param handle Handle to resource
252 */
253 virtual void BindDescriptorSet(const uint32_t set, const RenderHandle handle) = 0;
254
255 /** Bind a single descriptor set to pipeline.
256 * There can be maximum of 4 sets. I.e. the maximum set index is 3.
257 * @param set Set to bind
258 * @param handle Handle to resource
259 * @param dynamicOffsets Byte offsets for dynamic descriptors
260 */
261 virtual void BindDescriptorSet(
262 const uint32_t set, const RenderHandle handle, const BASE_NS::array_view<const uint32_t> dynamicOffsets) = 0;
263
264 /** Bind multiple descriptor sets to pipeline.
265 * There can be maximum of 4 sets. I.e. the maximum set index is 3.
266 * Descriptor sets needs to be a contiguous set.
267 * @param firstSet First set index
268 * @param handles Handles to resources
269 */
270 virtual void BindDescriptorSets(const uint32_t firstSet, const BASE_NS::array_view<const RenderHandle> handles) = 0;
271
272 /** Build acceleration structures
273 * @param geometry Acceleration structure build geometry data
274 * @param triangles Geometry triangles
275 * @param aabbs Geometry aabbs
276 * @param instances Geometry instances
277 */
278 virtual void BuildAccelerationStructures(const AccelerationStructureBuildGeometryData& geometry,
279 const BASE_NS::array_view<const AccelerationStructureGeometryTrianglesData> triangles,
280 const BASE_NS::array_view<const AccelerationStructureGeometryAabbsData> aabbs,
281 const BASE_NS::array_view<const AccelerationStructureGeometryInstancesData> instances) = 0;
282
283 /** Set dynamic state viewport
284 * @param viewportDesc Viewport descriptor
285 */
286 virtual void SetDynamicStateViewport(const ViewportDesc& viewportDesc) = 0;
287
288 /** Set dynamic state scissor
289 * @param scissorDesc Scissor descriptor
290 */
291 virtual void SetDynamicStateScissor(const ScissorDesc& scissorDesc) = 0;
292
293 /** Set dynamic state line width
294 * @param lineWidth Line width
295 */
296 virtual void SetDynamicStateLineWidth(const float lineWidth) = 0;
297
298 /** Set dynamic state depth bias
299 * @param depthBiasConstantFactor Depth bias constant factor
300 * @param depthBiasClamp Depth bias clamp
301 * @param depthBiasSlopeFactor Depth bias slope factor
302 */
303 virtual void SetDynamicStateDepthBias(
304 const float depthBiasConstantFactor, const float depthBiasClamp, const float depthBiasSlopeFactor) = 0;
305
306 /** Set dynamic state blend constants
307 * @param blendConstants Blend constants
308 */
309 virtual void SetDynamicStateBlendConstants(const BASE_NS::array_view<const float> blendConstants) = 0;
310
311 /** Set dynamic state depth bounds
312 * @param minDepthBounds Min depth bounds
313 * @param maxDepthBounds Max depth bounds
314 */
315 virtual void SetDynamicStateDepthBounds(const float minDepthBounds, const float maxDepthBounds) = 0;
316
317 /** Set dynamic state stencil compare mask
318 * @param faceMask Face mask
319 * @param compareMask Compare mask
320 */
321 virtual void SetDynamicStateStencilCompareMask(const StencilFaceFlags faceMask, const uint32_t compareMask) = 0;
322
323 /** Set dynamic state stencil write mask
324 * @param faceMask Face mask
325 * @param writeMask Write mask
326 */
327 virtual void SetDynamicStateStencilWriteMask(const StencilFaceFlags faceMask, const uint32_t writeMask) = 0;
328
329 /** Set dynamic state stencil reference
330 * @param faceMask Face mask
331 * @param reference Reference
332 */
333 virtual void SetDynamicStateStencilReference(const StencilFaceFlags faceMask, const uint32_t reference) = 0;
334
335 /** Set execute backend frame position. The position where the method is ran.
336 * Often this might be the only command in the render command list, when using backend nodes.
337 * This can be set only once during render command list setup per frame.
338 */
339 virtual void SetExecuteBackendFramePosition() = 0;
340
341 protected:
342 IRenderCommandList() = default;
343 virtual ~IRenderCommandList() = default;
344
345 IRenderCommandList(const IRenderCommandList&) = delete;
346 IRenderCommandList& operator=(const IRenderCommandList&) = delete;
347 IRenderCommandList(IRenderCommandList&&) = delete;
348 IRenderCommandList& operator=(IRenderCommandList&&) = delete;
349 };
350 RENDER_END_NAMESPACE()
351
352 #endif // API_RENDER_IRENDER_COMMAND_LIST_H
353