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