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