dali/public-api/actors/image-actor.h

   1 #ifndef __DALI_IMAGE_ACTOR_H__
   2 #define __DALI_IMAGE_ACTOR_H__
   3
   4 /*
   5  * Copyright (c) 2015 Samsung Electronics Co., Ltd.
   6  *
   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
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  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.
  18  *
  19  */
  20
  21 // EXTERNAL INCLUDES
  22 #include <string>
  23
  24 // INTERNAL INCLUDES
  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>
  31
  32 namespace Dali
  33 {
  34 /**
  35  * @addtogroup dali_core_actors
  36  * @{
  37  */
  38
  39 namespace Internal DALI_INTERNAL
  40 {
  41 class ImageActor;
  42 }
  43
  44 /**
  45  * @brief An actor for displaying images.
  46  *
  47  * Allows the developer to add an actor to stage which displays the content of an Image object.
  48  *
  49  * By default ImageActor can be viewed from all angles.
  50  *
  51  * If an ImageActor is created without setting size, then the actor takes the size of the image -
  52  * this is the natural size.
  53  * Setting a size on the ImageActor, e.g through the SetSize api or through an animation will
  54  * stop the natural size being used.
  55  *
  56  * If a pixel area is set on an ImageActor with natural size, the actor size will change
  57  * to match the pixel area. If a pixel area is set on an ImageActor that has had it's size set,
  58  * then the size doesn't change, and the partial image will be stretched to fill the set size.
  59  *
  60  * Clearing the pixel area on an Image actor with natural size will cause the actor to show the
  61  * whole image again, and will change size back to that of the image.
  62  *
  63  * Clearing the pixel area on an Image actor with a set size will cause the actor to show the
  64  * whole image again, but will not change the image size.
  65  * @SINCE_1_0.0
  66  */
  67 class DALI_IMPORT_API ImageActor : public Actor
  68 {
  69 public:
  70
  71   /**
  72    * @brief An enumeration of properties belonging to the ImageActor class.
  73    * Properties additional to RenderableActor.
  74    * @SINCE_1_0.0
  75    */
  76   struct Property
  77   {
  78     enum
  79     {
  80       PIXEL_AREA = DEFAULT_DERIVED_ACTOR_PROPERTY_START_INDEX, ///< name "pixelArea",   type Rect<int> @SINCE_1_0.0
  81       STYLE,                                                   ///< @deprecated Dali 1.1.11 name "style",       type std::string @SINCE_1_0.0
  82       BORDER,                                                  ///< @deprecated Dali 1.1.11 name "border",      type Vector4 @SINCE_1_0.0
  83       IMAGE,                                                   ///< name "image",       type Map {"filename":"", "loadPolicy":...} @SINCE_1_0.0
  84     };
  85   };
  86
  87   /**
  88    * @deprecated DALi 1.1.11, only quad style supported, use ImageView instead for nine patch
  89    *
  90    * @brief Style determines how the Image is rendered.
  91    *
  92    * STYLE_QUAD:
  93    *
  94    *  0---------2           0-----------------2
  95    *  |        /|           |                /|
  96    *  |  A    / |           |      A       /  |
  97    *  |      /  |           |            /    |
  98    *  |     /   | SCALE (X) |          /      |
  99    *  |    /    | --------> |        /        |
 100    *  |   /     |           |      /          |
 101    *  |  /      |           |    /            |
 102    *  | /    B  |           |  /        B     |
 103    *  |/        |           |/                |
 104    *  1---------3           1-----------------3
 105    *
 106    * Image is rendered as a textured rectangle. The texture
 107    * is scaled uniformly as the quad is resized.
 108    *
 109    * @SINCE_1_0.0
 110    */
 111   enum Style
 112   {
 113     STYLE_QUAD,                 ///< As a simple quad. @SINCE_1_0.0
 114     STYLE_NINE_PATCH,           ///< @deprecated Dali 1.1.11 As a nine-patch. @SINCE_1_0.0
 115     STYLE_NINE_PATCH_NO_CENTER  ///< @deprecated Dali 1.1.11 As a nine-patch without center section being rendered. @SINCE_1_0.0
 116   };
 117
 118   /**
 119    * @brief Pixel area is relative to the top-left (0,0) of the image.
 120    * @SINCE_1_0.0
 121    */
 122   typedef Rect<int> PixelArea;
 123
 124   static const BlendingMode::Type DEFAULT_BLENDING_MODE; ///< default value is BlendingMode::AUTO
 125
 126   /**
 127    * @brief Create an uninitialized ImageActor handle.
 128    *
 129    * This can be initialized with ImageActor::New(...)
 130    * Calling member functions with an uninitialized Dali::Object is not allowed.
 131    * @SINCE_1_0.0
 132    */
 133   ImageActor();
 134
 135   /**
 136    * @brief Create an empty image actor object.
 137    *
 138    * @SINCE_1_0.0
 139    * @return A handle to a newly allocated actor.
 140    */
 141   static ImageActor New();
 142
 143   /**
 144    * @brief Create a image actor object.
 145    *
 146    * The actor will take the image's natural size unless a custom size
 147    * is chosen, e.g. via Actor:SetSize().
 148    * If the handle is empty, ImageActor will display nothing
 149    * @SINCE_1_0.0
 150    * @param[in] image The image to display.
 151    * @return A handle to a newly allocated actor.
 152    * @pre ImageActor must be initialized.
 153    */
 154   static ImageActor New(Image image);
 155
 156   /**
 157    * @brief Create a image actor object.
 158    *
 159    * The actor will take the image's natural size unless a custom size
 160    * is chosen, e.g. via Actor:SetSize()
 161    * If the handle is empty, ImageActor will display nothing
 162    * @SINCE_1_0.0
 163    * @param [in] image The image to display.
 164    * @param [in] pixelArea The area of the image to display.
 165    * This in pixels, relative to the top-left (0,0) of the image.
 166    * @return A handle to a newly allocated actor.
 167    * @pre ImageActor must be initialized.
 168    */
 169   static ImageActor New(Image image, PixelArea pixelArea);
 170
 171   /**
 172    * @brief Downcast an Object handle to ImageActor.
 173    *
 174    *
 175    * If handle points to a ImageActor the downcast produces valid
 176    * handle. If not the returned handle is left uninitialized.
 177    *
 178    * @SINCE_1_0.0
 179    * @param[in] handle to An object
 180    * @return handle to a ImageActor or an uninitialized handle
 181    */
 182   static ImageActor DownCast( BaseHandle handle );
 183
 184   /**
 185    * @brief Destructor
 186    *
 187    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 188    * @SINCE_1_0.0
 189    */
 190   ~ImageActor();
 191
 192   /**
 193    * @brief Copy constructor
 194    *
 195    * @SINCE_1_0.0
 196    * @param [in] copy The actor to copy.
 197    */
 198   ImageActor(const ImageActor& copy);
 199
 200   /**
 201    * @brief Assignment operator
 202    *
 203    * @SINCE_1_0.0
 204    * @param [in] rhs The actor to copy.
 205    */
 206   ImageActor& operator=(const ImageActor& rhs);
 207
 208   /**
 209    * @brief Set the image rendered by the actor.
 210    * Set the image rendered by the actor.
 211    * If actor was already displaying a different image, the old image is dropped and actor may
 212    * temporarily display nothing. Setting an empty image (handle) causes the current image to be
 213    * dropped and actor displays nothing.
 214    * The actor will take the image's natural size unless a custom size
 215    * is chosen, e.g. via Actor:SetSize()
 216    *
 217    * @SINCE_1_0.0
 218    * @param [in] image The image to display.
 219    * @pre ImageActor must be initialized.
 220    */
 221   void SetImage(Image image);
 222
 223   /**
 224    * @brief Retrieve the image rendered by the actor.
 225    *
 226    * If no image is assigned, an empty handle is returned
 227    * @SINCE_1_0.0
 228    * @return The image.
 229    */
 230   Image GetImage();
 231
 232   /**
 233    * @brief Set a region of the image to display, in pixels.
 234    *
 235    * When the image is loaded the actor's size will be reset to the pixelArea,
 236    * unless a custom size was chosen, e.g. via Actor:SetSize().
 237    * Note! PixelArea should be inside the image data size. It gets clamped by GL
 238    * @SINCE_1_0.0
 239    * @param [in] pixelArea The area of the image to display.
 240    * This in pixels, relative to the top-left (0,0) of the image.
 241    * @pre image must be initialized.
 242    */
 243   void SetPixelArea(const PixelArea& pixelArea);
 244
 245   /**
 246    * @brief Retrieve the region of the image to display, in pixels.
 247    *
 248    * @SINCE_1_0.0
 249    * @return The pixel area, or a default-constructed area if none was set.
 250    * @pre image must be initialized.
 251    */
 252   PixelArea GetPixelArea() const;
 253
 254   /**
 255    * @deprecated DALi 1.1.11, use ImageView instead
 256    *
 257    * @brief Set how the image is rendered; the default is STYLE_QUAD.
 258    *
 259    * @SINCE_1_0.0
 260    * @param [in] style The new style.
 261    *
 262    * @pre image must be initialized.
 263    * @note The style specified is set (so GetStyle will return what's set) but ignored internally.
 264    */
 265   void SetStyle(Style style);
 266
 267   /**
 268    * @deprecated DALi 1.1.11, use ImageView instead
 269    *
 270    * @brief Query how the image is rendered.
 271    *
 272    * @SINCE_1_0.0
 273    * @return The rendering style.
 274    *
 275    * @pre image must be initialized.
 276    * @note This just returns the style set by SetStyle. In reality, only STYLE_QUAD is supported.
 277    */
 278   Style GetStyle() const;
 279
 280   /**
 281    * @deprecated DALi 1.1.11, use ImageView instead
 282    *
 283    * @brief Set the border used with STYLE_NINE_PATCH.
 284    *
 285    * The values are in pixels from the left, top, right, and bottom of the image respectively.
 286    * i.e. 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.
 287    * @SINCE_1_0.0
 288    * @param [in] border The new nine-patch border.
 289    */
 290   void SetNinePatchBorder(const Vector4& border);
 291
 292   /**
 293    * @deprecated DALi 1.1.11, use ImageView instead
 294    *
 295    * @brief Retrieve the border used with STYLE_NINE_PATCH.
 296    *
 297    * @SINCE_1_0.0
 298    * @return The nine-patch border.
 299    */
 300   Vector4 GetNinePatchBorder() const;
 301
 302
 303   /**
 304    * @brief Allows modification of an actors position in the depth sort algorithm.
 305    *
 306    * The offset can be altered for each coplanar actor hence allowing an order of painting.
 307    * @SINCE_1_0.0
 308    * @param [in] depthOffset the offset to be given to the actor. Positive values pushing it further back.
 309    * @pre The Actor has been initialized.
 310    */
 311   void SetSortModifier(float depthOffset);
 312
 313   /**
 314    * @brief Retrieves the offset used to modify an actors position in the depth sort algorithm.
 315    *
 316    * The offset can be altered for each coplanar actor hence allowing an order of painting.
 317    * @SINCE_1_0.0
 318    * @return  the offset that has been given to the actor. Positive values pushing it further back.
 319    * @pre The Actor has been initialized.
 320    */
 321   float GetSortModifier() const;
 322
 323   /**
 324    * @brief Sets the blending mode.
 325    *
 326    * Possible values are: BlendingMode::OFF, BlendingMode::AUTO and BlendingMode::ON. Default is BlendingMode::AUTO.
 327    *
 328    * If blending is disabled (BlendingMode::OFF) fade in and fade out animations do not work.
 329    *
 330    * <ul>
 331    *   <li> \e OFF Blending is disabled.
 332    *   <li> \e AUTO Blending is enabled only if the renderable actor has alpha channel.
 333    *   <li> \e ON Blending is enabled.
 334    * </ul>
 335    *
 336    * @SINCE_1_0.0
 337    * @param[in] mode The blending mode.
 338    */
 339   void SetBlendMode( BlendingMode::Type mode );
 340
 341   /**
 342    * @brief Retrieves the blending mode.
 343    *
 344    * @SINCE_1_0.0
 345    * @return The blending mode, one of BlendingMode::OFF, BlendingMode::AUTO or BlendingMode::ON.
 346    */
 347   BlendingMode::Type GetBlendMode() const;
 348
 349   /**
 350    * @brief Specify the pixel arithmetic used when the actor is blended.
 351    *
 352    * @SINCE_1_0.0
 353    * @param[in] srcFactorRgba Specifies how the red, green, blue, and alpha source blending factors are computed.
 354    * The options are BlendingFactor::ZERO, ONE, SRC_COLOR, ONE_MINUS_SRC_COLOR, DST_COLOR, ONE_MINUS_DST_COLOR,
 355    * SRC_ALPHA, ONE_MINUS_SRC_ALPHA, DST_ALPHA, ONE_MINUS_DST_ALPHA, CONSTANT_COLOR, ONE_MINUS_CONSTANT_COLOR,
 356    * GL_CONSTANT_ALPHA, GL_ONE_MINUS_CONSTANT_ALPHA, and GL_SRC_ALPHA_SATURATE.
 357    *
 358    * @param[in] destFactorRgba Specifies how the red, green, blue, and alpha destination blending factors are computed.
 359    * The options are BlendingFactor::ZERO, ONE, SRC_COLOR, ONE_MINUS_SRC_COLOR, DST_COLOR, ONE_MINUS_DST_COLOR,
 360    * SRC_ALPHA, ONE_MINUS_SRC_ALPHA, DST_ALPHA, ONE_MINUS_DST_ALPHA, CONSTANT_COLOR, ONE_MINUS_CONSTANT_COLOR,
 361    * GL_CONSTANT_ALPHA, and GL_ONE_MINUS_CONSTANT_ALPHA.
 362    */
 363   void SetBlendFunc( BlendingFactor::Type srcFactorRgba, BlendingFactor::Type destFactorRgba );
 364
 365   /**
 366    * @brief Specify the pixel arithmetic used when the actor is blended.
 367    *
 368    * @SINCE_1_0.0
 369    * @param[in] srcFactorRgb Specifies how the red, green, and blue source blending factors are computed.
 370    * The options are BlendingFactor::ZERO, ONE, SRC_COLOR, ONE_MINUS_SRC_COLOR, DST_COLOR, ONE_MINUS_DST_COLOR,
 371    * SRC_ALPHA, ONE_MINUS_SRC_ALPHA, DST_ALPHA, ONE_MINUS_DST_ALPHA, CONSTANT_COLOR, ONE_MINUS_CONSTANT_COLOR,
 372    * GL_CONSTANT_ALPHA, GL_ONE_MINUS_CONSTANT_ALPHA, and GL_SRC_ALPHA_SATURATE.
 373    *
 374    * @param[in] destFactorRgb Specifies how the red, green, blue, and alpha destination blending factors are computed.
 375    * The options are BlendingFactor::ZERO, ONE, SRC_COLOR, ONE_MINUS_SRC_COLOR, DST_COLOR, ONE_MINUS_DST_COLOR,
 376    * SRC_ALPHA, ONE_MINUS_SRC_ALPHA, DST_ALPHA, ONE_MINUS_DST_ALPHA, CONSTANT_COLOR, ONE_MINUS_CONSTANT_COLOR,
 377    * GL_CONSTANT_ALPHA, and GL_ONE_MINUS_CONSTANT_ALPHA.
 378    *
 379    * @param[in] srcFactorAlpha Specifies how the alpha source blending factor is computed.
 380    * The options are the same as for srcFactorRgb.
 381    *
 382    * @param[in] destFactorAlpha Specifies how the alpha source blending factor is computed.
 383    * The options are the same as for destFactorRgb.
 384    */
 385   void SetBlendFunc( BlendingFactor::Type srcFactorRgb,   BlendingFactor::Type destFactorRgb,
 386                      BlendingFactor::Type srcFactorAlpha, BlendingFactor::Type destFactorAlpha );
 387
 388   /**
 389    * @brief Query the pixel arithmetic used when the actor is blended.
 390    *
 391    * @SINCE_1_0.0
 392    * @param[out] srcFactorRgb Specifies how the red, green, blue, and alpha source blending factors are computed.
 393    * @param[out] destFactorRgb Specifies how the red, green, blue, and alpha destination blending factors are computed.
 394    * @param[out] srcFactorAlpha Specifies how the red, green, blue, and alpha source blending factors are computed.
 395    * @param[out] destFactorAlpha Specifies how the red, green, blue, and alpha destination blending factors are computed.
 396    */
 397   void GetBlendFunc( BlendingFactor::Type& srcFactorRgb,   BlendingFactor::Type& destFactorRgb,
 398                      BlendingFactor::Type& srcFactorAlpha, BlendingFactor::Type& destFactorAlpha ) const;
 399
 400   /**
 401    * @brief Specify the equation used when the actor is blended.
 402    *
 403    * The options are BlendingEquation::ADD, SUBTRACT, or REVERSE_SUBTRACT.
 404    * @SINCE_1_0.0
 405    * @param[in] equationRgba The equation used for combining red, green, blue, and alpha components.
 406    */
 407   void SetBlendEquation( BlendingEquation::Type equationRgba );
 408
 409   /**
 410    * @brief Specify the equation used when the actor is blended.
 411    *
 412    * @SINCE_1_0.0
 413    * @param[in] equationRgb The equation used for combining red, green, and blue components.
 414    * @param[in] equationAlpha The equation used for combining the alpha component.
 415    * The options are BlendingEquation::ADD, SUBTRACT, or REVERSE_SUBTRACT.
 416    */
 417   void SetBlendEquation( BlendingEquation::Type equationRgb, BlendingEquation::Type equationAlpha );
 418
 419   /**
 420    * @brief Query the equation used when the actor is blended.
 421    *
 422    * @SINCE_1_0.0
 423    * @param[out] equationRgb The equation used for combining red, green, and blue components.
 424    * @param[out] equationAlpha The equation used for combining the alpha component.
 425    */
 426   void GetBlendEquation( BlendingEquation::Type& equationRgb, BlendingEquation::Type& equationAlpha ) const;
 427
 428   /**
 429    * @brief Specify the color used when the actor is blended; the default is Vector4::ZERO.
 430    *
 431    * @SINCE_1_0.0
 432    * @param[in] color The blend color.
 433    */
 434   void SetBlendColor( const Vector4& color );
 435
 436   /**
 437    * @brief Query the color used when the actor is blended.
 438    *
 439    * @SINCE_1_0.0
 440    * @return The blend color.
 441    */
 442   const Vector4& GetBlendColor() const;
 443
 444   /**
 445    * @brief Sets the filtering mode.
 446    *
 447    * Possible values are: FilterMode::NEAREST and FilterMode::LINEAR. Default is FilterMode::LINEAR.
 448    *
 449    * <ul>
 450    *   <li> \e NEAREST Use nearest filtering
 451    *   <li> \e LINEAR Use linear filtering
 452    * </ul>
 453    *
 454    * @SINCE_1_0.0
 455    * @param[in] minFilter The minification filtering mode.
 456    * @param[in] magFilter The magnification filtering mode.
 457    */
 458   void SetFilterMode( FilterMode::Type minFilter, FilterMode::Type magFilter );
 459
 460   /**
 461    * @brief Retrieves the filtering mode.
 462    *
 463    * @SINCE_1_0.0
 464    * @param[out] minFilter The return minification value
 465    * @param[out] magFilter The return magnification value
 466    */
 467   void GetFilterMode( FilterMode::Type& minFilter, FilterMode::Type& magFilter) const;
 468
 469   /**
 470    * @brief Sets the shader effect for the RenderableActor.
 471    *
 472    * Shader effects provide special effects like ripple and bend.
 473    * Setting a shader effect removes any shader effect previously set by SetShaderEffect.
 474    * @SINCE_1_0.0
 475    * @param [in] effect The shader effect.
 476    * @pre The actor has been initialized.
 477    * @pre effect has been initialized.
 478    */
 479   void SetShaderEffect( ShaderEffect effect );
 480
 481   /**
 482    * @brief Retrieve the custom shader effect for the RenderableActor.
 483    * If default shader is used an empty handle is returned.
 484    *
 485    * @SINCE_1_0.0
 486    * @return The shader effect
 487    * @pre The Actor has been initialized.
 488    */
 489   ShaderEffect GetShaderEffect() const;
 490
 491   /**
 492    * @brief Removes the current shader effect.
 493    *
 494    * @SINCE_1_0.0
 495    * @pre The Actor has been initialized.
 496    */
 497   void RemoveShaderEffect();
 498
 499
 500 public: // Not intended for application developers
 501
 502   explicit DALI_INTERNAL ImageActor(Internal::ImageActor*);
 503 };
 504
 505
 506 /**
 507  * @brief Sets the shader effect for all ImageActors in a tree of Actors.
 508  *
 509  * @SINCE_1_0.0
 510  * @param [in] actor root of a tree of actors.
 511  * @param [in] effect The shader effect.
 512  * @see ImageActor::SetShaderEffect
 513  *
 514  */
 515 DALI_IMPORT_API void SetShaderEffectRecursively( Actor actor, ShaderEffect effect );
 516
 517 /**
 518  * @brief Removes the shader effect from all ImageActors in a tree of Actors.
 519  *
 520  * @SINCE_1_0.0
 521  * @param [in] actor root of a tree of actors.
 522  * @see ImageActor::RemoveShaderEffect
 523  *
 524  */
 525 DALI_IMPORT_API void RemoveShaderEffectRecursively( Actor actor );
 526
 527 /**
 528  * @}
 529  */
 530 } // namespace Dali
 531
 532 #endif // __DALI_IMAGE_ACTOR_H__