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