dali/graphics-api/graphics-controller.h

   1 #ifndef DALI_GRAPHICS_CONTROLLER_H
   2 #define DALI_GRAPHICS_CONTROLLER_H
   3
   4 /*
   5  * Copyright (c) 2024 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  */
  20
  21 // EXTERNAL INCLUDES
  22 #include <dali/integration-api/graphics-config.h>
  23 #include <dali/public-api/common/vector-wrapper.h>
  24 #include <memory>
  25
  26 // INTERNAL INCLUDES
  27 #include "graphics-buffer-create-info.h"
  28 #include "graphics-command-buffer-create-info.h"
  29 #include "graphics-framebuffer-create-info.h"
  30 #include "graphics-memory.h"
  31 #include "graphics-pipeline-create-info.h"
  32 #include "graphics-program-create-info.h"
  33 #include "graphics-reflection.h"
  34 #include "graphics-render-pass-create-info.h"
  35 #include "graphics-render-target-create-info.h"
  36 #include "graphics-sampler-create-info.h"
  37 #include "graphics-shader-create-info.h"
  38 #include "graphics-sync-object-create-info.h"
  39 #include "graphics-texture-create-info.h"
  40 #include "graphics-texture-upload-helper.h"
  41
  42 namespace Dali
  43 {
  44 namespace Integration
  45 {
  46 class GlAbstraction;
  47 } // namespace Integration
  48
  49 namespace Graphics
  50 {
  51 class Command;
  52 class CommandBuffer;
  53 class Buffer;
  54 class Framebuffer;
  55 class Memory;
  56 class Pipeline;
  57 class RenderPass;
  58 class RenderTarget;
  59 class Sampler;
  60 class Shader;
  61 class SyncObject;
  62 class Texture;
  63
  64 /**
  65  * @brief Controller class controls render loop
  66  *
  67  * Controller class is responsible for executing render calls
  68  * and controlling pipeline state.
  69  */
  70 class Controller
  71 {
  72 public:
  73   /**
  74    * Get graphics configuration for info about the graphics subsystem.
  75    */
  76   virtual Integration::GraphicsConfig& GetGraphicsConfig() = 0;
  77
  78   /**
  79    * @brief Destroys controller
  80    */
  81   virtual ~Controller() = default;
  82
  83   /**
  84    * @brief Submits array of command buffers
  85    *
  86    * Submits command buffers to the graphics pipeline. Submitted commands
  87    * may be executed instantly or postponed.
  88    *
  89    * @param[in] submitInfo Valid SubmitInfo structure
  90    */
  91   virtual void SubmitCommandBuffers(const SubmitInfo& submitInfo) = 0;
  92
  93   /**
  94    * @brief Presents render target
  95    * @param renderTarget render target to present
  96    */
  97   virtual void PresentRenderTarget(RenderTarget* renderTarget) = 0;
  98
  99   /**
 100    * @brief Waits until the GPU is idle
 101    */
 102   virtual void WaitIdle() = 0;
 103
 104   /**
 105    * @brief Lifecycle pause event
 106    */
 107   virtual void Pause() = 0;
 108
 109   /**
 110    * @brief Lifecycle resume event
 111    */
 112   virtual void Resume() = 0;
 113
 114   /**
 115    * @brief Lifecycle shutdown event
 116    */
 117   virtual void Shutdown() = 0;
 118
 119   /**
 120    * @brief Lifecycle destroy event
 121    */
 122   virtual void Destroy() = 0;
 123
 124   /**
 125    * @brief Executes batch update of textures
 126    *
 127    * This function may perform full or partial update of many textures.
 128    * The data source may come from:
 129    * - CPU memory (client side)
 130    * - GPU memory (another Texture or Buffer)
 131    *
 132    * UpdateTextures() is the only way to update unmappable Texture objects.
 133    * It is recommended to batch updates as it may help with optimizing
 134    * memory transfers based on dependencies.
 135    *
 136    */
 137   virtual void UpdateTextures(const std::vector<TextureUpdateInfo>&       updateInfoList,
 138                               const std::vector<TextureUpdateSourceInfo>& sourceList) = 0;
 139
 140   /**
 141    * Auto generates mipmaps for the texture
 142    * @param[in] texture The texture
 143    */
 144   virtual void GenerateTextureMipmaps(const Texture& texture) = 0;
 145
 146   /**
 147    * @brief Enables depth/stencil buffer
 148    *
 149    * @param[in] enableDepth True to enable depth
 150    * @param[in] enableStencil True to enable stencil
 151    * @return True on success
 152    */
 153   virtual bool EnableDepthStencilBuffer(bool enableDepth, bool enableStencil) = 0;
 154
 155   /**
 156    * @brief Runs garbage collector (if supported)
 157    *
 158    * @param[in] numberOfDiscardedRenderers number of discarded renderers
 159    */
 160   virtual void RunGarbageCollector(size_t numberOfDiscardedRenderers) = 0;
 161
 162   /**
 163    * @brief Discards unused resources
 164    */
 165   virtual void DiscardUnusedResources() = 0;
 166
 167   /**
 168    * @brief Tests whether discard queue is empty
 169    *
 170    * @return True if empty
 171    */
 172   virtual bool IsDiscardQueueEmpty() = 0;
 173
 174   /**
 175    * @brief Test if the graphics subsystem has resumed & should force a draw
 176    *
 177    * @return true if the graphics subsystem requires a re-draw
 178    */
 179   virtual bool IsDrawOnResumeRequired() = 0;
 180
 181   /**
 182    * @brief Creates new Buffer object
 183    *
 184    * The Buffer object is created with underlying memory. The Buffer
 185    * specification is immutable. Based on the BufferCreateInfo::usage,
 186    * the memory may be client-side mappable or not.
 187    *
 188    * The old buffer may be passed as BufferCreateInfo::oldbuffer, however,
 189    * it's up to the implementation whether the object will be reused or
 190    * discarded and replaced by the new one.
 191    *
 192    * @param[in] bufferCreateInfo The valid BufferCreateInfo structure
 193    * @param[in] oldBuffer The valid pointer to the old object or nullptr. The object will be reused or destroyed.
 194    * @return pointer to the Buffer object
 195    */
 196   virtual UniquePtr<Buffer> CreateBuffer(const BufferCreateInfo& bufferCreateInfo, UniquePtr<Buffer>&& oldBuffer) = 0;
 197
 198   /**
 199    * @brief Creates new CommandBuffer object
 200    *
 201    * @param[in] bufferCreateInfo The valid BufferCreateInfo structure
 202    * @param[in] oldCommandBuffer The valid pointer to the old object or nullptr. The object will be reused or destroyed.
 203    * @return pointer to the CommandBuffer object
 204    */
 205   virtual UniquePtr<CommandBuffer> CreateCommandBuffer(const CommandBufferCreateInfo& commandBufferCreateInfo, UniquePtr<CommandBuffer>&& oldCommandBuffer) = 0;
 206
 207   /**
 208    * @brief Creates new RenderPass object
 209    *
 210    * @param[in] renderPassCreateInfo The valid RenderPassCreateInfo structure
 211    * @param[in] oldRenderPass The valid pointer to the old object or nullptr. The object will be reused or destroyed.
 212    * @return pointer to the RenderPass object
 213    */
 214   virtual UniquePtr<RenderPass> CreateRenderPass(const RenderPassCreateInfo& renderPassCreateInfo, UniquePtr<RenderPass>&& oldRenderPass) = 0;
 215
 216   /**
 217    * @brief Creates new Texture object
 218    *
 219    * @param[in] textureCreateInfo The valid TextureCreateInfo structure
 220    * @param[in] oldTexture The valid pointer to the old object or nullptr. The object will be reused or destroyed.
 221    * @return pointer to the TextureCreateInfo object
 222    */
 223   virtual UniquePtr<Texture> CreateTexture(const TextureCreateInfo& textureCreateInfo, UniquePtr<Texture>&& oldTexture) = 0;
 224
 225   /**
 226    * @brief Creates new Framebuffer object
 227    *
 228    * @param[in] framebufferCreateInfo The valid FramebufferCreateInfo structure
 229    * @param[in] oldFramebuffer The valid pointer to the old object or nullptr. The object will be reused or destroyed.
 230    * @return pointer to the Framebuffer object
 231    */
 232   virtual UniquePtr<Framebuffer> CreateFramebuffer(const FramebufferCreateInfo& framebufferCreateInfo, UniquePtr<Framebuffer>&& oldFramebuffer) = 0;
 233
 234   /**
 235    * @brief Creates new Pipeline object
 236    *
 237    * @param[in] pipelineCreateInfo The valid PipelineCreateInfo structure
 238    * @param[in] oldPipeline The valid pointer to the old object or nullptr. The object will be reused or destroyed.
 239    * @return pointer to the Pipeline object
 240    */
 241   virtual UniquePtr<Pipeline> CreatePipeline(const PipelineCreateInfo& pipelineCreateInfo, UniquePtr<Pipeline>&& oldPipeline) = 0;
 242
 243   /**
 244    * @brief Creates new Program object
 245    *
 246    * @param[in] ProgramCreateInfo The valid ProgramCreateInfo structure
 247    * @param[in] oldProgram The valid pointer to the old object or nullptr. The object will be reused or destroyed.
 248    * @return pointer to the Program object
 249    */
 250   virtual UniquePtr<Program> CreateProgram(const ProgramCreateInfo& programCreateInfo, UniquePtr<Program>&& oldProgram) = 0;
 251
 252   /**
 253    * @brief Creates new Shader object
 254    *
 255    * @param[in] shaderCreateInfo The valid ShaderCreateInfo structure
 256    * @param[in] oldShader The valid pointer to the old object or nullptr. The object will be reused or destroyed.
 257    * @return pointer to the Shader object
 258    */
 259   virtual UniquePtr<Shader> CreateShader(const ShaderCreateInfo& shaderCreateInfo, UniquePtr<Shader>&& oldShader) = 0;
 260
 261   /**
 262    * @brief Creates new Sampler object
 263    *
 264    * @param[in] samplerCreateInfo The valid SamplerCreateInfo structure
 265    * @param[in] oldSampler The valid pointer to the old object or nullptr. The object will be reused or destroyed.
 266    * @return pointer to the Sampler object
 267    */
 268   virtual UniquePtr<Sampler> CreateSampler(const SamplerCreateInfo& samplerCreateInfo, UniquePtr<Sampler>&& oldSampler) = 0;
 269
 270   /**
 271    * @brief Creates new RenderTarget object
 272    *
 273    * @param[in] renderTargetCreateInfo The valid RenderTargetCreateInfo structure
 274    * @param[in] oldRenderTarget The valid pointer to the old object or nullptr. The object will be reused or destroyed.
 275    * @return pointer to the RenderTarget object
 276    */
 277   virtual UniquePtr<RenderTarget> CreateRenderTarget(const RenderTargetCreateInfo& renderTargetCreateInfo, UniquePtr<RenderTarget>&& oldRenderTarget) = 0;
 278
 279   /**
 280    * Create a synchronisation object.
 281    *
 282    * @return A pointer to an opaque sync object
 283    * @param[in] syncObjectCreateInfo The valid SyncObjectCreateInfo structure
 284    * @param[in] oldSyncObject The valid pointer to the old object or nullptr. The object will be reused or destroyed.
 285    */
 286   virtual UniquePtr<SyncObject> CreateSyncObject(const SyncObjectCreateInfo& syncObjectCreateInfo,
 287                                                  UniquePtr<SyncObject>&&     oldSyncObject) = 0;
 288
 289   /**
 290    * @brief Maps memory associated with Buffer object
 291    *
 292    * @param[in] mapInfo Filled details of mapped resource
 293    * @return Returns pointer to Memory object or nullptr on error
 294    */
 295   virtual UniquePtr<Memory> MapBufferRange(const MapBufferInfo& mapInfo) = 0;
 296
 297   /**
 298    * @brief Maps memory associated with the texture.
 299    *
 300    * Only Texture objects that are backed with linear memory (staging memory) can be mapped.
 301    * Example:
 302    * 1) GLES implementation may create PBO object as staging memory and couple it
 303    * with the texture. Texture can be mapped and the memory can be read/write on demand.
 304    *
 305    * 2) Vulkan implementation may allocate DeviceMemory and use linear layout.
 306    *
 307    * @param[in] mapInfo Filled details of mapped resource
 308    *
 309    * @return Valid Memory object or nullptr on error
 310    */
 311   virtual UniquePtr<Memory> MapTextureRange(const MapTextureInfo& mapInfo) = 0;
 312
 313   /**
 314    * @brief Unmaps memory and discards Memory object
 315    *
 316    * This function automatically removes lock if Memory has been
 317    * previously locked.
 318    *
 319    * @param[in] memory Valid and previously mapped Memory object
 320    */
 321   virtual void UnmapMemory(UniquePtr<Memory> memory) = 0;
 322
 323   /**
 324    * @brief Returns memory requirements of the Texture object.
 325    *
 326    * Call this function whenever it's necessary to know how much memory
 327    * is needed to store all the texture data and what memory alignment
 328    * the data should follow.
 329    *
 330    * @return Returns memory requirements of Texture
 331    */
 332   virtual MemoryRequirements GetTextureMemoryRequirements(Texture& texture) const = 0;
 333
 334   /**
 335    * @brief Returns memory requirements of the Buffer object.
 336    *
 337    * Call this function whenever it's necessary to know how much memory
 338    * is needed to store all the buffer data and what memory alignment
 339    * the data should follow.
 340    *
 341    * @return Returns memory requirements of Buffer
 342    */
 343   virtual MemoryRequirements GetBufferMemoryRequirements(Buffer& buffer) const = 0;
 344
 345   /**
 346    * @brief Returns specification of the Texture object
 347    *
 348    * Function obtains specification of the Texture object. It may retrieve
 349    * implementation dependent details like ie. whether the texture is
 350    * emulated (for example, RGB emulated on RGBA), compressed etc.
 351    *
 352    * @return Returns the TextureProperties object
 353    */
 354   virtual TextureProperties GetTextureProperties(const Texture& texture) = 0;
 355
 356   /**
 357    * @brief Returns the reflection of the given program
 358    *
 359    * @param[in] program The program
 360    * @return The reflection of the program
 361    */
 362   virtual const Reflection& GetProgramReflection(const Program& program) = 0;
 363
 364   /**
 365    * @brief Tests whether two Pipelines are the same.
 366    *
 367    * On the higher level, this function may help wit creating pipeline cache.
 368    *
 369    * @return true if pipeline objects match
 370    */
 371   virtual bool PipelineEquals(const Pipeline& pipeline0, const Pipeline& pipeline1) const = 0;
 372
 373   /**
 374    * @brief Retrieves program parameters
 375    *
 376    * This function can be used to retrieve data from internal implementation
 377    *
 378    * @param[in] program Valid program object
 379    * @param[in] parameterId Integer parameter id
 380    * @param[out] outData Pointer to output memory
 381    * @return True on success
 382    */
 383   virtual bool GetProgramParameter(Graphics::Program& program, uint32_t parameterId, void* outData) = 0;
 384
 385 public: // ResourceId relative API.
 386   /**
 387    * @brief Create Graphics::Texture as resourceId.
 388    * The ownership of Graphics::Texture will be hold on this controller.
 389    * @note If some Graphics::Texture already created before, assert.
 390    * @post DiscardTextureFromResourceId() or ReleaseTextureFromResourceId() should be called when we don't use resourceId texture anymore.
 391    *
 392    * @param[in] resourceId The unique id of resouces.
 393    * @return Pointer of Graphics::Texture, or nullptr if we fail to create.
 394    */
 395   virtual Graphics::Texture* CreateTextureByResourceId(uint32_t resourceId, const Graphics::TextureCreateInfo& createInfo) = 0;
 396
 397   /**
 398    * @brief Discard Graphics::Texture as resourceId.
 399    *
 400    * @param[in] resourceId The unique id of resouces.
 401    */
 402   virtual void DiscardTextureFromResourceId(uint32_t resourceId) = 0;
 403
 404   /**
 405    * @brief Get the Graphics::Texture as resourceId.
 406    *
 407    * @param[in] resourceId The unique id of resouces.
 408    * @return Pointer of Graphics::Texture, or nullptr if there is no valid objects.
 409    */
 410   virtual Graphics::Texture* GetTextureFromResourceId(uint32_t resourceId) = 0;
 411
 412   /**
 413    * @brief Get the ownership of Graphics::Texture as resourceId.
 414    *
 415    * @param[in] resourceId The unique id of resouces.
 416    * @return Pointer of Graphics::Texture.
 417    */
 418   virtual UniquePtr<Graphics::Texture> ReleaseTextureFromResourceId(uint32_t resourceId) = 0;
 419
 420 protected:
 421   /**
 422    * Creates controller
 423    */
 424   Controller() = default;
 425 };
 426 } // namespace Graphics
 427 } // namespace Dali
 428
 429 #endif