dali/public-api/rendering/renderer.h

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