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_TOOLKIT_IMAGE_VIEW_MODULE
26 #include <dali-toolkit/public-api/controls/control.h>
28 namespace Dali DALI_IMPORT_API
34 namespace Internal DALI_INTERNAL
36 class MaskedImageView;
40 * @brief MaskedImageView displays the result of an image created from a masking operation.
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.
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.
57 class MaskedImageView : public Control
62 * @brief The custom properties installed by this control.
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
76 * @brief Edit mode for this control.
82 EDIT_DISABLED, ///< Editting is disabled
83 EDIT_SOURCE, ///< Editting affects the source image
84 EDIT_MASK ///< Editting affects the mask
88 * @brief The rotation of the image.
90 * @see SetSourceRotation()
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
100 static const float DEFAULT_MAXIMUM_SOURCE_SCALE; ///< Default SetMaximumSourceScale() value
103 * @brief Creates an empty MaskedImageView handle.
108 * @brief Copy constructor.
110 * Creates another handle that points to the same real object
111 * @param handle to copy from
113 MaskedImageView( const MaskedImageView& handle );
116 * @brief Assignment operator.
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
122 MaskedImageView& operator=( const MaskedImageView& handle );
125 * @brief Virtual destructor.
127 * Dali::Object derived classes typically do not contain member data.
129 virtual ~MaskedImageView();
132 * @brief Create the MaskedImageView control.
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.
140 static MaskedImageView New( unsigned int targetWidth,
141 unsigned int targetHeight,
146 * @brief Downcast an Object handle to MaskedImageView.
148 * If handle points to an MaskedImageView the downcast produces
149 * valid handle. If not the returned handle is left uninitialized.
151 * @param[in] handle Handle to an object
152 * @return handle to a MaskedImageView or an uninitialized handle
154 static MaskedImageView DownCast( BaseHandle handle );
157 * @brief Set the image used as a source in the masking operation.
159 * @param[in] sourceImage The source image
161 void SetSourceImage( Image sourceImage );
164 * @brief Retrieve the image used as a source in the masking operation.
166 * @return sourceImage The source image
168 Image GetSourceImage();
171 * @brief Set the image used as a mask in the masking operation.
173 * @param[in] maskImage The mask image
175 void SetMaskImage( Image maskImage );
178 * @brief Retrieve the image used as a mask in the masking operation.
180 * @return sourceImage The mask image
182 Image GetMaskImage();
185 * @brief Get the property index for a custom MaskedImageView property.
187 * @param[in] customProperty A custom property enum defined in this class.
188 * @return The property index e.g. for use with Animation::AnimateTo()
190 Property::Index GetPropertyIndex( CustomProperty customProperty ) const;
193 * @brief Pause the masking operation to improve performance.
195 * Call this when the source & mask positions etc. are not being modified.
200 * @brief Resume the masking operation.
206 * @brief Query whether the masking operation has been paused.
208 * @return True if the masking operation has been paused.
210 bool IsPaused() const;
213 * @brief Enable or disable an edit mode.
215 * The default is EDIT_DISABLED.
216 * @param[in] editMode The edit mode required.
218 void SetEditMode( EditMode editMode );
221 * @brief Query which edit mode is enabled.
223 EditMode GetEditMode() const;
226 * @brief Set the aspect ratio to be preserved when editing the source image.
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.
231 void SetSourceAspectRatio( float widthOverHeight );
234 * @brief Query the aspect ratio preserved when editing the source image.
236 * @return The aspect ratio (width divided by height) or zero if no aspect ratio is set.
238 float GetSourceAspectRatio() const;
241 * @brief Set the maximum scale applied when editing the source image.
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.
247 void SetMaximumSourceScale( float scale );
250 * @brief Query the maximum scale applied when editing the source image.
252 * @return The maximum scale.
254 float GetMaximumSourceScale() const;
257 * @brief Set the rotation applied to the source image.
259 * @param[in] rotation The new rotation; by default the source image is not rotated (ROTATE_0).
261 void SetSourceRotation( ImageRotation rotation );
264 * @brief Query the rotation applied to the source image.
266 * @return The current rotation.
268 ImageRotation GetSourceRotation() const;
270 public: /* Signals */
272 /// @brief Finished signal type.
273 typedef SignalV2< void (MaskedImageView& source) > MaskedImageViewSignal;
276 * @brief Signal emitted when the render task which targets the
277 * frame buffer of the masked image has finished.
279 * This signal carries information of the control handle to the callback function.
282 MaskedImageViewSignal& MaskFinishedSignal();
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.
289 Dali::RenderTask::RenderTaskSignalV2& RenderFinishedSignal();
291 public: // Not intended for application developers
294 * @brief Creates a handle using the Toolkit::Internal implementation.
296 * @param[in] implementation The Control implementation.
298 MaskedImageView(Internal::MaskedImageView& implementation);
301 * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
303 * @param[in] internal A pointer to the internal CustomActor.
305 MaskedImageView(Dali::Internal::CustomActor* internal);
308 } // namespace Toolkit
315 #endif // __DALI_TOOLKIT_MASKED_IMAGE_VIEW_H__