dali/public-api/rendering/renderer.h

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