1 #ifndef __DALI_TOOLKIT_SHADOW_VIEW_H__
2 #define __DALI_TOOLKIT_SHADOW_VIEW_H__
5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
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
11 // http://floralicense.org/license/
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.
23 #include <dali-toolkit/public-api/controls/control.h>
25 namespace Dali DALI_IMPORT_API
31 namespace Internal DALI_INTERNAL
35 * ShadowView implementation class
39 } // namespace Internal
43 * ShadowView is a class for applying shadows to objects present in the view.
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.
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.
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.
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
66 * ShadowView shadowView = ShadowView::New();
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
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);
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);
87 * // Start rendering the ShadowView
88 * Stage::GetCurrent().Add(ShadowPlane);
89 * shadowView.Activate();
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();
98 * // Stop rendering the ShadowView
99 * Stage::GetCurrent().Remove(shadowView);
100 * shadowView.Deactivate();
103 class ShadowView : public Control
108 * Create an uninitialized ShadowView; this can be initialized with ShadowView::New()
109 * Calling member functions with an uninitialized Dali::Object is not allowed.
114 * Copy constructor. Creates another handle that points to the same real object
116 ShadowView(const ShadowView& handle);
119 * Assignment operator. Changes this handle to point to another real object
121 ShadowView& operator=(const ShadowView& view);
124 * Virtual destructor.
126 virtual ~ShadowView();
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
134 static ShadowView DownCast( BaseHandle handle );
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
140 static ShadowView New();
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
150 static ShadowView New(float downsampleWidthScale, float downsampleHeightScale);
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.
166 void Add(Actor child);
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.
176 void Remove(Actor child);
179 * Set the Shadow Plane for the shadow effect.
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
187 void SetShadowPlane(ImageActor shadowPlane);
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.
195 void SetPointLight(Actor pointLight);
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,
204 void SetPointLightFieldOfView(float fieldOfView);
208 * @param[in] color The shadow color
210 void SetShadowColor(Vector4 color);
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.
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.
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( ... )
229 Property::Index GetBlurStrengthPropertyIndex() const;
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( ... )
236 Property::Index GetShadowColorPropertyIndex() const;
242 * Creates a handle using the Toolkit::Internal implementation.
243 * @param[in] implementation The UI Control implementation.
245 ShadowView( Internal::ShadowView& implementation );
248 * Allows the creation of this UI Control from an Internal::CustomActor pointer.
249 * @param[in] internal A pointer to the internal CustomActor.
251 ShadowView( Dali::Internal::CustomActor* internal );
254 } // namespace Toolkit
258 #endif // __DALI_TOOLKIT_SHADOW_VIEW_H__