1 #ifndef __DALI_TOOLKIT_MASKED_IMAGE_VIEW_H__
2 #define __DALI_TOOLKIT_MASKED_IMAGE_VIEW_H__
5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
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
11 // http://floralicense.org/license/
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.
21 * @addtogroup CAPI_DALI_FRAMEWORK
26 #include <dali-toolkit/public-api/controls/control.h>
28 namespace Dali DALI_IMPORT_API
34 namespace Internal DALI_INTERNAL
36 class MaskedImageView;
40 * MaskedImageView displays the result of an image created from a masking operation, which is described below:
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.
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.
56 class MaskedImageView : public Control
61 * The custom properties installed by this control
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
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
89 static const float DEFAULT_MAXIMUM_SOURCE_SCALE; ///< Default SetMaximumSourceScale() value
92 * Creates an empty MaskedImageView handle
97 * Copy constructor. Creates another handle that points to the same real object
98 * @param handle to copy from
100 MaskedImageView( const MaskedImageView& handle );
103 * Assignment operator. Changes this handle to point to another real object
105 MaskedImageView& operator=( const MaskedImageView& handle );
108 * Virtual destructor.
109 * Dali::Object derived classes typically do not contain member data.
111 virtual ~MaskedImageView();
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.
121 static MaskedImageView New( unsigned int targetWidth,
122 unsigned int targetHeight,
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
132 static MaskedImageView DownCast( BaseHandle handle );
135 * Set the image used as a source in the masking operation
136 * @param[in] sourceImage The source image
138 void SetSourceImage( Image sourceImage );
141 * Retrieve the image used as a source in the masking operation
142 * @return sourceImage The source image
144 Image GetSourceImage();
147 * Set the image used as a mask in the masking operation
148 * @param[in] maskImage The mask image
150 void SetMaskImage( Image maskImage );
153 * Retrieve the image used as a mask in the masking operation
154 * @return sourceImage The mask image
156 Image GetMaskImage();
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()
163 Property::Index GetPropertyIndex( CustomProperty customProperty ) const;
166 * Pause the masking operation to improve performance.
167 * Call this when the source & mask positions etc. are not being modified.
172 * Resume the masking operation.
177 * Query whether the masking operation has been paused.
178 * @return True if the masking operation has been paused.
180 bool IsPaused() const;
183 * Enable or disable an edit mode. The default is EDIT_DISABLED.
184 * @param[in] editMode The edit mode required.
186 void SetEditMode( EditMode editMode );
189 * Query which edit mode is enabled.
191 EditMode GetEditMode() const;
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.
198 void SetSourceAspectRatio( float widthOverHeight );
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.
204 float GetSourceAspectRatio() const;
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.
212 void SetMaximumSourceScale( float scale );
215 * Query the maximum scale applied when editing the source image.
216 * @return The maximum scale.
218 float GetMaximumSourceScale() const;
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).
224 void SetSourceRotation( ImageRotation rotation );
227 * Query the rotation applied to the source image.
228 * @return The current rotation.
230 ImageRotation GetSourceRotation() const;
232 public: /* Signals */
234 typedef SignalV2< void (MaskedImageView& source) > MaskedImageViewSignal;
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.
240 MaskedImageViewSignal& MaskFinishedSignal();
243 * @deprecated Use MaskFinishedSignal() instead.
244 * Signal emitted when the render task which targets the frame buffer of the masked image has finished.
246 Dali::RenderTask::RenderTaskSignalV2& RenderFinishedSignal();
248 public: // Not intended for application developers
251 * Creates a handle using the Toolkit::Internal implementation.
252 * @param[in] implementation The Control implementation.
254 MaskedImageView(Internal::MaskedImageView& implementation);
257 * Allows the creation of this Control from an Internal::CustomActor pointer.
258 * @param[in] internal A pointer to the internal CustomActor.
260 MaskedImageView(Dali::Internal::CustomActor* internal);
263 } // namespace Toolkit
270 #endif // __DALI_TOOLKIT_MASKED_IMAGE_VIEW_H__