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 * @addtogroup CAPI_DALI_TOOLKIT_IMAGE_VIEW_MODULE
27 #include <dali-toolkit/public-api/controls/control.h>
29 namespace Dali DALI_IMPORT_API
35 namespace Internal DALI_INTERNAL
37 class MaskedImageView;
41 * @brief MaskedImageView displays the result of an image created from a masking operation.
44 * - Firstly a target image size is chosen. The MaskedImageView handles the creation of this image internally. Initially the
45 * target image will be filled according to the BACKGROUND_COLOR property.
46 * - A source image is provided and positioned with the target image area. The position of the source image (in pixels), can
47 * be controlled using the SOURCE_OFFSET and SOURCE_SIZE properties. By default the source image is centered within the target
48 * image, and stretched to fill. Note that by default, no attempt is made to maintain the aspect ratio of the source image.
49 * - A mask image is provided and positioned in the same way as the source image, using the MASK_OFFSET and MASK_SIZE properties.
50 * - Conceptually the source image is then painted using the mask image as a stencil. Areas of the source which overlap with opaque
51 * areas of the mask, will be painted into the target image. However where the mask is transparent, the source will be faded away.
52 * Note that the edge of the mask image will be stretched to cover the entire target area.
54 * Initially MaskedImageView will perform the masking operation on a per-frame basis. This can impact performance, and may be
55 * avoided by calling Pause() e.g. when the source & mask positions are not being modified. The Resume() method can then be called
56 * to continue the masking operation when required.
58 class MaskedImageView : public Control
63 * @brief The custom properties installed by this control.
67 BACKGROUND_COLOR, ///< Name "background-color", type VECTOR4
68 SOURCE_SIZE, ///< Name "source-size", type VECTOR2
69 SOURCE_OFFSET, ///< Name "source-offset", type VECTOR2
70 MASK_SIZE, ///< Name "mask-size", type VECTOR2
71 MASK_OFFSET, ///< Name "mask-offset", type VECTOR2
77 * @brief Edit mode for this control.
83 EDIT_DISABLED, ///< Editting is disabled
84 EDIT_SOURCE, ///< Editting affects the source image
85 EDIT_MASK ///< Editting affects the mask
89 * @brief The rotation of the image.
91 * @see SetSourceRotation()
95 ROTATE_0, ///< No rotation
96 ROTATE_90, ///< Image is rotated clockwise by 90 degrees
97 ROTATE_180, ///< Image is rotated clockwise by 180 degrees
98 ROTATE_270 ///< Image is rotated clockwise by 270 degrees
101 static const float DEFAULT_MAXIMUM_SOURCE_SCALE; ///< Default SetMaximumSourceScale() value
104 * @brief Creates an empty MaskedImageView handle.
109 * @brief Copy constructor.
111 * Creates another handle that points to the same real object
112 * @param handle to copy from
114 MaskedImageView( const MaskedImageView& handle );
117 * @brief Assignment operator.
119 * Changes this handle to point to another real object
120 * @param[in] handle the handle of the object to re-assign this to
121 * @return a reference to this
123 MaskedImageView& operator=( const MaskedImageView& handle );
128 * This is non-virtual since derived Handle types must not contain data or virtual methods.
133 * @brief Create the MaskedImageView control.
135 * @param[in] targetWidth The width of the target image
136 * @param[in] targetHeight The height of the target image
137 * @param[in] sourceImage The source image
138 * @param[in] maskImage The mask image
139 * @return A handle to the MaskedImageView control.
141 static MaskedImageView New( unsigned int targetWidth,
142 unsigned int targetHeight,
147 * @brief Downcast an Object handle to MaskedImageView.
149 * If handle points to an MaskedImageView the downcast produces
150 * valid handle. If not the returned handle is left uninitialized.
152 * @param[in] handle Handle to an object
153 * @return handle to a MaskedImageView or an uninitialized handle
155 static MaskedImageView DownCast( BaseHandle handle );
158 * @brief Set the image used as a source in the masking operation.
160 * @param[in] sourceImage The source image
162 void SetSourceImage( Image sourceImage );
165 * @brief Retrieve the image used as a source in the masking operation.
167 * @return sourceImage The source image
169 Image GetSourceImage();
172 * @brief Set the image used as a mask in the masking operation.
174 * @param[in] maskImage The mask image
176 void SetMaskImage( Image maskImage );
179 * @brief Retrieve the image used as a mask in the masking operation.
181 * @return sourceImage The mask image
183 Image GetMaskImage();
186 * @brief Get the property index for a custom MaskedImageView property.
188 * @param[in] customProperty A custom property enum defined in this class.
189 * @return The property index e.g. for use with Animation::AnimateTo()
191 Property::Index GetPropertyIndex( CustomProperty customProperty ) const;
194 * @brief Pause the masking operation to improve performance.
196 * Call this when the source & mask positions etc. are not being modified.
201 * @brief Resume the masking operation.
207 * @brief Query whether the masking operation has been paused.
209 * @return True if the masking operation has been paused.
211 bool IsPaused() const;
214 * @brief Enable or disable an edit mode.
216 * The default is EDIT_DISABLED.
217 * @param[in] editMode The edit mode required.
219 void SetEditMode( EditMode editMode );
222 * @brief Query which edit mode is enabled.
224 EditMode GetEditMode() const;
227 * @brief Set the aspect ratio to be preserved when editing the source image.
229 * @param[in] widthOverHeight The aspect ratio i.e. width divided by height. If a value
230 * of zero or less is set, then the aspect ratio of the source image will be ignored.
232 void SetSourceAspectRatio( float widthOverHeight );
235 * @brief Query the aspect ratio preserved when editing the source image.
237 * @return The aspect ratio (width divided by height) or zero if no aspect ratio is set.
239 float GetSourceAspectRatio() const;
242 * @brief Set the maximum scale applied when editing the source image.
244 * The minimum scale is implied by the target width/height i.e. the source image will
245 * always fill that area when edit mode is enabled.
246 * @param[in] scale The maximum scale.
248 void SetMaximumSourceScale( float scale );
251 * @brief Query the maximum scale applied when editing the source image.
253 * @return The maximum scale.
255 float GetMaximumSourceScale() const;
258 * @brief Set the rotation applied to the source image.
260 * @param[in] rotation The new rotation; by default the source image is not rotated (ROTATE_0).
262 void SetSourceRotation( ImageRotation rotation );
265 * @brief Query the rotation applied to the source image.
267 * @return The current rotation.
269 ImageRotation GetSourceRotation() const;
271 public: /* Signals */
273 /// @brief Finished signal type.
274 typedef SignalV2< void (MaskedImageView& source) > MaskedImageViewSignal;
277 * @brief Signal emitted when the render task which targets the
278 * frame buffer of the masked image has finished.
280 * This signal carries information of the control handle to the callback function.
283 MaskedImageViewSignal& MaskFinishedSignal();
286 * @deprecated Use MaskFinishedSignal() instead.
287 * Signal emitted when the render task which targets the frame buffer of the masked image has finished.
288 * @return the signal.
290 Dali::RenderTask::RenderTaskSignalV2& RenderFinishedSignal();
292 public: // Not intended for application developers
295 * @brief Creates a handle using the Toolkit::Internal implementation.
297 * @param[in] implementation The Control implementation.
299 MaskedImageView(Internal::MaskedImageView& implementation);
302 * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
304 * @param[in] internal A pointer to the internal CustomActor.
306 MaskedImageView(Dali::Internal::CustomActor* internal);
309 } // namespace Toolkit
316 #endif // __DALI_TOOLKIT_MASKED_IMAGE_VIEW_H__