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