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