1 #ifndef __DALI_TOOLKIT_BLOOM_VIEW_H__
2 #define __DALI_TOOLKIT_BLOOM_VIEW_H__
5 * Copyright (c) 2015 Samsung Electronics Co., Ltd.
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
22 #include <dali-toolkit/public-api/controls/control.h>
23 #include <dali-toolkit/public-api/controls/gaussian-blur-view/gaussian-blur-view.h>
31 namespace Internal DALI_INTERNAL
35 * BloomView implementation class
39 } // namespace Internal
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.
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.
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.
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
68 * BloomView bloomView = BloomView::New();\n
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
76 * // Start rendering the BloomView\n
77 * Stage::GetCurrent().Add(bloomView);\n
78 * bloomView.Activate();\n
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
87 * // Stop rendering the BloomView\n
88 * Stage::GetCurrent().Remove(bloomView);\n
89 * bloomView.Deactivate();\n
91 class DALI_IMPORT_API BloomView : public Control
96 * Create an uninitialized BloomView; this can be initialized with BloomView::New()
97 * Calling member functions with an uninitialized Dali::Object is not allowed.
102 * Copy constructor. Creates another handle that points to the same real object
104 BloomView(const BloomView& handle);
107 * Assignment operator. Changes this handle to point to another real object
109 BloomView& operator=(const BloomView& ZoomView);
114 * This is non-virtual since derived Handle types must not contain data or virtual methods.
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
124 static BloomView DownCast( BaseHandle handle );
127 * Create an initialized BloomView, using default settings. The default settings are:-\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
136 static BloomView New();
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
153 static BloomView New(const unsigned int numSamples, const float blurBellCurveWidth, const Pixel::Format renderTargetPixelFormat,
154 const float downsampleWidthScale, const float downsampleHeightScale);
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.
170 void Add(Actor child);
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.
180 void Remove(Actor child);
183 * Start rendering the BloomView. Must be called after you Add() it to the stage.
188 * Stop rendering the BloomView. Must be called after you Remove() it from the stage.
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( ... )
197 Dali::Property::Index GetBloomThresholdPropertyIndex() const;
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( ... )
204 Dali::Property::Index GetBlurStrengthPropertyIndex() const;
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( ... )
211 Dali::Property::Index GetBloomIntensityPropertyIndex() const;
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( ... )
218 Dali::Property::Index GetBloomSaturationPropertyIndex() const;
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( ... )
225 Dali::Property::Index GetImageIntensityPropertyIndex() const;
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( ... )
232 Dali::Property::Index GetImageSaturationPropertyIndex() const;
237 * Creates a handle using the Toolkit::Internal implementation.
238 * @param[in] implementation The UI Control implementation.
240 DALI_INTERNAL BloomView( Internal::BloomView& implementation );
243 * Allows the creation of this UI Control from an Internal::CustomActor pointer.
244 * @param[in] internal A pointer to the internal CustomActor.
246 explicit DALI_INTERNAL BloomView( Dali::Internal::CustomActor* internal );
250 } // namespace Toolkit
254 #endif // __DALI_TOOLKIT_BLOOM_VIEW_H__