dali/public-api/actors/renderable-actor.h

   1 #ifndef __DALI_RENDERABLE_ACTOR_H__
   2 #define __DALI_RENDERABLE_ACTOR_H__
   3
   4 /*
   5  * Copyright (c) 2014 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
  22 // INTERNAL INCLUDES
  23 #include <dali/public-api/actors/actor.h>
  24 #include <dali/public-api/actors/blending.h>
  25 #include <dali/public-api/actors/sampling.h>
  26
  27 namespace Dali
  28 {
  29 namespace Internal DALI_INTERNAL
  30 {
  31 class RenderableActor;
  32 }
  33
  34 class ShaderEffect;
  35
  36 /**
  37  * @brief Face culling modes.
  38  */
  39 enum CullFaceMode
  40 {
  41   CullNone,                 ///< Face culling disabled
  42   CullFront,                ///< Cull front facing polygons
  43   CullBack,                 ///< Cull back facing polygons
  44   CullFrontAndBack          ///< Cull front and back facing polygons
  45 };
  46
  47
  48 /**
  49  * @brief A base class for renderable actors.
  50  */
  51 class DALI_IMPORT_API RenderableActor : public Actor
  52 {
  53 public:
  54
  55   static const BlendingMode::Type DEFAULT_BLENDING_MODE; ///< default value is BlendingMode::AUTO
  56
  57   /**
  58    * @brief Create an uninitialized actor.
  59    *
  60    * Calling member functions with an uninitialized Dali::Object is not allowed.
  61    */
  62   RenderableActor();
  63
  64   /**
  65    * @brief Downcast an Object handle to RenderableActor.
  66    *
  67    * If handle points to a RenderableActor the
  68    * downcast produces valid handle. If not the returned handle is left uninitialized.
  69    * @param[in] handle to An object
  70    * @return handle to a RenderableActor or an uninitialized handle
  71    */
  72   static RenderableActor DownCast( BaseHandle handle );
  73
  74   /**
  75    * @brief Destructor
  76    *
  77    * This is non-virtual since derived Handle types must not contain data or virtual methods.
  78    */
  79   ~RenderableActor();
  80
  81   /**
  82    * @brief Copy constructor
  83    *
  84    * @param [in] copy The actor to copy.
  85    */
  86   RenderableActor(const RenderableActor& copy);
  87
  88   /**
  89    * @brief Assignment operator
  90    *
  91    * @param [in] rhs The actor to copy.
  92    */
  93   RenderableActor& operator=(const RenderableActor& rhs);
  94
  95   /**
  96    * @brief Allows modification of an actors position in the depth sort algorithm.
  97    *
  98    * The offset can be altered for each coplanar actor hence allowing an order of painting.
  99    * @pre The Actor has been initialized.
 100    * @param [in] depthOffset the offset to be given to the actor. Positive values pushing it further back.
 101    */
 102   void SetSortModifier(float depthOffset);
 103
 104   /**
 105    * @brief Retrieves the offset used to modify an actors position in the depth sort algorithm.
 106    *
 107    * The offset can be altered for each coplanar actor hence allowing an order of painting.
 108    * @pre The Actor has been initialized.
 109    * @return  the offset that has been given to the actor. Positive values pushing it further back.
 110    */
 111   float GetSortModifier() const;
 112
 113   /**
 114    * @brief Set the face-culling mode for this actor.
 115    *
 116    * @param[in] mode The culling mode.
 117    */
 118   void SetCullFace(CullFaceMode mode);
 119
 120   /**
 121    * @brief Retrieve the face-culling mode for this actor.
 122    *
 123    * @return mode The culling mode.
 124    */
 125   CullFaceMode GetCullFace() const;
 126
 127   /**
 128    * @brief Sets the blending mode.
 129    *
 130    * Possible values are: BlendingMode::OFF, BlendingMode::AUTO and BlendingMode::ON. Default is BlendingMode::AUTO.
 131    *
 132    * If blending is disabled (BlendingMode::OFF) fade in and fade out animations do not work.
 133    *
 134    * <ul>
 135    *   <li> \e OFF Blending is disabled.
 136    *   <li> \e AUTO Blending is enabled only if the renderable actor has alpha channel.
 137    *   <li> \e ON Blending is enabled.
 138    * </ul>
 139    *
 140    * @param[in] mode The blending mode.
 141    */
 142   void SetBlendMode( BlendingMode::Type mode );
 143
 144   /**
 145    * @brief Retrieves the blending mode.
 146    *
 147    * @return The blending mode, one of BlendingMode::OFF, BlendingMode::AUTO or BlendingMode::ON.
 148    */
 149   BlendingMode::Type GetBlendMode() const;
 150
 151   /**
 152    * @brief Specify the pixel arithmetic used when the actor is blended.
 153    *
 154    * @param[in] srcFactorRgba Specifies how the red, green, blue, and alpha source blending factors are computed.
 155    * The options are BlendingFactor::ZERO, ONE, SRC_COLOR, ONE_MINUS_SRC_COLOR, DST_COLOR, ONE_MINUS_DST_COLOR,
 156    * SRC_ALPHA, ONE_MINUS_SRC_ALPHA, DST_ALPHA, ONE_MINUS_DST_ALPHA, CONSTANT_COLOR, ONE_MINUS_CONSTANT_COLOR,
 157    * GL_CONSTANT_ALPHA, GL_ONE_MINUS_CONSTANT_ALPHA, and GL_SRC_ALPHA_SATURATE.
 158    *
 159    * @param[in] destFactorRgba Specifies how the red, green, blue, and alpha destination blending factors are computed.
 160    * The options are BlendingFactor::ZERO, ONE, SRC_COLOR, ONE_MINUS_SRC_COLOR, DST_COLOR, ONE_MINUS_DST_COLOR,
 161    * SRC_ALPHA, ONE_MINUS_SRC_ALPHA, DST_ALPHA, ONE_MINUS_DST_ALPHA, CONSTANT_COLOR, ONE_MINUS_CONSTANT_COLOR,
 162    * GL_CONSTANT_ALPHA, and GL_ONE_MINUS_CONSTANT_ALPHA.
 163    */
 164   void SetBlendFunc( BlendingFactor::Type srcFactorRgba, BlendingFactor::Type destFactorRgba );
 165
 166   /**
 167    * @brief Specify the pixel arithmetic used when the actor is blended.
 168    *
 169    * @param[in] srcFactorRgb Specifies how the red, green, and blue source blending factors are computed.
 170    * The options are BlendingFactor::ZERO, ONE, SRC_COLOR, ONE_MINUS_SRC_COLOR, DST_COLOR, ONE_MINUS_DST_COLOR,
 171    * SRC_ALPHA, ONE_MINUS_SRC_ALPHA, DST_ALPHA, ONE_MINUS_DST_ALPHA, CONSTANT_COLOR, ONE_MINUS_CONSTANT_COLOR,
 172    * GL_CONSTANT_ALPHA, GL_ONE_MINUS_CONSTANT_ALPHA, and GL_SRC_ALPHA_SATURATE.
 173    *
 174    * @param[in] destFactorRgb Specifies how the red, green, blue, and alpha destination blending factors are computed.
 175    * The options are BlendingFactor::ZERO, ONE, SRC_COLOR, ONE_MINUS_SRC_COLOR, DST_COLOR, ONE_MINUS_DST_COLOR,
 176    * SRC_ALPHA, ONE_MINUS_SRC_ALPHA, DST_ALPHA, ONE_MINUS_DST_ALPHA, CONSTANT_COLOR, ONE_MINUS_CONSTANT_COLOR,
 177    * GL_CONSTANT_ALPHA, and GL_ONE_MINUS_CONSTANT_ALPHA.
 178    *
 179    * @param[in] srcFactorAlpha Specifies how the alpha source blending factor is computed.
 180    * The options are the same as for srcFactorRgb.
 181    *
 182    * @param[in] destFactorAlpha Specifies how the alpha source blending factor is computed.
 183    * The options are the same as for destFactorRgb.
 184    */
 185   void SetBlendFunc( BlendingFactor::Type srcFactorRgb,   BlendingFactor::Type destFactorRgb,
 186                      BlendingFactor::Type srcFactorAlpha, BlendingFactor::Type destFactorAlpha );
 187
 188   /**
 189    * @brief Query the pixel arithmetic used when the actor is blended.
 190    *
 191    * @param[out] srcFactorRgb Specifies how the red, green, blue, and alpha source blending factors are computed.
 192    * @param[out] destFactorRgb Specifies how the red, green, blue, and alpha destination blending factors are computed.
 193    * @param[out] srcFactorAlpha Specifies how the red, green, blue, and alpha source blending factors are computed.
 194    * @param[out] destFactorAlpha Specifies how the red, green, blue, and alpha destination blending factors are computed.
 195    */
 196   void GetBlendFunc( BlendingFactor::Type& srcFactorRgb,   BlendingFactor::Type& destFactorRgb,
 197                      BlendingFactor::Type& srcFactorAlpha, BlendingFactor::Type& destFactorAlpha ) const;
 198
 199   /**
 200    * @brief Specify the equation used when the actor is blended.
 201    *
 202    * The options are BlendingEquation::ADD, SUBTRACT, or REVERSE_SUBTRACT.
 203    * @param[in] equationRgba The equation used for combining red, green, blue, and alpha components.
 204    */
 205   void SetBlendEquation( BlendingEquation::Type equationRgba );
 206
 207   /**
 208    * @brief Specify the equation used when the actor is blended.
 209    *
 210    * @param[in] equationRgb The equation used for combining red, green, and blue components.
 211    * @param[in] equationAlpha The equation used for combining the alpha component.
 212    * The options are BlendingEquation::ADD, SUBTRACT, or REVERSE_SUBTRACT.
 213    */
 214   void SetBlendEquation( BlendingEquation::Type equationRgb, BlendingEquation::Type equationAlpha );
 215
 216   /**
 217    * @brief Query the equation used when the actor is blended.
 218    *
 219    * @param[out] equationRgb The equation used for combining red, green, and blue components.
 220    * @param[out] equationAlpha The equation used for combining the alpha component.
 221    */
 222   void GetBlendEquation( BlendingEquation::Type& equationRgb, BlendingEquation::Type& equationAlpha ) const;
 223
 224   /**
 225    * @brief Specify the color used when the actor is blended; the default is Vector4::ZERO.
 226    *
 227    * @param[in] color The blend color.
 228    */
 229   void SetBlendColor( const Vector4& color );
 230
 231   /**
 232    * @brief Query the color used when the actor is blended.
 233    *
 234    * @return The blend color.
 235    */
 236   const Vector4& GetBlendColor() const;
 237
 238   /**
 239    * @brief Sets the filtering mode.
 240    *
 241    * Possible values are: FilterMode::NEAREST and FilterMode::LINEAR. Default is FilterMode::LINEAR.
 242    *
 243    * <ul>
 244    *   <li> \e NEAREST Use nearest filtering
 245    *   <li> \e LINEAR Use linear filtering
 246    * </ul>
 247    *
 248    * @param[in] minFilter The minification filtering mode.
 249    * @param[in] magFilter The magnification filtering mode.
 250    */
 251   void SetFilterMode( FilterMode::Type minFilter, FilterMode::Type magFilter );
 252
 253   /**
 254    * @brief Retrieves the filtering mode.
 255    *
 256    * @param[out] minFilter The return minification value
 257    * @param[out] magFilter The return magnification value
 258    */
 259   void GetFilterMode( FilterMode::Type& minFilter, FilterMode::Type& magFilter) const;
 260
 261   /**
 262    * @brief Sets the shader effect for the RenderableActor.
 263    *
 264    * Shader effects provide special effects like ripple and bend.
 265    * Setting a shader effect removes any shader effect previously set by SetShaderEffect.
 266    * @pre The actor has been initialized.
 267    * @pre effect has been initialized.
 268    * @param [in] effect The shader effect.
 269    */
 270   void SetShaderEffect( ShaderEffect effect );
 271
 272   /**
 273    * @brief Retrieve the custom shader effect for the RenderableActor.
 274    * If default shader is used an empty handle is returned.
 275    *
 276    * @pre The Actor has been initialized.
 277    * @return The shader effect
 278    */
 279   ShaderEffect GetShaderEffect() const;
 280
 281   /**
 282    * @brief Removes the current shader effect.
 283    *
 284    * @pre The Actor has been initialized.
 285    */
 286   void RemoveShaderEffect();
 287
 288 public: // Not intended for application developers
 289
 290   /**
 291    * @brief This constructor is used by Dali New() methods
 292    *
 293    * @param [in] actor A pointer to a newly allocated Dali resource
 294    */
 295   explicit DALI_INTERNAL RenderableActor(Internal::RenderableActor* actor);
 296 };
 297
 298 /**
 299  * @brief Sets the shader effect for all RenderableActors in a tree of Actors.
 300  *
 301  * @see RenderableActor::SetShaderEffect
 302  *
 303  * @param [in] actor root of a tree of actors.
 304  * @param [in] effect The shader effect.
 305  */
 306 DALI_IMPORT_API void SetShaderEffectRecursively( Actor actor, ShaderEffect effect );
 307
 308 /**
 309  * @brief Removes the shader effect from all RenderableActors in a tree of Actors.
 310  *
 311  * @see RenderableActor::RemoveShaderEffect
 312  *
 313  * @param [in] actor root of a tree of actors.
 314  */
 315 DALI_IMPORT_API void RemoveShaderEffectRecursively( Actor actor );
 316
 317 } // namespace Dali
 318
 319 #endif // __DALI_RENDERABLE_ACTOR_H__