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