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