dali/public-api/rendering/renderer.h

   1 #ifndef DALI_RENDERER_H
   2 #define DALI_RENDERER_H
   3
   4 /*
   5  * Copyright (c) 2016 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 namespace Internal DALI_INTERNAL
  31 {
  32 class Renderer;
  33 }
  34
  35 namespace FaceCullingMode
  36 {
  37
  38 /**
  39  * @brief Face culling mode.
  40  * @SINCE_1_1.43
  41  */
  42 enum Type
  43 {
  44   NONE,                ///< None of the faces should be culled                 @SINCE_1_1.43
  45   FRONT,               ///< Cull front face, front faces should never be shown @SINCE_1_1.43
  46   BACK,                ///< Cull back face, back faces should never be shown   @SINCE_1_1.43
  47   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
  48 };
  49
  50 } // namespace FaceCullingMode
  51
  52 namespace BlendMode
  53 {
  54
  55 /**
  56  * @brief Blend mode.
  57  * @SINCE_1_1.43
  58  */
  59 enum Type
  60 {
  61   OFF,  ///< Blending is disabled.                                                    @SINCE_1_1.43
  62   AUTO, ///< Blending is enabled if there is alpha channel. This is the default mode. @SINCE_1_1.43
  63   ON    ///< Blending is enabled.                                                     @SINCE_1_1.43
  64 };
  65
  66 } // namespace BlendMode
  67
  68 namespace BlendEquation
  69 {
  70
  71 /**
  72  * @brief Blend Equation.
  73  * @SINCE_1_1.43
  74  */
  75 enum Type
  76 {
  77   ADD              = 0x8006,  ///< The source and destination colors are added to each other. @SINCE_1_1.43
  78   SUBTRACT         = 0x800A,  ///< Subtracts the destination from the source.                 @SINCE_1_1.43
  79   REVERSE_SUBTRACT = 0x800B   ///< Subtracts the source from the destination.                 @SINCE_1_1.43
  80 };
  81
  82 } // namespace BlendEquation
  83
  84 namespace BlendFactor
  85 {
  86
  87 /**
  88  * @brief 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 /**
 116  * @brief 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 /**
 132  * @brief Depth buffer test (read) modes.
 133  * @SINCE_1_1.43
 134  */
 135 enum Type
 136 {
 137   OFF,  ///< Renderer does not read from the depth buffer                    @SINCE_1_1.43
 138   AUTO, ///< Renderer only reads from the depth buffer if in a 3D layer      @SINCE_1_1.43
 139   ON    ///< Renderer reads from the depth buffer based on the DepthFunction @SINCE_1_1.43
 140 };
 141
 142 } // namespace DepthTestMode
 143
 144 namespace DepthFunction
 145 {
 146
 147 /**
 148  * @brief 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 StencilFunction
 166 {
 167
 168 /**
 169  * @brief The comparison function used on the stencil buffer.
 170  * @SINCE_1_1.43
 171  */
 172 enum Type
 173 {
 174   NEVER,         ///< Always fails                                         @SINCE_1_1.43
 175   LESS,          ///< Passes if ( reference & mask ) <  ( stencil & mask ) @SINCE_1_1.43
 176   EQUAL,         ///< Passes if ( reference & mask ) =  ( stencil & mask ) @SINCE_1_1.43
 177   LESS_EQUAL,    ///< Passes if ( reference & mask ) <= ( stencil & mask ) @SINCE_1_1.43
 178   GREATER,       ///< Passes if ( reference & mask ) >  ( stencil & mask ) @SINCE_1_1.43
 179   NOT_EQUAL,     ///< Passes if ( reference & mask ) != ( stencil & mask ) @SINCE_1_1.43
 180   GREATER_EQUAL, ///< Passes if ( reference & mask ) >= ( stencil & mask ) @SINCE_1_1.43
 181   ALWAYS,        ///< Always passes                                        @SINCE_1_1.43
 182 };
 183
 184 } // namespace StencilFunction
 185
 186 namespace StencilMode
 187 {
 188
 189 /**
 190  * @brief How the stencil buffer will be managed.
 191  * @SINCE_1_1.43
 192  */
 193 enum Type
 194 {
 195   OFF,       ///< Off for this renderer                                  @SINCE_1_1.43
 196   AUTO,      ///< Managed by the Actor clipping API. This is the default @SINCE_1_1.43
 197   ON         ///< On for this renderer. Select this to use the Renderer stencil properties to manage behavior. Note that Actor clipping management is bypassed for this renderer @SINCE_1_1.43
 198 };
 199
 200 } // namespace StencilMode
 201
 202 namespace StencilOperation
 203 {
 204
 205 /**
 206  * @brief Specifies 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 /**
 225  * @brief Renderer is a handle to an object used to show content by combining a Geometry, a TextureSet and a shader
 226  *
 227  * @SINCE_1_1.43
 228  */
 229 class DALI_IMPORT_API Renderer : public Handle
 230 {
 231 public:
 232
 233   /**
 234    * @brief An enumeration of properties belonging to the Renderer class.
 235    */
 236   struct Property
 237   {
 238     enum
 239     {
 240       /**
 241        * @brief name "depthIndex", type INTEGER
 242        * @note The default value is 0
 243        * @SINCE_1_1.43
 244        */
 245       DEPTH_INDEX = DEFAULT_RENDERER_PROPERTY_START_INDEX,
 246
 247       /**
 248        * @brief name "faceCullingMode", type INTEGER
 249        * @note The default value is FaceCullingMode::NONE
 250        * @SINCE_1_1.43
 251        */
 252       FACE_CULLING_MODE,
 253
 254       /**
 255        * @brief name "blendMode", type INTEGER
 256        * @note The default value is BlendMode::AUTO
 257        * @SINCE_1_1.43
 258        */
 259       BLEND_MODE,
 260
 261       /**
 262        * @brief name "blendEquationRgb", type INTEGER
 263        * @note The default value is BlendEquation::ADD
 264        * @SINCE_1_1.43
 265        */
 266       BLEND_EQUATION_RGB,
 267
 268       /**
 269        * @brief name "blendEquationAlpha", type INTEGER
 270        * @note The default value is BlendEquation::ADD
 271        * @SINCE_1_1.43
 272        */
 273       BLEND_EQUATION_ALPHA,
 274
 275       /**
 276        * @brief name "blendFactorSrcRgb", type INTEGER
 277        * @note The default value is BlendFactor::SRC_ALPHA
 278        * @SINCE_1_1.43
 279        */
 280       BLEND_FACTOR_SRC_RGB,
 281
 282       /**
 283        * @brief name "blendFactorDestRgb", type INTEGER
 284        * @note The default value is BlendFactor::ONE_MINUS_SRC_ALPHA
 285        * @SINCE_1_1.43
 286        */
 287       BLEND_FACTOR_DEST_RGB,
 288
 289       /**
 290        * @brief name "blendFactorSrcAlpha", type INTEGER
 291        * @note The default value is BlendFactor::ONE
 292        * @SINCE_1_1.43
 293        */
 294       BLEND_FACTOR_SRC_ALPHA,
 295
 296       /**
 297        * @brief name "blendFactorDestAlpha", type INTEGER
 298        * @note The default value is BlendFactor::ONE_MINUS_SRC_ALPHA
 299        * @SINCE_1_1.43
 300        */
 301       BLEND_FACTOR_DEST_ALPHA,
 302
 303       /**
 304        * @brief name "blendColor", type VECTOR4
 305        * @note The default value is Color::TRANSPARENT
 306        * @SINCE_1_1.43
 307        */
 308       BLEND_COLOR,
 309
 310       /**
 311        * @brief name "blendPreMultipledAlpha", type BOOLEAN
 312        * @note The default value is false
 313        * @SINCE_1_1.43
 314        */
 315       BLEND_PRE_MULTIPLIED_ALPHA,
 316
 317       /**
 318        * @brief name "indexRangeFirst", type INTEGER
 319        * @note The default value is 0
 320        * @SINCE_1_1.43
 321        */
 322       INDEX_RANGE_FIRST,
 323
 324       /**
 325        * @brief name "indexRangeCount", type INTEGER
 326        * @note The default (0) means that whole range of indices will be used
 327        * @SINCE_1_1.43
 328        */
 329       INDEX_RANGE_COUNT,
 330
 331       /**
 332        * @brief name "depthWriteMode", type INTEGER
 333        * @see DepthWriteMode
 334        * @note The default value is DepthWriteMode::AUTO
 335        * @SINCE_1_1.43
 336        */
 337       DEPTH_WRITE_MODE,
 338
 339       /**
 340        * @brief name "depthFunction", type INTEGER
 341        * @see DepthFunction
 342        * @note The default value is DepthFunction::LESS
 343        * @SINCE_1_1.43
 344        */
 345       DEPTH_FUNCTION,
 346
 347       /**
 348        * @brief name "depthTestMode", type INTEGER
 349        * @see DepthTestMode
 350        * @note The default value is DepthTestMode::AUTO
 351        * @SINCE_1_1.43
 352        */
 353       DEPTH_TEST_MODE,
 354
 355       /**
 356        * @brief name "stencilFunction", type INTEGER
 357        * @see StencilFunction
 358        * @note The default value is StencilFunction::ALWAYS
 359        * @SINCE_1_1.43
 360        */
 361       STENCIL_FUNCTION,
 362
 363       /**
 364        * @brief name "stencilFunctionMask", type INTEGER
 365        * @note The default value is 0xFF
 366        * @SINCE_1_1.43
 367        */
 368       STENCIL_FUNCTION_MASK,
 369
 370       /**
 371        * @brief name "stencilFunctionReference", type INTEGER
 372        * @note The default value is 0
 373        * @SINCE_1_1.43
 374        */
 375       STENCIL_FUNCTION_REFERENCE,
 376
 377       /**
 378        * @brief name "stencilMask", type INTEGER
 379        * @note The default value is 0xFF
 380        * @SINCE_1_1.43
 381        */
 382       STENCIL_MASK,
 383
 384       /**
 385        * @brief name "stencilMode", type INTEGER
 386        * @see StencilMode
 387        * @note The default value is StencilMode::AUTO
 388        * @SINCE_1_1.43
 389        */
 390       STENCIL_MODE,
 391
 392       /**
 393        * @brief name "stencilOperationOnFail", type INTEGER
 394        * @see StencilOperation
 395        * @note The default value is StencilOperation::KEEP
 396        * @SINCE_1_1.43
 397        */
 398       STENCIL_OPERATION_ON_FAIL,
 399
 400       /**
 401        * @brief name "stencilOperationOnZFail", type INTEGER
 402        * @see StencilOperation
 403        * @note The default value is StencilOperation::KEEP
 404        * @SINCE_1_1.43
 405        */
 406       STENCIL_OPERATION_ON_Z_FAIL,
 407
 408       /**
 409        * @brief name "stencilOperationOnZPass", type INTEGER
 410        * @see StencilOperation
 411        * @note The default value is StencilOperation::KEEP
 412        * @SINCE_1_1.43
 413        */
 414       STENCIL_OPERATION_ON_Z_PASS,
 415
 416       /**
 417        * @brief name "writeToColorBuffer", type BOOLEAN
 418        * This allows per-renderer control of writing to the color buffer.
 419        * For example: This can be turned off to write to the stencil or depth buffers only.
 420        * @note The default value is True
 421        * @SINCE_1_1.43
 422        */
 423       WRITE_TO_COLOR_BUFFER
 424     };
 425   };
 426
 427   /**
 428    * @brief Creates a new Renderer object
 429    *
 430    * @SINCE_1_1.43
 431    * @param[in] geometry Geometry to be used by this renderer
 432    * @param[in] shader Shader to be used by this renderer
 433    */
 434   static Renderer New( Geometry& geometry, Shader& shader );
 435
 436   /**
 437    * @brief Default constructor, creates an empty handle
 438    *
 439    * @SINCE_1_1.43
 440    */
 441   Renderer();
 442
 443   /**
 444    * @brief Destructor
 445    *
 446    * @SINCE_1_1.43
 447    */
 448   ~Renderer();
 449
 450   /**
 451    * @brief Copy constructor, creates a new handle to the same object
 452    *
 453    * @SINCE_1_1.43
 454    * @param[in] handle Handle to an object
 455    */
 456   Renderer( const Renderer& handle );
 457
 458   /**
 459    * @brief Downcast to a renderer handle.
 460    * If not a renderer the returned renderer handle is left uninitialized.
 461    *
 462    * @SINCE_1_1.43
 463    * @param[in] handle Handle to an object
 464    * @return Renderer handle or an uninitialized handle
 465    */
 466   static Renderer DownCast( BaseHandle handle );
 467
 468   /**
 469    * @brief Assignment operator, changes this handle to point at the same object
 470    *
 471    * @SINCE_1_1.43
 472    * @param[in] handle Handle to an object
 473    * @return Reference to the assigned object
 474    */
 475   Renderer& operator=( const Renderer& handle );
 476
 477   /**
 478    * @brief Sets the geometry to be used by this renderer
 479    *
 480    * @SINCE_1_1.43
 481    * @param[in] geometry The geometry to be used by this renderer
 482    */
 483   void SetGeometry( Geometry& geometry );
 484
 485   /**
 486    * @brief Gets the geometry used by this renderer
 487    *
 488    * @SINCE_1_1.43
 489    * @return The geometry used by the renderer
 490    */
 491   Geometry GetGeometry() const;
 492
 493   /**
 494    * @brief Sets effective range of indices to draw from bound index buffer
 495    *
 496    * @SINCE_1_1.43
 497    * @param[in] firstElement The First element to draw
 498    * @param[in] elementsCount The number of elements to draw
 499    */
 500   inline void SetIndexRange( int firstElement, int elementsCount )
 501   {
 502     SetProperty( Property::INDEX_RANGE_FIRST, firstElement );
 503     SetProperty( Property::INDEX_RANGE_COUNT, elementsCount );
 504   }
 505
 506   /**
 507    * @brief Sets the texture set to be used by this renderer
 508    *
 509    * @SINCE_1_1.43
 510    * @param[in] textureSet The texture set to be used by this renderer
 511    */
 512   void SetTextures( TextureSet& textureSet );
 513
 514   /**
 515    * @brief Gets the texture set used by this renderer
 516    *
 517    * @SINCE_1_1.43
 518    * @return The texture set used by the renderer
 519    */
 520   TextureSet GetTextures() const;
 521
 522   /**
 523    * @brief Set the shader used by this renderer
 524    *
 525    * @SINCE_1_1.43
 526    * @param[in] shader The shader to be used by this renderer
 527    */
 528   void SetShader( Shader& shader );
 529
 530   /**
 531    * @brief Get the shader used by this renderer
 532    *
 533    * @SINCE_1_1.43
 534    * @return The shader used by the renderer
 535    */
 536   Shader GetShader() const;
 537
 538 public:
 539
 540   /**
 541    * @brief The constructor.
 542    * @note  Not intended for application developers.
 543    * @SINCE_1_1.43
 544    * @param[in] pointer A pointer to a newly allocated Renderer
 545    */
 546   explicit DALI_INTERNAL Renderer( Internal::Renderer* pointer );
 547 };
 548
 549 } //namespace Dali
 550
 551 #endif // DALI_RENDERER_H