dali/graphics-api/graphics-command-buffer.h

   1 #ifndef DALI_GRAPHICS_COMMAND_BUFFER_H
   2 #define DALI_GRAPHICS_COMMAND_BUFFER_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 // INTERNAL INCLUDES
  22 #include "graphics-types.h"
  23
  24 namespace Dali::Graphics
  25 {
  26 class Buffer;
  27 class Pipeline;
  28 class RenderTarget;
  29 class RenderPass;
  30 class Sampler;
  31 class SyncObject;
  32 class Texture;
  33
  34 /**
  35  * @brief Uniform buffer bindings.
  36  */
  37 struct UniformBufferBinding
  38 {
  39   Buffer* buffer; // Buffer
  40   union
  41   {
  42     void*    offsetPtr; // pointer to the client-side memory
  43     uint32_t offset;    // Offset within buffer
  44   };
  45   uint32_t dataSize; // Size of data to bind
  46   uint32_t binding;  // Binding index
  47 };
  48
  49 /**
  50  * @brief Texture bindings
  51  *
  52  * Additionally, sampler may be used in case of having combined
  53  * image and sampler.
  54  *
  55  */
  56 struct TextureBinding
  57 {
  58   const Texture* texture; // texture to be bound
  59   const Sampler* sampler; // sampler to be bound
  60   uint32_t       binding; // binding index
  61 };
  62
  63 /**
  64  * @brief Sampler binding
  65  */
  66 struct SamplerBinding
  67 {
  68   Sampler* sampler; // sampler to be bound
  69   uint32_t binding; // binding index
  70 };
  71
  72 /**
  73  * @brief ClearValue contains an union of RGBA and depthStencil values.
  74  */
  75 struct ClearValue
  76 {
  77   union
  78   {
  79     struct
  80     {
  81       float r, g, b, a;
  82     } color;
  83     struct
  84     {
  85       float    depth;   // glClearDepthf
  86       uint32_t stencil; // glClearStencil
  87     } depthStencil;
  88   };
  89 };
  90
  91 // Native rendering (using native APIs)
  92
  93 enum class DrawNativeAPI
  94 {
  95   GLES,
  96   UNDEFINED
  97 };
  98
  99 /**
 100  * Specifies native draw commands execution mode
 101  */
 102 enum class DrawNativeExecutionMode
 103 {
 104   ISOLATED, ///< Commands execute isolated from the main pipeline (not altering state)
 105   DIRECT ///< Commands inherit and alter current state of the main pipeline (unsafe!)
 106 };
 107
 108 struct DrawNativeInfo
 109 {
 110   DrawNativeAPI       api;      ///< API used by the callback
 111   Dali::CallbackBase* callback; ///< Callback pointer
 112
 113   /**
 114    * The call allows binding the resource so they can be passed into the callback
 115    * Each resource will pass API specific data (for example GL texture and buffer ids)
 116    */
 117   Graphics::Texture** textureList;  ///< Textures to be used by the call
 118   uint32_t            textureCount; ///< Number of texture used by the callback
 119   Graphics::Buffer**  bufferList;   ///< Buffers to be used by the call
 120   uint32_t            bufferCount;  ///< Number of buffers used by the callback
 121
 122   DrawNativeExecutionMode executionMode; ///< Specifies whether to isolate rendering from main pipeline
 123
 124   /**
 125    * The GLES api specific structure that stores pointers to objects to be filled when requested
 126    * by caller. The structure cointains void* to avoid creating any complex constructors and keep
 127    * the class trivial.
 128    */
 129   struct GLESNativeInfo
 130   {
 131     void* eglSharedContextStoragePointer; ///< Indicates the storage object to pass the shared context, must be null if not in use
 132
 133     /**
 134      * If false, it will inject GL calls into current context (window)
 135      * and won't create own context. This will alter GLES state and
 136      * it's application responsibility to maintain it so DALi can render
 137      * correctly after.
 138      */
 139     bool useOwnEglContext;
 140   } glesNativeInfo;
 141
 142   void* userData; ///< Data passed into the callback (unspecified type, callback should decode it)
 143   void* reserved; ///< Reserved for internal use
 144 };
 145
 146 /**
 147  * @brief CommandBuffer contains a stream of commands to be executed
 148  * by the controller.
 149  */
 150 class CommandBuffer
 151 {
 152 public:
 153   CommandBuffer()          = default;
 154   virtual ~CommandBuffer() = default;
 155
 156   // not copyable
 157   CommandBuffer(const CommandBuffer&) = delete;
 158   CommandBuffer& operator=(const CommandBuffer&) = delete;
 159
 160   /**
 161    * @brief Binds vertex buffers
 162    *
 163    * The buffers and offsets arrays must be same length
 164    *
 165    * @param[in] firstBinding First binding index
 166    * @param[in] buffers List of buffers to bind
 167    * @param[in] offsets List of offsets for each buffer
 168    */
 169   virtual void BindVertexBuffers(uint32_t                          firstBinding,
 170                                  const std::vector<const Buffer*>& buffers,
 171                                  const std::vector<uint32_t>&      offsets) = 0;
 172
 173   /**
 174    * @brief Binds uniform buffers
 175    *
 176    * @param[in] bindings List of uniform buffer bindings
 177    */
 178   virtual void BindUniformBuffers(const std::vector<UniformBufferBinding>& bindings) = 0;
 179
 180   /**
 181    * @brief Binds pipeline
 182    *
 183    * @param[in] pipeline valid pipeline
 184    */
 185   virtual void BindPipeline(const Pipeline& pipeline) = 0;
 186
 187   /**
 188    * @brief Binds textures
 189    *
 190    * @param[in] textureBindings List of texture bindings
 191    */
 192   virtual void BindTextures(const std::vector<TextureBinding>& textureBindings) = 0;
 193
 194   /**
 195    * @brief Binds samplers
 196    *
 197    * @param[in] samplerBindings List of sampler bindings
 198    */
 199   virtual void BindSamplers(const std::vector<SamplerBinding>& samplerBindings) = 0;
 200
 201   /**
 202    * @brief Binds buffer containing push constants
 203    *
 204    * @param[in] data pointer to the buffer
 205    * @param[in] size size of data in bytes
 206    * @param[in] binding push constants binding index
 207    */
 208   virtual void BindPushConstants(void*    data,
 209                                  uint32_t size,
 210                                  uint32_t binding) = 0;
 211
 212   /**
 213    * @brief Binds index buffer
 214    *
 215    * Most commonly used formats:
 216    * R32_UINT,
 217    * R16_UINT
 218    *
 219    * @param[in] buffer Valid buffer
 220    * @param[in] offset offset within buffer
 221    * @param[in] format Format of index buffer
 222    */
 223   virtual void BindIndexBuffer(const Buffer& buffer,
 224                                uint32_t      offset,
 225                                Format        format) = 0;
 226   /**
 227    * @brief Begins render pass
 228    *
 229    * The function initialises rendering for specified RenderPass object
 230    * onto renderTarget. renderArea defines the scissor rect. Depends on the
 231    * renderPass spec, the clearValues may be used.
 232    *
 233    * Calling EndRenderPass() is necessary to finalize the render pass.
 234    *
 235    * @param[in] renderPass valid render pass object
 236    * @param[in] renderTarget valid render target, must not be used when framebuffer set
 237    * @param[in] renderArea area to draw (clear operation is affected)
 238    * @param[in] clearValues clear values (compatible with renderpass spec)
 239    */
 240   virtual void BeginRenderPass(
 241     RenderPass*                    renderPass,
 242     RenderTarget*                  renderTarget,
 243     Rect2D                         renderArea,
 244     const std::vector<ClearValue>& clearValues) = 0;
 245
 246   /**
 247    * @brief Ends current render pass
 248    *
 249    * This command must be issued in order to finalize the render pass.
 250    * It's up to the implementation whether anything has to be done but
 251    * the Controller may use end RP marker in order to resolve resource
 252    * dependencies (for example, to know when target texture is ready
 253    * before passing it to another render pass).
 254    *
 255    * The caller may query the sync object to determine when this render
 256    * pass has actually finished on the GPU.
 257    *
 258    * @param[in] syncObject If non-null, this object will ensure an
 259    * appropriate fence sync object is created after the render pass is
 260    * executed.
 261    */
 262   virtual void EndRenderPass(Graphics::SyncObject* syncObject) = 0;
 263
 264   /**
 265    * @brief Executes a list of secondary command buffers
 266    *
 267    * The secondary command buffers will be executed as a part of a primary
 268    * command buffer that calls this function.
 269    *
 270    * @param[in] commandBuffers List of buffers to execute
 271    */
 272   virtual void ExecuteCommandBuffers(std::vector<const CommandBuffer*>&& commandBuffers) = 0;
 273
 274   /**
 275    * @brief Draw primitives
 276    *
 277    * @param[in] vertexCount number of vertices
 278    * @param[in] instanceCount number of instances
 279    * @param[in] firstVertex index of first vertex
 280    * @param[in] firstInstance index of first instance
 281    */
 282   virtual void Draw(
 283     uint32_t vertexCount,
 284     uint32_t instanceCount,
 285     uint32_t firstVertex,
 286     uint32_t firstInstance) = 0;
 287
 288   /**
 289    * @brief Draws indexed primitives
 290    *
 291    * @param[in] indexCount Number of indices
 292    * @param[in] instanceCount Number of instances
 293    * @param[in] firstIndex first index
 294    * @param[in] vertexOffset offset of first vertex
 295    * @param[in] firstInstance first instance
 296    */
 297   virtual void DrawIndexed(
 298     uint32_t indexCount,
 299     uint32_t instanceCount,
 300     uint32_t firstIndex,
 301     int32_t  vertexOffset,
 302     uint32_t firstInstance) = 0;
 303
 304   /**
 305    * @brief Draws indexed primitives indirectly
 306    *
 307    * Indirect draw uses additional buffer that holds render data.
 308    *
 309    * Indirect draw support depends on the hardware (most of modern hardware
 310    * supports this drawing technique).
 311    *
 312    * @param[in] buffer Buffer containing draw parameters
 313    * @param[in] offset Offset in bytes where parameters begin
 314    * @param[in] drawCount number of draws to execute
 315    * @param[in] stride stride between draw parameters
 316    */
 317   virtual void DrawIndexedIndirect(
 318     Buffer&  buffer,
 319     uint32_t offset,
 320     uint32_t drawCount,
 321     uint32_t stride) = 0;
 322
 323   /**
 324    * @brief Draws using native API (via callback)
 325    *
 326    * DrawNative should be use in order to acquire direct access to the
 327    * graphics API like GL. Upon command execution, the backend will
 328    * invoke given callback and pass API-specific arguments (for example,
 329    * the GL callback will receive EGL context used for rendering).
 330    *
 331    * The client side must make sure the callback is valid for the
 332    * time of execution.
 333    *
 334    * @param[in] drawInfo NativeDrawInfo structure
 335    */
 336   virtual void DrawNative(const DrawNativeInfo* drawInfo) = 0;
 337
 338   /**
 339    * @brief Resets CommandBuffer
 340    *
 341    * This function resets the command buffer and discards all previously
 342    * recorded commands.
 343    *
 344    * Since the allocation may use internal memory pool of the CommandBuffer,
 345    * resetting doesn't have to discard all the resources (for example, it doesn't
 346    * need to destroy command but only move the pointer to the beginning of
 347    * the command buffer).
 348    *
 349    * It is useful if the command buffer has to be re-recorded frequently, for example,
 350    * every frame.
 351    */
 352   virtual void Reset() = 0;
 353
 354   /**
 355    * @brief Changes scissor rect
 356    *
 357    * @param[in] value 2D scissor rectangle
 358    */
 359   virtual void SetScissor(Rect2D value) = 0;
 360
 361   /**
 362    * @brief Enables/disables scissor test
 363    *
 364    * @param[in] value State of scissor test
 365    */
 366   virtual void SetScissorTestEnable(bool value) = 0;
 367
 368   /**
 369    * @brief Sets viewport
 370    *
 371    * @param[in] value 2D viewport area
 372    */
 373   virtual void SetViewport(Viewport value) = 0;
 374
 375   /**
 376    * @brief Sets whether the viewport should be changed
 377    * @param[in] value state of viewport
 378    */
 379   virtual void SetViewportEnable(bool value) = 0;
 380
 381   /**
 382    * @brief Sets the color mask for all channels.
 383    */
 384   virtual void SetColorMask(bool enabled) = 0;
 385
 386   /**
 387    * @brief Clears the stencil buffer (outside of BeginRenderPass) to the current stencil mask
 388    */
 389   virtual void ClearStencilBuffer() = 0;
 390
 391   /**
 392    * @brief Clears the depth buffer (outside of BeginRenderPass) to the current depth mask
 393    */
 394   virtual void ClearDepthBuffer() = 0;
 395
 396   /**
 397    * @brief Enable or disable the stencil test
 398    *
 399    * @param[in] stencilEnable whether stencil test should be enabled
 400    */
 401   virtual void SetStencilTestEnable(bool stencilEnable) = 0;
 402
 403   /**
 404    * @brief The mask used for writing to the stencil buffer.
 405    *
 406    * It should be as wide as necessary for the stencil texture format.
 407    * @param[in] writeMask The mask for wriing to / clearing the stencil buffer
 408    */
 409   virtual void SetStencilWriteMask(uint32_t writeMask) = 0;
 410
 411   /**
 412    * @brief Setup the stencil function
 413    *
 414    * @param[in] compareOp How the stencil buffer, reference and compareMask are combined to determine whether to draw a pixel or not.
 415    * @param[in] reference A reference value that is ANDed with the mask in the compare op.
 416    * @param[in] compareMask The bitplanes from the stencil buffer that are active.
 417    */
 418   virtual void SetStencilFunc(Graphics::CompareOp compareOp,
 419                               uint32_t            reference,
 420                               uint32_t            compareMask) = 0;
 421
 422   /**
 423    * @brief Set how subsequent draws will affect the stencil buffer.
 424    * @param[in] failOp What happens to stencil buffer if drawing a pixel fails the stencil test
 425    * @param[in] passOp What happens to stencil buffer if drawing a pixel passes stencil & depth test
 426    * @param[in] depthFailOp What happens to stencil buffer if drawing a pixel passes stencil but fails depth test.
 427    */
 428   virtual void SetStencilOp(Graphics::StencilOp failOp,
 429                             Graphics::StencilOp passOp,
 430                             Graphics::StencilOp depthFailOp) = 0;
 431
 432   /**
 433    * @brief Defines the comparison operator for passing the depth test.
 434    *
 435    * @param[in] compareOp The comparison operator
 436    */
 437   virtual void SetDepthCompareOp(Graphics::CompareOp compareOp) = 0;
 438
 439   /**
 440    * @brief Enables depth testing
 441    *
 442    * @param[in] depthTestEnable True if depth testing will be enabled.
 443    */
 444   virtual void SetDepthTestEnable(bool depthTestEnable) = 0;
 445
 446   /**
 447    * @brief Enables depth writing / clearing
 448    *
 449    * @param[in] depthWriteEnabled True if the depth buffer can be updated or cleared.
 450    */
 451   virtual void SetDepthWriteEnable(bool depthWriteEnable) = 0;
 452
 453 protected:
 454   CommandBuffer(CommandBuffer&&) = default;
 455   CommandBuffer& operator=(CommandBuffer&&) = default;
 456 };
 457 } // namespace Dali::Graphics
 458
 459 #endif