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) 2022 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 /**
  92  * @brief CommandBuffer contains a stream of commands to be executed
  93  * by the controller.
  94  */
  95 class CommandBuffer
  96 {
  97 public:
  98   CommandBuffer()          = default;
  99   virtual ~CommandBuffer() = default;
 100
 101   // not copyable
 102   CommandBuffer(const CommandBuffer&) = delete;
 103   CommandBuffer& operator=(const CommandBuffer&) = delete;
 104
 105   /**
 106    * @brief Binds vertex buffers
 107    *
 108    * The buffers and offsets arrays must be same length
 109    *
 110    * @param[in] firstBinding First binding index
 111    * @param[in] buffers List of buffers to bind
 112    * @param[in] offsets List of offsets for each buffer
 113    */
 114   virtual void BindVertexBuffers(uint32_t                          firstBinding,
 115                                  const std::vector<const Buffer*>& buffers,
 116                                  const std::vector<uint32_t>&      offsets) = 0;
 117
 118   /**
 119    * @brief Binds uniform buffers
 120    *
 121    * @param[in] bindings List of uniform buffer bindings
 122    */
 123   virtual void BindUniformBuffers(const std::vector<UniformBufferBinding>& bindings) = 0;
 124
 125   /**
 126    * @brief Binds pipeline
 127    *
 128    * @param[in] pipeline valid pipeline
 129    */
 130   virtual void BindPipeline(const Pipeline& pipeline) = 0;
 131
 132   /**
 133    * @brief Binds textures
 134    *
 135    * @param[in] textureBindings List of texture bindings
 136    */
 137   virtual void BindTextures(const std::vector<TextureBinding>& textureBindings) = 0;
 138
 139   /**
 140    * @brief Binds samplers
 141    *
 142    * @param[in] samplerBindings List of sampler bindings
 143    */
 144   virtual void BindSamplers(const std::vector<SamplerBinding>& samplerBindings) = 0;
 145
 146   /**
 147    * @brief Binds buffer containing push constants
 148    *
 149    * @param[in] data pointer to the buffer
 150    * @param[in] size size of data in bytes
 151    * @param[in] binding push constants binding index
 152    */
 153   virtual void BindPushConstants(void*    data,
 154                                  uint32_t size,
 155                                  uint32_t binding) = 0;
 156
 157   /**
 158    * @brief Binds index buffer
 159    *
 160    * Most commonly used formats:
 161    * R32_UINT,
 162    * R16_UINT
 163    *
 164    * @param[in] buffer Valid buffer
 165    * @param[in] offset offset within buffer
 166    * @param[in] format Format of index buffer
 167    */
 168   virtual void BindIndexBuffer(const Buffer& buffer,
 169                                uint32_t      offset,
 170                                Format        format) = 0;
 171   /**
 172    * @brief Begins render pass
 173    *
 174    * The function initialises rendering for specified RenderPass object
 175    * onto renderTarget. renderArea defines the scissor rect. Depends on the
 176    * renderPass spec, the clearValues may be used.
 177    *
 178    * Calling EndRenderPass() is necessary to finalize the render pass.
 179    *
 180    * @param[in] renderPass valid render pass object
 181    * @param[in] renderTarget valid render target, must not be used when framebuffer set
 182    * @param[in] renderArea area to draw (clear operation is affected)
 183    * @param[in] clearValues clear values (compatible with renderpass spec)
 184    */
 185   virtual void BeginRenderPass(
 186     RenderPass*                    renderPass,
 187     RenderTarget*                  renderTarget,
 188     Rect2D                         renderArea,
 189     const std::vector<ClearValue>& clearValues) = 0;
 190
 191   /**
 192    * @brief Ends current render pass
 193    *
 194    * This command must be issued in order to finalize the render pass.
 195    * It's up to the implementation whether anything has to be done but
 196    * the Controller may use end RP marker in order to resolve resource
 197    * dependencies (for example, to know when target texture is ready
 198    * before passing it to another render pass).
 199    *
 200    * The caller may query the sync object to determine when this render
 201    * pass has actually finished on the GPU.
 202    *
 203    * @param[in] syncObject If non-null, this object will ensure an
 204    * appropriate fence sync object is created after the render pass is
 205    * executed.
 206    */
 207   virtual void EndRenderPass(Graphics::SyncObject* syncObject) = 0;
 208
 209   /**
 210    * @brief Executes a list of secondary command buffers
 211    *
 212    * The secondary command buffers will be executed as a part of a primary
 213    * command buffer that calls this function.
 214    *
 215    * @param[in] commandBuffers List of buffers to execute
 216    */
 217   virtual void ExecuteCommandBuffers(std::vector<const CommandBuffer*>&& commandBuffers) = 0;
 218
 219   /**
 220    * @brief Draw primitives
 221    *
 222    * @param[in] vertexCount number of vertices
 223    * @param[in] instanceCount number of instances
 224    * @param[in] firstVertex index of first vertex
 225    * @param[in] firstInstance index of first instance
 226    */
 227   virtual void Draw(
 228     uint32_t vertexCount,
 229     uint32_t instanceCount,
 230     uint32_t firstVertex,
 231     uint32_t firstInstance) = 0;
 232
 233   /**
 234    * @brief Draws indexed primitives
 235    *
 236    * @param[in] indexCount Number of indices
 237    * @param[in] instanceCount Number of instances
 238    * @param[in] firstIndex first index
 239    * @param[in] vertexOffset offset of first vertex
 240    * @param[in] firstInstance first instance
 241    */
 242   virtual void DrawIndexed(
 243     uint32_t indexCount,
 244     uint32_t instanceCount,
 245     uint32_t firstIndex,
 246     int32_t  vertexOffset,
 247     uint32_t firstInstance) = 0;
 248
 249   /**
 250    * @brief Draws indexed primitives indirectly
 251    *
 252    * Indirect draw uses additional buffer that holds render data.
 253    *
 254    * Indirect draw support depends on the hardware (most of modern hardware
 255    * supports this drawing technique).
 256    *
 257    * @param[in] buffer Buffer containing draw parameters
 258    * @param[in] offset Offset in bytes where parameters begin
 259    * @param[in] drawCount number of draws to execute
 260    * @param[in] stride stride between draw parameters
 261    */
 262   virtual void DrawIndexedIndirect(
 263     Buffer&  buffer,
 264     uint32_t offset,
 265     uint32_t drawCount,
 266     uint32_t stride) = 0;
 267
 268   /**
 269    * @brief Resets CommandBuffer
 270    *
 271    * This function resets the command buffer and discards all previously
 272    * recorded commands.
 273    *
 274    * Since the allocation may use internal memory pool of the CommandBuffer,
 275    * resetting doesn't have to discard all the resources (for example, it doesn't
 276    * need to destroy command but only move the pointer to the beginning of
 277    * the command buffer).
 278    *
 279    * It is useful if the command buffer has to be re-recorded frequently, for example,
 280    * every frame.
 281    */
 282   virtual void Reset() = 0;
 283
 284   /**
 285    * @brief Changes scissor rect
 286    *
 287    * @param[in] value 2D scissor rectangle
 288    */
 289   virtual void SetScissor(Rect2D value) = 0;
 290
 291   /**
 292    * @brief Enables/disables scissor test
 293    *
 294    * @param[in] value State of scissor test
 295    */
 296   virtual void SetScissorTestEnable(bool value) = 0;
 297
 298   /**
 299    * @brief Sets viewport
 300    *
 301    * @param[in] value 2D viewport area
 302    */
 303   virtual void SetViewport(Viewport value) = 0;
 304
 305   /**
 306    * @brief Sets whether the viewport should be changed
 307    * @param[in] value state of viewport
 308    */
 309   virtual void SetViewportEnable(bool value) = 0;
 310
 311   /**
 312    * @brief Sets the color mask for all channels.
 313    */
 314   virtual void SetColorMask(bool enabled) = 0;
 315
 316   /**
 317    * @brief Clears the stencil buffer (outside of BeginRenderPass) to the current stencil mask
 318    */
 319   virtual void ClearStencilBuffer() = 0;
 320
 321   /**
 322    * @brief Clears the depth buffer (outside of BeginRenderPass) to the current depth mask
 323    */
 324   virtual void ClearDepthBuffer() = 0;
 325
 326   /**
 327    * @brief Enable or disable the stencil test
 328    *
 329    * @param[in] stencilEnable whether stencil test should be enabled
 330    */
 331   virtual void SetStencilTestEnable(bool stencilEnable) = 0;
 332
 333   /**
 334    * @brief The mask used for writing to the stencil buffer.
 335    *
 336    * It should be as wide as necessary for the stencil texture format.
 337    * @param[in] writeMask The mask for wriing to / clearing the stencil buffer
 338    */
 339   virtual void SetStencilWriteMask(uint32_t writeMask) = 0;
 340
 341   /**
 342    * @brief Setup the stencil function
 343    *
 344    * @param[in] compareOp How the stencil buffer, reference and compareMask are combined to determine whether to draw a pixel or not.
 345    * @param[in] reference A reference value that is ANDed with the mask in the compare op.
 346    * @param[in] compareMask The bitplanes from the stencil buffer that are active.
 347    */
 348   virtual void SetStencilFunc(Graphics::CompareOp compareOp,
 349                               uint32_t            reference,
 350                               uint32_t            compareMask) = 0;
 351
 352   /**
 353    * @brief Set how subsequent draws will affect the stencil buffer.
 354    * @param[in] failOp What happens to stencil buffer if drawing a pixel fails the stencil test
 355    * @param[in] passOp What happens to stencil buffer if drawing a pixel passes stencil & depth test
 356    * @param[in] depthFailOp What happens to stencil buffer if drawing a pixel passes stencil but fails depth test.
 357    */
 358   virtual void SetStencilOp(Graphics::StencilOp failOp,
 359                             Graphics::StencilOp passOp,
 360                             Graphics::StencilOp depthFailOp) = 0;
 361
 362   /**
 363    * @brief Defines the comparison operator for passing the depth test.
 364    *
 365    * @param[in] compareOp The comparison operator
 366    */
 367   virtual void SetDepthCompareOp(Graphics::CompareOp compareOp) = 0;
 368
 369   /**
 370    * @brief Enables depth testing
 371    *
 372    * @param[in] depthTestEnable True if depth testing will be enabled.
 373    */
 374   virtual void SetDepthTestEnable(bool depthTestEnable) = 0;
 375
 376   /**
 377    * @brief Enables depth writing / clearing
 378    *
 379    * @param[in] depthWriteEnabled True if the depth buffer can be updated or cleared.
 380    */
 381   virtual void SetDepthWriteEnable(bool depthWriteEnable) = 0;
 382
 383 protected:
 384   CommandBuffer(CommandBuffer&&) = default;
 385   CommandBuffer& operator=(CommandBuffer&&) = default;
 386 };
 387 } // namespace Dali::Graphics
 388
 389 #endif