capi/dali-toolkit/public-api/controls/image-view/masked-image-view.h

   1 #ifndef __DALI_TOOLKIT_MASKED_IMAGE_VIEW_H__
   2 #define __DALI_TOOLKIT_MASKED_IMAGE_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 /**
  21  * @addtogroup CAPI_DALI_TOOLKIT_IMAGE_VIEW_MODULE
  22  * @{
  23  */
  24
  25 // INTERNAL INCLUDES
  26 #include <dali-toolkit/public-api/controls/control.h>
  27
  28 namespace Dali DALI_IMPORT_API
  29 {
  30
  31 namespace Toolkit
  32 {
  33
  34 namespace Internal DALI_INTERNAL
  35 {
  36 class MaskedImageView;
  37 }
  38
  39 /**
  40  * @brief MaskedImageView displays the result of an image created from a masking operation.
  41  *
  42  * Masking operations:
  43  *  - Firstly a target image size is chosen. The MaskedImageView handles the creation of this image internally. Initially the
  44  *    target image will be filled according to the BACKGROUND_COLOR property.
  45  *  - A source image is provided and positioned with the target image area. The position of the source image (in pixels), can
  46  *    be controlled using the SOURCE_OFFSET and SOURCE_SIZE properties. By default the source image is centered within the target
  47  *    image, and stretched to fill. Note that by default, no attempt is made to maintain the aspect ratio of the source image.
  48  *  - A mask image is provided and positioned in the same way as the source image, using the MASK_OFFSET and MASK_SIZE properties.
  49  *  - Conceptually the source image is then painted using the mask image as a stencil. Areas of the source which overlap with opaque
  50  *    areas of the mask, will be painted into the target image. However where the mask is transparent, the source will be faded away.
  51  *    Note that the edge of the mask image will be stretched to cover the entire target area.
  52  *
  53  * Initially MaskedImageView will perform the masking operation on a per-frame basis. This can impact performance, and may be
  54  * avoided by calling Pause() e.g. when the source & mask positions are not being modified. The Resume() method can then be called
  55  * to continue the masking operation when required.
  56  */
  57 class MaskedImageView : public Control
  58 {
  59 public:
  60
  61   /**
  62    * @brief The custom properties installed by this control.
  63    */
  64   enum CustomProperty
  65   {
  66     BACKGROUND_COLOR,    ///< Name "background-color", type VECTOR4
  67     SOURCE_SIZE,         ///< Name "source-size",      type VECTOR2
  68     SOURCE_OFFSET,       ///< Name "source-offset",    type VECTOR2
  69     MASK_SIZE,           ///< Name "mask-size",        type VECTOR2
  70     MASK_OFFSET,         ///< Name "mask-offset",      type VECTOR2
  71
  72     CUSTOM_PROPERTY_COUNT
  73   };
  74
  75   /**
  76    * @brief Edit mode for this control.
  77    *
  78    * @see SetEditMode()
  79    */
  80   enum EditMode
  81   {
  82     EDIT_DISABLED, ///< Editting is disabled
  83     EDIT_SOURCE,   ///< Editting affects the source image
  84     EDIT_MASK      ///< Editting affects the mask
  85   };
  86
  87   /**
  88    * @brief The rotation of the image.
  89    *
  90    * @see SetSourceRotation()
  91    */
  92   enum ImageRotation
  93   {
  94     ROTATE_0,   ///< No rotation
  95     ROTATE_90,  ///< Image is rotated clockwise by 90 degrees
  96     ROTATE_180, ///< Image is rotated clockwise by 180 degrees
  97     ROTATE_270  ///< Image is rotated clockwise by 270 degrees
  98   };
  99
 100   static const float DEFAULT_MAXIMUM_SOURCE_SCALE; ///< Default SetMaximumSourceScale() value
 101
 102   /**
 103    * @brief Creates an empty MaskedImageView handle.
 104    */
 105   MaskedImageView();
 106
 107   /**
 108    * @brief Copy constructor.
 109    *
 110    * Creates another handle that points to the same real object
 111    * @param handle to copy from
 112    */
 113   MaskedImageView( const MaskedImageView& handle );
 114
 115   /**
 116    * @brief Assignment operator.
 117    *
 118    * Changes this handle to point to another real object
 119    * @param[in] handle the handle of the object to re-assign this to
 120    * @return a reference to this
 121    */
 122   MaskedImageView& operator=( const MaskedImageView& handle );
 123
 124   /**
 125    * @brief Virtual destructor.
 126    *
 127    * Dali::Object derived classes typically do not contain member data.
 128    */
 129   virtual ~MaskedImageView();
 130
 131   /**
 132    * @brief Create the MaskedImageView control.
 133    *
 134    * @param[in] targetWidth The width of the target image
 135    * @param[in] targetHeight The height of the target image
 136    * @param[in] sourceImage The source image
 137    * @param[in] maskImage The mask image
 138    * @return A handle to the MaskedImageView control.
 139    */
 140   static MaskedImageView New( unsigned int targetWidth,
 141                               unsigned int targetHeight,
 142                               Image sourceImage,
 143                               Image maskImage );
 144
 145   /**
 146    * @brief Downcast an Object handle to MaskedImageView.
 147    *
 148    * If handle points to an MaskedImageView the downcast produces
 149    * valid handle. If not the returned handle is left uninitialized.
 150    *
 151    * @param[in] handle Handle to an object
 152    * @return handle to a MaskedImageView or an uninitialized handle
 153    */
 154   static MaskedImageView DownCast( BaseHandle handle );
 155
 156   /**
 157    * @brief Set the image used as a source in the masking operation.
 158    *
 159    * @param[in] sourceImage The source image
 160    */
 161   void SetSourceImage( Image sourceImage );
 162
 163   /**
 164    * @brief Retrieve the image used as a source in the masking operation.
 165    *
 166    * @return sourceImage The source image
 167    */
 168   Image GetSourceImage();
 169
 170   /**
 171    * @brief Set the image used as a mask in the masking operation.
 172    *
 173    * @param[in] maskImage The mask image
 174    */
 175   void SetMaskImage( Image maskImage );
 176
 177   /**
 178    * @brief Retrieve the image used as a mask in the masking operation.
 179    *
 180    * @return sourceImage The mask image
 181    */
 182   Image GetMaskImage();
 183
 184   /**
 185    * @brief Get the property index for a custom MaskedImageView property.
 186    *
 187    * @param[in] customProperty A custom property enum defined in this class.
 188    * @return The property index e.g. for use with Animation::AnimateTo()
 189    */
 190   Property::Index GetPropertyIndex( CustomProperty customProperty ) const;
 191
 192   /**
 193    * @brief Pause the masking operation to improve performance.
 194    *
 195    * Call this when the source & mask positions etc. are not being modified.
 196    */
 197   void Pause();
 198
 199   /**
 200    * @brief Resume the masking operation.
 201    *
 202    */
 203   void Resume();
 204
 205   /**
 206    * @brief Query whether the masking operation has been paused.
 207    *
 208    * @return True if the masking operation has been paused.
 209    */
 210   bool IsPaused() const;
 211
 212   /**
 213    * @brief Enable or disable an edit mode.
 214    *
 215    * The default is EDIT_DISABLED.
 216    * @param[in] editMode The edit mode required.
 217    */
 218   void SetEditMode( EditMode editMode );
 219
 220   /**
 221    * @brief Query which edit mode is enabled.
 222    */
 223   EditMode GetEditMode() const;
 224
 225   /**
 226    * @brief Set the aspect ratio to be preserved when editing the source image.
 227    *
 228    * @param[in] widthOverHeight The aspect ratio i.e. width divided by height. If a value
 229    * of zero or less is set, then the aspect ratio of the source image will be ignored.
 230    */
 231   void SetSourceAspectRatio( float widthOverHeight );
 232
 233   /**
 234    * @brief Query the aspect ratio preserved when editing the source image.
 235    *
 236    * @return The aspect ratio (width divided by height) or zero if no aspect ratio is set.
 237    */
 238   float GetSourceAspectRatio() const;
 239
 240   /**
 241    * @brief Set the maximum scale applied when editing the source image.
 242    *
 243    * The minimum scale is implied by the target width/height i.e. the source image will
 244    * always fill that area when edit mode is enabled.
 245    * @param[in] scale The maximum scale.
 246    */
 247   void SetMaximumSourceScale( float scale );
 248
 249   /**
 250    * @brief Query the maximum scale applied when editing the source image.
 251    *
 252    * @return The maximum scale.
 253    */
 254   float GetMaximumSourceScale() const;
 255
 256   /**
 257    * @brief Set the rotation applied to the source image.
 258    *
 259    * @param[in] rotation The new rotation; by default the source image is not rotated (ROTATE_0).
 260    */
 261   void SetSourceRotation( ImageRotation rotation );
 262
 263   /**
 264    * @brief Query the rotation applied to the source image.
 265    *
 266    * @return The current rotation.
 267    */
 268   ImageRotation GetSourceRotation() const;
 269
 270 public: /* Signals */
 271
 272   /// @brief Finished signal type.
 273   typedef SignalV2< void (MaskedImageView& source) > MaskedImageViewSignal;
 274
 275   /**
 276    * @brief Signal emitted when the render task which targets the
 277    * frame buffer of the masked image has finished.
 278    *
 279    * This signal carries information of the control handle to the callback function.
 280    * @return the signal
 281    */
 282   MaskedImageViewSignal& MaskFinishedSignal();
 283
 284   /**
 285    * @deprecated Use MaskFinishedSignal() instead.
 286    * Signal emitted when the render task which targets the frame buffer of the masked image has finished.
 287    * @return the signal.
 288    */
 289   Dali::RenderTask::RenderTaskSignalV2& RenderFinishedSignal();
 290
 291 public: // Not intended for application developers
 292
 293   /**
 294    * @brief Creates a handle using the Toolkit::Internal implementation.
 295    *
 296    * @param[in]  implementation  The Control implementation.
 297    */
 298   MaskedImageView(Internal::MaskedImageView& implementation);
 299
 300   /**
 301    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 302    *
 303    * @param[in]  internal  A pointer to the internal CustomActor.
 304    */
 305   MaskedImageView(Dali::Internal::CustomActor* internal);
 306 };
 307
 308 } // namespace Toolkit
 309
 310 } // namespace Dali
 311
 312 /**
 313  * @}
 314  */
 315 #endif // __DALI_TOOLKIT_MASKED_IMAGE_VIEW_H__