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