Add 'ExclusiveArch: armv7l' limit build to arm architecture
[platform/core/uifw/dali-toolkit.git] / optional / dali-toolkit / public-api / shader-effects / motion-blur-effect.h
1 #ifndef __DALI_TOOLKIT_SHADER_EFFECT_MOTION_BLUR_H__
2 #define __DALI_TOOLKIT_SHADER_EFFECT_MOTION_BLUR_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/dali.h>
24
25 namespace Dali DALI_IMPORT_API
26 {
27
28 namespace Toolkit
29 {
30
31 /**
32  *
33  * Class for motion blur shader that works on a per object basis. Objects will
34  * blur when they move, or if the camera moves. Can be applied to ImageActor or
35  * TextActor only.
36  *
37  * Usage example:-
38  *
39  * // Create shader used for doing motion blur\n
40  * MotionBlurEffect MotionBlurEffect = MotionBlurEffect::New();
41  *
42  * // set actor shader to the blur one\n
43  * Actor Actor = Actor::New( ... );\n
44  * Actor.SetShaderEffect( MotionBlurEffect );
45  *
46  */
47 class MotionBlurEffect : public ShaderEffect
48 {
49
50 public:
51
52   /**
53    * Create an uninitialized MotionBlurEffect; this can be initialized with MotionBlurEffect::New()
54    * Calling member functions with an uninitialized Dali::Object is not allowed.
55    */
56   MotionBlurEffect();
57
58   /**
59    * Virtual destructor.
60    */
61   virtual ~MotionBlurEffect();
62
63   /**
64    * Create an initialized MotionBlurEffect
65    * The number of texture samples taken along the motion velocity vector of the
66    * actor, producing the blur, is set to a default of 8.
67    * @return A handle to a newly allocated Dali resource.
68    */
69   static MotionBlurEffect New();
70
71   /**
72    * Create a  MotionBlurEffect and attach it to the specified actor
73    * The number of texture samples taken along the motion velocity vector of the
74    * actor, producing the blur, is set to a default of 8.
75    * @return A handle to a newly allocated Dali resource.
76    */
77   static MotionBlurEffect Apply( Actor handle );
78
79   /**
80    * Create an initialized MotionBlurEffect
81    * @param numBlurSamples The number of texture samples taken along the motion
82    * velocity vector of the actor, producing the blur. A higher number gives a
83    * smoother blur but costs more in terms of performance.
84    * @return A handle to a newly allocated Dali resource.
85    */
86   static MotionBlurEffect New( const unsigned int numBlurSamples );
87
88   /**
89    * Set texcoord scale property. This scales the offset for texture samples
90    * along the motion velocity vector. A smaller value means the samples will
91    * be spaced closer, larger value further apart. User should use this to get
92    * the blur to look contiguous, i.e. the blur texels should not be too widely
93    * spread, with gaps in between. Default 0.125.
94    * @param texcoordScale The scaling factor that multiplies the motion velocity vector for texture lookups.
95    */
96   void SetTexcoordScale( float texcoordScale );
97
98   /**
99    * Set geometry stretch factor property. This scales the amount the
100    * geometry stretches backwards along the motion velocity vector. A smaller
101    * value means the geometry stretches less, larger it stretches more. User
102    * should use this to get the blur to 'bleed' into areas outside the physical
103    * bounds of the actor. We need this as the blur is only applied inside the
104    * bounds of the actor, but you would expect motion blur trails where the
105    * actor was previously but is there no longer. Default 0.05.
106    * @param scalingFactor The scaling factor that extrudes the geometry backwards along the motion velocity vector.
107    */
108   void SetGeometryStretchFactor( float scalingFactor );
109
110   /**
111    * Set speed scaling factor property. This takes the magnitude of the motion
112    * velocity vector and scales it to produce a value which is used to fade the
113    * blur in / out with the speed that the actor is moving. As the blur fades
114    * in, more of the blur is visible and less of the original actor, and vice
115    * versa.
116    * This value is also used to control how much to fade the actor near the
117    * edges, based on the speed the actor is moving. When the actor is at rest
118    * this is not applied. Default 0.5.
119    * @param scalingFactor The scaling factor that controls the edge fade / blur fade of the actor.
120    */
121   void SetSpeedScalingFactor( float scalingFactor );
122
123   /**
124    * Set the displacement from the centre of the actor that the actor will start
125    * to fade towards its edges. This is used to prevent an unsightly hard edge
126    * between the blurred actor and the scene. Depends on the values of the
127    * vertices in the vertex stream. When the actor is at rest this is not applied.
128    * Default 0.25, which is half way towards the edge for an ImageRenderer::QUAD.
129    * @param displacement The displacement from the centre of the actor that the actor will start to edge fade.
130    */
131   void SetObjectFadeStart( Vector2 displacement );
132
133   /**
134    * Set the displacement from the centre of the actor that the actor will
135    * finish fading towards its edges. This is used to prevent an unsightly hard
136    * edge between the blurred actor and the scene. Depends on the values of the
137    * vertices in the vertex stream. When the actor is at rest this is not applied.
138    * Default 0.5, which is all the way towards the edge for an ImageRenderer::QUAD.
139    * @param displacement The displacement from the centre of the actor that the actor will finish edge fading.
140    */
141   void SetObjectFadeEnd( Vector2 displacement );
142
143   /**
144    * Set a global scaler applied to the alpha of the actor. Used to make the
145    * blurred actor a bit more subtle (helps to hide discontinuities due to
146    * limited number of texture samples) and reveal a bit of the background
147    * behind it as it moves. When the actor is at rest this is not applied. Default 0.75.
148    * @param alphaScale The scaling factor which multiplies the alpha of each pixel of the actor.
149    */
150   void SetAlphaScale( float alphaScale );
151
152   /**
153    * Set the number of texture samples to be taken. Increasing the number of
154    * samples provides better quality at the cost of performance.
155    * @param numSamples The number of texture samples to be taken. Default is 8.
156    */
157   void SetNumSamples( int numSamples );
158
159   /**
160    * Get the name for the texcoord scale property. Useful for animation.
161    * @return A std::string containing the property name
162    */
163   const std::string& GetTexcoordScalePropertyName() const;
164
165   /**
166    * Get the name for the geometry stretching property. Useful for animation.
167    * @return A std::string containing the property name
168    */
169   const std::string& GetGeometryStretchFactorPropertyName() const;
170
171   /**
172    * Get the name for the speed scaling property. Useful for animation.
173    * @return A std::string containing the property name
174    */
175   const std::string& GetSpeedScalingFactorPropertyName() const;
176
177   /**
178    * Get the name for the fade start property. Useful for animation.
179    * @return A std::string containing the property name
180    */
181   const std::string& GetObjectFadeStartPropertyName() const;
182
183   /**
184    * Get the name for the fade end property. Useful for animation.
185    * @return A std::string containing the property name
186    */
187   const std::string& GetObjectFadeEndPropertyName() const;
188
189   /**
190    * Get the name for the alpha scale property. Useful for animation.
191    * @return A std::string containing the property name
192    */
193   const std::string& GetAlphaScalePropertyName() const;
194
195   /**
196    * Downcast an ShaderEffect handle to MotionBlurEffect handle. If handle points to a MotionBlurEffect object the
197    * downcast produces valid handle. If not the returned handle is left uninitialized.
198    * @param[in] handle to a ShaderEffect
199    * @return handle to a MotionBlurEffect object or an uninitialized handle
200    */
201   static MotionBlurEffect DownCast( ShaderEffect handle );
202
203 private:
204   // Not intended for application developers
205   MotionBlurEffect( ShaderEffect handle );
206 };
207
208 }
209
210 }
211
212 #endif //#ifndef __DALI_TOOLKIT_SHADER_EFFECT_MOTION_BLUR_H__
213