dali-toolkit/public-api/controls/bloom-view/bloom-view.h

   1 #ifndef __DALI_TOOLKIT_BLOOM_VIEW_H__
   2 #define __DALI_TOOLKIT_BLOOM_VIEW_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 // INTERNAL INCLUDES
  22 #include <dali-toolkit/public-api/controls/control.h>
  23 #include <dali-toolkit/public-api/controls/gaussian-blur-view/gaussian-blur-view.h>
  24
  25 namespace Dali
  26 {
  27
  28 namespace Toolkit
  29 {
  30
  31 namespace Internal DALI_INTERNAL
  32 {
  33
  34 /**
  35  * BloomView implementation class
  36  */
  37 class BloomView;
  38
  39 } // namespace Internal
  40
  41 /**
  42  *
  43  * BloomView is a class for applying a render process that intensifies and blurs the bright parts of an image, bleeding bright areas into darker ones and making bright
  44  * light look more realistic.
  45  *
  46  * Basic idea:-
  47  *
  48  * 1) The BloomView object will render all its child actors offscreen.\n
  49  * 2) The BloomView object then extract the parts of that image that are brighter than the bloom threshold.\n
  50  * 3) The BloomView object then blurs the result of step 2), which makes the brightness bleed into surrounding areas.\n
  51  * 3) The BloomView object then composites the bloom from step 3) with the child actors image from step 1), using parameters that can be set by the user.
  52  * The compositing is additive (image + bloom).\n
  53  * 4) The BloomView object gets rendered automatically, either to the screen via the default render task, or via a RenderTask the user has created for
  54  * e.g. further offscreen rendering.
  55  *
  56  * Fundamentally, the BloomView 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
  57  * normal ways. It can be considered a 'portal' in the sense that all child actors are clipped to the BloomView actor bounds.
  58  *
  59  * ************\n
  60  * NB: It is essential to remove the BloomView from the stage and also to call Deactivate() on it when you are not using it. This will ensure that resources are freed and
  61  * rendering stops.\n
  62  * ************\n
  63  *
  64  *
  65  * Usage example:-
  66  *
  67  *  // initialise\n
  68  *  BloomView bloomView = BloomView::New();\n
  69  *
  70  *  // create and add some visible actors to the BloomView, all these child actors will therefore get bloomed\n
  71  *  Image image = Image::New(...);\n
  72  *  ImageActor imageActor = ImageActor::New(image);\n
  73  *  bloomView.Add(imageActor);\n
  74  *  ...\n
  75  *
  76  *  // Start rendering the BloomView\n
  77  *  Stage::GetCurrent().Add(bloomView);\n
  78  *  bloomView.Activate();\n
  79  *  ...\n
  80  *
  81  *  // animate the strength of the bloom - this can fade between no bloom and your desired max bloom. See GetBloomIntensityPropertyIndex().\n
  82  *  Animation blurAnimation = Animation::New( ... );\n
  83  *  blurAnimation.AnimateTo( Property( bloomView, bloomView.GetBloomIntensityPropertyIndex() ), ... );\n
  84  *  blurAnimation.Play();\n
  85  *
  86  *  ...\n
  87  *  // Stop rendering the BloomView\n
  88  *  Stage::GetCurrent().Remove(bloomView);\n
  89  *  bloomView.Deactivate();\n
  90  */
  91 class DALI_IMPORT_API BloomView : public Control
  92 {
  93 public:
  94
  95   /**
  96    * Create an uninitialized BloomView; this can be initialized with BloomView::New()
  97    * Calling member functions with an uninitialized Dali::Object is not allowed.
  98    */
  99   BloomView();
 100
 101   /**
 102    * Copy constructor. Creates another handle that points to the same real object
 103    */
 104   BloomView(const BloomView& handle);
 105
 106   /**
 107    * Assignment operator. Changes this handle to point to another real object
 108    */
 109   BloomView& operator=(const BloomView& ZoomView);
 110
 111   /**
 112    * @brief Destructor
 113    *
 114    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 115    */
 116   ~BloomView();
 117
 118   /**
 119    * Downcast an Object handle to BloomView. If handle points to a BloomView the
 120    * downcast produces valid handle. If not the returned handle is left uninitialized.
 121    * @param[in] handle Handle to an object
 122    * @return handle to a BloomView or an uninitialized handle
 123    */
 124   static BloomView DownCast( BaseHandle handle );
 125
 126   /**
 127    * Create an initialized BloomView, using default settings. The default settings are:-\n
 128    *
 129    * numSamples = 5\n
 130    * blurBellCurveWidth = 1.5\n
 131    * renderTargetPixelFormat = RGB888\n
 132    * downsampleWidthScale = 0.5\n
 133    * downsampleHeightScale = 0.5\n
 134    * @return A handle to a newly allocated Dali resource
 135    */
 136   static BloomView New();
 137
 138  /**
 139   * Create an initialized BloomView.
 140   * @param numSamples The size of the Gaussian blur kernel (number of samples in horizontal / vertical blur directions) that is used to blur the bloom
 141   * @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
 142   * 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
 143   * 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
 144   * 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
 145   * have close to zero weights.
 146   * @param renderTargetPixelFormat The pixel format of the render targets we are using to perform the bloom.
 147   * @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.
 148   * Useful for downsampling - trades visual quality for processing speed. A value of 1.0f results in no scaling applied.
 149   * @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.
 150   * Useful for downsampling - trades visual quality for processing speed. A value of 1.0f results in no scaling applied.
 151   * @return A handle to a newly allocated Dali resource
 152   */
 153   static BloomView New(const unsigned int numSamples, const float blurBellCurveWidth, const Pixel::Format renderTargetPixelFormat,
 154                               const float downsampleWidthScale, const float downsampleHeightScale);
 155
 156   /**
 157    * Adds a child Actor to this Actor.
 158    * NOTE! if the child already has a parent, it will be removed from old parent
 159    * and reparented to this actor. This may change childs position, color, shader effect,
 160    * scale etc as it now inherits them from this actor
 161    * @pre This Actor (the parent) has been initialized.
 162    * @pre The child actor has been initialized.
 163    * @pre The child actor is not the same as the parent actor.
 164    * @pre The actor is not the Root actor
 165    * @param [in] child The child.
 166    * @post The child will be referenced by its parent. This means that the child will be kept alive,
 167    * even if the handle passed into this method is reset or destroyed.
 168    * @post This may invalidate ActorContainer iterators.
 169    */
 170   void Add(Actor child);
 171
 172   /**
 173    * Removes a child Actor from this Actor.
 174    * If the actor was not a child of this actor, this is a no-op.
 175    * @pre This Actor (the parent) has been initialized.
 176    * @pre The child actor is not the same as the parent actor.
 177    * @param [in] child The child.
 178    * @post This may invalidate ActorContainer iterators.
 179    */
 180   void Remove(Actor child);
 181
 182   /**
 183    * Start rendering the BloomView. Must be called after you Add() it to the stage.
 184    */
 185   void Activate();
 186
 187   /**
 188    * Stop rendering the BloomView. Must be called after you Remove() it from the stage.
 189    */
 190   void Deactivate();
 191
 192   /**
 193    * Get the property index that controls the intensity threshold above which the pixels will be bloomed. Useful for animating this property.
 194    * This property represents a value such that pixels brighter than this threshold will be bloomed. Values are normalised, i.e. RGB 0.0 = 0, 1.0 = 255.  Default 0.25.
 195    * @return The property index that can be used with e.g. AnimateTo( ... )
 196    */
 197   Dali::Property::Index GetBloomThresholdPropertyIndex() const;
 198
 199   /**
 200    * Get the property index that controls the strength of the blur applied to the bloom. Useful for animating this property.
 201    * This property represents a value in the range [0.0 - 1.0] where 0.0 is no blur and 1.0 is full blur. Default 1.0.
 202    * @return The property index that can be used with e.g. AnimateTo( ... )
 203    */
 204   Dali::Property::Index GetBlurStrengthPropertyIndex() const;
 205
 206   /**
 207    * Get the property index that controls the intensity of the child actor render texture used during compositing. Useful for animating this property.
 208    * This property represents a multiplier on the intensity of the bloom texture. Default 1.0.
 209    * @return The property index that can be used with e.g. AnimateTo( ... )
 210    */
 211   Dali::Property::Index GetBloomIntensityPropertyIndex() const;
 212
 213   /**
 214    * Get the property index that controls the saturation of the child actor render texture used during compositing. Useful for animating this property.
 215    * This property represents a multiplier on the saturation of the bloom texture. Default 1.0.
 216    * @return The property index that can be used with e.g. AnimateTo( ... )
 217    */
 218   Dali::Property::Index GetBloomSaturationPropertyIndex() const;
 219
 220   /**
 221    * Get the property index that controls the intensity of the child actor render texture used during compositing. Useful for animating this property.
 222    * This property represents a multiplier on the intensity of the image texture. Default 1.0.
 223    * @return The property index that can be used with e.g. AnimateTo( ... )
 224    */
 225   Dali::Property::Index GetImageIntensityPropertyIndex() const;
 226
 227   /**
 228    * Get the property index that controls the saturation of the child actor render texture used during compositing. Useful for animating this property.
 229    * This property represents a multiplier on the saturation of the image texture. Default 1.0.
 230    * @return The property index that can be used with e.g. AnimateTo( ... )
 231    */
 232   Dali::Property::Index GetImageSaturationPropertyIndex() const;
 233
 234 public:
 235
 236   /**
 237    * Creates a handle using the Toolkit::Internal implementation.
 238    * @param[in]  implementation  The UI Control implementation.
 239    */
 240   DALI_INTERNAL BloomView( Internal::BloomView& implementation );
 241
 242   /**
 243    * Allows the creation of this UI Control from an Internal::CustomActor pointer.
 244    * @param[in]  internal  A pointer to the internal CustomActor.
 245    */
 246   explicit DALI_INTERNAL BloomView( Dali::Internal::CustomActor* internal );
 247
 248 };
 249
 250 } // namespace Toolkit
 251
 252 } // namespace Dali
 253
 254 #endif // __DALI_TOOLKIT_BLOOM_VIEW_H__