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