dali-toolkit/public-api/image-loader/async-image-loader.h

   1 #ifndef DALI_TOOLKIT_ASYNC_IMAGE_LOADER_H
   2 #define DALI_TOOLKIT_ASYNC_IMAGE_LOADER_H
   3
   4 /*
   5  * Copyright (c) 2018 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 // EXTERNAL INCLUDES
  21 #include <string>
  22 #include <dali/public-api/object/base-handle.h>
  23 #include <dali/public-api/images/image-operations.h>
  24 #include <dali/public-api/signals/dali-signal.h>
  25
  26 // INTERNAL INCLUDES
  27 #include <dali-toolkit/public-api/dali-toolkit-common.h>
  28
  29 namespace Dali
  30 {
  31 class PixelData;
  32
  33 namespace Toolkit
  34 {
  35
  36 namespace Internal DALI_INTERNAL
  37 {
  38 class AsyncImageLoader;
  39 }
  40
  41 /**
  42  * @addtogroup dali_toolkit_image_loader
  43  * @{
  44  */
  45
  46 /**
  47  * @brief The AsyncImageLoader is used to load pixel data from a URL asynchronously.
  48  *
  49  * The images are loaded in a worker thread to avoid blocking the main event thread.
  50  *
  51  * To keep track of the loading images, each load call is assigned an ID (which is returned by the Load() call).
  52  * To know when the Load has completed, connect to the ImageLoadedSignal.
  53  * This signal should be connected before Load is called (in case the signal is emitted immediately).
  54  *
  55  * Load errors can be detected by checking the PixelData object is valid from within the signal handler.
  56
  57  * Note: The PixelData object will automatically be destroyed when it leaves its scope.
  58  *
  59  * Example:
  60  *
  61  * @code
  62  * class MyClass : public ConnectionTracker
  63  * {
  64  *   public:
  65  *
  66  *   MyCallback( uint32_t loadedTaskId, PixelData pixelData )
  67  *   {
  68  *     // First check if the image loaded correctly.
  69  *     if( pixelData )
  70  *     {
  71  *       if( loadedTaskId == mId1 )
  72  *       {
  73  *         // use the loaded pixel data from the first image
  74  *       }
  75  *       else if( loadedTaskId == mId2 )
  76  *       {
  77  *         // use the loaded pixel data from the second image
  78  *       }
  79  *     }
  80  *   }
  81  *
  82  *   uint32_t mId1;
  83  *   uint32_t mId2;
  84  * };
  85  *
  86  * MyClass myObject;
  87  * AsyncImageLoader imageLoader = AsyncImageLoader::New();
  88  *
  89  * // Connect the signal here.
  90  * imageLoader.ImageLoadedSignal().Connect( &myObject, &MyClass::MyCallback );
  91  *
  92  * // Invoke the load calls (must do this after connecting the signal to guarantee callbacks occur).
  93  * myObject.mId1 = imageLoader.Load( "first_image_url.jpg" );
  94  * myObject.mId2 = imageLoader.Load( "second_image_url.jpg" );
  95  *
  96  * @endcode
  97  */
  98 class DALI_TOOLKIT_API AsyncImageLoader : public BaseHandle
  99 {
 100 public:
 101
 102   typedef Signal< void( uint32_t, PixelData ) > ImageLoadedSignalType; ///< Image loaded signal type @SINCE_1_2_14
 103
 104 public:
 105
 106   /**
 107    * @brief Constructor which creates an empty AsyncImageLoader handle.
 108    * @SINCE_1_2_14
 109    *
 110    * Use AsyncImageLoader::New() to create an initialised object.
 111    */
 112   AsyncImageLoader();
 113
 114   /**
 115    * @brief Destructor.
 116    * @SINCE_1_2_14
 117    *
 118    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 119    */
 120   ~AsyncImageLoader();
 121
 122   /**
 123    * @brief This copy constructor is required for (smart) pointer semantics.
 124    * @SINCE_1_2_14
 125    *
 126    * @param[in] handle A reference to the copied handle
 127    */
 128   AsyncImageLoader( const AsyncImageLoader& handle );
 129
 130   /**
 131    * @brief This assignment operator is required for (smart) pointer semantics.
 132    * @SINCE_1_2_14
 133    *
 134    * @param[in] handle  A reference to the copied handle
 135    * @return A reference to this
 136    */
 137   AsyncImageLoader& operator=( const AsyncImageLoader& handle );
 138
 139   /**
 140    * @brief Creates a new loader to load the image asynchronously in a worker thread.
 141    * @SINCE_1_2_14
 142    *
 143    * @return The image loader
 144    */
 145   static AsyncImageLoader New();
 146
 147   /**
 148    * @brief Downcasts a handle to AsyncImageLoader handle.
 149    *
 150    * If the handle points to an AsyncImageLoader object, the downcast produces a valid handle.
 151    * If not, the returned handle is left uninitialized.
 152    *
 153    * @SINCE_1_2_14
 154    * @param[in] handle A handle to an object
 155    * @return A handle to a AsyncImageLoader object or an uninitialized handle
 156    */
 157   static AsyncImageLoader DownCast( BaseHandle handle );
 158
 159   /**
 160    * @brief Starts an image loading task.
 161    * Note: When using this method, the following defaults will be used:
 162    * fittingMode = FittingMode::DEFAULT
 163    * samplingMode = SamplingMode::BOX_THEN_LINEAR
 164    * orientationCorrection = true
 165    *
 166    * @SINCE_1_2_14
 167    * @REMARK_INTERNET
 168    * @REMARK_STORAGE
 169    * @param[in] url The URL of the image file to load
 170    * @return The loading task id
 171    */
 172   uint32_t Load( const std::string& url );
 173
 174   /**
 175    * @brief Starts an image loading task.
 176    * Note: When using this method, the following defaults will be used:
 177    * fittingMode = FittingMode::DEFAULT
 178    * samplingMode = SamplingMode::BOX_THEN_LINEAR
 179    * orientationCorrection = true
 180    *
 181    * @SINCE_1_2_14
 182    * @REMARK_INTERNET
 183    * @REMARK_STORAGE
 184    * @param[in] url The URL of the image file to load
 185    * @param[in] dimensions The width and height to fit the loaded image to
 186    * @return The loading task id
 187    */
 188   uint32_t Load( const std::string& url, ImageDimensions dimensions );
 189
 190   /**
 191    * @brief Starts an image loading task.
 192    * @SINCE_1_2_14
 193    * @REMARK_INTERNET
 194    * @REMARK_STORAGE
 195    * @param[in] url The URL of the image file to load
 196    * @param[in] dimensions The width and height to fit the loaded image to
 197    * @param[in] fittingMode The method used to fit the shape of the image before loading to the shape defined by the size parameter
 198    * @param[in] samplingMode The filtering method used when sampling pixels from the input image while fitting it to desired size
 199    * @param[in] orientationCorrection Reorient the image to respect any orientation metadata in its header
 200    * @return The loading task id
 201    */
 202   uint32_t Load( const std::string& url,
 203                  ImageDimensions dimensions,
 204                  FittingMode::Type fittingMode,
 205                  SamplingMode::Type samplingMode,
 206                  bool orientationCorrection );
 207
 208   /**
 209    * @brief Cancels an image loading task if it is still queueing in the work thread.
 210    * @SINCE_1_2_14
 211    *
 212    * @param[in] loadingTaskId The task id returned when invoking the load call.
 213    * @return If true, the loading task is removed from the queue, otherwise the loading is already implemented and unable to cancel anymore
 214    */
 215   bool Cancel( uint32_t loadingTaskId );
 216
 217   /**
 218    * @brief Cancels all the loading tasks in the queue.
 219    * @SINCE_1_2_14
 220    */
 221   void CancelAll();
 222
 223   /**
 224    * @brief Signal emitted for connected callback functions to get access to the loaded pixel data.
 225    *
 226    * A callback of the following type may be connected:
 227    * @code
 228    *   void YourCallbackName( uint32_t id, PixelData pixelData );
 229    * @endcode
 230    * @SINCE_1_2_14
 231    * @return A reference to a signal object to Connect() with
 232    */
 233   ImageLoadedSignalType& ImageLoadedSignal();
 234
 235 public: // Not intended for developer use
 236
 237   /// @cond internal
 238   /**
 239    * @brief Allows the creation of a AsyncImageLoader handle from an internal pointer.
 240    *
 241    * @note Not intended for application developers
 242    * @SINCE_1_2_14
 243    * @param[in] impl A pointer to the object
 244    */
 245   explicit DALI_INTERNAL AsyncImageLoader( Internal::AsyncImageLoader* impl );
 246   /// @endcond
 247
 248 };
 249
 250 /**
 251  * @}
 252  */
 253 } // namespace Toolkit
 254
 255 } // namespace Dali
 256
 257 #endif // DALI_TOOLKIT_ASYNC_IMAGE_LOADER_H