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

   1 #ifndef __DALI_RENDERABLE_ACTOR_H__
   2 #define __DALI_RENDERABLE_ACTOR_H__
   3
   4 /*
   5  * Copyright (c) 2015 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] srcFactorRgb Specifies how the red, green, and blue 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] destFactorRgb 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    * @param[in] srcFactorAlpha Specifies how the alpha source blending factor is computed.
 164    * The options are the same as for srcFactorRgb.
 165    *
 166    * @param[in] destFactorAlpha Specifies how the alpha source blending factor is computed.
 167    * The options are the same as for destFactorRgb.
 168    */
 169   void SetBlendFunc( BlendingFactor::Type srcFactorRgb,   BlendingFactor::Type destFactorRgb,
 170                      BlendingFactor::Type srcFactorAlpha, BlendingFactor::Type destFactorAlpha );
 171
 172   /**
 173    * @brief Query the pixel arithmetic used when the actor is blended.
 174    *
 175    * @param[out] srcFactorRgb Specifies how the red, green, blue, and alpha source blending factors are computed.
 176    * @param[out] destFactorRgb Specifies how the red, green, blue, and alpha destination blending factors are computed.
 177    * @param[out] srcFactorAlpha Specifies how the red, green, blue, and alpha source blending factors are computed.
 178    * @param[out] destFactorAlpha Specifies how the red, green, blue, and alpha destination blending factors are computed.
 179    */
 180   void GetBlendFunc( BlendingFactor::Type& srcFactorRgb,   BlendingFactor::Type& destFactorRgb,
 181                      BlendingFactor::Type& srcFactorAlpha, BlendingFactor::Type& destFactorAlpha ) const;
 182
 183   /**
 184    * @brief Sets the filtering mode.
 185    *
 186    * Possible values are: FilterMode::NEAREST and FilterMode::LINEAR. Default is FilterMode::LINEAR.
 187    *
 188    * <ul>
 189    *   <li> \e NEAREST Use nearest filtering
 190    *   <li> \e LINEAR Use linear filtering
 191    * </ul>
 192    *
 193    * @param[in] minFilter The minification filtering mode.
 194    * @param[in] magFilter The magnification filtering mode.
 195    */
 196   void SetFilterMode( FilterMode::Type minFilter, FilterMode::Type magFilter );
 197
 198   /**
 199    * @brief Retrieves the filtering mode.
 200    *
 201    * @param[out] minFilter The return minification value
 202    * @param[out] magFilter The return magnification value
 203    */
 204   void GetFilterMode( FilterMode::Type& minFilter, FilterMode::Type& magFilter) const;
 205
 206   /**
 207    * @brief Sets the shader effect for the RenderableActor.
 208    *
 209    * Shader effects provide special effects like ripple and bend.
 210    * Setting a shader effect removes any shader effect previously set by SetShaderEffect.
 211    * @pre The actor has been initialized.
 212    * @pre effect has been initialized.
 213    * @param [in] effect The shader effect.
 214    */
 215   void SetShaderEffect( ShaderEffect effect );
 216
 217   /**
 218    * @brief Retrieve the custom shader effect for the RenderableActor.
 219    * If default shader is used an empty handle is returned.
 220    *
 221    * @pre The Actor has been initialized.
 222    * @return The shader effect
 223    */
 224   ShaderEffect GetShaderEffect() const;
 225
 226   /**
 227    * @brief Removes the current shader effect.
 228    *
 229    * @pre The Actor has been initialized.
 230    */
 231   void RemoveShaderEffect();
 232
 233 public: // Not intended for application developers
 234
 235   /**
 236    * @brief This constructor is used by Dali New() methods
 237    *
 238    * @param [in] actor A pointer to a newly allocated Dali resource
 239    */
 240   explicit DALI_INTERNAL RenderableActor(Internal::RenderableActor* actor);
 241 };
 242
 243 /**
 244  * @brief Sets the shader effect for all RenderableActors in a tree of Actors.
 245  *
 246  * @see RenderableActor::SetShaderEffect
 247  *
 248  * @param [in] actor root of a tree of actors.
 249  * @param [in] effect The shader effect.
 250  */
 251 DALI_IMPORT_API void SetShaderEffectRecursively( Actor actor, ShaderEffect effect );
 252
 253 /**
 254  * @brief Removes the shader effect from all RenderableActors in a tree of Actors.
 255  *
 256  * @see RenderableActor::RemoveShaderEffect
 257  *
 258  * @param [in] actor root of a tree of actors.
 259  */
 260 DALI_IMPORT_API void RemoveShaderEffectRecursively( Actor actor );
 261
 262 } // namespace Dali
 263
 264 #endif // __DALI_RENDERABLE_ACTOR_H__