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