1 #ifndef __DALI_TOOLKIT_SHADER_EFFECT_MOTION_BLUR_H__
2 #define __DALI_TOOLKIT_SHADER_EFFECT_MOTION_BLUR_H__
5 * Copyright (c) 2015 Samsung Electronics Co., Ltd.
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
22 #include <dali/public-api/actors/image-actor.h>
23 #include <dali/public-api/shader-effects/shader-effect.h>
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
39 * // Create shader used for doing motion blur\n
40 * MotionBlurEffect MotionBlurEffect = MotionBlurEffect::New();
42 * // set actor shader to the blur one\n
43 * Actor Actor = Actor::New( ... );\n
44 * Actor.SetShaderEffect( MotionBlurEffect );
47 class DALI_IMPORT_API MotionBlurEffect : public ShaderEffect
53 * Create an uninitialized MotionBlurEffect; this can be initialized with MotionBlurEffect::New()
54 * Calling member functions with an uninitialized Dali::Object is not allowed.
61 * This is non-virtual since derived Handle types must not contain data or virtual methods.
66 * Create an initialized MotionBlurEffect
67 * The number of texture samples taken along the motion velocity vector of the
68 * actor, producing the blur, is set to a default of 8.
69 * @return A handle to a newly allocated Dali resource.
71 static MotionBlurEffect New();
74 * Create a MotionBlurEffect and attach it to the specified actor
75 * The number of texture samples taken along the motion velocity vector of the
76 * actor, producing the blur, is set to a default of 8.
77 * @param renderable actor to apply the effect to
78 * @return A handle to a newly allocated Dali resource.
80 static MotionBlurEffect Apply( ImageActor renderable );
83 * Create an initialized MotionBlurEffect
84 * @param numBlurSamples The number of texture samples taken along the motion
85 * velocity vector of the actor, producing the blur. A higher number gives a
86 * smoother blur but costs more in terms of performance.
87 * @param numBlurSamples to have
88 * @return A handle to a newly allocated Dali resource.
90 static MotionBlurEffect New( unsigned int numBlurSamples );
93 * Set texcoord scale property. This scales the offset for texture samples
94 * along the motion velocity vector. A smaller value means the samples will
95 * be spaced closer, larger value further apart. User should use this to get
96 * the blur to look contiguous, i.e. the blur texels should not be too widely
97 * spread, with gaps in between. Default 0.125.
98 * @param texcoordScale The scaling factor that multiplies the motion velocity vector for texture lookups.
100 void SetTexcoordScale( float texcoordScale );
103 * Set geometry stretch factor property. This scales the amount the
104 * geometry stretches backwards along the motion velocity vector. A smaller
105 * value means the geometry stretches less, larger it stretches more. User
106 * should use this to get the blur to 'bleed' into areas outside the physical
107 * bounds of the actor. We need this as the blur is only applied inside the
108 * bounds of the actor, but you would expect motion blur trails where the
109 * actor was previously but is there no longer. Default 0.05.
110 * @param scalingFactor The scaling factor that extrudes the geometry backwards along the motion velocity vector.
112 void SetGeometryStretchFactor( float scalingFactor );
115 * Set speed scaling factor property. This takes the magnitude of the motion
116 * velocity vector and scales it to produce a value which is used to fade the
117 * blur in / out with the speed that the actor is moving. As the blur fades
118 * in, more of the blur is visible and less of the original actor, and vice
120 * This value is also used to control how much to fade the actor near the
121 * edges, based on the speed the actor is moving. When the actor is at rest
122 * this is not applied. Default 0.5.
123 * @param scalingFactor The scaling factor that controls the edge fade / blur fade of the actor.
125 void SetSpeedScalingFactor( float scalingFactor );
128 * Set the displacement from the centre of the actor that the actor will start
129 * to fade towards its edges. This is used to prevent an unsightly hard edge
130 * between the blurred actor and the scene. Depends on the values of the
131 * vertices in the vertex stream. When the actor is at rest this is not applied.
132 * Default 0.25, which is half way towards the edge for an ImageRenderer::QUAD.
133 * @param displacement The displacement from the centre of the actor that the actor will start to edge fade.
135 void SetObjectFadeStart( Vector2 displacement );
138 * Set the displacement from the centre of the actor that the actor will
139 * finish fading towards its edges. This is used to prevent an unsightly hard
140 * edge between the blurred actor and the scene. Depends on the values of the
141 * vertices in the vertex stream. When the actor is at rest this is not applied.
142 * Default 0.5, which is all the way towards the edge for an ImageRenderer::QUAD.
143 * @param displacement The displacement from the centre of the actor that the actor will finish edge fading.
145 void SetObjectFadeEnd( Vector2 displacement );
148 * Set a global scaler applied to the alpha of the actor. Used to make the
149 * blurred actor a bit more subtle (helps to hide discontinuities due to
150 * limited number of texture samples) and reveal a bit of the background
151 * behind it as it moves. When the actor is at rest this is not applied. Default 0.75.
152 * @param alphaScale The scaling factor which multiplies the alpha of each pixel of the actor.
154 void SetAlphaScale( float alphaScale );
157 * Set the number of texture samples to be taken. Increasing the number of
158 * samples provides better quality at the cost of performance.
159 * @param numSamples The number of texture samples to be taken. Default is 8.
161 void SetNumSamples( int numSamples );
164 * Get the name for the texcoord scale property. Useful for animation.
165 * @return A std::string containing the property name
167 const std::string& GetTexcoordScalePropertyName() const;
170 * Get the name for the geometry stretching property. Useful for animation.
171 * @return A std::string containing the property name
173 const std::string& GetGeometryStretchFactorPropertyName() const;
176 * Get the name for the speed scaling property. Useful for animation.
177 * @return A std::string containing the property name
179 const std::string& GetSpeedScalingFactorPropertyName() const;
182 * Get the name for the fade start property. Useful for animation.
183 * @return A std::string containing the property name
185 const std::string& GetObjectFadeStartPropertyName() const;
188 * Get the name for the fade end property. Useful for animation.
189 * @return A std::string containing the property name
191 const std::string& GetObjectFadeEndPropertyName() const;
194 * Get the name for the alpha scale property. Useful for animation.
195 * @return A std::string containing the property name
197 const std::string& GetAlphaScalePropertyName() const;
200 * Downcast an ShaderEffect handle to MotionBlurEffect handle. If handle points to a MotionBlurEffect object the
201 * downcast produces valid handle. If not the returned handle is left uninitialized.
202 * @param[in] handle to a ShaderEffect
203 * @return handle to a MotionBlurEffect object or an uninitialized handle
205 static MotionBlurEffect DownCast( ShaderEffect handle );
208 // Not intended for application developers
209 DALI_INTERNAL MotionBlurEffect( ShaderEffect handle );
216 #endif //#ifndef __DALI_TOOLKIT_SHADER_EFFECT_MOTION_BLUR_H__