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