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 RenderMode
 166 {
 167
 168 /**
 169  * @brief Controls 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 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 Specifies 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 An enumeration of properties belonging to the Renderer class.
 237    */
 238   struct Property
 239   {
 240     enum
 241     {
 242       /**
 243        * @brief name "depthIndex", type INTEGER
 244        * @note The default value is 0
 245        * @SINCE_1_1.43
 246        */
 247       DEPTH_INDEX = DEFAULT_RENDERER_PROPERTY_START_INDEX,
 248
 249       /**
 250        * @brief name "faceCullingMode", type INTEGER
 251        * @note The default value is FaceCullingMode::NONE
 252        * @SINCE_1_1.43
 253        */
 254       FACE_CULLING_MODE,
 255
 256       /**
 257        * @brief name "blendMode", type INTEGER
 258        * @note The default value is BlendMode::AUTO
 259        * @SINCE_1_1.43
 260        */
 261       BLEND_MODE,
 262
 263       /**
 264        * @brief name "blendEquationRgb", type INTEGER
 265        * @note The default value is BlendEquation::ADD
 266        * @SINCE_1_1.43
 267        */
 268       BLEND_EQUATION_RGB,
 269
 270       /**
 271        * @brief name "blendEquationAlpha", type INTEGER
 272        * @note The default value is BlendEquation::ADD
 273        * @SINCE_1_1.43
 274        */
 275       BLEND_EQUATION_ALPHA,
 276
 277       /**
 278        * @brief name "blendFactorSrcRgb", type INTEGER
 279        * @note The default value is BlendFactor::SRC_ALPHA
 280        * @SINCE_1_1.43
 281        */
 282       BLEND_FACTOR_SRC_RGB,
 283
 284       /**
 285        * @brief name "blendFactorDestRgb", type INTEGER
 286        * @note The default value is BlendFactor::ONE_MINUS_SRC_ALPHA
 287        * @SINCE_1_1.43
 288        */
 289       BLEND_FACTOR_DEST_RGB,
 290
 291       /**
 292        * @brief name "blendFactorSrcAlpha", type INTEGER
 293        * @note The default value is BlendFactor::ONE
 294        * @SINCE_1_1.43
 295        */
 296       BLEND_FACTOR_SRC_ALPHA,
 297
 298       /**
 299        * @brief name "blendFactorDestAlpha", type INTEGER
 300        * @note The default value is BlendFactor::ONE_MINUS_SRC_ALPHA
 301        * @SINCE_1_1.43
 302        */
 303       BLEND_FACTOR_DEST_ALPHA,
 304
 305       /**
 306        * @brief name "blendColor", type VECTOR4
 307        * @note The default value is Color::TRANSPARENT
 308        * @SINCE_1_1.43
 309        */
 310       BLEND_COLOR,
 311
 312       /**
 313        * @brief name "blendPreMultipledAlpha", type BOOLEAN
 314        * @note The default value is false
 315        * @SINCE_1_1.43
 316        */
 317       BLEND_PRE_MULTIPLIED_ALPHA,
 318
 319       /**
 320        * @brief name "indexRangeFirst", type INTEGER
 321        * @note The default value is 0
 322        * @SINCE_1_1.43
 323        */
 324       INDEX_RANGE_FIRST,
 325
 326       /**
 327        * @brief name "indexRangeCount", type INTEGER
 328        * @note The default (0) means that whole range of indices will be used
 329        * @SINCE_1_1.43
 330        */
 331       INDEX_RANGE_COUNT,
 332
 333       /**
 334        * @brief name "depthWriteMode", type INTEGER
 335        * @see DepthWriteMode
 336        * @note The default value is DepthWriteMode::AUTO
 337        * @SINCE_1_1.43
 338        */
 339       DEPTH_WRITE_MODE,
 340
 341       /**
 342        * @brief name "depthFunction", type INTEGER
 343        * @see DepthFunction
 344        * @note The default value is DepthFunction::LESS
 345        * @SINCE_1_1.43
 346        */
 347       DEPTH_FUNCTION,
 348
 349       /**
 350        * @brief name "depthTestMode", type INTEGER
 351        * @see DepthTestMode
 352        * @note The default value is DepthTestMode::AUTO
 353        * @SINCE_1_1.43
 354        */
 355       DEPTH_TEST_MODE,
 356
 357       /**
 358        * @brief name "renderMode", type INTEGER
 359        * @see RenderMode
 360        * @note The default value is RenderMode::AUTO
 361        * @SINCE_1_2.5
 362        */
 363       RENDER_MODE,
 364
 365       /**
 366        * @brief name "stencilFunction", type INTEGER
 367        * @see StencilFunction
 368        * @note The default value is StencilFunction::ALWAYS
 369        * @SINCE_1_1.43
 370        */
 371       STENCIL_FUNCTION,
 372
 373       /**
 374        * @brief name "stencilFunctionMask", type INTEGER
 375        * @note The default value is 0xFF
 376        * @SINCE_1_1.43
 377        */
 378       STENCIL_FUNCTION_MASK,
 379
 380       /**
 381        * @brief name "stencilFunctionReference", type INTEGER
 382        * @note The default value is 0
 383        * @SINCE_1_1.43
 384        */
 385       STENCIL_FUNCTION_REFERENCE,
 386
 387       /**
 388        * @brief name "stencilMask", type INTEGER
 389        * @note The default value is 0xFF
 390        * @SINCE_1_1.43
 391        */
 392       STENCIL_MASK,
 393
 394       /**
 395        * @brief name "stencilOperationOnFail", type INTEGER
 396        * @see StencilOperation
 397        * @note The default value is StencilOperation::KEEP
 398        * @SINCE_1_1.43
 399        */
 400       STENCIL_OPERATION_ON_FAIL,
 401
 402       /**
 403        * @brief name "stencilOperationOnZFail", type INTEGER
 404        * @see StencilOperation
 405        * @note The default value is StencilOperation::KEEP
 406        * @SINCE_1_1.43
 407        */
 408       STENCIL_OPERATION_ON_Z_FAIL,
 409
 410       /**
 411        * @brief name "stencilOperationOnZPass", type INTEGER
 412        * @see StencilOperation
 413        * @note The default value is StencilOperation::KEEP
 414        * @SINCE_1_1.43
 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    */
 427   static Renderer New( Geometry& geometry, Shader& shader );
 428
 429   /**
 430    * @brief Default constructor, creates an empty handle
 431    *
 432    * @SINCE_1_1.43
 433    */
 434   Renderer();
 435
 436   /**
 437    * @brief Destructor
 438    *
 439    * @SINCE_1_1.43
 440    */
 441   ~Renderer();
 442
 443   /**
 444    * @brief Copy constructor, creates a new handle to the same object
 445    *
 446    * @SINCE_1_1.43
 447    * @param[in] handle Handle to an object
 448    */
 449   Renderer( const Renderer& handle );
 450
 451   /**
 452    * @brief Downcast to a renderer handle.
 453    * If not a renderer the returned renderer handle is left uninitialized.
 454    *
 455    * @SINCE_1_1.43
 456    * @param[in] handle Handle to an object
 457    * @return Renderer handle or an uninitialized handle
 458    */
 459   static Renderer DownCast( BaseHandle handle );
 460
 461   /**
 462    * @brief Assignment operator, changes this handle to point at the same object
 463    *
 464    * @SINCE_1_1.43
 465    * @param[in] handle Handle to an object
 466    * @return Reference to the assigned object
 467    */
 468   Renderer& operator=( const Renderer& handle );
 469
 470   /**
 471    * @brief Sets the geometry to be used by this renderer
 472    *
 473    * @SINCE_1_1.43
 474    * @param[in] geometry The geometry to be used by this renderer
 475    */
 476   void SetGeometry( Geometry& geometry );
 477
 478   /**
 479    * @brief Gets the geometry used by this renderer
 480    *
 481    * @SINCE_1_1.43
 482    * @return The geometry used by the renderer
 483    */
 484   Geometry GetGeometry() const;
 485
 486   /**
 487    * @brief Sets effective range of indices to draw from bound index buffer
 488    *
 489    * @SINCE_1_1.43
 490    * @param[in] firstElement The First element to draw
 491    * @param[in] elementsCount The number of elements to draw
 492    */
 493   inline void SetIndexRange( int firstElement, int elementsCount )
 494   {
 495     SetProperty( Property::INDEX_RANGE_FIRST, firstElement );
 496     SetProperty( Property::INDEX_RANGE_COUNT, elementsCount );
 497   }
 498
 499   /**
 500    * @brief Sets the texture set to be used by this renderer
 501    *
 502    * @SINCE_1_1.43
 503    * @param[in] textureSet The texture set to be used by this renderer
 504    */
 505   void SetTextures( TextureSet& textureSet );
 506
 507   /**
 508    * @brief Gets the texture set used by this renderer
 509    *
 510    * @SINCE_1_1.43
 511    * @return The texture set used by the renderer
 512    */
 513   TextureSet GetTextures() const;
 514
 515   /**
 516    * @brief Set the shader used by this renderer
 517    *
 518    * @SINCE_1_1.43
 519    * @param[in] shader The shader to be used by this renderer
 520    */
 521   void SetShader( Shader& shader );
 522
 523   /**
 524    * @brief Get the shader used by this renderer
 525    *
 526    * @SINCE_1_1.43
 527    * @return The shader used by the renderer
 528    */
 529   Shader GetShader() const;
 530
 531 public:
 532
 533   /**
 534    * @brief The constructor.
 535    * @note  Not intended for application developers.
 536    * @SINCE_1_1.43
 537    * @param[in] pointer A pointer to a newly allocated Renderer
 538    */
 539   explicit DALI_INTERNAL Renderer( Internal::Renderer* pointer );
 540 };
 541
 542 } //namespace Dali
 543
 544 #endif // DALI_RENDERER_H