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