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