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