dali-toolkit/devel-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) 2015 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 #include <dali/public-api/actors/renderable-actor.h>
  23 #include <dali/public-api/shader-effects/shader-effect.h>
  24
  25 namespace Dali
  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 DALI_IMPORT_API 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    * @brief Destructor
  60    *
  61    * This is non-virtual since derived Handle types must not contain data or virtual methods.
  62    */
  63   ~MotionBlurEffect();
  64
  65   /**
  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.
  70    */
  71   static MotionBlurEffect New();
  72
  73   /**
  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.
  79    */
  80   static MotionBlurEffect Apply( RenderableActor renderable );
  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    * @param numBlurSamples to have
  88    * @return A handle to a newly allocated Dali resource.
  89    */
  90   static MotionBlurEffect New( unsigned int numBlurSamples );
  91
  92   /**
  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.
  99    */
 100   void SetTexcoordScale( float texcoordScale );
 101
 102   /**
 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.
 111    */
 112   void SetGeometryStretchFactor( float scalingFactor );
 113
 114   /**
 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
 119    * versa.
 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.
 124    */
 125   void SetSpeedScalingFactor( float scalingFactor );
 126
 127   /**
 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.
 134    */
 135   void SetObjectFadeStart( Vector2 displacement );
 136
 137   /**
 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.
 144    */
 145   void SetObjectFadeEnd( Vector2 displacement );
 146
 147   /**
 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.
 153    */
 154   void SetAlphaScale( float alphaScale );
 155
 156   /**
 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.
 160    */
 161   void SetNumSamples( int numSamples );
 162
 163   /**
 164    * Get the name for the texcoord scale property. Useful for animation.
 165    * @return A std::string containing the property name
 166    */
 167   const std::string& GetTexcoordScalePropertyName() const;
 168
 169   /**
 170    * Get the name for the geometry stretching property. Useful for animation.
 171    * @return A std::string containing the property name
 172    */
 173   const std::string& GetGeometryStretchFactorPropertyName() const;
 174
 175   /**
 176    * Get the name for the speed scaling property. Useful for animation.
 177    * @return A std::string containing the property name
 178    */
 179   const std::string& GetSpeedScalingFactorPropertyName() const;
 180
 181   /**
 182    * Get the name for the fade start property. Useful for animation.
 183    * @return A std::string containing the property name
 184    */
 185   const std::string& GetObjectFadeStartPropertyName() const;
 186
 187   /**
 188    * Get the name for the fade end property. Useful for animation.
 189    * @return A std::string containing the property name
 190    */
 191   const std::string& GetObjectFadeEndPropertyName() const;
 192
 193   /**
 194    * Get the name for the alpha scale property. Useful for animation.
 195    * @return A std::string containing the property name
 196    */
 197   const std::string& GetAlphaScalePropertyName() const;
 198
 199   /**
 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
 204    */
 205   static MotionBlurEffect DownCast( ShaderEffect handle );
 206
 207 private:
 208   // Not intended for application developers
 209   DALI_INTERNAL MotionBlurEffect( ShaderEffect handle );
 210 };
 211
 212 }
 213
 214 }
 215
 216 #endif //#ifndef __DALI_TOOLKIT_SHADER_EFFECT_MOTION_BLUR_H__