dali-toolkit/devel-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) 2022 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-toolkit/public-api/controls/control.h>
  23
  24 namespace Dali
  25 {
  26 namespace Toolkit
  27 {
  28 namespace Internal DALI_INTERNAL
  29 {
  30 /**
  31  * ShadowView implementation class
  32  */
  33 class ShadowView;
  34
  35 } // namespace DALI_INTERNAL
  36
  37 /**
  38  *
  39  * ShadowView is a class for applying shadows to objects present in the view.
  40  *
  41  * Basic idea:-
  42  *
  43  * 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
  44  * 2) The ShadowView object then blurs the result of step 1), using a two pass separated Gaussian blur.\n
  45  * 3) The ShadowView object gets rendered automatically in the default render task along with it's children.
  46  *
  47  * 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
  48  * normal way. It can be considered a 'portal' in the sense that all child actors are clipped to the ShadowView actor bounds.
  49  *
  50  * LIMITATIONS:
  51  * 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.
  52  *
  53  * ************\n
  54  * 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
  55  * rendering stops.\n
  56  * ************\n
  57  *
  58  * Usage example:-
  59  *
  60  *  @code
  61  *  // initialise\n
  62  *  ShadowView shadowView = ShadowView::New();
  63  *
  64  *  // create and add some visible actors to the ShadowView, all these child actors will therefore cast a shadow.
  65  *  Image image = Image::New(...);
  66  *  ImageView imageView = ImageView::New(image);
  67  *  imageView.SetProperty( Actor::Property::PARENT_ORIGIN, ParentOrigin::CENTER );
  68  *  imageView.SetProperty( Actor::Property::ANCHOR_POINT, AnchorPoint::CENTER );
  69  *  shadowView.Add(imageView);\n Add the renderable actor to the shadow view
  70  *
  71  *  ImageView shadowPlaneBg = ImageView::New(); //This will be the shadow plane
  72  *  shadowPlaneBg.SetProperty( Actor::Property::PARENT_ORIGIN, ParentOrigin::CENTER );
  73  *  shadowPlaneBg.SetProperty( Actor::Property::ANCHOR_POINT, AnchorPoint::CENTER );
  74  *  shadowPlaneBg.SetProperty( Actor::Property::SIZE, Vector2(700.0f, 700.0f) );
  75  *  shadowPlaneBg.SetProperty( Actor::Property::POSITION, Vector3(0.0f, 0.0f, -30.0f) ); //Just behind the image view.
  76  *  shadowView.SetShadowPlaneBackground(ShadowPlane);
  77  *
  78  *  Actor pointLight = Actor::New(); // This will be the light source
  79  *  pointLight.SetProperty( Actor::Property::POSITION, Vector3(300.0f, 250.0f, 600.0f) );
  80  *  Stage::GetCurrent().Add(pointLight);
  81  *  shadowView.SetPointLight(pointLight);
  82  *
  83  *  // Start rendering the ShadowView
  84  *  Stage::GetCurrent().Add(ShadowPlane);
  85  *  shadowView.Activate();
  86  *  ...
  87  *
  88  *  // animate the strength of the blur - this can fade between no blur and full blur. See GetBlurStrengthPropertyIndex().
  89  *  Animation blurAnimation = Animation::New( ... );
  90  *  blurAnimation.AnimateTo( Property( shadowView, shadowView.GetBlurStrengthPropertyIndex() ), ... );
  91  *  blurAnimation.Play();
  92  *
  93  *  ...
  94  *  // Stop rendering the ShadowView
  95  *  Stage::GetCurrent().Remove(shadowView);
  96  *  shadowView.Deactivate();
  97  *  @endcode
  98  */
  99 class DALI_TOOLKIT_API ShadowView : public Control
 100 {
 101 public:
 102   /**
 103    * Create an uninitialized ShadowView; this can be initialized with ShadowView::New()
 104    * Calling member functions with an uninitialized Dali::Object is not allowed.
 105    */
 106   ShadowView();
 107
 108   /**
 109    * Copy constructor. Creates another handle that points to the same real object
 110    * @param[in] handle to copy from
 111    */
 112   ShadowView(const ShadowView& handle);
 113
 114   /**
 115    * Assignment operator. Changes this handle to point to another real object
 116    * @param[in] handle to copy from
 117    * @return reference to this
 118    */
 119   ShadowView& operator=(const ShadowView& handle);
 120
 121   /**
 122    * Move constructor. Creates another handle that points to the same real object
 123    * @param[in] rhs to move from
 124    */
 125   ShadowView(ShadowView&& rhs);
 126
 127   /**
 128    * Move assignment operator. Changes this handle to point to another real object
 129    * @param[in] rhs to move from
 130    * @return reference to this
 131    */
 132   ShadowView& operator=(ShadowView&& rhs);
 133
 134   /**
 135    * @brief Destructor
 136    *
 137    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 138    */
 139   ~ShadowView();
 140
 141   /**
 142    * Downcast an Object handle to ShadowView. If handle points to a ShadowView the
 143    * downcast produces valid handle. If not the returned handle is left uninitialized.
 144    * @param[in] handle Handle to an object
 145    * @return handle to a ShadowView or an uninitialized handle
 146    */
 147   static ShadowView DownCast(BaseHandle handle);
 148
 149   /**
 150   * Create an initialized ShadowView. Add children and call SetShadowPlane to make shadows visible\n
 151   * @return A handle to a newly allocated Dali resource
 152   */
 153   static ShadowView New();
 154
 155   /**
 156    * Create an initialized ShadowView. Add children and call SetShadowPlane to make shadows visible\n
 157    * @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.
 158    * Useful for downsampling - trades visual quality for processing speed. A value of 1.0f results in no scaling applied.
 159    * @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.
 160    * Useful for downsampling - trades visual quality for processing speed. A value of 1.0f results in no scaling applied.
 161    * @return A handle to a newly allocated Dali resource
 162    */
 163   static ShadowView New(float downsampleWidthScale, float downsampleHeightScale);
 164
 165   /**
 166    * Set the Shadow Plane Background for the shadow effect.
 167    *
 168    * @param[in] shadowPlaneBackground An actor representing the shadow
 169    * plane. The position of the actor represents the origin of the
 170    * plane, and the orientation of the actor represents the direction
 171    * of the plane normal. Make the plane sufficiently large if the shadows are
 172    * clipped.
 173    */
 174   void SetShadowPlaneBackground(Actor shadowPlaneBackground);
 175
 176   /**
 177    * Set the Point Light for the shadow effect. This is usually NOT a renderable actor.
 178    * The orientation of the actor is not considered for the shadow calculation.
 179    * @param[in] pointLight An actor representing the location of the
 180    * directionless light source that casts the shadow.
 181    */
 182   void SetPointLight(Actor pointLight);
 183
 184   /**
 185    * Set the field of view of the point light source. This will be used by an additional
 186    * internal camera to look at the scene form the light source. If you notice any aritifacts
 187    * when the light position is near to the object, Increase the field of view.
 188    * @param[in] fieldOfView  New field of view in radians, Typical values are  Math::PI / 4.0f,
 189    *  Math::PI / 2.0f
 190    */
 191   void SetPointLightFieldOfView(float fieldOfView);
 192
 193   /**
 194    * Set shadow color.
 195    * @param[in] color The shadow color
 196    */
 197   void SetShadowColor(Vector4 color);
 198
 199   /**
 200    * Start rendering the ShadowView. Must be called after you Add() it to the stage.
 201    * @pre This Actor has been added to the stage.
 202    */
 203   void Activate();
 204
 205   /**
 206    * Stop rendering the ShadowView. Must be called after you Remove() it from the stage.
 207    * @pre This Actor has been removed from the stage.
 208    */
 209   void Deactivate();
 210
 211   /**
 212    * Get the property index that controls the strength of the blur applied to the shadow. Useful for animating this property.
 213    * 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.
 214    * @return The property index that can be used with e.g. AnimateTo( ... )
 215    */
 216   Dali::Property::Index GetBlurStrengthPropertyIndex() const;
 217
 218   /**
 219    * Get the property index that controls the color of the shadow. Useful for animating this property.
 220    * 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).
 221    * @return The property index that can be used with e.g. AnimateTo( ... )
 222    */
 223   Dali::Property::Index GetShadowColorPropertyIndex() const;
 224
 225 public:
 226   /**
 227    * Creates a handle using the Toolkit::Internal implementation.
 228    * @param[in]  implementation  The UI Control implementation.
 229    */
 230   DALI_INTERNAL ShadowView(Internal::ShadowView& implementation);
 231
 232   /**
 233    * Allows the creation of this UI Control from an Internal::CustomActor pointer.
 234    * @param[in]  internal  A pointer to the internal CustomActor.
 235    */
 236   explicit DALI_INTERNAL ShadowView(Dali::Internal::CustomActor* internal);
 237 };
 238
 239 } // namespace Toolkit
 240
 241 } // namespace Dali
 242
 243 #endif // DALI_TOOLKIT_SHADOW_VIEW_H