dali-toolkit/devel-api/controls/gaussian-blur-view/gaussian-blur-view.h

   1 #ifndef DALI_TOOLKIT_GAUSSIAN_BLUR_EFFECT_H
   2 #define DALI_TOOLKIT_GAUSSIAN_BLUR_EFFECT_H
   3
   4 /*
   5  * Copyright (c) 2019 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/camera-actor.h>
  23 #include <dali/public-api/common/dali-vector.h>
  24 #include <dali/public-api/rendering/frame-buffer.h>
  25 #include <dali/public-api/rendering/texture.h>
  26 #include <dali/public-api/render-tasks/render-task.h>
  27
  28 // INTERNAL INCLUDES
  29 #include <dali-toolkit/public-api/controls/control.h>
  30
  31 namespace Dali
  32 {
  33
  34 namespace Toolkit
  35 {
  36
  37 namespace Internal DALI_INTERNAL
  38 {
  39
  40 /**
  41  * GaussianBlurView implementation class
  42  */
  43 class GaussianBlurView;
  44
  45 /**
  46  * BloomView implementation class - requires access to private methods
  47  */
  48 class BloomView;
  49
  50 } // namespace Internal
  51 /**
  52  * @addtogroup dali_toolkit_controls_gaussian_blur_view
  53  * @{
  54  */
  55
  56 /**
  57  * @brief
  58  * GaussianBlurView is a class for applying a render process that blurs an image.
  59  *
  60  * Basic idea:-
  61  *
  62  * 1) The GaussianBlurView object will render all its child actors offscreen.\n
  63  * 2) The GaussianBlurView object then blurs the result of step 1), using a two pass separated Gaussian blur.\n
  64  * 3) The GaussianBlurView object then composites the blur from step 2) with the child actors image from step 1). See GetBlurStrengthPropertyIndex() for more info.\n
  65  * 4) The GaussianBlurView object gets rendered automatically, either to the screen via the default render task, or via a RenderTask the user has created for
  66  * e.g. further offscreen rendering.
  67  *
  68  * Fundamentally, the GaussianBlurView is simply an Actor in the normal actor tree that affects all of its children. It should be added to your Actor tree and manipulated in the
  69  * normal ways. It can be considered a 'portal' in the sense that all child actors are clipped to the GaussianBlurView actor bounds.
  70  *
  71  * ************\n
  72  * NB: It is essential to remove the GaussianBlurView from the stage and also to call Deactivate() on it when you are not using it. This will ensure that resources are freed and
  73  * rendering stops.\n
  74  * ************\n
  75  *
  76  * Usage example:-
  77  *
  78  * @code
  79  *  // Initialise
  80  *  GaussianBlurView gaussianBlurView = GaussianBlurView::New();
  81  *
  82  *  // Create and add some visible actors to the GaussianBlurView, all these child actors will therefore get blurred.
  83  *  Image image = Image::New(...);
  84  *  ImageView imageView = ImageView::New(image);
  85  *  gaussianBlurView.Add(imageView);
  86  *  ...
  87  *
  88  *  // Start rendering the GaussianBlurView
  89  *  Stage::GetCurrent().Add(gaussianBlurView);
  90  *  gaussianBlurView.Activate();
  91  *  ...
  92  *
  93  *  // Animate the strength of the blur - this can fade between no blur and full blur. See GetBlurStrengthPropertyIndex().
  94  *  Animation blurAnimation = Animation::New( ... );
  95  *  blurAnimation.AnimateTo( Property( gaussianBlurView, gaussianBlurView.GetBlurStrengthPropertyIndex() ), ... );
  96  *  blurAnimation.Play();
  97  *
  98  *  ...
  99  *  // Stop rendering the GaussianBlurView
 100  *  Stage::GetCurrent().Remove(gaussianBlurView);
 101  *  gaussianBlurView.Deactivate();
 102  * @endcode
 103  * @SINCE_1_0.0
 104  * @remarks This is an experimental feature and might not be supported in the next release.
 105  * We do recommend not to use this class.
 106  */
 107 class DALI_TOOLKIT_API GaussianBlurView : public Control
 108 {
 109 public:
 110   /**
 111    * @brief Signal type for notifications
 112    * @SINCE_1_0.0
 113    */
 114   typedef Signal< void (GaussianBlurView source) > GaussianBlurViewSignal;
 115
 116   /**
 117    * @brief Create an uninitialized GaussianBlurView; this can be initialized with GaussianBlurView::New().
 118    * Calling member functions with an uninitialized Dali::Object is not allowed.
 119    * @SINCE_1_0.0
 120    */
 121   GaussianBlurView();
 122
 123   /**
 124    * @brief Copy constructor. Creates another handle that points to the same real object.
 125    * @SINCE_1_0.0
 126    */
 127   GaussianBlurView(const GaussianBlurView& handle);
 128
 129   /**
 130    * @brief Assignment operator. Changes this handle to point to another real object.
 131    * @SINCE_1_0.0
 132    */
 133   GaussianBlurView& operator=(const GaussianBlurView& ZoomView);
 134
 135   /**
 136    * @brief Destructor
 137    *
 138    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 139    * @SINCE_1_0.0
 140    */
 141   ~GaussianBlurView();
 142
 143   /**
 144    * @brief Downcast a handle to GaussianBlurView handle.
 145    *
 146    * If handle points to a GaussianBlurView the
 147    * downcast produces valid handle. If not the returned handle is left uninitialized.
 148    * @SINCE_1_0.0
 149    * @param[in] handle Handle to an object
 150    * @return A handle to a GaussianBlurView or an uninitialized handle
 151    */
 152   static GaussianBlurView DownCast( BaseHandle handle );
 153
 154   /**
 155   * @brief Create an initialized GaussianBlurView, using default settings. The default settings are:-\n
 156   *
 157   * numSamples = 5\n
 158   * blurBellCurveWidth = 1.5\n
 159   * renderTargetPixelFormat = RGB888\n
 160   * downsampleWidthScale = 0.5\n
 161   * downsampleHeightScale = 0.5\n
 162   * blurUserImage = false
 163   * @SINCE_1_0.0
 164   * @return A handle to a newly allocated Dali resource
 165   */
 166   static GaussianBlurView New();
 167
 168   /**
 169   * @brief Create an initialized GaussianBlurView.
 170   * @SINCE_1_0.0
 171   * @param numSamples The size of the Gaussian blur kernel (number of samples in horizontal / vertical blur directions).
 172   * @param blurBellCurveWidth The constant controlling the Gaussian function, must be > 0.0. Controls the width of the bell curve, i.e. the look of the blur and also indirectly
 173   * the amount of blurriness Smaller numbers for a tighter curve. Useful values in the range [0.5..3.0] - near the bottom of that range the curve is weighted heavily towards
 174   * the centre pixel of the kernel (so there won't be much blur), near the top of that range the pixels have nearly equal weighting (closely approximating a box filter
 175   * therefore). Values close to zero result in the bell curve lying almost entirely within a single pixel, in other words there will be basically no blur as neighbouring pixels
 176   * have close to zero weights.
 177   * @param renderTargetPixelFormat The pixel format of the render targets we are using to perform the blur.
 178   * @param downsampleWidthScale The width scale factor applied during the blur process, scaling the size of the source image to the size of the final blurred image output.
 179   * Useful for downsampling - trades visual quality for processing speed. A value of 1.0f results in no scaling applied.
 180   * @param downsampleHeightScale The height scale factor applied during the blur process, scaling the size of the source image to the size of the final blurred image output.
 181   * Useful for downsampling - trades visual quality for processing speed. A value of 1.0f results in no scaling applied.
 182   * @param blurUserImage If this is set to true, the GaussianBlurView object will operate in a special mode that allows the user to blur an image of their choice. See
 183   * SetUserImageAndOutputRenderTarget().
 184   * @return A handle to a newly allocated Dali resource
 185   */
 186   static GaussianBlurView New(const unsigned int numSamples, const float blurBellCurveWidth, const Pixel::Format renderTargetPixelFormat,
 187                               const float downsampleWidthScale, const float downsampleHeightScale,
 188                               bool blurUserImage = false);
 189
 190   /**
 191    * @DEPRECATED_1_1.28 Use Actor::Add(Actor) instead
 192    * @brief Adds a child Actor to this Actor.
 193    * @SINCE_1_0.0
 194    * @param [in] child The child.
 195    * @pre This Actor (the parent) has been initialized.
 196    * @pre The child actor has been initialized.
 197    * @pre The child actor is not the same as the parent actor.
 198    * @pre The actor is not the Root actor
 199    * @post The child will be referenced by its parent. This means that the child will be kept alive,
 200    * even if the handle passed into this method is reset or destroyed.
 201    * @note If the child already has a parent, it will be removed from old parent
 202    * and reparented to this actor. This may change childs position, color, shader effect,
 203    * scale etc as it now inherits them from this actor.
 204    */
 205   void Add(Actor child);
 206
 207   /**
 208    * @DEPRECATED_1_1.28 Use Actor::Remove(Actor) instead
 209    * @brief Removes a child Actor from this Actor.
 210    *
 211    * If the actor was not a child of this actor, this is a no-op.
 212    * @SINCE_1_0.0
 213    * @param [in] child The child.
 214    * @pre This Actor (the parent) has been initialized.
 215    * @pre The child actor is not the same as the parent actor.
 216    */
 217   void Remove(Actor child);
 218
 219   /**
 220    * @brief Start rendering the GaussianBlurView. Must be called after you Add() it to the stage.
 221    * @SINCE_1_0.0
 222    */
 223   void Activate();
 224
 225   /**
 226    * @brief Render the GaussianBlurView once.
 227    *
 228    * Must be called after you Add() it to the stage.
 229    * Only works with a gaussian blur view created with blurUserImage = true.
 230    * Listen to the Finished signal to determine when the rendering has completed.
 231    * @SINCE_1_0.0
 232    */
 233   void ActivateOnce();
 234
 235   /**
 236    * @brief Stop rendering the GaussianBlurView. Must be called after you Remove() it from the stage.
 237    * @SINCE_1_0.0
 238    */
 239   void Deactivate();
 240
 241   /**
 242    * @brief Sets a custom image to be blurred and a render target to receive the blurred result.
 243    *
 244    * If this is called the children of the GaussianBlurObject will not be rendered blurred,
 245    * instead the inputImage will get blurred.
 246    * To retrieve the blurred image the user can either pass a handle on a render target they own as the second parameter to SetUserImageAndOutputRenderTarget( ... ), or they
 247    * can pass NULL for this parameter and instead call GetBlurredRenderTarget() which will return a handle on a render target created internally to the GaussianBlurView object.
 248    * @SINCE_1_0.0
 249    * @param inputImage The image that the user wishes to blur.
 250    * @param outputRenderTarget A render target to receive the blurred result. Passing NULL is allowed. See also GetBlurredRenderTarget().
 251    * @pre This object was created with a New( ... ) call where the blurUserImage argument was set to true. If this was not the case an exception will be thrown.
 252    */
 253   void SetUserImageAndOutputRenderTarget(Dali::Texture inputImage, Dali::FrameBuffer outputRenderTarget);
 254
 255   /**
 256    * @brief Get the index of the property that can be used to fade the blur in / out.
 257    *
 258    * This is the overall strength of the blur.
 259    * User can use this to animate the blur. A value of 0.0 is zero blur and 1.0 is full blur. Default is 1.0.
 260    * Note that if you set the blur to 0.0, the result will be no blur BUT the internal rendering will still be happening. If you wish to turn the blur off, you should remove
 261    * the GaussianBlurView object from the stage also.
 262    * @SINCE_1_0.0
 263    * @return Index of the property that can be used to fade the blur in / out
 264    */
 265   Dali::Property::Index GetBlurStrengthPropertyIndex() const;
 266
 267   /**
 268    * @brief Get the final blurred image.
 269    *
 270    * Use can call this function to get the blurred result as an image, to use as they wish. It is not necessary to call this unless you specifically require it.
 271    * @SINCE_1_0.0
 272    * @return A handle on the blurred image, contained in a render target.
 273    * @pre The user must call Activate() before the render target will be returned.
 274    */
 275   Dali::FrameBuffer GetBlurredRenderTarget() const;
 276
 277   /**
 278   * @brief Set background color for the view. The background will be filled with this color.
 279   * @SINCE_1_0.0
 280   * @param[in] color The background color.
 281   */
 282   void SetBackgroundColor( const Vector4& color );
 283
 284   /**
 285   * @brief Get the background color.
 286   * @SINCE_1_0.0
 287   * @return The background color.
 288   */
 289   Vector4 GetBackgroundColor() const;
 290
 291 public: // Signals
 292   /**
 293    * @brief If ActivateOnce has been called, then connect to this signal to be notified when the
 294    * target actor has been rendered.
 295    * @SINCE_1_0.0
 296    * @return The Finished signal
 297    */
 298   GaussianBlurViewSignal& FinishedSignal();
 299
 300 public:
 301
 302   /// @cond internal
 303   /**
 304    * @brief Creates a handle using the Toolkit::Internal implementation.
 305    * @SINCE_1_0.0
 306    * @param[in]  implementation  The UI Control implementation.
 307    */
 308   DALI_INTERNAL GaussianBlurView( Internal::GaussianBlurView& implementation );
 309
 310   /**
 311    * @brief Allows the creation of this UI Control from an Internal::CustomActor pointer.
 312    * @SINCE_1_0.0
 313    * @param[in]  internal  A pointer to the internal CustomActor.
 314    */
 315   DALI_INTERNAL GaussianBlurView( Dali::Internal::CustomActor* internal );
 316   /// @endcond
 317
 318 };
 319
 320 /**
 321  * @}
 322  */
 323 } // namespace Toolkit
 324
 325 } // namespace Dali
 326
 327 #endif // DALI_TOOLKIT_GAUSSIAN_BLUR_EFFECT_H