dali/graphics-api/graphics-controller.h

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