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