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