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