optional/dali-toolkit/public-api/controls/shadow-view/shadow-view.h

   1 #ifndef __DALI_TOOLKIT_SHADOW_VIEW_H__
   2 #define __DALI_TOOLKIT_SHADOW_VIEW_H__
   3
   4 //
   5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
   6 //
   7 // Licensed under the Flora License, Version 1.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://floralicense.org/license/
  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 // EXTERNAL INCLUDES
  21
  22 // INTERNAL INCLUDES
  23 #include <dali-toolkit/public-api/controls/control.h>
  24
  25 namespace Dali DALI_IMPORT_API
  26 {
  27
  28 namespace Toolkit
  29 {
  30
  31 namespace Internal DALI_INTERNAL
  32 {
  33
  34 /**
  35  * ShadowView implementation class
  36  */
  37 class ShadowView;
  38
  39 } // namespace Internal
  40
  41 /**
  42  *
  43  * ShadowView is a class for applying shadows to objects present in the view.
  44  *
  45  * Basic idea:-
  46  *
  47  * 1) The ShadowView object will render all its child actors offscreen from the light's point of view projected on to the shadow plane in a seperate render task.\n
  48  * 2) The ShadowView object then blurs the result of step 1), using a two pass separated Gaussian blur.\n
  49  * 3) The ShadowView object gets rendered automatically in the default render task along with it's children.
  50  *
  51  * Fundamentally, the ShadowView is simply an Actor in the normal actor tree that affects all of its children. It should be added to your Actor tree and manipulated in the
  52  * normal way. It can be considered a 'portal' in the sense that all child actors are clipped to the ShadowView actor bounds.
  53  *
  54  * LIMITATIONS:
  55  * The ShadowView is intended to provide simple planar projection shadows, Which means it needs a flat plane to cast shadows. So Shadows can't be cast on other objects.
  56  *
  57  * ************\n
  58  * NB: It is essential to remove the ShadowView from the stage and also to call Deactivate() on it when you are not using it. This will ensure that resources are freed and
  59  * rendering stops.\n
  60  * ************\n
  61  *
  62  * Usage example:-
  63  *
  64  *  @code
  65  *  // initialise\n
  66  *  ShadowView shadowView = ShadowView::New();
  67  *
  68  *  // create and add some visible actors to the ShadowView, all these child actors will therefore cast a shadow.
  69  *  Image image = Image::New(...);
  70  *  ImageActor imageActor = ImageActor::New(image);
  71  *  imageActor.SetParentOrigin( ParentOrigin::CENTER );
  72  *  imageActor.SetAnchorPoint( AnchorPoint::CENTER );
  73  *  shadowView.Add(imageActor);\n Add the renderable actor to the shadow view
  74  *
  75  *  ImageActor shadowPlane = ImageActor::New(); //This will be the shadow plane
  76  *  shadowPlane.SetParentOrigin( ParentOrigin::CENTER );
  77  *  shadowPlane.SetAnchorPoint( AnchorPoint::CENTER );
  78  *  shadowPlane.SetSize(700.0f, 700.0f);
  79  *  shadowPlane.SetPosition( Vector3(0.0f, 0.0f, -30.0f) ); //Just behind the image actor.
  80  *  shadowPlane.SetShadowPlane(ShadowPlane);
  81  *
  82  *  Actor pointLight = Actor::New(); // This will be the light source
  83  *  pointLight.SetPosition(300.0f, 250.0f, 600.0f);
  84  *  Stage::GetCurrent().Add(pointLight);
  85  *  shadowView.SetPointLight(pointLight);
  86  *
  87  *  // Start rendering the ShadowView
  88  *  Stage::GetCurrent().Add(ShadowPlane);
  89  *  shadowView.Activate();
  90  *  ...
  91  *
  92  *  // animate the strength of the blur - this can fade between no blur and full blur. See GetBlurStrengthPropertyIndex().
  93  *  Animation blurAnimation = Animation::New( ... );
  94  *  blurAnimation.AnimateTo( Property( shadowView, shadowView.GetBlurStrengthPropertyIndex() ), ... );
  95  *  blurAnimation.Play();
  96  *
  97  *  ...
  98  *  // Stop rendering the ShadowView
  99  *  Stage::GetCurrent().Remove(shadowView);
 100  *  shadowView.Deactivate();
 101  *  @endcode
 102  */
 103 class ShadowView : public Control
 104 {
 105 public:
 106
 107   /**
 108    * Create an uninitialized ShadowView; this can be initialized with ShadowView::New()
 109    * Calling member functions with an uninitialized Dali::Object is not allowed.
 110    */
 111   ShadowView();
 112
 113   /**
 114    * Copy constructor. Creates another handle that points to the same real object
 115    */
 116   ShadowView(const ShadowView& handle);
 117
 118   /**
 119    * Assignment operator. Changes this handle to point to another real object
 120    */
 121   ShadowView& operator=(const ShadowView& view);
 122
 123   /**
 124    * Virtual destructor.
 125    */
 126   virtual ~ShadowView();
 127
 128   /**
 129    * Downcast an Object handle to ShadowView. If handle points to a ShadowView the
 130    * downcast produces valid handle. If not the returned handle is left uninitialized.
 131    * @param[in] handle Handle to an object
 132    * @return handle to a ShadowView or an uninitialized handle
 133    */
 134   static ShadowView DownCast( BaseHandle handle );
 135
 136   /**
 137   * Create an initialized ShadowView. Add children and call SetShadowPlane to make shadows visible\n
 138   * @return A handle to a newly allocated Dali resource
 139   */
 140   static ShadowView New();
 141
 142   /**
 143    * Create an initialized ShadowView. Add children and call SetShadowPlane to make shadows visible\n
 144    * @param[in] downsampleWidthScale The width scale factor applied during the blur process, scaling the size of the source image to the size of the final blurred image output.
 145    * Useful for downsampling - trades visual quality for processing speed. A value of 1.0f results in no scaling applied.
 146    * @param[in] downsampleHeightScale The height scale factor applied during the blur process, scaling the size of the source image to the size of the final blurred image output.
 147    * Useful for downsampling - trades visual quality for processing speed. A value of 1.0f results in no scaling applied.
 148    * @return A handle to a newly allocated Dali resource
 149    */
 150   static ShadowView New(float downsampleWidthScale, float downsampleHeightScale);
 151
 152   /**
 153    * Adds a child Actor to this Actor.
 154    * NOTE! if the child already has a parent, it will be removed from old parent
 155    * and reparented to this actor. This may change childs position, color, shader effect,
 156    * scale etc as it now inherits them from this actor
 157    * @pre This Actor (the parent) has been initialized.
 158    * @pre The child actor has been initialized.
 159    * @pre The child actor is not the same as the parent actor.
 160    * @pre The actor is not the Root actor
 161    * @param [in] child The child.
 162    * @post The child will be referenced by its parent. This means that the child will be kept alive,
 163    * even if the handle passed into this method is reset or destroyed.
 164    * @post This may invalidate ActorContainer iterators.
 165    */
 166   void Add(Actor child);
 167
 168   /**
 169    * Removes a child Actor from this Actor.
 170    * If the actor was not a child of this actor, this is a no-op.
 171    * @pre This Actor (the parent) has been initialized.
 172    * @pre The child actor is not the same as the parent actor.
 173    * @param [in] child The child.
 174    * @post This may invalidate ActorContainer iterators.
 175    */
 176   void Remove(Actor child);
 177
 178   /**
 179    * Set the Shadow Plane for the shadow effect.
 180    *
 181    * @param[in] shadowPlane An actor representing the shadow
 182    * plane. The position of the actor represents the origin of the
 183    * plane, and the orientation of the actor represents the direction
 184    * of the plane normal. Make the plane sufficiently large if the shadows are
 185    * clipped.
 186    */
 187   void SetShadowPlane(ImageActor shadowPlane);
 188
 189   /**
 190    * Set the Point Light for the shadow effect. This is usually NOT a renderable actor.
 191    * The orientation of the actor is not considered for the shadow calculation.
 192    * @param[in] pointLight An actor representing the location of the
 193    * directionless light source that casts the shadow.
 194    */
 195   void SetPointLight(Actor pointLight);
 196
 197   /**
 198    * Set the field of view of the point light source. This will be used by an additional
 199    * internal camera to look at the scene form the light source. If you notice any aritifacts
 200    * when the light position is near to the object, Increase the field of view.
 201    * @param[in] fieldOfView  New field of view in radians, Typical values are  Math::PI / 4.0f,
 202    *  Math::PI / 2.0f
 203    */
 204   void SetPointLightFieldOfView(float fieldOfView);
 205
 206   /**
 207    * Set shadow color.
 208    * @param[in] color The shadow color
 209    */
 210   void SetShadowColor(Vector4 color);
 211
 212   /**
 213    * Start rendering the ShadowView. Must be called after you Add() it to the stage.
 214    * @pre This Actor has been added to the stage.
 215    */
 216   void Activate();
 217
 218   /**
 219    * Stop rendering the ShadowView. Must be called after you Remove() it from the stage.
 220    * @pre This Actor has been removed from the stage.
 221    */
 222   void Deactivate();
 223
 224   /**
 225    * Get the property index that controls the strength of the blur applied to the shadow. Useful for animating this property.
 226    * This property represents a value in the range [0.0 - 1.0] where 0.0 is no blur and 1.0 is full blur. Default 0.2.
 227    * @return The property index that can be used with e.g. AnimateTo( ... )
 228    */
 229   Property::Index GetBlurStrengthPropertyIndex() const;
 230
 231   /**
 232    * Get the property index that controls the color of the shadow. Useful for animating this property.
 233    * This property represents a value in the Vector4 format. Default color value is Vector4(0.2f, 0.2f, 0.2f, 0.8f) (i.e grey color).
 234    * @return The property index that can be used with e.g. AnimateTo( ... )
 235    */
 236   Property::Index GetShadowColorPropertyIndex() const;
 237
 238
 239 public:
 240
 241   /**
 242    * Creates a handle using the Toolkit::Internal implementation.
 243    * @param[in]  implementation  The UI Control implementation.
 244    */
 245   ShadowView( Internal::ShadowView& implementation );
 246
 247   /**
 248    * Allows the creation of this UI Control from an Internal::CustomActor pointer.
 249    * @param[in]  internal  A pointer to the internal CustomActor.
 250    */
 251   ShadowView( Dali::Internal::CustomActor* internal );
 252 };
 253
 254 } // namespace Toolkit
 255
 256 } // namespace Dali
 257
 258 #endif // __DALI_TOOLKIT_SHADOW_VIEW_H__