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