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