1 #ifndef __DALI_IMAGE_ACTOR_H__
2 #define __DALI_IMAGE_ACTOR_H__
5 * Copyright (c) 2015 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.
25 #include <dali/public-api/actors/actor.h>
26 #include <dali/public-api/math/rect.h>
27 #include <dali/public-api/images/image.h>
28 #include <dali/public-api/shader-effects/shader-effect.h>
29 #include <dali/public-api/actors/blending.h>
30 #include <dali/public-api/actors/sampling.h>
35 * @addtogroup dali_core_actors
39 namespace Internal DALI_INTERNAL
45 * @DEPRECATED_1_1.11 Use an actor with renderer instead.
46 * @brief An actor for displaying images.
48 * Allows the developer to add an actor to stage which displays the content of an Image object.
50 * By default ImageActor can be viewed from all angles.
52 * If an ImageActor is created without setting size, then the actor takes the size of the image -
53 * this is the natural size.
54 * Setting a size on the ImageActor, e.g through the @ref Actor::SetSize api or through an animation will
55 * stop the natural size being used.
58 * @remarks This is an experimental feature and might not be supported in the next release. We do recommend not to use it. Use of ImageActor should be avoided unless shader effects need to be applied.
60 class DALI_IMPORT_API ImageActor : public Actor
65 * @brief An enumeration of properties belonging to the ImageActor class
67 * @remarks This is an experimental feature and might not be supported in the next release.
68 * We do recommend not to use it.
75 * @brief name "pixelArea", type Rect<int>
77 * @remarks This is an experimental feature and might not be supported in the next release.
78 * We do recommend not to use it.
80 PIXEL_AREA = DEFAULT_DERIVED_ACTOR_PROPERTY_START_INDEX,
83 * @brief name "style", type std::string
85 * @remarks This is an experimental feature and might not be supported in the next release.
86 * We do recommend not to use it.
91 * @brief name "border", type Vector4
93 * @remarks This is an experimental feature and might not be supported in the next release.
94 * We do recommend not to use it.
98 * @brief name "image", type Map {"filename":"", "loadPolicy":...}
100 * @remarks This is an experimental feature and might not be supported in the next release.
101 * We do recommend not to use it.
108 * @DEPRECATED_1_1.11. Only quad style supported.
110 * @brief Style determines how the Image is rendered.
114 * 0---------2 0-----------------2
118 * | / | SCALE (X) | / |
119 * | / | --------> | / |
124 * 1---------3 1-----------------3
126 * Image is rendered as a textured rectangle. The texture
127 * is scaled uniformly as the quad is resized.
130 * @remarks This is an experimental feature and might not be supported in the next release.
131 * We do recommend not to use it.
137 * @brief As a simple quad.
139 * @remarks This is an experimental feature and might not be supported in the next release.
140 * We do recommend not to use it.
145 * @brief As a nine-patch.
147 * @remarks This is an experimental feature and might not be supported in the next release.
148 * We do recommend not to use it.
153 * @brief As a nine-patch without center section being rendered.
155 * @remarks This is an experimental feature and might not be supported in the next release.
156 * We do recommend not to use it.
158 STYLE_NINE_PATCH_NO_CENTER
162 * @brief Pixel area is relative to the top-left (0,0) of the image.
164 * @remarks This is an experimental feature and might not be supported in the next release.
165 * We do recommend not to use it.
167 typedef Rect<int> PixelArea;
169 static const BlendingMode::Type DEFAULT_BLENDING_MODE; ///< default value is BlendingMode::AUTO
172 * @brief Create an uninitialized ImageActor handle.
174 * This can be initialized with ImageActor::New(...).
175 * Calling member functions with an uninitialized ImageActor handle is not allowed.
177 * @remarks This is an experimental feature and might not be supported in the next release.
178 * We do recommend not to use it.
183 * @brief Create an empty image actor object.
186 * @remarks This is an experimental feature and might not be supported in the next release.
187 * We do recommend not to use it.
188 * @return A handle to a newly allocated actor.
190 static ImageActor New();
193 * @brief Create a image actor object.
195 * The actor will take the image's natural size unless a custom size
196 * is chosen, e.g. via Actor:SetSize().
197 * If the handle is empty, ImageActor will display nothing.
199 * @remarks This is an experimental feature and might not be supported in the next release.
200 * We do recommend not to use it.
201 * @param[in] image The image to display.
202 * @return A handle to a newly allocated actor.
203 * @pre ImageActor must be initialized.
205 static ImageActor New(Image image);
208 * @brief Create a image actor object.
210 * The actor will take the image's natural size unless a custom size
211 * is chosen, e.g. via Actor:SetSize().
212 * If the handle is empty, ImageActor will display nothing.
214 * @remarks This is an experimental feature and might not be supported in the next release.
215 * We do recommend not to use it.
216 * @param [in] image The image to display.
217 * @param [in] pixelArea The area of the image to display.
218 * This in pixels, relative to the top-left (0,0) of the image.
219 * @return A handle to a newly allocated actor.
220 * @pre ImageActor must be initialized.
222 static ImageActor New(Image image, PixelArea pixelArea);
225 * @brief Downcast a handle to ImageActor handle.
228 * If handle points to a ImageActor the downcast produces valid
229 * handle. If not the returned handle is left uninitialized.
232 * @remarks This is an experimental feature and might not be supported in the next release.
233 * We do recommend not to use it.
234 * @param[in] handle Handle to an object
235 * @return Handle to a ImageActor or an uninitialized handle
237 static ImageActor DownCast( BaseHandle handle );
242 * This is non-virtual since derived Handle types must not contain data or virtual methods.
244 * @remarks This is an experimental feature and might not be supported in the next release.
245 * We do recommend not to use it.
250 * @brief Copy constructor
253 * @remarks This is an experimental feature and might not be supported in the next release.
254 * We do recommend not to use it.
255 * @param [in] copy The actor to copy
257 ImageActor(const ImageActor& copy);
260 * @brief Assignment operator
263 * @remarks This is an experimental feature and might not be supported in the next release.
264 * We do recommend not to use it.
265 * @param [in] rhs The actor to copy
266 * @return A reference to this
268 ImageActor& operator=(const ImageActor& rhs);
271 * @brief Set the image rendered by the actor.
273 * If actor was already displaying a different image, the old image is dropped and actor may
274 * temporarily display nothing. Setting an empty image (handle) causes the current image to be
275 * dropped and actor displays nothing.
276 * The actor will take the image's natural size unless a custom size
277 * is chosen, e.g. via Actor::SetSize().
280 * @remarks This is an experimental feature and might not be supported in the next release.
281 * We do recommend not to use it.
282 * @param [in] image The image to display
283 * @pre ImageActor must be initialized.
285 void SetImage(Image image);
288 * @brief Retrieve the image rendered by the actor.
290 * If no image is assigned, an empty handle is returned.
292 * @remarks This is an experimental feature and might not be supported in the next release.
293 * We do recommend not to use it.
299 * @brief Set a region of the image to display, in pixels.
301 * When the image is loaded the actor's size will be reset to the pixelArea,
302 * unless a custom size was chosen, e.g. via Actor::SetSize().
304 * @remarks This is an experimental feature and might not be supported in the next release.
305 * We do recommend not to use it.
306 * @param [in] pixelArea The area of the image to display.
307 * This in pixels, relative to the top-left (0,0) of the image.
308 * @pre Image must be initialized.
309 * @note PixelArea should be inside the image data size. It gets clamped by GL.
311 void SetPixelArea(const PixelArea& pixelArea);
314 * @brief Retrieve the region of the image to display, in pixels.
317 * @remarks This is an experimental feature and might not be supported in the next release.
318 * We do recommend not to use it.
319 * @return The pixel area, or a default-constructed area if none was set.
320 * @pre Image must be initialized.
322 PixelArea GetPixelArea() const;
327 * @brief Set how the image is rendered; the default is STYLE_QUAD.
330 * @remarks This is an experimental feature and might not be supported in the next release.
331 * We do recommend not to use it.
332 * @param [in] style The new style
333 * @pre Image must be initialized.
334 * @note The style specified is set (so GetStyle will return what's set) but ignored internally.
336 void SetStyle(Style style);
341 * @brief Query how the image is rendered.
344 * @remarks This is an experimental feature and might not be supported in the next release.
345 * We do recommend not to use it.
346 * @return The rendering style
347 * @pre Image must be initialized.
348 * @note This just returns the style set by SetStyle. In reality, only STYLE_QUAD is supported.
350 Style GetStyle() const;
355 * @brief Set the border used with ImageActor::STYLE_NINE_PATCH.
357 * The values are in pixels from the left, top, right, and bottom of the image respectively.
358 * i.e. ImageActor::SetNinePatchBorder( Vector4(1,2,3,4) ) sets the left-border to 1, top-border to 2, right-border to 3, and bottom-border to 4 pixels.
360 * @remarks This is an experimental feature and might not be supported in the next release.
361 * We do recommend not to use it.
362 * @param [in] border The new nine-patch border
364 void SetNinePatchBorder(const Vector4& border);
369 * @brief Retrieve the border used with ImageActor::STYLE_NINE_PATCH.
372 * @remarks This is an experimental feature and might not be supported in the next release.
373 * We do recommend not to use it.
374 * @return The nine-patch border.
376 Vector4 GetNinePatchBorder() const;
380 * @brief Allows modification of an actors position in the depth sort algorithm.
382 * The offset can be altered for each coplanar actor hence allowing an order of painting.
384 * @remarks This is an experimental feature and might not be supported in the next release.
385 * We do recommend not to use it.
386 * @param [in] depthOffset The offset to be given to the actor. Positive values pushing it up front.
387 * @pre The Actor has been initialized.
388 * @see Layer::Behavior
390 void SetSortModifier(float depthOffset);
393 * @brief Retrieves the offset used to modify an actors position in the depth sort algorithm.
395 * The offset can be altered for each coplanar actor hence allowing an order of painting.
397 * @remarks This is an experimental feature and might not be supported in the next release.
398 * We do recommend not to use it.
399 * @return The offset that has been given to the actor. Positive values pushing it further back.
400 * @pre The Actor has been initialized.
401 * @see Layer::Behavior
403 float GetSortModifier() const;
406 * @brief Sets the blending mode.
408 * Possible values are: BlendingMode::OFF, BlendingMode::AUTO and BlendingMode::ON. Default is BlendingMode::AUTO.
410 * If blending is disabled (BlendingMode::OFF) fade in and fade out animations do not work.
413 * <li> \e OFF Blending is disabled.
414 * <li> \e AUTO Blending is enabled only if the renderable actor has alpha channel.
415 * <li> \e ON Blending is enabled.
419 * @remarks This is an experimental feature and might not be supported in the next release.
420 * We do recommend not to use it.
421 * @param[in] mode The blending mode
423 void SetBlendMode( BlendingMode::Type mode );
426 * @brief Retrieves the blending mode.
429 * @remarks This is an experimental feature and might not be supported in the next release.
430 * We do recommend not to use it.
431 * @return The blending mode, one of BlendingMode::OFF, BlendingMode::AUTO or BlendingMode::ON.
433 BlendingMode::Type GetBlendMode() const;
436 * @brief Specify the pixel arithmetic used when the actor is blended.
439 * @remarks This is an experimental feature and might not be supported in the next release.
440 * We do recommend not to use it.
441 * @param[in] srcFactorRgba Specifies how the red, green, blue, and alpha source blending factors are computed.
442 * The options are BlendingFactor::ZERO, ONE, SRC_COLOR, ONE_MINUS_SRC_COLOR, DST_COLOR, ONE_MINUS_DST_COLOR,
443 * SRC_ALPHA, ONE_MINUS_SRC_ALPHA, DST_ALPHA, ONE_MINUS_DST_ALPHA, CONSTANT_COLOR, ONE_MINUS_CONSTANT_COLOR,
444 * GL_CONSTANT_ALPHA, GL_ONE_MINUS_CONSTANT_ALPHA, and GL_SRC_ALPHA_SATURATE.
446 * @param[in] destFactorRgba Specifies how the red, green, blue, and alpha destination blending factors are computed.
447 * The options are BlendingFactor::ZERO, ONE, SRC_COLOR, ONE_MINUS_SRC_COLOR, DST_COLOR, ONE_MINUS_DST_COLOR,
448 * SRC_ALPHA, ONE_MINUS_SRC_ALPHA, DST_ALPHA, ONE_MINUS_DST_ALPHA, CONSTANT_COLOR, ONE_MINUS_CONSTANT_COLOR,
449 * GL_CONSTANT_ALPHA, and GL_ONE_MINUS_CONSTANT_ALPHA.
451 void SetBlendFunc( BlendingFactor::Type srcFactorRgba, BlendingFactor::Type destFactorRgba );
454 * @brief Specify the pixel arithmetic used when the actor is blended.
457 * @remarks This is an experimental feature and might not be supported in the next release.
458 * We do recommend not to use it.
459 * @param[in] srcFactorRgb Specifies how the red, green, and blue source blending factors are computed.
460 * The options are BlendingFactor::ZERO, ONE, SRC_COLOR, ONE_MINUS_SRC_COLOR, DST_COLOR, ONE_MINUS_DST_COLOR,
461 * SRC_ALPHA, ONE_MINUS_SRC_ALPHA, DST_ALPHA, ONE_MINUS_DST_ALPHA, CONSTANT_COLOR, ONE_MINUS_CONSTANT_COLOR,
462 * GL_CONSTANT_ALPHA, GL_ONE_MINUS_CONSTANT_ALPHA, and GL_SRC_ALPHA_SATURATE.
464 * @param[in] destFactorRgb Specifies how the red, green, blue, and alpha destination blending factors are computed.
465 * The options are BlendingFactor::ZERO, ONE, SRC_COLOR, ONE_MINUS_SRC_COLOR, DST_COLOR, ONE_MINUS_DST_COLOR,
466 * SRC_ALPHA, ONE_MINUS_SRC_ALPHA, DST_ALPHA, ONE_MINUS_DST_ALPHA, CONSTANT_COLOR, ONE_MINUS_CONSTANT_COLOR,
467 * GL_CONSTANT_ALPHA, and GL_ONE_MINUS_CONSTANT_ALPHA.
469 * @param[in] srcFactorAlpha Specifies how the alpha source blending factor is computed.
470 * The options are the same as for srcFactorRgb.
472 * @param[in] destFactorAlpha Specifies how the alpha source blending factor is computed.
473 * The options are the same as for destFactorRgb.
475 void SetBlendFunc( BlendingFactor::Type srcFactorRgb, BlendingFactor::Type destFactorRgb,
476 BlendingFactor::Type srcFactorAlpha, BlendingFactor::Type destFactorAlpha );
479 * @brief Query the pixel arithmetic used when the actor is blended.
482 * @remarks This is an experimental feature and might not be supported in the next release.
483 * We do recommend not to use it.
484 * @param[out] srcFactorRgb Specifies how the red, green and blue source blending factors are computed.
485 * @param[out] destFactorRgb Specifies how the red, green and blue destination blending factors are computed.
486 * @param[out] srcFactorAlpha Specifies how the alpha source blending factor is computed.
487 * @param[out] destFactorAlpha Specifies how the alpha destination blending factor is computed.
489 void GetBlendFunc( BlendingFactor::Type& srcFactorRgb, BlendingFactor::Type& destFactorRgb,
490 BlendingFactor::Type& srcFactorAlpha, BlendingFactor::Type& destFactorAlpha ) const;
493 * @brief Specify the equation used when the actor is blended.
495 * The options are BlendingEquation::ADD, BlendingEquation::SUBTRACT, or BlendingEquation::REVERSE_SUBTRACT.
497 * @remarks This is an experimental feature and might not be supported in the next release.
498 * We do recommend not to use it.
499 * @param[in] equationRgba The equation used for combining red, green, blue, and alpha components.
501 void SetBlendEquation( BlendingEquation::Type equationRgba );
504 * @brief Specify the equation used when the actor is blended.
507 * @remarks This is an experimental feature and might not be supported in the next release.
508 * We do recommend not to use it.
509 * @param[in] equationRgb The equation used for combining red, green, and blue components.
510 * @param[in] equationAlpha The equation used for combining the alpha component.
511 * The options are BlendingEquation::ADD, BlendingEquation::SUBTRACT, or BlendingEquation::REVERSE_SUBTRACT.
513 void SetBlendEquation( BlendingEquation::Type equationRgb, BlendingEquation::Type equationAlpha );
516 * @brief Query the equation used when the actor is blended.
519 * @remarks This is an experimental feature and might not be supported in the next release.
520 * We do recommend not to use it.
521 * @param[out] equationRgb The equation used for combining red, green, and blue components.
522 * @param[out] equationAlpha The equation used for combining the alpha component.
524 void GetBlendEquation( BlendingEquation::Type& equationRgb, BlendingEquation::Type& equationAlpha ) const;
527 * @brief Specify the color used when the actor is blended; the default is Vector4::ZERO.
530 * @remarks This is an experimental feature and might not be supported in the next release.
531 * We do recommend not to use it.
532 * @param[in] color The blend color
534 void SetBlendColor( const Vector4& color );
537 * @brief Query the color used when the actor is blended.
540 * @remarks This is an experimental feature and might not be supported in the next release.
541 * We do recommend not to use it.
542 * @return The blend color
544 const Vector4& GetBlendColor() const;
547 * @brief Sets the filtering mode.
549 * Possible values are: FilterMode::NEAREST and FilterMode::LINEAR. Default is FilterMode::LINEAR.
552 * <li> \e NEAREST Use nearest filtering
553 * <li> \e LINEAR Use linear filtering
557 * @remarks This is an experimental feature and might not be supported in the next release.
558 * We do recommend not to use it.
559 * @param[in] minFilter The minification filtering mode
560 * @param[in] magFilter The magnification filtering mode
562 void SetFilterMode( FilterMode::Type minFilter, FilterMode::Type magFilter );
565 * @brief Retrieves the filtering mode.
568 * @remarks This is an experimental feature and might not be supported in the next release.
569 * We do recommend not to use it.
570 * @param[out] minFilter The return minification value
571 * @param[out] magFilter The return magnification value
573 void GetFilterMode( FilterMode::Type& minFilter, FilterMode::Type& magFilter) const;
576 * @brief Sets the shader effect for the ImageActor.
578 * Shader effects provide special effects like ripple and bend.
579 * Setting a shader effect removes any shader effect previously set by @ref ImageActor::SetShaderEffect.
581 * @remarks This is an experimental feature and might not be supported in the next release.
582 * We do recommend not to use it.
583 * @param [in] effect The shader effect
584 * @pre The actor has been initialized.
585 * @pre Effect has been initialized.
587 void SetShaderEffect( ShaderEffect effect );
590 * @brief Retrieve the custom shader effect for the ImageActor.
592 * If default shader is used an empty handle is returned.
595 * @remarks This is an experimental feature and might not be supported in the next release.
596 * We do recommend not to use it.
597 * @return The shader effect
598 * @pre The Actor has been initialized.
600 ShaderEffect GetShaderEffect() const;
603 * @brief Removes the current shader effect.
606 * @remarks This is an experimental feature and might not be supported in the next release.
607 * We do recommend not to use it.
608 * @pre The Actor has been initialized.
610 void RemoveShaderEffect();
613 public: // Not intended for application developers
615 explicit DALI_INTERNAL ImageActor(Internal::ImageActor*);
620 * @brief Sets the shader effect for all ImageActors in a tree of Actors.
623 * @remarks This is an experimental feature and might not be supported in the next release.
624 * We do recommend not to use it.
625 * @param [in] actor Root of a tree of actors
626 * @param [in] effect The shader effect
627 * @see ImageActor::SetShaderEffect
630 DALI_IMPORT_API void SetShaderEffectRecursively( Dali::Actor actor, Dali::ShaderEffect effect );
633 * @brief Removes the shader effect from all ImageActors in a tree of Actors.
636 * @remarks This is an experimental feature and might not be supported in the next release.
637 * We do recommend not to use it.
638 * @param [in] actor Root of a tree of actors
639 * @see ImageActor::RemoveShaderEffect
642 DALI_IMPORT_API void RemoveShaderEffectRecursively( Dali::Actor actor );
649 #endif // __DALI_IMAGE_ACTOR_H__