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) 2020 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 Move constructor
 132    * @SINCE_1_9.23
 133    *
 134    * @param[in] rhs A reference to the moved handle
 135    */
 136   AsyncImageLoader( AsyncImageLoader&& rhs );
 137
 138   /**
 139    * @brief This assignment operator is required for (smart) pointer semantics.
 140    * @SINCE_1_2_14
 141    *
 142    * @param[in] handle  A reference to the copied handle
 143    * @return A reference to this
 144    */
 145   AsyncImageLoader& operator=( const AsyncImageLoader& handle );
 146
 147   /**
 148    * @brief Move assignment
 149    * @SINCE_1_9.23
 150    *
 151    * @param[in] rhs A reference to the moved handle
 152    */
 153   AsyncImageLoader& operator=( AsyncImageLoader&& rhs );
 154
 155   /**
 156    * @brief Creates a new loader to load the image asynchronously in a worker thread.
 157    * @SINCE_1_2_14
 158    *
 159    * @return The image loader
 160    */
 161   static AsyncImageLoader New();
 162
 163   /**
 164    * @brief Downcasts a handle to AsyncImageLoader handle.
 165    *
 166    * If the handle points to an AsyncImageLoader object, the downcast produces a valid handle.
 167    * If not, the returned handle is left uninitialized.
 168    *
 169    * @SINCE_1_2_14
 170    * @param[in] handle A handle to an object
 171    * @return A handle to a AsyncImageLoader object or an uninitialized handle
 172    */
 173   static AsyncImageLoader DownCast( BaseHandle handle );
 174
 175   /**
 176    * @brief Starts an image loading task.
 177    * Note: When using this method, the following defaults will be used:
 178    * fittingMode = FittingMode::DEFAULT
 179    * samplingMode = SamplingMode::BOX_THEN_LINEAR
 180    * orientationCorrection = true
 181    *
 182    * @SINCE_1_2_14
 183    * @REMARK_INTERNET
 184    * @REMARK_STORAGE
 185    * @param[in] url The URL of the image file to load
 186    * @return The loading task id
 187    */
 188   uint32_t Load( const std::string& url );
 189
 190   /**
 191    * @brief Starts an image loading task.
 192    * Note: When using this method, the following defaults will be used:
 193    * fittingMode = FittingMode::DEFAULT
 194    * samplingMode = SamplingMode::BOX_THEN_LINEAR
 195    * orientationCorrection = true
 196    *
 197    * @SINCE_1_2_14
 198    * @REMARK_INTERNET
 199    * @REMARK_STORAGE
 200    * @param[in] url The URL of the image file to load
 201    * @param[in] dimensions The width and height to fit the loaded image to
 202    * @return The loading task id
 203    */
 204   uint32_t Load( const std::string& url, ImageDimensions dimensions );
 205
 206   /**
 207    * @brief Starts an image loading task.
 208    * @SINCE_1_2_14
 209    * @REMARK_INTERNET
 210    * @REMARK_STORAGE
 211    * @param[in] url The URL of the image file to load
 212    * @param[in] dimensions The width and height to fit the loaded image to
 213    * @param[in] fittingMode The method used to fit the shape of the image before loading to the shape defined by the size parameter
 214    * @param[in] samplingMode The filtering method used when sampling pixels from the input image while fitting it to desired size
 215    * @param[in] orientationCorrection Reorient the image to respect any orientation metadata in its header
 216    * @return The loading task id
 217    */
 218   uint32_t Load( const std::string& url,
 219                  ImageDimensions dimensions,
 220                  FittingMode::Type fittingMode,
 221                  SamplingMode::Type samplingMode,
 222                  bool orientationCorrection );
 223
 224   /**
 225    * @brief Cancels an image loading task if it is still queueing in the work thread.
 226    * @SINCE_1_2_14
 227    *
 228    * @param[in] loadingTaskId The task id returned when invoking the load call.
 229    * @return If true, the loading task is removed from the queue, otherwise the loading is already implemented and unable to cancel anymore
 230    */
 231   bool Cancel( uint32_t loadingTaskId );
 232
 233   /**
 234    * @brief Cancels all the loading tasks in the queue.
 235    * @SINCE_1_2_14
 236    */
 237   void CancelAll();
 238
 239   /**
 240    * @brief Signal emitted for connected callback functions to get access to the loaded pixel data.
 241    *
 242    * A callback of the following type may be connected:
 243    * @code
 244    *   void YourCallbackName( uint32_t id, PixelData pixelData );
 245    * @endcode
 246    * @SINCE_1_2_14
 247    * @return A reference to a signal object to Connect() with
 248    */
 249   ImageLoadedSignalType& ImageLoadedSignal();
 250
 251 public: // Not intended for developer use
 252
 253   /// @cond internal
 254   /**
 255    * @brief Allows the creation of a AsyncImageLoader handle from an internal pointer.
 256    *
 257    * @note Not intended for application developers
 258    * @SINCE_1_2_14
 259    * @param[in] impl A pointer to the object
 260    */
 261   explicit DALI_INTERNAL AsyncImageLoader( Internal::AsyncImageLoader* impl );
 262   /// @endcond
 263
 264 };
 265
 266 /**
 267  * @}
 268  */
 269 } // namespace Toolkit
 270
 271 } // namespace Dali
 272
 273 #endif // DALI_TOOLKIT_ASYNC_IMAGE_LOADER_H