dali/graphics-api/graphics-controller.h

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