dali/public-api/images/image.h

   1 #ifndef __DALI_IMAGE_H__
   2 #define __DALI_IMAGE_H__
   3
   4 /*
   5  * Copyright (c) 2014 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/common/loading-state.h>
  26 #include <dali/public-api/images/pixel.h>
  27 #include <dali/public-api/object/base-handle.h>
  28 #include <dali/public-api/signals/dali-signal-v2.h>
  29
  30 namespace Dali DALI_IMPORT_API
  31 {
  32 struct Vector2;
  33
  34 namespace Internal DALI_INTERNAL
  35 {
  36 class Image;
  37 }
  38
  39 class NativeImage;
  40 class ImageAttributes;
  41
  42
  43 /**
  44  * @brief An Image object represents an image resource that can be added to ImageActors.
  45  *
  46  * Image objects can also handle custom requests for image loading and are responsible for
  47  * the underlying resource's lifetime.
  48  *
  49  * <h3>Image Loading</h3>
  50  *
  51  * When the Image object is created, resource loading will be attempted unless
  52  * the Image object is created with OnDemand loading policy or a compatible resource is found in cache.
  53  * In case of loading images on demand, resource loading will only be attempted if the associated ImageActor
  54  * is put on Stage.
  55  * Custom loading requests can be made by providing an ImageAttributes object to Image::New().
  56  *
  57  * <i>LoadPolicies</i>
  58  * - Immediate: acquire image resource when creating Image object.
  59  * - OnDemand: only load in case the associated ImageActor is put on Stage
  60  *
  61  * <i>ReleasePolicies</i>
  62  * - Unused: release resource once ImageActor using it is taken off stage.
  63  * - Never: keep resource alive until Image object is thrown away.
  64  *
  65  * <i>Resolution of conflicting policies</i>
  66  * If the same image is created more than once with conflicting policies, LoadPolicy "Immediate" overrides "OnDemand"
  67  * and ReleasePolicy "Never" overrides "Unused".
  68  *
  69  * <i>Custom load requests</i>
  70  * Size, scaling mode, orientation compensation can be set when requesting an image resource.
  71  * See ImageAttributes for more details.
  72  *
  73  * <i>Compatible resources</i>
  74  *
  75  * Before loading a new image the internal image resource cache is checked by dali.
  76  * If there is an Image already loaded in memory and is deemed "compatible" with the requested Image,
  77  * that resource is reused.
  78  * This happens for example if a loaded image exists with the same filename, and the difference between both
  79  * of the dimensions is less than 50%.
  80  *
  81  * <i>Reloading Images</i>
  82  *
  83  * The same request used on creating the Image is re-issued when reloading Images.
  84  * If the file changed since the last load operation, this might result in a different resource.
  85  * Reload only takes effect if both of these conditions apply:
  86  * - The Image has already finished loading
  87  * - The Image is either on Stage or using Immediate load policy
  88  *
  89  * <h3>Image resource lifetime</h3>
  90  *
  91  * Image objects can be shared between ImageActors. This is practical if you have a visual element on screen
  92  * which is repeatedly used. An example would be a button background image.
  93  * The image resource is discarded when all ImageActors using the Image object are discarded or in case they
  94  * were created with ReleasePolicy::Unused, taken off stage.
  95  * Note: if a resource was shared between Image objects it exists until its last reference is gone.
  96  *
  97  */
  98 class Image : public BaseHandle
  99 {
 100 public:
 101   /**
 102    * @brief Resource management options.
 103    */
 104
 105   /**
 106    * @brief LoadPolicy controls the way images are loaded into memory.
 107    */
 108   enum LoadPolicy
 109   {
 110     Immediate, ///< load image once it is created (default)
 111     OnDemand   ///< delay loading until the image is being used (a related actor is added to Stage)
 112   };
 113
 114   /**
 115    * @brief ReleasePolicy controls the way images are deleted from memory.
 116    */
 117   enum ReleasePolicy
 118   {
 119     Unused, ///< release resource once image is not in use anymore (eg. all actors using it become offstage). Reload when resource is required again.
 120     Never   ///< keep image data for the lifetime of the object. (default)
 121   };
 122
 123   /**
 124    * @brief Type of signal for LoadingFinished and Uploaded.
 125    */
 126   typedef SignalV2< void (Image) > ImageSignalV2;
 127
 128   // Signal Names
 129   static const char* const SIGNAL_IMAGE_LOADING_FINISHED; ///< Name of LoadingFinished signal
 130   static const char* const SIGNAL_IMAGE_UPLOADED; ///< Name of Uploaded signal
 131
 132 public:
 133
 134   /**
 135    * @brief Get the size of an image from disk.
 136    *
 137    * This function will read the header info from file on disk and is
 138    * synchronous, so it should not be used repeatedly or in tight
 139    * loops.
 140    *
 141    * @param [in] filename of the image file to use.
 142    * @return The width and height in pixels of the image.
 143    */
 144   static Vector2 GetImageSize(const std::string filename);
 145
 146   /**
 147    * @brief Constructor which creates an empty Image object.
 148    *
 149    * Use Image::New(...) to create an initialised object.
 150    */
 151   Image();
 152
 153   /**
 154    * @brief Destructor
 155    *
 156    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 157    */
 158   ~Image();
 159
 160   /**
 161    * @brief This copy constructor is required for (smart) pointer semantics.
 162    *
 163    * @param [in] handle A reference to the copied handle
 164    */
 165   Image(const Image& handle);
 166
 167   /**
 168    * @brief This assignment operator is required for (smart) pointer semantics.
 169    *
 170    * @param [in] rhs  A reference to the copied handle
 171    * @return A reference to this
 172    */
 173   Image& operator=(const Image& rhs);
 174
 175   /**
 176    * @brief This method is defined to allow assignment of the NULL value,
 177    * and will throw an exception if passed any other value.
 178    *
 179    * Assigning to NULL is an alias for Reset().
 180    * @param [in] rhs  A NULL pointer
 181    * @return A reference to this handle
 182    */
 183   Image& operator=(BaseHandle::NullType* rhs);
 184
 185   /**
 186    * @brief Create an initialised image object.
 187    *
 188    * @param [in] filename The filename of the image file to use.
 189    * @return A handle to a newly allocated object
 190    */
 191   static Image New(const std::string& filename);
 192
 193   /**
 194    * @brief Create an initialised image object.
 195    *
 196    * @param [in] filename The filename of the image file to use.
 197    * @param [in] loadPol    The LoadPolicy to apply when loading the image resource.
 198    * @param [in] releasePol The ReleasePolicy to apply to Image.
 199    * @return A handle to a newly allocated object
 200    */
 201   static Image New(const std::string& filename, LoadPolicy loadPol, ReleasePolicy releasePol);
 202
 203   /**
 204    * @brief Create an initialised image object.
 205    *
 206    * @param [in] filename   The filename of the image file to use.
 207    * @param [in] attributes Requested parameters for loading (size, scaling etc.).
 208    * @return A handle to a newly allocated object
 209    */
 210   static Image New(const std::string& filename, const ImageAttributes& attributes);
 211
 212   /**
 213    * @brief Create an initialised image object.
 214    *
 215    * @param [in] filename   The filename of the image file to use.
 216    * @param [in] attributes Requested parameters for loading (size, scaling etc.).
 217    * @param [in] loadPol    The LoadPolicy to apply when loading the image resource.
 218    * @param [in] releasePol The ReleasePolicy to apply to Image.
 219    * @return A handle to a newly allocated object
 220    */
 221   static Image New(const std::string& filename, const ImageAttributes& attributes, LoadPolicy loadPol, ReleasePolicy releasePol);
 222
 223   /**
 224    * @brief Create an initialised image object.
 225    *
 226    * @param [in] filename The filename of the image file to use.
 227    * @return A handle to a newly allocated object
 228    */
 229   static Image NewDistanceField(const std::string& filename);
 230
 231   /**
 232    * @brief Create an initialised image object.
 233    *
 234    * @param [in] filename   The filename of the image file to use.
 235    * @param [in] loadPol    The LoadPolicy to apply when loading the image resource.
 236    * @param [in] releasePol The ReleasePolicy to apply to Image.
 237    * @return A handle to a newly allocated object
 238    */
 239   static Image NewDistanceField(const std::string& filename, LoadPolicy loadPol, ReleasePolicy releasePol);
 240
 241   /**
 242    * @brief Create an initialised image object.
 243    *
 244    * @param [in] filename   The filename of the image file to use.
 245    * @param [in] attributes The minimum search radius to check for differing pixels
 246    * @return A handle to a newly allocated object
 247    */
 248   static Image NewDistanceField(const std::string& filename, const ImageAttributes& attributes );
 249
 250   /**
 251    * @brief Create an initialised image object.
 252    *
 253    * @param [in] filename   The filename of the image file to use.
 254    * @param [in] attributes The minimum search radius to check for differing pixels
 255    * @param [in] loadPol    The LoadPolicy to apply when loading the image resource.
 256    * @param [in] releasePol The ReleasePolicy to apply to Image.
 257    * @return A handle to a newly allocated object
 258    */
 259   static Image NewDistanceField(const std::string& filename, const ImageAttributes& attributes, LoadPolicy loadPol, ReleasePolicy releasePol);
 260
 261   /**
 262    * @brief Creates object with already loaded NativeImage.
 263    *
 264    * The maximum size of the image is limited by GL_MAX_TEXTURE_SIZE
 265    * @pre nativeImg should be initialised
 266    * @param [in] nativeImg already initialised NativeImage
 267    * @return A handle to a newly allocated object
 268    */
 269   static Image New(NativeImage& nativeImg);
 270
 271   /**
 272    * @brief Creates object with already loaded NativeImage.
 273    *
 274    * The maximum size of the image is limited by GL_MAX_TEXTURE_SIZE
 275    * @pre nativeImg should be initialised
 276    * @param [in] nativeImg already initialised NativeImage
 277    * @param [in] loadPol    The LoadPolicy to apply when allocating the GL resource.
 278    * @param [in] releasePol The ReleasePolicy to apply to Image.
 279    * @return A handle to a newly allocated object
 280    */
 281   static Image New(NativeImage& nativeImg, LoadPolicy loadPol, ReleasePolicy releasePol);
 282
 283   /**
 284    * @brief Downcast an Object handle to Image handle.
 285    *
 286    * If handle points to a Image object the
 287    * downcast produces valid handle. If not the returned handle is left uninitialized.
 288    * @param[in] handle to An object
 289    * @return handle to a Image object or an uninitialized handle
 290    */
 291   static Image DownCast( BaseHandle handle );
 292
 293   /**
 294    * @brief Query whether the image data has loaded.
 295    *
 296    * The asynchronous loading begins when the Image object is created.
 297    * After the Image object is discarded, the image data will be released from memory.
 298    * @return The loading state, either Loading, Success or Failed.
 299    */
 300   LoadingState GetLoadingState() const;
 301
 302   /**
 303    * @brief Returns the filename of the image if the image is created from a file.
 304    *
 305    * @return the image filename or empty string
 306    */
 307   std::string GetFilename() const;
 308
 309   /**
 310    * @brief Return load policy.
 311    *
 312    * @return resource load policy
 313    */
 314   LoadPolicy GetLoadPolicy () const;
 315
 316   /**
 317    * @brief Return resource release policy.
 318    *
 319    * @return resource release policy
 320    */
 321   ReleasePolicy GetReleasePolicy () const;
 322
 323   /**
 324    * @brief Reload image from filesystem.
 325    *
 326    * The set ImageAttributes are used when requesting the image again.
 327    * @note if Image is offstage and OnDemand policy is set, reload request is ignored.
 328    */
 329   void Reload();
 330
 331   /**
 332    * @brief Returns the width of the image.
 333    *
 334    * Returns either the requested width or the actual loaded width if no specific size was requested.
 335    *
 336    * @return width of the image in pixels.
 337    */
 338   unsigned int GetWidth() const;
 339
 340   /**
 341    * @brief Returns the height of the image.
 342    *
 343    * Returns either the requested height or the actual loaded height if no specific size was requested.
 344    *
 345    * @return height of the image in pixels.
 346    */
 347   unsigned int GetHeight() const;
 348
 349   /**
 350    * @brief Get the attributes of an image.
 351    *
 352    * Only to be used after the image has finished loading.
 353    * (Ticket's LoadingSucceeded callback was called)
 354    * The returned value will reflect the true image dimensions once the asynchronous loading has finished.
 355    * Connect to SignalLoadingFinished or use GetLoadingState to make sure this value is actual.
 356    * @pre image should be loaded
 357    * @return a copy of the attributes
 358    */
 359   ImageAttributes GetAttributes() const;
 360
 361 public: // Signals
 362
 363   /**
 364    * @brief Emitted when the image data loads successfully, or when the loading fails.
 365    *
 366    * @return A signal object to Connect() with.
 367    */
 368   ImageSignalV2& LoadingFinishedSignal();
 369
 370   /**
 371    * @brief This signal is emitted when the image data gets uploaded to GL.
 372    *
 373    * It Will be sent after an actor using the image is added to
 374    * the stage, when such a staged image is reloaded, or when a staged
 375    * BitmapImage calls Update().
 376    * @return A signal object to Connect() with.
 377    */
 378   ImageSignalV2& UploadedSignal();
 379
 380 public: // Not intended for application developers
 381
 382   explicit DALI_INTERNAL Image(Internal::Image*);
 383 };
 384
 385 } // namespace Dali
 386
 387 #endif // __DALI_IMAGE_H__