1 /*
2  * Copyright (c) 2024 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_IPIPELINE_DESCRIPTORSET_BINDER_H
17 #define API_RENDER_IPIPELINE_DESCRIPTORSET_BINDER_H
18 
19 #include <base/containers/array_view.h>
20 #include <base/containers/unique_ptr.h>
21 #include <render/device/pipeline_layout_desc.h>
22 #include <render/device/pipeline_state_desc.h>
23 #include <render/namespace.h>
24 #include <render/resource_handle.h>
25 
RENDER_BEGIN_NAMESPACE()26 RENDER_BEGIN_NAMESPACE()
27 /** @ingroup group_render_ipipelinedescriptorsetbinder */
28 /** Descriptor set binder interface class */
29 class IDescriptorSetBinder {
30 public:
31     /** Clear bind handles. This should be used to reset if the same binder is used in many frames.
32      */
33     virtual void ClearBindings() = 0;
34 
35     /** Get descriptor set handle */
36     virtual RenderHandle GetDescriptorSetHandle() const = 0;
37 
38     /** Get descriptor set layout binding resources */
39     virtual DescriptorSetLayoutBindingResources GetDescriptorSetLayoutBindingResources() const = 0;
40 
41     /** Get descriptor set layout binding validity. Checks through all bindings that they have valid handles.
42      * When the validity of the bindings might be up-to API user, this should be called.
43      */
44     virtual bool GetDescriptorSetLayoutBindingValidity() const = 0;
45 
46     /** Bind buffer. Automatically checks needed flag from pipeline layout which was used for descriptor set binder
47      * creation.
48      * @param binding Binding index
49      * @param handle Binding resource handle
50      * @param byteOffset Byte offset
51      */
52     virtual void BindBuffer(const uint32_t binding, const RenderHandle handle, const uint32_t byteOffset) = 0;
53 
54     /** Bind buffer. Automatically checks needed flag from pipeline layout which was used for descriptor set binder
55      * creation.
56      * @param binding Binding index
57      * @param handle Binding resource handle
58      * @param byteOffset Byte offset
59      * @param byteSize Byte size for binding if needed
60      */
61     virtual void BindBuffer(
62         const uint32_t binding, const RenderHandle handle, const uint32_t byteOffset, const uint32_t byteSize) = 0;
63 
64     /** Bind buffer. Automatically checks needed flag from pipeline layout which was used for descriptor set binder
65      * creation.
66      * @param binding Binding index
67      * @param resource Binding resource
68      */
69     virtual void BindBuffer(const uint32_t binding, const BindableBuffer& resource) = 0;
70 
71     /** Bind buffers to descriptor array
72      * @param binding Binding index
73      * @param resources Binding resources
74      */
75     virtual void BindBuffers(const uint32_t binding, const BASE_NS::array_view<const BindableBuffer> resources) = 0;
76 
77     /** Bind image.
78      * @param binding Binding index
79      * @param handle Binding resource handle
80      */
81     virtual void BindImage(const uint32_t binding, const RenderHandle handle) = 0;
82 
83     /** Bind image.
84      * @param binding Binding index
85      * @param handle Binding resource handle
86      * @param samplerHandle Binding resource handle for combined image sampler
87      */
88     virtual void BindImage(const uint32_t binding, const RenderHandle handle, const RenderHandle samplerHandle) = 0;
89 
90     /** Bind image.
91      * @param binding Binding index
92      * @param resource Binding resources
93      */
94     virtual void BindImage(const uint32_t binding, const BindableImage& resource) = 0;
95 
96     /** Bind images to descriptor array
97      * @param binding Binding index
98      * @param resources Binding resources
99      */
100     virtual void BindImages(const uint32_t binding, const BASE_NS::array_view<const BindableImage> resources) = 0;
101 
102     /** Bind sampler
103      * @param binding Binding index
104      * @param handle Binding resource handle
105      */
106     virtual void BindSampler(const uint32_t binding, const RenderHandle handle) = 0;
107 
108     /** Bind sampler
109      * @param binding Binding index
110      * @param resource Binding resource
111      */
112     virtual void BindSampler(const uint32_t binding, const BindableSampler& resource) = 0;
113 
114     /** Bind sampler
115      * @param binding Binding index
116      * @param handles Binding resource handles
117      */
118     virtual void BindSamplers(const uint32_t binding, const BASE_NS::array_view<const BindableSampler> resources) = 0;
119 
120     /** Bind buffer with additional descriptor flags. Automatically checks needed flag from pipeline layout which was
121      * used for descriptor set binder creation.
122      * @param binding Binding index
123      * @param resource Binding resource
124      * @param flags Additional decriptor flags
125      */
126     virtual void BindBuffer(
127         const uint32_t binding, const BindableBuffer& resource, const AdditionalDescriptorFlags flags) = 0;
128 
129     /** Bind image with additional descriptor flags.
130      * @param binding Binding index
131      * @param resource Binding resources
132      * @param flags Additional decriptor flags
133      */
134     virtual void BindImage(
135         const uint32_t binding, const BindableImage& resource, const AdditionalDescriptorFlags flags) = 0;
136 
137     /** Bind sampler with additional descriptor flags
138      * @param binding Binding index
139      * @param resource Binding resource
140      * @param flags Additional decriptor flags
141      */
142     virtual void BindSampler(
143         const uint32_t binding, const BindableSampler& resource, const AdditionalDescriptorFlags flags) = 0;
144 
145     /** Print validity. Checks through all bindings that they have valid handles.
146      */
147     virtual void PrintDescriptorSetLayoutBindingValidation() const = 0;
148 
149     struct Deleter {
150         constexpr Deleter() noexcept = default;
151         void operator()(IDescriptorSetBinder* ptr) const
152         {
153             ptr->Destroy();
154         }
155     };
156     using Ptr = BASE_NS::unique_ptr<IDescriptorSetBinder, Deleter>;
157 
158 protected:
159     IDescriptorSetBinder() = default;
160     virtual ~IDescriptorSetBinder() = default;
161     virtual void Destroy() = 0;
162 };
163 
164 /** @ingroup group_render_ipipelinedescriptorsetbinder */
165 /** Pipeline descriptor set binder interface class */
166 class IPipelineDescriptorSetBinder {
167 public:
168     IPipelineDescriptorSetBinder(const IPipelineDescriptorSetBinder&) = delete;
169     IPipelineDescriptorSetBinder& operator=(const IPipelineDescriptorSetBinder&) = delete;
170 
171     /** Clear bind handles. This should be used to reset if the same binder is used in many frames.
172      */
173     virtual void ClearBindings() = 0;
174 
175     /** Get descriptor set handle
176      * @param set Set handle
177      * @return Descriptor set handle
178      */
179     virtual RenderHandle GetDescriptorSetHandle(const uint32_t set) const = 0;
180 
181     /** Get descriptor set layout binding resources
182      * @param set Set index
183      * @return Descriptor set layout binding resources
184      */
185     virtual DescriptorSetLayoutBindingResources GetDescriptorSetLayoutBindingResources(const uint32_t set) const = 0;
186 
187     /** Get pipeline descriptor set layout binding validity. Checks through all sets and their bindings that they have
188      * valid handles. When the validity of the bindings might be up-to API user, this should be called.
189      */
190     virtual bool GetPipelineDescriptorSetLayoutBindingValidity() const = 0;
191 
192     /** Get descriptor set count
193      * @return Descriptor set count
194      */
195     virtual uint32_t GetDescriptorSetCount() const = 0;
196 
197     /** Get first set
198      * @return First descriptor set index
199      */
200     virtual uint32_t GetFirstSet() const = 0;
201 
202     /** Get array of set indices
203      * @return All descriptor set indices
204      */
205     virtual BASE_NS::array_view<const uint32_t> GetSetIndices() const = 0;
206 
207     /** Get array of descriptor set handles
208      * @return All descriptor set handles
209      */
210     virtual BASE_NS::array_view<const RenderHandle> GetDescriptorSetHandles() const = 0;
211 
212     /** Get contiguous range of descriptor set handles for binding
213      * @param beginSet Index of the first set
214      * @param count Number of sets forward from beginSet
215      * @return Specific descriptor set handles
216      */
217     virtual BASE_NS::array_view<const RenderHandle> GetDescriptorSetHandles(
218         const uint32_t beginSet, const uint32_t count) const = 0;
219 
220     /** Bind buffer
221      * @param set Set index
222      * @param binding Binding index
223      * @param resource Binding resource
224      */
225     virtual void BindBuffer(const uint32_t set, const uint32_t binding, const BindableBuffer& resource) = 0;
226 
227     /** Bind buffers to descriptor array.
228      * Input array_view counts must match. Bind is only valid if (handles.size == byteOffsets.size() ==
229      * byteSizes.size())
230      * @param set Set index
231      * @param binding Binding index
232      * @param resources Binding resources
233      */
234     virtual void BindBuffers(
235         const uint32_t set, const uint32_t binding, const BASE_NS::array_view<const BindableBuffer> resources) = 0;
236 
237     /** Bind image. (Sampled Image or Storage Image)
238      * (e.g. input attachment and color attachment)
239      * @param set Set index
240      * @param binding Binding index
241      * @param resource Binding resource
242      */
243     virtual void BindImage(const uint32_t set, const uint32_t binding, const BindableImage& resource) = 0;
244 
245     /** Bind images to descriptor array
246      * @param set Set index
247      * @param binding Binding index
248      * @param resources Binding resources
249      */
250     virtual void BindImages(
251         const uint32_t set, const uint32_t binding, const BASE_NS::array_view<const BindableImage> resources) = 0;
252 
253     /** Bind sampler
254      * @param set Set index
255      * @param binding Binding index
256      * @param resource Binding resource
257      */
258     virtual void BindSampler(const uint32_t set, const uint32_t binding, const BindableSampler& resource) = 0;
259 
260     /** Bind samplers to descriptor array
261      * @param set Set index
262      * @param binding Binding index
263      * @param resources Binding resources
264      */
265     virtual void BindSamplers(
266         const uint32_t set, const uint32_t binding, const BASE_NS::array_view<const BindableSampler> resources) = 0;
267 
268     /** Bind buffer with additional descriptor set flags
269      * @param set Set index
270      * @param binding Binding index
271      * @param resource Binding resource
272      * @param flags Additional descriptor set flags
273      */
274     virtual void BindBuffer(const uint32_t set, const uint32_t binding, const BindableBuffer& resource,
275         const AdditionalDescriptorFlags flags) = 0;
276 
277     /** Bind image with additional descriptor set flags. (Sampled Image or Storage Image)
278      * (e.g. input attachment and color attachment)
279      * @param set Set index
280      * @param binding Binding index
281      * @param resource Binding resource
282      * @param flags Additional descriptor set flags
283      */
284     virtual void BindImage(const uint32_t set, const uint32_t binding, const BindableImage& resource,
285         const AdditionalDescriptorFlags flags) = 0;
286 
287     /** Bind sampler with additional descriptor set flags
288      * @param set Set index
289      * @param binding Binding index
290      * @param resource Binding resource
291      * @param flags Additional descriptor set flags
292      */
293     virtual void BindSampler(const uint32_t set, const uint32_t binding, const BindableSampler& resource,
294         const AdditionalDescriptorFlags flags) = 0;
295 
296     /** Print validity. Checks through all set bindings that they have valid handles and prints errors.
297      */
298     virtual void PrintPipelineDescriptorSetLayoutBindingValidation() const = 0;
299 
300     struct Deleter {
301         constexpr Deleter() noexcept = default;
operatorDeleter302         void operator()(IPipelineDescriptorSetBinder* ptr) const
303         {
304             ptr->Destroy();
305         }
306     };
307     using Ptr = BASE_NS::unique_ptr<IPipelineDescriptorSetBinder, Deleter>;
308 
309 protected:
310     IPipelineDescriptorSetBinder() = default;
311     virtual ~IPipelineDescriptorSetBinder() = default;
312     virtual void Destroy() = 0;
313 };
314 RENDER_END_NAMESPACE()
315 
316 #endif // API_RENDER_IPIPELINE_DESCRIPTORSET_BINDER_H
317