capi/dali-toolkit/public-api/controls/bubble-effect/bubble-emitter.h

   1 #ifndef __DALI_TOOLKIT_BUBBLE_EMMITER_H__
   2 #define __DALI_TOOLKIT_BUBBLE_EMMITER_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 /**
  21  * @addtogroup CAPI_DALI_TOOLKIT_BUBBLE_EFFECT_MODULE
  22  * @{
  23  */
  24
  25 // INTERNAL INCLUDES
  26 #include <dali/dali.h>
  27 #include <dali-toolkit/public-api/controls/control.h>
  28
  29 namespace Dali DALI_IMPORT_API
  30 {
  31
  32 namespace Toolkit
  33 {
  34
  35 namespace Internal DALI_INTERNAL
  36 {
  37   /**
  38    * @brief BubbleEmitter implementation class.
  39    */
  40   class BubbleEmitter;
  41 }
  42
  43 /**
  44  * @brief BubbleEmitter is used to display lots of moving bubbles on the stage.
  45  *
  46  * This is done by applying BubbleEffect to multiple specifically created meshActors.
  47  */
  48 class BubbleEmitter : public Control
  49 {
  50 public:
  51
  52   /**
  53    * @brief Create an empty BubbleEmitter handle.
  54    */
  55   BubbleEmitter();
  56
  57   /**
  58    * @brief Virtual destructor.
  59    */
  60   ~BubbleEmitter();
  61
  62   /**
  63    * @brief Create an initialized BubbleEmitter.
  64    *
  65    * @param[in] winSize The size of the bubble moving area, usually the same size as the background image actor.
  66    * @param[in] shapeImage The alpha channnel of this texture defines the bubble shape.
  67    * @param[in] maximumNumberOfBubble The maximum number of bubble needed.
  68    * @param[in] bubbleSizeRange The size range of the bubbles; x component is the low bound, and y component is the up bound.
  69    * @return The initialized BubbleEmitter object.
  70    */
  71   static BubbleEmitter New( const Vector2& winSize,
  72                             Image shapeImage,
  73                             unsigned int maximumNumberOfBubble,
  74                             const Vector2& bubbleSizeRange );
  75
  76
  77   /**
  78    * @brief Copy constructor.
  79    *
  80    * Creates another handle that points to the same real object
  81    * @param[in] handle The handle to copy
  82    */
  83   BubbleEmitter( const BubbleEmitter& handle );
  84
  85   /**
  86    * @brief Assignment operator.
  87    *
  88    * Changes this handle to point to another real object
  89    * @param[in] rhs The object to point at
  90    * @return A reference to this
  91    */
  92   BubbleEmitter& operator=( const BubbleEmitter& rhs );
  93
  94   /**
  95    * @brief Downcast an Object handle to SuperBlurView.
  96    *
  97    * If handle points to a BubbleEmitter, the downcast produces valid handle.
  98    * If not, the returned handle is left uninitialized.
  99    * @param[in] handle Handle to an object
 100    * @return handle to a BubbleEmitter or an uninitialized handle
 101    */
 102   static BubbleEmitter DownCast( BaseHandle handle );
 103
 104   /**
 105    * @brief Return the root actor of all bubbles, should then be added to stage.
 106    *
 107    * @return The bubble root actor.
 108    */
 109   Actor GetRootActor();
 110
 111   /**
 112    * @brief Set Background image.
 113    *
 114    * The bubbles pick color from this image with HSV values adjusted.
 115    * @param[in] bgImage The background image which provide color to bubbles.
 116    * @param[in] hsvDelta The hsv channel difference used to adjust the background image color.
 117    *            If set these vector as Vector3::Zero, original colors are used.
 118    */
 119   void SetBackground( Image bgImage, const Vector3& hsvDelta );
 120
 121   /**
 122    * @brief Set bubble shape.
 123    *
 124    * The bubble mesh is a rectangular patch, but its displayed shape is decided by the alpha channel of the shape image.
 125    * @param[in] shapeImage The image whose alpha channel defines the bubble shape.
 126    */
 127   void SetShapeImage( Image shapeImage );
 128
 129   /**
 130    * @brief Set the scale factor applied to all the bubbles.
 131    *
 132    * @param [in] scale The scale factor applied on bubbles.
 133    */
 134   void SetBubbleScale( float scale );
 135
 136   /**
 137    * @brief Set the density of the bubble.
 138    *
 139    * Ideally every bubble's moving track is controlled by different uniforms in BubbleEffect shaders.
 140    * To increase the density, 'density' number of bubbles are sharing one group of uniforms, but with random offsets between these bubbles.
 141    * The available density is one to nine. The default density is five.
 142    * By set the density bigger than one, instead of emit one bubble each time, a 'density' number of bubbles are emitted.
 143    * @param[in] density The density of the bubble.
 144    */
 145   void SetBubbleDensity( unsigned int density );
 146
 147   /**
 148    * @brief Enable different blending mode for rendering.
 149    *
 150    * @param[in] enable If false, the default blending function for RenderableActor is used.
 151    */
 152   void SetBlendMode( bool enable );
 153
 154   /**
 155    * @brief Add a bubble movement to the animation.
 156    *
 157    * @param[in] animation The animation reference.
 158    * By passing the animation into BubbleEmitter, the animation's duration and how many bubbles contained within this animation are freely decided in App.
 159    * @param[in] emitPosition The start position of the bubble movement.
 160    * @param[in] direction The direction used to constrain the bubble to move in an adjacent direction around it.
 161    * @param[in] displacement The displacement used to bound the moving distance of the bubble.
 162    */
 163   void EmitBubble( Animation& animation, const Vector2& emitPosition, const Vector2& direction, const Vector2& displacement );
 164
 165   /**
 166    * @brief Start an animation to enlarge every activated bubble's size and moving speed.
 167    *
 168    * @param[in] duration The duration of the animation
 169    * @param[in] multiple The bubble size and moving speed will be increased gradually to multiple speed during the animation.
 170    */
 171   void StartExplosion( float duration, float multiple );
 172
 173   /**
 174    * @brief Reset all the parameters controlling the bubbles after animation.
 175    */
 176   void Restore();
 177
 178 public: // Not intended for developer use
 179
 180   /**
 181    * @brief Creates a handle using the Toolkit::Internal implementation.
 182    *
 183    * @param[in]  implementation  The Control implementation.
 184    */
 185   DALI_INTERNAL BubbleEmitter(Internal::BubbleEmitter& implementation);
 186
 187   /**
 188    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 189    *
 190    * @param[in]  internal  A pointer to the internal CustomActor.
 191    */
 192   DALI_INTERNAL BubbleEmitter(Dali::Internal::CustomActor* internal);
 193 };
 194
 195 } // namespace Toolkit
 196
 197 } // namespace Dali
 198 /**
 199  * @}
 200  */
 201 #endif /* __DALI_TOOLKIT_BUBBLE_EMMITER_H__ */