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 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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
22 #include <dali-toolkit/public-api/controls/control.h>
30 namespace Internal DALI_INTERNAL
32 class MaskedImageView;
36 * @brief MaskedImageView displays the result of an image created from a masking operation.
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.
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.
53 class DALI_IMPORT_API MaskedImageView : public Control
58 * @brief The custom properties installed by this control.
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
72 * @brief Edit mode for this control.
78 EDIT_DISABLED, ///< Editting is disabled
79 EDIT_SOURCE, ///< Editting affects the source image
80 EDIT_MASK ///< Editting affects the mask
84 * @brief The rotation of the image.
86 * @see SetSourceRotation()
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
96 static const float DEFAULT_MAXIMUM_SOURCE_SCALE; ///< Default SetMaximumSourceScale() value
99 * @brief Creates an empty MaskedImageView handle.
104 * @brief Copy constructor.
106 * Creates another handle that points to the same real object
107 * @param handle to copy from
109 MaskedImageView( const MaskedImageView& handle );
112 * @brief Assignment operator.
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
118 MaskedImageView& operator=( const MaskedImageView& handle );
123 * This is non-virtual since derived Handle types must not contain data or virtual methods.
128 * @brief Create the MaskedImageView control.
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.
136 static MaskedImageView New( unsigned int targetWidth,
137 unsigned int targetHeight,
142 * @brief Downcast an Object handle to MaskedImageView.
144 * If handle points to an MaskedImageView the downcast produces
145 * valid handle. If not the returned handle is left uninitialized.
147 * @param[in] handle Handle to an object
148 * @return handle to a MaskedImageView or an uninitialized handle
150 static MaskedImageView DownCast( BaseHandle handle );
153 * @brief Set the image used as a source in the masking operation.
155 * @param[in] sourceImage The source image
157 void SetSourceImage( Image sourceImage );
160 * @brief Retrieve the image used as a source in the masking operation.
162 * @return sourceImage The source image
164 Image GetSourceImage();
167 * @brief Set the image used as a mask in the masking operation.
169 * @param[in] maskImage The mask image
171 void SetMaskImage( Image maskImage );
174 * @brief Retrieve the image used as a mask in the masking operation.
176 * @return sourceImage The mask image
178 Image GetMaskImage();
181 * @brief Get the property index for a custom MaskedImageView property.
183 * @param[in] customProperty A custom property enum defined in this class.
184 * @return The property index e.g. for use with Animation::AnimateTo()
186 Dali::Property::Index GetPropertyIndex( CustomProperty customProperty ) const;
189 * @brief Pause the masking operation to improve performance.
191 * Call this when the source & mask positions etc. are not being modified.
196 * @brief Resume the masking operation.
202 * @brief Query whether the masking operation has been paused.
204 * @return True if the masking operation has been paused.
206 bool IsPaused() const;
209 * @brief Enable or disable an edit mode.
211 * The default is EDIT_DISABLED.
212 * @param[in] editMode The edit mode required.
214 void SetEditMode( EditMode editMode );
217 * @brief Query which edit mode is enabled.
219 EditMode GetEditMode() const;
222 * @brief Set the aspect ratio to be preserved when editing the source image.
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.
227 void SetSourceAspectRatio( float widthOverHeight );
230 * @brief Query the aspect ratio preserved when editing the source image.
232 * @return The aspect ratio (width divided by height) or zero if no aspect ratio is set.
234 float GetSourceAspectRatio() const;
237 * @brief Set the maximum scale applied when editing the source image.
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.
243 void SetMaximumSourceScale( float scale );
246 * @brief Query the maximum scale applied when editing the source image.
248 * @return The maximum scale.
250 float GetMaximumSourceScale() const;
253 * @brief Set the rotation applied to the source image.
255 * @param[in] rotation The new rotation; by default the source image is not rotated (ROTATE_0).
257 void SetSourceRotation( ImageRotation rotation );
260 * @brief Query the rotation applied to the source image.
262 * @return The current rotation.
264 ImageRotation GetSourceRotation() const;
266 public: /* Signals */
268 /// @brief Finished signal type.
269 typedef Signal< void (MaskedImageView& source) > MaskedImageViewSignal;
272 * @brief Signal emitted when the render task which targets the
273 * frame buffer of the masked image has finished.
275 * This signal carries information of the control handle to the callback function.
278 MaskedImageViewSignal& MaskFinishedSignal();
280 public: // Not intended for application developers
283 * @brief Creates a handle using the Toolkit::Internal implementation.
285 * @param[in] implementation The Control implementation.
287 DALI_INTERNAL MaskedImageView(Internal::MaskedImageView& implementation);
290 * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
292 * @param[in] internal A pointer to the internal CustomActor.
294 explicit DALI_INTERNAL MaskedImageView(Dali::Internal::CustomActor* internal);
297 } // namespace Toolkit
301 #endif // __DALI_TOOLKIT_MASKED_IMAGE_VIEW_H__