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_DEVICE_IGPU_RESOURCE_MANAGER_H 17 #define API_RENDER_DEVICE_IGPU_RESOURCE_MANAGER_H 18 19 #include <cstdint> 20 21 #include <base/containers/array_view.h> 22 #include <base/containers/string_view.h> 23 #include <core/image/intf_image_container.h> 24 #include <render/device/gpu_resource_desc.h> 25 #include <render/device/pipeline_state_desc.h> 26 #include <render/namespace.h> 27 #include <render/resource_handle.h> 28 29 RENDER_BEGIN_NAMESPACE() 30 /** \addtogroup group_igpuresourcemanager 31 * @{ 32 */ 33 /** Backend specific image descriptor */ 34 struct BackendSpecificImageDesc {}; 35 36 /** Backend specific buffer descriptor */ 37 struct BackendSpecificBufferDesc {}; 38 39 /** Gpu resource manager. 40 * Internally synchronized. 41 * (except WaitForIdleAndDestroyGpuResources, MapBuffer, and UnmapBuffer are not internally synchronized) 42 * 43 * Handles waiting of gpu resource destruction internally. 44 * 45 * Create methods take a unique name (if named). 46 * Object is re-created if the name is already in use. 47 * Therefore do not use scoped handles if you're recreating them. 48 * Create method with a given GpuResourceHandle will replace the handle and return the same valid handle. 49 */ 50 class IGpuResourceManager { 51 public: 52 IGpuResourceManager(const IGpuResourceManager&) = delete; 53 IGpuResourceManager& operator=(const IGpuResourceManager&) = delete; 54 55 /** Get render handle reference of raw handle. 56 * @param handle Raw render handle 57 * @return Returns A render handle reference for the handle. 58 */ 59 virtual RenderHandleReference Get(const RenderHandle& handle) const = 0; 60 61 /** Create a GpuBuffer with unique buffer name. 62 * @param name Name of buffer 63 * @param desc Descriptor 64 * @return Returns A valid resource handle if the creation was successfull. 65 */ 66 virtual RenderHandleReference Create(const BASE_NS::string_view name, const GpuBufferDesc& desc) = 0; 67 68 /** Create a GpuBuffer with unique buffer name and data. 69 * @param name Name of buffer 70 * @param desc Descriptor 71 * @param data Gpu buffer data 72 * @return Returns A valid resource handle if the creation was successfull. 73 */ 74 virtual RenderHandleReference Create( 75 const BASE_NS::string_view name, const GpuBufferDesc& desc, const BASE_NS::array_view<const uint8_t> data) = 0; 76 77 /** Create an unnamed GpuBuffer with data. 78 * @param desc Descriptor 79 * @param data Gpu buffer data 80 * @return Returns A valid resource handle if the creation was successfull. 81 */ 82 virtual RenderHandleReference Create(const GpuBufferDesc& desc, const BASE_NS::array_view<const uint8_t> data) = 0; 83 84 /** Create a new GPU resource for a given GpuResourceHandle. (Old handle and name (if given) are valid) 85 * @param replacedHandle A valid handle which current resource will be destroyed and replaced with a new one. 86 * @param desc Descriptor 87 * @return Returns the same handle that was given if the resource handle was valid. 88 */ 89 virtual RenderHandleReference Create(const RenderHandleReference& replacedHandle, const GpuBufferDesc& desc) = 0; 90 91 /** Create an unnamed GpuBuffer. 92 * @param desc Descriptor 93 * @return Returns A valid resource handle if the creation was successfull. 94 */ 95 virtual RenderHandleReference Create(const GpuBufferDesc& desc) = 0; 96 97 /** Create a GpuImage with unique image name. 98 * @param name Name of image 99 * @param desc Descriptor 100 * @return Returns A valid resource handle if the creation was successfull. 101 */ 102 virtual RenderHandleReference Create(const BASE_NS::string_view name, const GpuImageDesc& desc) = 0; 103 104 /** Create a GpuImage with unique image name and data. 105 * @param name Name of image 106 * @param desc Descriptor 107 * @param data Gpu image data 108 * @return Returns A valid resource handle if the creation was successfull. 109 */ 110 virtual RenderHandleReference Create( 111 const BASE_NS::string_view name, const GpuImageDesc& desc, const BASE_NS::array_view<const uint8_t> data) = 0; 112 113 /** Create a GpuImage with unique image name and data with image copy description. 114 * @param name Name of image 115 * @param desc Descriptor 116 * @param data Gpu image data 117 * @param bufferImageCopies Array of buffer image copies 118 * @return Returns A valid resource handle if the creation was successfull. 119 */ 120 virtual RenderHandleReference Create(const BASE_NS::string_view name, const GpuImageDesc& desc, 121 const BASE_NS::array_view<const uint8_t> data, 122 const BASE_NS::array_view<const BufferImageCopy> bufferImageCopies) = 0; 123 124 /** Create a new GPU resource for a given GpuResourceHandle. (Old handle and name (if given) are valid) 125 * @param replacedHandle A valid handle which current resource will be destroyed and replaced with a new one. 126 * @param desc Descriptor 127 * @return Returns the same handle that was given if the resource handle was valid. 128 */ 129 virtual RenderHandleReference Create(const RenderHandleReference& replacedHandle, const GpuImageDesc& desc) = 0; 130 131 /** Create an unnamed GpuImage. 132 * @param desc Descriptor 133 * @return Returns A valid resource handle if the creation was successfull. 134 */ 135 virtual RenderHandleReference Create(const GpuImageDesc& desc) = 0; 136 137 /** Create an unnamed GpuImage with data. 138 * @param desc Descriptor 139 * @param data Gpu image data 140 * @return Returns A valid resource handle if the creation was successfull. 141 */ 142 virtual RenderHandleReference Create(const GpuImageDesc& desc, const BASE_NS::array_view<const uint8_t> data) = 0; 143 144 /** Create an unnamed GpuImage with data and image copy description. 145 * @param desc Descriptor 146 * @param data Gpu image data 147 * @param bufferImageCopies Array of buffer image copies 148 * @return Returns A valid resource handle if the creation was successfull. 149 */ 150 virtual RenderHandleReference Create(const GpuImageDesc& desc, const BASE_NS::array_view<const uint8_t> data, 151 const BASE_NS::array_view<const BufferImageCopy> bufferImageCopies) = 0; 152 153 /** Create GpuImage with unique image name from IImageContainer::Ptr 154 * @param name Name of image 155 * @param desc Descriptor 156 * @param image Image container 157 * @return Returns A valid resource handle if the creation was successfull. 158 */ 159 virtual RenderHandleReference Create( 160 const BASE_NS::string_view name, const GpuImageDesc& desc, CORE_NS::IImageContainer::Ptr image) = 0; 161 162 /** Create Unnamed GpuImage from IImageContainer::Ptr 163 * @param desc Descriptor 164 * @param image Image container 165 * @return Returns A valid resource handle if the creation was successfull. 166 */ 167 virtual RenderHandleReference Create(const GpuImageDesc& desc, CORE_NS::IImageContainer::Ptr image) = 0; 168 169 /** Create a GpuImage with unique image name from external texture 170 * @param name Name of image 171 * @param desc Descriptor 172 * @param backendSpecificData Image description 173 * @return Returns A valid resource handle if the creation was successfull. 174 */ 175 virtual RenderHandleReference CreateView(const BASE_NS::string_view name, const GpuImageDesc& desc, 176 const BackendSpecificImageDesc& backendSpecificData) = 0; 177 178 /** Create a GpuSampler with unique image name. 179 * @param name Name of image 180 * @param desc Descriptor 181 * @return Returns A valid resource handle if the creation was successfull. 182 */ 183 virtual RenderHandleReference Create(const BASE_NS::string_view name, const GpuSamplerDesc& desc) = 0; 184 185 /** Create a GpuSampler with replaced handle. 186 * @param replacedHandle Replaced handle 187 * @param desc Descriptor 188 * @return Returns A valid resource handle if the creation was successfull. 189 */ 190 virtual RenderHandleReference Create(const RenderHandleReference& replacedHandle, const GpuSamplerDesc& desc) = 0; 191 192 /** Create unnamed GpuSampler. 193 * @param desc Descriptor 194 * @return Returns A valid resource handle if the creation was successfull. 195 */ 196 virtual RenderHandleReference Create(const GpuSamplerDesc& desc) = 0; 197 198 /** Create unnamed GpuAccelerationStructure. 199 * @param desc Descriptor 200 * @return Returns A valid resource handle if the creation was successfull. 201 */ 202 virtual RenderHandleReference Create(const GpuAccelerationStructureDesc& desc) = 0; 203 204 /** Create uniely named GpuAccelerationStructure. If name is found, the handle is replaced 205 * @param name Unique name for the acceleration structure 206 * @param desc Descriptor 207 * @return Returns A valid resource handle if the creation was successfull. 208 */ 209 virtual RenderHandleReference Create(const BASE_NS::string_view name, const GpuAccelerationStructureDesc& desc) = 0; 210 211 /** Create GpuAccelerationStructure and replace the given handle if it's valid (the same is returned in valid case). 212 * @param replacedHandle A valid handle which current resource will be destroyed and replaced with a new one. 213 * @param desc Descriptor 214 * @return Returns A valid resource handle if the creation was successfull. 215 */ 216 virtual RenderHandleReference Create( 217 const RenderHandleReference& replacedHandle, const GpuAccelerationStructureDesc& desc) = 0; 218 219 /** Get buffer handle. (Invalid handle if not found.) 220 * @param name Name of buffer 221 * @return Returns A valid resource handle if the named resource is available. 222 */ 223 virtual RenderHandleReference GetBufferHandle(const BASE_NS::string_view name) const = 0; 224 225 /** Get image handle. (Invalid handle if not found.) 226 * @param name Name of image 227 * @return Returns A valid resource handle if the named resource is available. 228 */ 229 virtual RenderHandleReference GetImageHandle(const BASE_NS::string_view name) const = 0; 230 231 /** Get sampler handle. (Invalid handle if not found.) 232 * @param name Name of sampler 233 * @return Returns A valid resource handle if the named resource is available. 234 */ 235 virtual RenderHandleReference GetSamplerHandle(const BASE_NS::string_view name) const = 0; 236 237 /** Get acceleration structure handle. (Invalid handle if not found.) 238 * @param name Name of acceleration structure 239 * @return Returns A valid resource handle if the named resource is available. 240 */ 241 virtual RenderHandleReference GetAccelerationStructureHandle(const BASE_NS::string_view name) const = 0; 242 243 /** Get buffer descriptor 244 * @param handle Handle to resource 245 * @return Returns A GpuBufferDesc of a given GPU resource handle. 246 */ 247 virtual GpuBufferDesc GetBufferDescriptor(const RenderHandleReference& handle) const = 0; 248 249 /** Get image descriptor 250 * @param handle Handle to resource 251 * @return Returns A GpuImageDesc of a given GPU resource handle. 252 */ 253 virtual GpuImageDesc GetImageDescriptor(const RenderHandleReference& handle) const = 0; 254 255 /** Get sampler descriptor 256 * @param handle Handle to resource 257 * @return Returns A GpuSamplerDesc of a given GPU resource handle. 258 */ 259 virtual GpuSamplerDesc GetSamplerDescriptor(const RenderHandleReference& handle) const = 0; 260 261 /** Get acceleration structure descriptor 262 * @param handle Handle to resource 263 * @return Returns A GpuAccelerationStructureDesc of a given GPU resource handle. 264 */ 265 virtual GpuAccelerationStructureDesc GetAccelerationStructureDescriptor( 266 const RenderHandleReference& handle) const = 0; 267 268 /** Wait for Gpu to become idle and destroy all Gpu resources of destroyed handles. 269 * Not internally syncronized. Needs to be called from render thread where renderFrame is called. 270 * 271 * This is a hazardous method and should be called with extreme caution. 272 * In normal rendering situation RenderFrame() does the resource management automatically. 273 * This method is provided for forced destruction of Gpu resurces when RenderFrame() is not called. 274 * 275 * Do not call this method per frame. 276 */ 277 virtual void WaitForIdleAndDestroyGpuResources() = 0; 278 279 /** Map buffer memory. Always maps from the beginning of buffer. 280 * Preferrably use only for staging kind of data (e.g. fill data in another thread and then pass to staging). 281 * 1. Map once and get the pointer to memory 282 * 2. Write data to memory 283 * 3. Unmap and pass the handle to rendering/staging or whatever (with offset) 284 * The buffer needs to created with CORE_ENGINE_BUFFER_CREATION_MAP_OUTSIDE_RENDERER, 285 * CORE_ENGINE_BUFFER_CREATION_CREATE_IMMEDIATE and CORE_ENGINE_BUFFER_CREATION_DEFERRED_DESTROY and cannot be 286 * replaced with name or handle. 287 * @param handle Handle to resource 288 */ 289 virtual void* MapBufferMemory(const RenderHandleReference& handle) const = 0; 290 291 /** Unmap buffer 292 * @param handle Handle to resource 293 */ 294 virtual void UnmapBuffer(const RenderHandleReference& handle) const = 0; 295 296 /** Checks if resource is a GPU buffer */ 297 virtual bool IsGpuBuffer(const RenderHandleReference& handle) const = 0; 298 /** Checks if resource is a GPU image */ 299 virtual bool IsGpuImage(const RenderHandleReference& handle) const = 0; 300 /** Checks if resource is a GPU sampler */ 301 virtual bool IsGpuSampler(const RenderHandleReference& handle) const = 0; 302 /** Checks if resource is a GPU acceleration structure */ 303 virtual bool IsGpuAccelerationStructure(const RenderHandleReference& handle) const = 0; 304 305 /** Checks if resource is a client mappable */ 306 virtual bool IsMappableOutsideRender(const RenderHandleReference& handle) const = 0; 307 308 /** Returns supported flags for given resource handle format. */ 309 virtual FormatProperties GetFormatProperties(const RenderHandleReference& handle) const = 0; 310 /** Returns supported flags for given format. */ 311 virtual FormatProperties GetFormatProperties(const BASE_NS::Format& format) const = 0; 312 313 /** Returns GpuImageDesc based on image container's ImageDesc. 314 * Conversion helper when loading images with image loaders. 315 * Sets automatically basic values which are needed for typical image usage: 316 * imageTiling = CORE_IMAGE_TILING_OPTIMAL 317 * usageFlags |= CORE_IMAGE_USAGE_SAMPLED_BIT | CORE_IMAGE_USAGE_TRANSFER_DST_BIT 318 * memoryPropertyFlags = CORE_MEMORY_PROPERTY_DEVICE_LOCAL_BIT 319 * if mips are requested adds mips related flags 320 * @param desc ImageDesc from IImageContainer. 321 * @return GpuImageDesc GPU image desc based on input. 322 */ 323 virtual GpuImageDesc CreateGpuImageDesc(const CORE_NS::IImageContainer::ImageDesc& desc) const = 0; 324 325 /** Returns name for the resource "" if no name found. 326 * NOTE: method should not be used during run-time on hot path. 327 * @param handle Handle of the resource. 328 * @return string Name of the resource. 329 */ 330 virtual BASE_NS::string GetName(const RenderHandleReference& handle) const = 0; 331 332 protected: 333 IGpuResourceManager() = default; 334 virtual ~IGpuResourceManager() = default; 335 }; 336 337 /** IRenderNodeGpuResourceManager. 338 * Gpu resource manager interface to be used inside render nodes. 339 * Has management for per render node graph resources. 340 * All resources, created through this interface, are automatically tracked 341 * and destroyed when the render node graph which uses this render node is destroyed. 342 * 343 * Create methods take a unique name (if named). 344 * Object is re-created if the name is already in use. 345 * Therefore do not use scoped handles if you're recreating them. 346 */ 347 class IRenderNodeGpuResourceManager { 348 public: 349 /** Get render handle reference of raw handle. 350 * @param handle Raw render handle 351 * @return Returns A render handle reference for the handle. 352 */ 353 virtual RenderHandleReference Get(const RenderHandle& handle) const = 0; 354 355 /** Create a GpuBuffer. 356 * @param desc Descriptor 357 */ 358 virtual RenderHandleReference Create(const GpuBufferDesc& desc) = 0; 359 360 /** Create a GpuBuffer with unique buffer name. 361 * @param name Name used for creation 362 * @param desc Descriptor 363 */ 364 virtual RenderHandleReference Create(const BASE_NS::string_view name, const GpuBufferDesc& desc) = 0; 365 366 /** Create a GpuBuffer with replaced handle. 367 * @param handle Replaced handle 368 * @param desc Descriptor 369 */ 370 virtual RenderHandleReference Create(const RenderHandleReference& handle, const GpuBufferDesc& desc) = 0; 371 372 /** Create a GpuBuffer with unique buffer name and data. 373 * @param name Name for buffer 374 * @param desc Descriptor 375 * @param data Buffer data 376 */ 377 virtual RenderHandleReference Create( 378 const BASE_NS::string_view name, const GpuBufferDesc& desc, const BASE_NS::array_view<const uint8_t> data) = 0; 379 380 /** Create a GpuImage. 381 * @param desc Descriptor 382 */ 383 virtual RenderHandleReference Create(const GpuImageDesc& desc) = 0; 384 385 /** Create a GpuImage with unique image name. 386 * @param name Name for image 387 * @param desc Descriptor 388 */ 389 virtual RenderHandleReference Create(const BASE_NS::string_view name, const GpuImageDesc& desc) = 0; 390 391 /** Create a GpuImage with replaced handle. 392 * @param handle Replaced handle 393 * @param desc Descriptor 394 */ 395 virtual RenderHandleReference Create(const RenderHandleReference& handle, const GpuImageDesc& desc) = 0; 396 397 /** Create a GpuImage with unique image name and data. 398 * @param name Name for image 399 * @param desc Descriptor 400 * @param data Image buffer data 401 */ 402 virtual RenderHandleReference Create( 403 const BASE_NS::string_view name, const GpuImageDesc& desc, const BASE_NS::array_view<const uint8_t> data) = 0; 404 405 /** Create a GpuSampler. 406 * @param desc Descriptor 407 */ 408 virtual RenderHandleReference Create(const GpuSamplerDesc& desc) = 0; 409 410 /** Create a GpuSampler with unique sampler name. 411 * @param name Name for sampler 412 * @param desc Descriptor 413 */ 414 virtual RenderHandleReference Create(const BASE_NS::string_view name, const GpuSamplerDesc& desc) = 0; 415 416 /** Create a GpuSampler with replaced handle. 417 * @param handle Replaced handle 418 * @param desc Descriptor 419 */ 420 virtual RenderHandleReference Create(const RenderHandleReference& handle, const GpuSamplerDesc& desc) = 0; 421 422 /** Create a GpuAccelerationStructureDesc. 423 * @param desc Descriptor 424 */ 425 virtual RenderHandleReference Create(const GpuAccelerationStructureDesc& desc) = 0; 426 427 /** Create a GpuAccelerationStructureDesc with unique name. 428 * @param name Name for sampler 429 * @param desc Descriptor 430 */ 431 virtual RenderHandleReference Create(const BASE_NS::string_view name, const GpuAccelerationStructureDesc& desc) = 0; 432 433 /** Create a GpuAccelerationStructureDesc with replaced handle. 434 * @param handle Replaced handle 435 * @param desc Descriptor 436 */ 437 virtual RenderHandleReference Create( 438 const RenderHandleReference& handle, const GpuAccelerationStructureDesc& desc) = 0; 439 440 /** Get buffer handle 441 * @param name Name of buffer 442 */ 443 virtual RenderHandle GetBufferHandle(const BASE_NS::string_view name) const = 0; 444 445 /** Get image handle 446 * @param name Name of image 447 */ 448 virtual RenderHandle GetImageHandle(const BASE_NS::string_view name) const = 0; 449 450 /** Get sampler handle 451 * @param name Name of sampler 452 */ 453 virtual RenderHandle GetSamplerHandle(const BASE_NS::string_view name) const = 0; 454 455 /** Get acceleration structure handle 456 * @param name Name of acceleration structure 457 */ 458 virtual RenderHandle GetAccelerationStructureHandle(const BASE_NS::string_view name) const = 0; 459 460 /** Get buffer descriptor 461 * @param handle Handle to resource 462 */ 463 virtual GpuBufferDesc GetBufferDescriptor(const RenderHandle& handle) const = 0; 464 465 /** Get image descriptor 466 * @param handle Handle to resource 467 */ 468 virtual GpuImageDesc GetImageDescriptor(const RenderHandle& handle) const = 0; 469 470 /** Get sampler descriptor 471 * @param handle Handle to resource 472 */ 473 virtual GpuSamplerDesc GetSamplerDescriptor(const RenderHandle& handle) const = 0; 474 475 /** Get acceleration structure descriptor 476 * @param handle Handle to resource 477 */ 478 virtual GpuAccelerationStructureDesc GetAccelerationStructureDescriptor(const RenderHandle& handle) const = 0; 479 480 /** Map buffer, Only available in render nodes. 481 * Automatically advances buffered dynamic ring buffer offset. 482 * @param handle Handle to resource 483 */ 484 virtual void* MapBuffer(const RenderHandle& handle) const = 0; 485 486 /** Map buffer memory, Only available in render nodes. 487 * Always maps from the beginning of buffer. 488 * @param handle Handle to resource 489 */ 490 virtual void* MapBufferMemory(const RenderHandle& handle) const = 0; 491 492 /** Unmap buffer 493 * @param handle Handle to resource 494 */ 495 virtual void UnmapBuffer(const RenderHandle& handle) const = 0; 496 497 /** Checks validity of a handle */ 498 virtual bool IsValid(const RenderHandle& handle) const = 0; 499 /** Checks if resource is a GPU buffer */ 500 virtual bool IsGpuBuffer(const RenderHandle& handle) const = 0; 501 /** Checks if resource is a GPU image */ 502 virtual bool IsGpuImage(const RenderHandle& handle) const = 0; 503 /** Checks if resource is a GPU sampler */ 504 virtual bool IsGpuSampler(const RenderHandle& handle) const = 0; 505 506 /** Returns supported flags for given resource handle format. */ 507 virtual FormatProperties GetFormatProperties(const RenderHandle& handle) const = 0; 508 /** Returns supported flags for given format. */ 509 virtual FormatProperties GetFormatProperties(const BASE_NS::Format format) const = 0; 510 511 /** Returns name for the resource "" if no name found. 512 * NOTE: method should not be used during run-time on hot path. 513 * @param handle Handle of the resource. 514 * @return string Name of the resource. 515 */ 516 virtual BASE_NS::string GetName(const RenderHandle& handle) const = 0; 517 518 protected: 519 IRenderNodeGpuResourceManager() = default; 520 virtual ~IRenderNodeGpuResourceManager() = default; 521 }; 522 /** @} */ 523 RENDER_END_NAMESPACE() 524 525 #endif // API_RENDER_DEVICE_IGPU_RESOURCE_MANAGER_H 526