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