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
  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 DALI_IMPORT_API 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 Create an initialised image object.
 177    *
 178    * @param [in] filename The filename of the image file to use.
 179    * @return A handle to a newly allocated object
 180    */
 181   static Image New(const std::string& filename);
 182
 183   /**
 184    * @brief Create an initialised image object.
 185    *
 186    * @param [in] filename The filename of the image file to use.
 187    * @param [in] loadPol    The LoadPolicy to apply when loading the image resource.
 188    * @param [in] releasePol The ReleasePolicy to apply to Image.
 189    * @return A handle to a newly allocated object
 190    */
 191   static Image New(const std::string& filename, LoadPolicy loadPol, ReleasePolicy releasePol);
 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] attributes Requested parameters for loading (size, scaling etc.).
 198    * @return A handle to a newly allocated object
 199    */
 200   static Image New(const std::string& filename, const ImageAttributes& attributes);
 201
 202   /**
 203    * @brief Create an initialised image object.
 204    *
 205    * @param [in] filename   The filename of the image file to use.
 206    * @param [in] attributes Requested parameters for loading (size, scaling etc.).
 207    * @param [in] loadPol    The LoadPolicy to apply when loading the image resource.
 208    * @param [in] releasePol The ReleasePolicy to apply to Image.
 209    * @return A handle to a newly allocated object
 210    */
 211   static Image New(const std::string& filename, const ImageAttributes& attributes, LoadPolicy loadPol, ReleasePolicy releasePol);
 212
 213   /**
 214    * @brief Create an initialised image object.
 215    *
 216    * @param [in] filename The filename of the image file to use.
 217    * @return A handle to a newly allocated object
 218    */
 219   static Image NewDistanceField(const std::string& filename);
 220
 221   /**
 222    * @brief Create an initialised image object.
 223    *
 224    * @param [in] filename   The filename of the image file to use.
 225    * @param [in] loadPol    The LoadPolicy to apply when loading the image resource.
 226    * @param [in] releasePol The ReleasePolicy to apply to Image.
 227    * @return A handle to a newly allocated object
 228    */
 229   static Image NewDistanceField(const std::string& filename, LoadPolicy loadPol, ReleasePolicy releasePol);
 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] attributes The minimum search radius to check for differing pixels
 236    * @return A handle to a newly allocated object
 237    */
 238   static Image NewDistanceField(const std::string& filename, const ImageAttributes& attributes );
 239
 240   /**
 241    * @brief Create an initialised image object.
 242    *
 243    * @param [in] filename   The filename of the image file to use.
 244    * @param [in] attributes The minimum search radius to check for differing pixels
 245    * @param [in] loadPol    The LoadPolicy to apply when loading the image resource.
 246    * @param [in] releasePol The ReleasePolicy to apply to Image.
 247    * @return A handle to a newly allocated object
 248    */
 249   static Image NewDistanceField(const std::string& filename, const ImageAttributes& attributes, LoadPolicy loadPol, ReleasePolicy releasePol);
 250
 251   /**
 252    * @brief Creates object with already loaded NativeImage.
 253    *
 254    * The maximum size of the image is limited by GL_MAX_TEXTURE_SIZE
 255    * @pre nativeImg should be initialised
 256    * @param [in] nativeImg already initialised NativeImage
 257    * @return A handle to a newly allocated object
 258    */
 259   static Image New(NativeImage& nativeImg);
 260
 261   /**
 262    * @brief Downcast an Object handle to Image handle.
 263    *
 264    * If handle points to a Image object the
 265    * downcast produces valid handle. If not the returned handle is left uninitialized.
 266    * @param[in] handle to An object
 267    * @return handle to a Image object or an uninitialized handle
 268    */
 269   static Image DownCast( BaseHandle handle );
 270
 271   /**
 272    * @brief Query whether the image data has loaded.
 273    *
 274    * The asynchronous loading begins when the Image object is created.
 275    * After the Image object is discarded, the image data will be released from memory.
 276    * @return The loading state, either Loading, Success or Failed.
 277    */
 278   LoadingState GetLoadingState() const;
 279
 280   /**
 281    * @brief Returns the filename of the image if the image is created from a file.
 282    *
 283    * @return the image filename or empty string
 284    */
 285   std::string GetFilename() const;
 286
 287   /**
 288    * @brief Return load policy.
 289    *
 290    * @return resource load policy
 291    */
 292   LoadPolicy GetLoadPolicy () const;
 293
 294   /**
 295    * @brief Return resource release policy.
 296    *
 297    * @return resource release policy
 298    */
 299   ReleasePolicy GetReleasePolicy () const;
 300
 301   /**
 302    * @brief Reload image from filesystem.
 303    *
 304    * The set ImageAttributes are used when requesting the image again.
 305    * @note if Image is offstage and OnDemand policy is set, reload request is ignored.
 306    */
 307   void Reload();
 308
 309   /**
 310    * @brief Returns the width of the image.
 311    *
 312    * Returns either the requested width or the actual loaded width if no specific size was requested.
 313    *
 314    * @return width of the image in pixels.
 315    */
 316   unsigned int GetWidth() const;
 317
 318   /**
 319    * @brief Returns the height of the image.
 320    *
 321    * Returns either the requested height or the actual loaded height if no specific size was requested.
 322    *
 323    * @return height of the image in pixels.
 324    */
 325   unsigned int GetHeight() const;
 326
 327   /**
 328    * @brief Get the attributes of an image.
 329    *
 330    * Only to be used after the image has finished loading.
 331    * (Ticket's LoadingSucceeded callback was called)
 332    * The returned value will reflect the true image dimensions once the asynchronous loading has finished.
 333    * Connect to SignalLoadingFinished or use GetLoadingState to make sure this value is actual.
 334    * @pre image should be loaded
 335    * @return a copy of the attributes
 336    */
 337   ImageAttributes GetAttributes() const;
 338
 339 public: // Signals
 340
 341   /**
 342    * @brief Emitted when the image data loads successfully, or when the loading fails.
 343    *
 344    * @return A signal object to Connect() with.
 345    */
 346   ImageSignalV2& LoadingFinishedSignal();
 347
 348   /**
 349    * @brief This signal is emitted when the image data gets uploaded to GL.
 350    *
 351    * It Will be sent after an actor using the image is added to
 352    * the stage, when such a staged image is reloaded, or when a staged
 353    * BitmapImage calls Update().
 354    * @return A signal object to Connect() with.
 355    */
 356   ImageSignalV2& UploadedSignal();
 357
 358 public: // Not intended for application developers
 359
 360   explicit DALI_INTERNAL Image(Internal::Image*);
 361 };
 362
 363 } // namespace Dali
 364
 365 #endif // __DALI_IMAGE_H__