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