dali/public-api/rendering/renderer.h

   1 #ifndef DALI_RENDERER_H
   2 #define DALI_RENDERER_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 <dali/public-api/object/handle.h>                // Dali::Handle
  23 #include <dali/public-api/object/property-index-ranges.h> // DEFAULT_RENDERER_PROPERTY_START_INDEX
  24 #include <dali/public-api/rendering/geometry.h>           // Dali::Geometry
  25 #include <dali/public-api/rendering/texture-set.h>        // Dali::TextureSet
  26
  27 namespace Dali
  28 {
  29 class RenderCallback;
  30
  31 /**
  32  * @addtogroup dali_core_rendering_effects
  33  * @{
  34  */
  35
  36 namespace Internal DALI_INTERNAL
  37 {
  38 class Renderer;
  39 }
  40
  41 namespace FaceCullingMode
  42 {
  43 /**
  44  * @brief Enumeration for face culling mode.
  45  * @SINCE_1_1.43
  46  */
  47 enum Type
  48 {
  49   NONE,           ///< None of the faces should be culled                 @SINCE_1_1.43
  50   FRONT,          ///< Cull front face, front faces should never be shown @SINCE_1_1.43
  51   BACK,           ///< Cull back face, back faces should never be shown   @SINCE_1_1.43
  52   FRONT_AND_BACK, ///< Cull front and back faces; if the geometry is composed of triangles none of the faces will be shown @SINCE_1_1.43
  53 };
  54
  55 } // namespace FaceCullingMode
  56
  57 namespace BlendMode
  58 {
  59 /**
  60  * @brief Enumeration for blend mode.
  61  * @SINCE_1_1.43
  62  */
  63 enum Type
  64 {
  65   OFF,               ///< Blending is disabled.                                                    @SINCE_1_1.43
  66   AUTO,              ///< Blending is enabled if there is alpha channel. This is the default mode. @SINCE_1_1.43
  67   ON,                ///< Blending is enabled.                                                     @SINCE_1_1.43
  68   ON_WITHOUT_CULL,   ///< Blending is enabled, and don't cull the renderer                         @SINCE_2_0.43
  69   USE_ACTOR_OPACITY  ///< Blending is enabled when the actor is not opaque                         @SINCE_2_2.7
  70 };
  71
  72 } // namespace BlendMode
  73
  74 namespace BlendEquation
  75 {
  76 /**
  77  * @brief Enumeration for blend equation.
  78  * @SINCE_1_1.43
  79  */
  80 enum Type
  81 {
  82   ADD              = 0x8006, ///< The source and destination colors are added to each other. @SINCE_1_1.43
  83   SUBTRACT         = 0x800A, ///< Subtracts the destination from the source.                 @SINCE_1_1.43
  84   REVERSE_SUBTRACT = 0x800B  ///< Subtracts the source from the destination.                 @SINCE_1_1.43
  85 };
  86
  87 } // namespace BlendEquation
  88
  89 namespace BlendFactor
  90 {
  91 /**
  92  * @brief Enumeration for blend factor.
  93  * @SINCE_1_1.43
  94  */
  95 enum Type
  96 {
  97   ZERO                     = 0,      ///< ZERO                     @SINCE_1_1.43
  98   ONE                      = 1,      ///< ONE                      @SINCE_1_1.43
  99   SRC_COLOR                = 0x0300, ///< SRC_COLOR                @SINCE_1_1.43
 100   ONE_MINUS_SRC_COLOR      = 0x0301, ///< ONE_MINUS_SRC_COLOR      @SINCE_1_1.43
 101   SRC_ALPHA                = 0x0302, ///< SRC_ALPHA                @SINCE_1_1.43
 102   ONE_MINUS_SRC_ALPHA      = 0x0303, ///< ONE_MINUS_SRC_ALPHA      @SINCE_1_1.43
 103   DST_ALPHA                = 0x0304, ///< DST_ALPHA                @SINCE_1_1.43
 104   ONE_MINUS_DST_ALPHA      = 0x0305, ///< ONE_MINUS_DST_ALPHA      @SINCE_1_1.43
 105   DST_COLOR                = 0x0306, ///< DST_COLOR                @SINCE_1_1.43
 106   ONE_MINUS_DST_COLOR      = 0x0307, ///< ONE_MINUS_DST_COLOR      @SINCE_1_1.43
 107   SRC_ALPHA_SATURATE       = 0x0308, ///< SRC_ALPHA_SATURATE       @SINCE_1_1.43
 108   CONSTANT_COLOR           = 0x8001, ///< CONSTANT_COLOR           @SINCE_1_1.43
 109   ONE_MINUS_CONSTANT_COLOR = 0x8002, ///< ONE_MINUS_CONSTANT_COLOR @SINCE_1_1.43
 110   CONSTANT_ALPHA           = 0x8003, ///< CONSTANT_ALPHA           @SINCE_1_1.43
 111   ONE_MINUS_CONSTANT_ALPHA = 0x8004  ///< ONE_MINUS_CONSTANT_ALPHA @SINCE_1_1.43
 112 };
 113
 114 } // namespace BlendFactor
 115
 116 namespace DepthWriteMode
 117 {
 118 /**
 119  * @brief Enumeration for depth buffer write modes.
 120  * @SINCE_1_1.43
 121  */
 122 enum Type
 123 {
 124   OFF,  ///< Renderer doesn't write to the depth buffer              @SINCE_1_1.43
 125   AUTO, ///< Renderer only writes to the depth buffer if it's opaque @SINCE_1_1.43
 126   ON    ///< Renderer writes to the depth buffer                     @SINCE_1_1.43
 127 };
 128
 129 } // namespace DepthWriteMode
 130
 131 namespace DepthTestMode
 132 {
 133 /**
 134  * @brief Enumeration for depth buffer test (read) modes.
 135  * @SINCE_1_1.43
 136  */
 137 enum Type
 138 {
 139   OFF,  ///< Renderer does not read from the depth buffer                    @SINCE_1_1.43
 140   AUTO, ///< Renderer only reads from the depth buffer if in a 3D layer      @SINCE_1_1.43
 141   ON    ///< Renderer reads from the depth buffer based on the DepthFunction @SINCE_1_1.43
 142 };
 143
 144 } // namespace DepthTestMode
 145
 146 namespace DepthFunction
 147 {
 148 /**
 149  * @brief Enumeration for depth functions.
 150  * @SINCE_1_1.43
 151  */
 152 enum Type
 153 {
 154   NEVER,        ///< Depth test never passes                                                                          @SINCE_1_1.43
 155   ALWAYS,       ///< Depth test always passes                                                                         @SINCE_1_1.43
 156   LESS,         ///< Depth test passes if the incoming depth value is less than the stored depth value                @SINCE_1_1.43
 157   GREATER,      ///< Depth test passes if the incoming depth value is greater than the stored depth value             @SINCE_1_1.43
 158   EQUAL,        ///< Depth test passes if the incoming depth value is equal to the stored depth value                 @SINCE_1_1.43
 159   NOT_EQUAL,    ///< Depth test passes if the incoming depth value is not equal to the stored depth value             @SINCE_1_1.43
 160   LESS_EQUAL,   ///< Depth test passes if the incoming depth value is less than or equal to the stored depth value    @SINCE_1_1.43
 161   GREATER_EQUAL ///< Depth test passes if the incoming depth value is greater than or equal to the stored depth value @SINCE_1_1.43
 162 };
 163
 164 } // namespace DepthFunction
 165
 166 namespace RenderMode
 167 {
 168 /**
 169  * @brief Enumeration for the controls of how this renderer uses its stencil properties and writes to the color buffer.
 170  * @SINCE_1_2_5
 171  */
 172 enum Type
 173 {
 174   NONE,         ///< Do not write to either color or stencil buffer (But will potentially render to depth buffer). @SINCE_1_2_5
 175   AUTO,         ///< Managed by the Actor Clipping API. This is the default.                                       @SINCE_1_2_5
 176   COLOR,        ///< Ingore stencil properties.  Write to the color buffer.                                        @SINCE_1_2_5
 177   STENCIL,      ///< Use the stencil properties. Do not write to the color buffer.                                 @SINCE_1_2_5
 178   COLOR_STENCIL ///< Use the stencil properties AND Write to the color buffer.                                     @SINCE_1_2_5
 179 };
 180
 181 } // namespace RenderMode
 182
 183 namespace StencilFunction
 184 {
 185 /**
 186  * @brief Enumeration for the comparison function used on the stencil buffer.
 187  * @SINCE_1_1.43
 188  */
 189 enum Type
 190 {
 191   NEVER,         ///< Always fails                                         @SINCE_1_1.43
 192   LESS,          ///< Passes if ( reference & mask ) <  ( stencil & mask ) @SINCE_1_1.43
 193   EQUAL,         ///< Passes if ( reference & mask ) =  ( stencil & mask ) @SINCE_1_1.43
 194   LESS_EQUAL,    ///< Passes if ( reference & mask ) <= ( stencil & mask ) @SINCE_1_1.43
 195   GREATER,       ///< Passes if ( reference & mask ) >  ( stencil & mask ) @SINCE_1_1.43
 196   NOT_EQUAL,     ///< Passes if ( reference & mask ) != ( stencil & mask ) @SINCE_1_1.43
 197   GREATER_EQUAL, ///< Passes if ( reference & mask ) >= ( stencil & mask ) @SINCE_1_1.43
 198   ALWAYS,        ///< Always passes                                        @SINCE_1_1.43
 199 };
 200
 201 } // namespace StencilFunction
 202
 203 namespace StencilOperation
 204 {
 205 /**
 206  * @brief Enumeration for specifying the action to take when the stencil (or depth) test fails during stencil test.
 207  * @SINCE_1_1.43
 208  */
 209 enum Type
 210 {
 211   ZERO,           ///< Sets the stencil buffer value to 0                                                              @SINCE_1_1.43
 212   KEEP,           ///< Keeps the current value                                                                         @SINCE_1_1.43
 213   REPLACE,        ///< Sets the stencil buffer value to ref, as specified by glStencilFunc                             @SINCE_1_1.43
 214   INCREMENT,      ///< Increments the current stencil buffer value. Clamps to the maximum representable unsigned value @SINCE_1_1.43
 215   DECREMENT,      ///< Decrements the current stencil buffer value. Clamps to 0                                        @SINCE_1_1.43
 216   INVERT,         ///< Bitwise inverts the current stencil buffer value                                                @SINCE_1_1.43
 217   INCREMENT_WRAP, ///< Increments the current stencil buffer value. Wraps stencil buffer value to zero when incrementing the maximum representable unsigned value @SINCE_1_1.43
 218   DECREMENT_WRAP  ///< Decrements the current stencil buffer value. Wraps stencil buffer value to the maximum representable unsigned value when decrementing a stencil buffer value of zero @SINCE_1_1.43
 219 };
 220
 221 } // namespace StencilOperation
 222
 223 /**
 224  * @brief Renderer is a handle to an object used to show content by combining a Geometry, a TextureSet and a shader.
 225  *
 226  * @SINCE_1_1.43
 227  */
 228 class DALI_CORE_API Renderer : public Handle
 229 {
 230 public:
 231   /**
 232    * @brief Enumeration for instances of properties belonging to the Renderer class.
 233    * @SINCE_1_1.43
 234    */
 235   struct Property
 236   {
 237     /**
 238      * @brief Enumeration for instances of properties belonging to the Renderer class.
 239      * @SINCE_1_1.43
 240      */
 241     enum
 242     {
 243       /**
 244        * @brief Name "depthIndex", type INTEGER.
 245        * @SINCE_1_1.43
 246        * @note The default value is 0.
 247        */
 248       DEPTH_INDEX = DEFAULT_RENDERER_PROPERTY_START_INDEX,
 249
 250       /**
 251        * @brief Name "faceCullingMode", type INTEGER.
 252        * @SINCE_1_1.43
 253        * @note The default value is FaceCullingMode::NONE.
 254        */
 255       FACE_CULLING_MODE,
 256
 257       /**
 258        * @brief Name "blendMode", type INTEGER.
 259        * @SINCE_1_1.43
 260        * @note The default value is BlendMode::AUTO.
 261        */
 262       BLEND_MODE,
 263
 264       /**
 265        * @brief Name "blendEquationRgb", type INTEGER.
 266        * @SINCE_1_1.43
 267        * @note The default value is BlendEquation::ADD.
 268        */
 269       BLEND_EQUATION_RGB,
 270
 271       /**
 272        * @brief Name "blendEquationAlpha", type INTEGER.
 273        * @SINCE_1_1.43
 274        * @note The default value is BlendEquation::ADD.
 275        */
 276       BLEND_EQUATION_ALPHA,
 277
 278       /**
 279        * @brief Name "blendFactorSrcRgb", type INTEGER.
 280        * @SINCE_1_1.43
 281        * @note The default value is BlendFactor::SRC_ALPHA.
 282        */
 283       BLEND_FACTOR_SRC_RGB,
 284
 285       /**
 286        * @brief Name "blendFactorDestRgb", type INTEGER.
 287        * @SINCE_1_1.43
 288        * @note The default value is BlendFactor::ONE_MINUS_SRC_ALPHA.
 289        */
 290       BLEND_FACTOR_DEST_RGB,
 291
 292       /**
 293        * @brief Name "blendFactorSrcAlpha", type INTEGER.
 294        * @SINCE_1_1.43
 295        * @note The default value is BlendFactor::ONE.
 296        */
 297       BLEND_FACTOR_SRC_ALPHA,
 298
 299       /**
 300        * @brief Name "blendFactorDestAlpha", type INTEGER.
 301        * @SINCE_1_1.43
 302        * @note The default value is BlendFactor::ONE_MINUS_SRC_ALPHA.
 303        */
 304       BLEND_FACTOR_DEST_ALPHA,
 305
 306       /**
 307        * @brief Name "blendColor", type VECTOR4.
 308        * @SINCE_1_1.43
 309        * @note The default value is Color::TRANSPARENT.
 310        */
 311       BLEND_COLOR,
 312
 313       /**
 314        * @brief Name "blendPreMultipledAlpha", type BOOLEAN.
 315        * @SINCE_1_1.43
 316        * @note The default value is false.
 317        */
 318       BLEND_PRE_MULTIPLIED_ALPHA,
 319
 320       /**
 321        * @brief Name "indexRangeFirst", type INTEGER.
 322        * @SINCE_1_1.43
 323        * @note The default value is 0.
 324        */
 325       INDEX_RANGE_FIRST,
 326
 327       /**
 328        * @brief Name "indexRangeCount", type INTEGER.
 329        * @SINCE_1_1.43
 330        * @note The default (0) means that whole range of indices will be used.
 331        */
 332       INDEX_RANGE_COUNT,
 333
 334       /**
 335        * @brief Name "depthWriteMode", type INTEGER.
 336        * @SINCE_1_1.43
 337        * @see DepthWriteMode
 338        * @note The default value is DepthWriteMode::AUTO.
 339        */
 340       DEPTH_WRITE_MODE,
 341
 342       /**
 343        * @brief Name "depthFunction", type INTEGER.
 344        * @SINCE_1_1.43
 345        * @see DepthFunction
 346        * @note The default value is DepthFunction::LESS.
 347        */
 348       DEPTH_FUNCTION,
 349
 350       /**
 351        * @brief Name "depthTestMode", type INTEGER.
 352        * @SINCE_1_1.43
 353        * @see DepthTestMode
 354        * @note The default value is DepthTestMode::AUTO.
 355        */
 356       DEPTH_TEST_MODE,
 357
 358       /**
 359        * @brief Name "renderMode", type INTEGER.
 360        * @SINCE_1_2_5
 361        * @see RenderMode
 362        * @note The default value is RenderMode::AUTO.
 363        */
 364       RENDER_MODE,
 365
 366       /**
 367        * @brief Name "stencilFunction", type INTEGER.
 368        * @SINCE_1_1.43
 369        * @see StencilFunction
 370        * @note The default value is StencilFunction::ALWAYS.
 371        */
 372       STENCIL_FUNCTION,
 373
 374       /**
 375        * @brief Name "stencilFunctionMask", type INTEGER.
 376        * @SINCE_1_1.43
 377        * @note The default value is 0xFF.
 378        */
 379       STENCIL_FUNCTION_MASK,
 380
 381       /**
 382        * @brief Name "stencilFunctionReference", type INTEGER.
 383        * @SINCE_1_1.43
 384        * @note The default value is 0.
 385        */
 386       STENCIL_FUNCTION_REFERENCE,
 387
 388       /**
 389        * @brief Name "stencilMask", type INTEGER.
 390        * @SINCE_1_1.43
 391        * @note The default value is 0xFF.
 392        */
 393       STENCIL_MASK,
 394
 395       /**
 396        * @brief Name "stencilOperationOnFail", type INTEGER.
 397        * @SINCE_1_1.43
 398        * @see StencilOperation
 399        * @note The default value is StencilOperation::KEEP
 400        */
 401       STENCIL_OPERATION_ON_FAIL,
 402
 403       /**
 404        * @brief Name "stencilOperationOnZFail", type INTEGER.
 405        * @SINCE_1_1.43
 406        * @see StencilOperation
 407        * @note The default value is StencilOperation::KEEP.
 408        */
 409       STENCIL_OPERATION_ON_Z_FAIL,
 410
 411       /**
 412        * @brief Name "stencilOperationOnZPass", type INTEGER.
 413        * @SINCE_1_1.43
 414        * @see StencilOperation
 415        * @note The default value is StencilOperation::KEEP.
 416        */
 417       STENCIL_OPERATION_ON_Z_PASS,
 418     };
 419   };
 420
 421   /**
 422    * @brief Creates a new Renderer object.
 423    *
 424    * @SINCE_1_1.43
 425    * @param[in] geometry Geometry to be used by this renderer
 426    * @param[in] shader Shader to be used by this renderer
 427    * @return A handle to the Renderer
 428    */
 429   static Renderer New(Geometry& geometry, Shader& shader);
 430
 431   /**
 432    * @brief Creates a new Renderer object with RenderCallback.
 433    *
 434    * @SINCE_2_1.18
 435    * @param[in] renderCallback Valid RenderCallback
 436    * @return A handle to the Renderer
 437    */
 438   static Renderer New(RenderCallback& renderCallback);
 439
 440   /**
 441    * @brief Default constructor, creates an empty handle
 442    *
 443    * @SINCE_1_1.43
 444    */
 445   Renderer();
 446
 447   /**
 448    * @brief Destructor.
 449    *
 450    * @SINCE_1_1.43
 451    */
 452   ~Renderer();
 453
 454   /**
 455    * @brief Copy constructor, creates a new handle to the same object.
 456    *
 457    * @SINCE_1_1.43
 458    * @param[in] handle Handle to an object
 459    */
 460   Renderer(const Renderer& handle);
 461
 462   /**
 463    * @brief Downcasts to a renderer handle.
 464    * If not, a renderer the returned renderer handle is left uninitialized.
 465    *
 466    * @SINCE_1_1.43
 467    * @param[in] handle Handle to an object
 468    * @return Renderer handle or an uninitialized handle
 469    */
 470   static Renderer DownCast(BaseHandle handle);
 471
 472   /**
 473    * @brief Assignment operator, changes this handle to point at the same object.
 474    *
 475    * @SINCE_1_1.43
 476    * @param[in] handle Handle to an object
 477    * @return Reference to the assigned object
 478    */
 479   Renderer& operator=(const Renderer& handle);
 480
 481   /**
 482    * @brief Move constructor.
 483    *
 484    * @SINCE_1_9.22
 485    * @param[in] rhs A reference to the moved handle
 486    */
 487   Renderer(Renderer&& rhs) noexcept;
 488
 489   /**
 490    * @brief Move assignment operator.
 491    *
 492    * @SINCE_1_9.22
 493    * @param[in] rhs A reference to the moved handle
 494    * @return A reference to this handle
 495    */
 496   Renderer& operator=(Renderer&& rhs) noexcept;
 497
 498   /**
 499    * @brief Sets the geometry to be used by this renderer.
 500    *
 501    * @SINCE_1_1.43
 502    * @param[in] geometry The geometry to be used by this renderer
 503    */
 504   void SetGeometry(Geometry& geometry);
 505
 506   /**
 507    * @brief Gets the geometry used by this renderer.
 508    *
 509    * @SINCE_1_1.43
 510    * @return The geometry used by the renderer
 511    */
 512   Geometry GetGeometry() const;
 513
 514   /**
 515    * @brief Sets effective range of indices to draw from bound index buffer.
 516    *
 517    * @SINCE_1_1.43
 518    * @param[in] firstElement The First element to draw
 519    * @param[in] elementsCount The number of elements to draw
 520    */
 521   inline void SetIndexRange(int firstElement, int elementsCount)
 522   {
 523     SetProperty(Property::INDEX_RANGE_FIRST, firstElement);
 524     SetProperty(Property::INDEX_RANGE_COUNT, elementsCount);
 525   }
 526
 527   /**
 528    * @brief Sets the texture set to be used by this renderer.
 529    *
 530    * @SINCE_1_1.43
 531    * @param[in] textureSet The texture set to be used by this renderer
 532    */
 533   void SetTextures(TextureSet& textureSet);
 534
 535   /**
 536    * @brief Gets the texture set used by this renderer.
 537    *
 538    * @SINCE_1_1.43
 539    * @return The texture set used by the renderer
 540    */
 541   TextureSet GetTextures() const;
 542
 543   /**
 544    * @brief Sets the shader used by this renderer.
 545    *
 546    * @SINCE_1_1.43
 547    * @param[in] shader The shader to be used by this renderer
 548    */
 549   void SetShader(Shader& shader);
 550
 551   /**
 552    * @brief Gets the shader used by this renderer.
 553    *
 554    * @SINCE_1_1.43
 555    * @return The shader used by the renderer
 556    */
 557   Shader GetShader() const;
 558
 559   /**
 560    * @brief Sets RenderCallback to be used for native rendering
 561    *
 562    * @SINCE_2_1.15
 563    * @param[in] callback Pointer to a valid RenderCallback object
 564    */
 565   void SetRenderCallback(RenderCallback* callback);
 566
 567 public:
 568   /// @cond internal
 569   /**
 570    * @brief The constructor.
 571    * @note  Not intended for application developers.
 572    * @SINCE_1_1.43
 573    * @param[in] pointer A pointer to a newly allocated Renderer
 574    */
 575   explicit DALI_INTERNAL Renderer(Internal::Renderer* pointer);
 576   /// @endcond
 577 };
 578
 579 /**
 580  * @}
 581  */
 582 } //namespace Dali
 583
 584 #endif // DALI_RENDERER_H