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_DEVICE_GPU_RESOURCE_DESC_H
17 #define API_RENDER_DEVICE_GPU_RESOURCE_DESC_H
18 
19 #include <cstdint>
20 
21 #include <base/util/formats.h>
22 #include <render/device/pipeline_layout_desc.h>
23 #include <render/device/pipeline_state_desc.h>
24 #include <render/namespace.h>
25 
26 RENDER_BEGIN_NAMESPACE()
27 /** Image type */
28 enum ImageType {
29     /** 1D */
30     CORE_IMAGE_TYPE_1D = 0,
31     /** 2D */
32     CORE_IMAGE_TYPE_2D = 1,
33     /** 3D */
34     CORE_IMAGE_TYPE_3D = 2,
35 };
36 
37 /** Image view type */
38 enum ImageViewType {
39     /** 1D */
40     CORE_IMAGE_VIEW_TYPE_1D = 0,
41     /** 2D */
42     CORE_IMAGE_VIEW_TYPE_2D = 1,
43     /** 3D */
44     CORE_IMAGE_VIEW_TYPE_3D = 2,
45     /** Cube */
46     CORE_IMAGE_VIEW_TYPE_CUBE = 3,
47     /** 1D array */
48     CORE_IMAGE_VIEW_TYPE_1D_ARRAY = 4,
49     /** 2D array */
50     CORE_IMAGE_VIEW_TYPE_2D_ARRAY = 5,
51     /** Cube array */
52     CORE_IMAGE_VIEW_TYPE_CUBE_ARRAY = 6,
53 };
54 
55 /** Image tiling */
56 enum ImageTiling {
57     /** Optimal */
58     CORE_IMAGE_TILING_OPTIMAL = 0,
59     /** Linear */
60     CORE_IMAGE_TILING_LINEAR = 1,
61 };
62 
63 /** Image usage flag bits */
64 enum ImageUsageFlagBits {
65     /** Transfer source bit */
66     CORE_IMAGE_USAGE_TRANSFER_SRC_BIT = 0x00000001,
67     /** Transfer destination bit */
68     CORE_IMAGE_USAGE_TRANSFER_DST_BIT = 0x00000002,
69     /** Sampled bit */
70     CORE_IMAGE_USAGE_SAMPLED_BIT = 0x00000004,
71     /** Storage bit */
72     CORE_IMAGE_USAGE_STORAGE_BIT = 0x00000008,
73     /** Color attachment bit */
74     CORE_IMAGE_USAGE_COLOR_ATTACHMENT_BIT = 0x00000010,
75     /** Depth stencil attachment bit */
76     CORE_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT = 0x00000020,
77     /** Transient attachment bit */
78     CORE_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT = 0x00000040,
79     /** Input attachment bit */
80     CORE_IMAGE_USAGE_INPUT_ATTACHMENT_BIT = 0x00000080,
81     /** Fragment shading rate attachment bit */
82     CORE_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT = 0x00000100,
83 };
84 /** Container for image usage flag bits */
85 using ImageUsageFlags = uint32_t;
86 
87 /** Engine image creation flag bits */
88 enum EngineImageCreationFlagBits {
89     /** Dynamic barriers */
90     CORE_ENGINE_IMAGE_CREATION_DYNAMIC_BARRIERS = 0x00000001,
91     /** Reset state on frame borders */
92     CORE_ENGINE_IMAGE_CREATION_RESET_STATE_ON_FRAME_BORDERS = 0x00000002,
93     /** Generate mips */
94     CORE_ENGINE_IMAGE_CREATION_GENERATE_MIPS = 0x00000004,
95     /** Scale image when created from data */
96     CORE_ENGINE_IMAGE_CREATION_SCALE = 0x00000008,
97     /** Destroy is deferred to the end of the current frame */
98     CORE_ENGINE_IMAGE_CREATION_DEFERRED_DESTROY = 0x00000010,
99 };
100 /** Container for engine image creation flag bits */
101 using EngineImageCreationFlags = uint32_t;
102 
103 /** Engine sampler creation flag bits */
104 enum EngineSamplerCreationFlagBits {
105     /** Create ycbcr sampler */
106     CORE_ENGINE_SAMPLER_CREATION_YCBCR = 0x00000001,
107 };
108 /** Container for engine sampler creation flag bits */
109 using EngineSamplerCreationFlags = uint32_t;
110 
111 /** Image create flag bits */
112 enum ImageCreateFlagBits {
113     /** Cube compatible bit */
114     CORE_IMAGE_CREATE_CUBE_COMPATIBLE_BIT = 0x00000010,
115     /** 2D array compatible bit */
116     CORE_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT = 0x00000020,
117 };
118 /** Container for image create flag bits */
119 using ImageCreateFlags = uint32_t;
120 
121 /** Engine buffer creation flag bits */
122 enum EngineBufferCreationFlagBits {
123     /** Dynamic barriers */
124     CORE_ENGINE_BUFFER_CREATION_DYNAMIC_BARRIERS = 0x00000001,
125     /** Dynamic ring buffer */
126     CORE_ENGINE_BUFFER_CREATION_DYNAMIC_RING_BUFFER = 0x00000002,
127     /** Single shot staging */
128     CORE_ENGINE_BUFFER_CREATION_SINGLE_SHOT_STAGING = 0x00000004,
129     /** Hint to enable memory optimizations if possible (e.g. on integrated might use direct copies without staging) */
130     CORE_ENGINE_BUFFER_CREATION_ENABLE_MEMORY_OPTIMIZATIONS = 0x00000008,
131     /** Immediately created GPU resource */
132     CORE_ENGINE_BUFFER_CREATION_CREATE_IMMEDIATE = 0x00000010,
133     /** Destroy is deferred to the end of the current frame */
134     CORE_ENGINE_BUFFER_CREATION_DEFERRED_DESTROY = 0x00000020,
135     /** Buffer is mappable outside renderer (i.e. outside render nodes). Slower, do not used if not necessary. */
136     CORE_ENGINE_BUFFER_CREATION_MAP_OUTSIDE_RENDERER = 0x00000040,
137 };
138 /** Container for engine buffer creation flag bits */
139 using EngineBufferCreationFlags = uint32_t;
140 
141 /** Buffer usage flag bits */
142 enum BufferUsageFlagBits {
143     /** Transfer source bit */
144     CORE_BUFFER_USAGE_TRANSFER_SRC_BIT = 0x00000001,
145     /** Transfer destination bit */
146     CORE_BUFFER_USAGE_TRANSFER_DST_BIT = 0x00000002,
147     /** Uniform texel buffer bit */
148     CORE_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT = 0x00000004,
149     /** Storage texel buffer bit */
150     CORE_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT = 0x00000008,
151     /** Uniform buffer bit */
152     CORE_BUFFER_USAGE_UNIFORM_BUFFER_BIT = 0x00000010,
153     /** Storage buffer bit */
154     CORE_BUFFER_USAGE_STORAGE_BUFFER_BIT = 0x00000020,
155     /** Index buffer bit */
156     CORE_BUFFER_USAGE_INDEX_BUFFER_BIT = 0x00000040,
157     /** Vertex buffer bit */
158     CORE_BUFFER_USAGE_VERTEX_BUFFER_BIT = 0x00000080,
159     /** Indirect buffer bit */
160     CORE_BUFFER_USAGE_INDIRECT_BUFFER_BIT = 0x00000100,
161     /** Acceleration structure binding table bit */
162     CORE_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT = 0x00000400,
163     /** Shader device address bit */
164     CORE_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT = 0x00020000,
165     /** Acceleration structure build input read only bit */
166     CORE_BUFFER_USAGE_ACCELERATION_STRUCTURE_BUILD_INPUT_READ_ONLY_BIT = 0x00080000,
167     /** Acceleration structure storage bit */
168     CORE_BUFFER_USAGE_ACCELERATION_STRUCTURE_STORAGE_BIT = 0x00100000,
169 };
170 /** Container for buffer usage flag bits */
171 using BufferUsageFlags = uint32_t;
172 
173 /** Filter */
174 enum Filter {
175     /** Nearest */
176     CORE_FILTER_NEAREST = 0,
177     /** Linear */
178     CORE_FILTER_LINEAR = 1,
179 };
180 
181 /** Sampler address mode */
182 enum SamplerAddressMode {
183     /** Repeat */
184     CORE_SAMPLER_ADDRESS_MODE_REPEAT = 0,
185     /** Mirrored repeat */
186     CORE_SAMPLER_ADDRESS_MODE_MIRRORED_REPEAT = 1,
187     /** Clamp to edge */
188     CORE_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE = 2,
189     /** Clamp to border */
190     CORE_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER = 3,
191     /** Mirror clamp to edge */
192     CORE_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE = 4,
193 };
194 
195 /** Border color */
196 enum BorderColor {
197     /** Float transparent black */
198     CORE_BORDER_COLOR_FLOAT_TRANSPARENT_BLACK = 0,
199     /** Int transparent black */
200     CORE_BORDER_COLOR_INT_TRANSPARENT_BLACK = 1,
201     /** Float opaque black */
202     CORE_BORDER_COLOR_FLOAT_OPAQUE_BLACK = 2,
203     /** Int opaque black */
204     CORE_BORDER_COLOR_INT_OPAQUE_BLACK = 3,
205     /** Float opaque white */
206     CORE_BORDER_COLOR_FLOAT_OPAQUE_WHITE = 4,
207     /** Int opaque white */
208     CORE_BORDER_COLOR_INT_OPAQUE_WHITE = 5,
209 };
210 
211 /** Sample count flag bits */
212 enum SampleCountFlagBits : uint32_t {
213     /** 1 bit */
214     CORE_SAMPLE_COUNT_1_BIT = 0x00000001,
215     /** 2 bit */
216     CORE_SAMPLE_COUNT_2_BIT = 0x00000002,
217     /** 4 bit */
218     CORE_SAMPLE_COUNT_4_BIT = 0x00000004,
219     /** 8 bit */
220     CORE_SAMPLE_COUNT_8_BIT = 0x00000008,
221     /** 16 bit */
222     CORE_SAMPLE_COUNT_16_BIT = 0x00000010,
223     /** 32 bit */
224     CORE_SAMPLE_COUNT_32_BIT = 0x00000020,
225     /** 64 bit */
226     CORE_SAMPLE_COUNT_64_BIT = 0x00000040,
227 };
228 /** Sample count flags */
229 using SampleCountFlags = uint32_t;
230 
231 /** Component swizzle */
232 enum ComponentSwizzle : uint32_t {
233     /** Swizzle identity */
234     CORE_COMPONENT_SWIZZLE_IDENTITY = 0,
235     /** Swizzle zero */
236     CORE_COMPONENT_SWIZZLE_ZERO = 1,
237     /** Swizzle one */
238     CORE_COMPONENT_SWIZZLE_ONE = 2,
239     /** Swizzle red */
240     CORE_COMPONENT_SWIZZLE_R = 3,
241     /** Swizzle green */
242     CORE_COMPONENT_SWIZZLE_G = 4,
243     /** Swizzle blue */
244     CORE_COMPONENT_SWIZZLE_B = 5,
245     /** Swizzle alpha */
246     CORE_COMPONENT_SWIZZLE_A = 6,
247 };
248 
249 /** Acceleration structure create flag bits */
250 enum AccelerationStructureCreateFlagBits {};
251 /** Container for acceleration create flag bits */
252 using AccelerationStructureCreateFlags = uint32_t;
253 
254 /** Engine acceleration structure creation flag bits */
255 enum EngineAccelerationStructureCreationFlagBits {};
256 /** Container for engine acceleration structure creation flag bits */
257 using EngineAccelerationStructureCreationFlags = uint32_t;
258 
259 /**
260  * UBO:
261  * - BufferUsageFlags:
262  * CORE_BUFFER_USAGE_UNIFORM_BUFFER_BIT
263  * - EngineBufferCreationFlags
264  * CORE_ENGINE_BUFFER_CREATION_DYNAMIC_RING_BUFFER
265  * NOTE: automatically buffered with map-method (ring buffer hidden inside) (the binding offset is updated with
266  * UpdateDescriptorSets)
267  * - MemoryPropertyFlags
268  * CORE_MEMORY_PROPERTY_HOST_VISIBLE_BIT | CORE_MEMORY_PROPERTY_HOST_COHERENT_BIT
269  *
270  * VBO:
271  * - BufferUsageFlags:
272  * CORE_BUFFER_USAGE_VERTEX_BUFFER_BIT | CORE_BUFFER_USAGE_TRANSFER_DST_BIT
273  * - MemoryPropertyFlags:
274  * CORE_MEMORY_PROPERTY_DEVICE_LOCAL_BIT
275  *
276  * SSBO:
277  * - BufferUsageFlags:
278  * CORE_BUFFER_USAGE_STORAGE_BUFFER_BIT
279  * MemoryPropertyFlags
280  * CORE_MEMORY_PROPERTY_DEVICE_LOCAL_BIT
281  *
282  * EngineBufferCreationFlags:
283  *
284  * CORE_ENGINE_BUFFER_CREATION_DYNAMIC_BARRIERS, set this flag only for dynamic state changing data (e.g. SSBOs etc)
285  * This flag is not needed for regular vertex buffers. Staging handles the copies and barriers automatically.
286  *
287  * CORE_ENGINE_BUFFER_CREATION_DYNAMIC_RING_BUFFER, set this for dynamic buffer mapping
288  * Dynamic ring buffer updates offsets automatically when buffer is mapped and descriptor set is updated.
289  *
290  * CORE_ENGINE_BUFFER_CREATION_SINGLE_SHOT_STAGING, tells memory allocator that this resource can be forget after this
291  * frame Engine internally flags staging buffers with this flag, Do not use if you cannot guarentee that the gpu buffer
292  * is destroyed immediately
293  *
294  * CORE_ENGINE_BUFFER_CREATION_ENABLE_MEMORY_OPTIMIZATIONS, can enable some memory optimizations.
295  * E.g. on some platforms all memory can be host visible (except lazy allocations).
296  * With this flag you can make sure that your CORE_BUFFER_USAGE_TRANSFER_DST_BIT buffer
297  * Might by-pass staging buffers and enable direct cpu->gpu memcpy on some platforms and use less memory.
298  *
299  * CORE_ENGINE_BUFFER_CREATION_CREATE_IMMEDIATE, creates the resource immediately/instantly so it can be mapped.
300  * Should only be used when instant mapping is required.
301  *
302  * CORE_ENGINE_BUFFER_CREATION_DEFERRED_DESTROY, the resource is destroyed at the end of the frame
303  * after Destroy has been called to the GpuResourceHandle.
304  * Should only be used when object lifetime cannot be guaranteed in some scoped section.
305  * Might increase memory consumption.
306  *
307  * CORE_ENGINE_BUFFER_CREATION_MAP_OUTSIDE_RENDERER, the resource is mappable outside
308  * renderer. Normal mapping is suggested to be done within render nodes or with default staging memory copy.
309  *
310  */
311 /** \addtogroup group_gpuresourcedesc
312  *  @{
313  */
314 /** GPU buffer descriptor */
315 struct GpuBufferDesc {
316     /** Usage flags */
317     BufferUsageFlags usageFlags { 0 };
318     /** Memory property flags */
319     MemoryPropertyFlags memoryPropertyFlags { 0 };
320     /** Engine creation flags */
321     EngineBufferCreationFlags engineCreationFlags { 0 };
322     /** Byte size */
323     uint32_t byteSize { 0 };
324     /** View format (for texel buffer view) */
325     BASE_NS::Format format { BASE_NS::Format::BASE_FORMAT_UNDEFINED };
326 };
327 
328 /** RGBA component mapping */
329 struct ComponentMapping {
330     /* Swizzle for red */
331     ComponentSwizzle r { CORE_COMPONENT_SWIZZLE_IDENTITY };
332     /* Swizzle for green */
333     ComponentSwizzle g { CORE_COMPONENT_SWIZZLE_IDENTITY };
334     /* Swizzle for blue */
335     ComponentSwizzle b { CORE_COMPONENT_SWIZZLE_IDENTITY };
336     /* Swizzle for alpha */
337     ComponentSwizzle a { CORE_COMPONENT_SWIZZLE_IDENTITY };
338 };
339 
340 /**
341  * EngineImageCreationFlags:
342  *
343  * CORE_ENGINE_IMAGE_CREATION_DYNAMIC_BARRIERS, set this flag only for dynamic state changing data (e.g. render targets)
344  * default value (zero, 0), is usually always the correct one (e.g. loaded textures, sampled textures)
345  *
346  * CORE_ENGINE_IMAGE_CREATION_SCALE, set this if a simple image scaling is needed when staging the
347  * Images to the GPU. Linear single pass scaling is used.
348  * Final image size is taken from the GpuImageDesc,
349  * the input size is taken from the IImageContainer or BufferImageCopies which are given to Create -method.
350  */
351 /** \addtogroup group_gpuresourcedesc
352  *  @{
353  */
354 /** GPU image descriptor */
355 struct GpuImageDesc {
356     /** Image type */
357     ImageType imageType { ImageType::CORE_IMAGE_TYPE_2D };
358     /** Image view type */
359     ImageViewType imageViewType { ImageViewType::CORE_IMAGE_VIEW_TYPE_2D };
360     /** Format */
361     BASE_NS::Format format { BASE_NS::Format::BASE_FORMAT_UNDEFINED };
362     /** Image tiling */
363     ImageTiling imageTiling { ImageTiling::CORE_IMAGE_TILING_OPTIMAL };
364     /** Usage tiling */
365     ImageUsageFlags usageFlags { 0 };
366     /** Memory property flags */
367     MemoryPropertyFlags memoryPropertyFlags { 0 };
368 
369     /** Create flags */
370     ImageCreateFlags createFlags { 0 };
371 
372     /** Engine creation flags */
373     EngineImageCreationFlags engineCreationFlags { 0 };
374 
375     /** Width */
376     uint32_t width { 1u };
377     /** Height */
378     uint32_t height { 1u };
379     /** Depth */
380     uint32_t depth { 1u };
381 
382     /** Mip count */
383     uint32_t mipCount { 1u };
384     /** Layer count */
385     uint32_t layerCount { 1u };
386 
387     /** Sample count flags */
388     SampleCountFlags sampleCountFlags { SampleCountFlagBits::CORE_SAMPLE_COUNT_1_BIT };
389 
390     /** RGBA component mapping */
391     ComponentMapping componentMapping;
392 };
393 
394 /** GPU sampler descriptor */
395 struct GpuSamplerDesc {
396     /** Magnification filter */
397     Filter magFilter { Filter::CORE_FILTER_NEAREST };
398     /** Minification filter */
399     Filter minFilter { Filter::CORE_FILTER_NEAREST };
400     /** Mip map filter mode */
401     Filter mipMapMode { Filter::CORE_FILTER_NEAREST };
402 
403     /** Address mode U */
404     SamplerAddressMode addressModeU { SamplerAddressMode::CORE_SAMPLER_ADDRESS_MODE_REPEAT };
405     /** Address mode V */
406     SamplerAddressMode addressModeV { SamplerAddressMode::CORE_SAMPLER_ADDRESS_MODE_REPEAT };
407     /** Address mode W */
408     SamplerAddressMode addressModeW { SamplerAddressMode::CORE_SAMPLER_ADDRESS_MODE_REPEAT };
409 
410     /** Engine creation flags */
411     EngineSamplerCreationFlags engineCreationFlags { 0 };
412 
413     /** Mip lod bias */
414     float mipLodBias { 0.0f };
415 
416     /** Enable anisotropy */
417     bool enableAnisotropy { false };
418     /** Max anisotropy */
419     float maxAnisotropy { 1.0f };
420 
421     /** Enable compare operation */
422     bool enableCompareOp { false };
423     /** Compare operation */
424     CompareOp compareOp { CompareOp::CORE_COMPARE_OP_NEVER };
425 
426     /** Minimum lod */
427     float minLod { 0.0f };
428     /** Maximum lod */
429     float maxLod { 0.0f };
430 
431     /** Border color */
432     BorderColor borderColor { BorderColor::CORE_BORDER_COLOR_FLOAT_OPAQUE_BLACK };
433 
434     /** Enable unnormalized coordinates */
435     bool enableUnnormalizedCoordinates { false };
436 };
437 
438 /** GPU acceleration structure descriptor */
439 struct GpuAccelerationStructureDesc {
440     /* Acceleration structure type */
441     AccelerationStructureType accelerationStructureType {
442         AccelerationStructureType::CORE_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL
443     };
444     /* Buffer desc which holds the buffer info */
445     GpuBufferDesc bufferDesc;
446 };
447 /** @} */
448 RENDER_END_NAMESPACE()
449 
450 #endif // API_RENDER_DEVICE_GPU_RESOURCE_DESC_H
451