dali/public-api/images/resource-image.h

   1 #ifndef __DALI_RESOURCE_IMAGE_H__
   2 #define __DALI_RESOURCE_IMAGE_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
  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/image.h>
  27 #include <dali/public-api/signals/dali-signal.h>
  28 #include <dali/public-api/images/image-operations.h>
  29
  30 namespace Dali
  31 {
  32 /**
  33  * @addtogroup dali_core_images
  34  * @{
  35  */
  36
  37 namespace Internal DALI_INTERNAL
  38 {
  39 class ResourceImage;
  40 }
  41
  42 /**
  43  * @DEPRECATED_1_2.41
  44  *
  45  * @brief ResourceImage is an image loaded using a URL.
  46  *
  47  * <i>Customizing load requests</i>
  48  *
  49  * Size, scaling mode, filter mode, and orientation compensation can be set when requesting an image.
  50  *
  51  * <i>Reloading images</i>
  52  *
  53  * The same request used on creating the ResourceImage is re-issued when reloading images.
  54  * If the file changed since the last load operation, this might result in a different resource.
  55  * Reload only takes effect if the ResourceImage has already finished loading.
  56  *
  57  * Signals
  58  * | %Signal Name         | Method                       |
  59  * |----------------------|------------------------------|
  60  * | imageLoadingFinished | @ref LoadingFinishedSignal() |
  61  * @SINCE_1_0.0
  62  */
  63 class DALI_CORE_API ResourceImage : public Image
  64 {
  65 public:
  66
  67   /**
  68    * @DEPRECATED_1_2.41
  69    *
  70    * @brief Type of signal for LoadingFinished and Uploaded.
  71    * @SINCE_1_0.0
  72    */
  73   typedef Signal< void (ResourceImage) > ResourceImageSignal;
  74
  75 public:
  76
  77   /**
  78    * @DEPRECATED_1_2.41
  79    *
  80    * @brief Gets the size of an image from disk.
  81    *
  82    * This function will read the header info from file on disk and is
  83    * synchronous, so it should not be used repeatedly or in tight
  84    * loops.
  85    *
  86    * @SINCE_1_0.0
  87    * @REMARK_STORAGE
  88    * @param[in] url The URL of the image file
  89    * @return The width and height in pixels of the image
  90    */
  91   static ImageDimensions GetImageSize( const std::string& url ) DALI_DEPRECATED_API;
  92
  93   /**
  94    * @DEPRECATED_1_2.41
  95    *
  96    * @brief Constructor which creates an empty ResourceImage object.
  97    *
  98    * Use ResourceImage::New(...) to create an initialised object.
  99    * @SINCE_1_0.0
 100    */
 101   ResourceImage() DALI_DEPRECATED_API;
 102
 103   /**
 104    * @DEPRECATED_1_2.41
 105    *
 106    * @brief Destructor.
 107    *
 108    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 109    * @SINCE_1_0.0
 110    */
 111   ~ResourceImage() DALI_DEPRECATED_API;
 112
 113   /**
 114    * @DEPRECATED_1_2.41
 115    *
 116    * @brief This copy constructor is required for (smart) pointer semantics.
 117    *
 118    * @SINCE_1_0.0
 119    * @param[in] handle A reference to the copied handle
 120    */
 121   ResourceImage( const ResourceImage& handle ) DALI_DEPRECATED_API;
 122
 123   /**
 124    * @DEPRECATED_1_2.41
 125    *
 126    * @brief This assignment operator is required for (smart) pointer semantics.
 127    *
 128    * @SINCE_1_0.0
 129    * @param[in] rhs A reference to the copied handle
 130    * @return A reference to this
 131    */
 132   ResourceImage& operator=( const ResourceImage& rhs ) DALI_DEPRECATED_API;
 133
 134   /**
 135    * @name ResourceImageFactoryFunctions
 136    * Creates ResourceImage object instances using these functions.
 137    */
 138   ///@{
 139
 140   /**
 141    * @DEPRECATED_1_2.41
 142    *
 143    * @brief Creates an initialized ResourceImage object.
 144    *
 145    * Uses defaults for all options.
 146    *
 147    * @sa Dali::FittingMode::Type Dali::SamplingMode::Type
 148    * @SINCE_1_0.0
 149    * @REMARK_INTERNET
 150    * @REMARK_STORAGE
 151    * @param[in] url The URL of the image file to use
 152    * @param[in] orientationCorrection Reorient the image to respect any orientation metadata in its header
 153    * @return A handle to a newly allocated object
 154    */
 155   static ResourceImage New( const std::string& url, bool orientationCorrection = true ) DALI_DEPRECATED_API;
 156
 157   /**
 158    * @DEPRECATED_1_2.41
 159    *
 160    * @brief Creates an initialized ResourceImage object.
 161    *
 162    * @SINCE_1_0.0
 163    * @REMARK_INTERNET
 164    * @REMARK_STORAGE
 165    * @param[in] url The URL of the image file to use
 166    * @param[in] size The width and height to fit the loaded image to
 167    * @param[in] fittingMode The method used to fit the shape of the image before loading to the shape defined by the size parameter
 168    * @param[in] samplingMode The filtering method used when sampling pixels from the input image while fitting it to desired size
 169    * @param[in] orientationCorrection Reorient the image to respect any orientation metadata in its header
 170    * @return A handle to a newly allocated object
 171    */
 172   static ResourceImage New( const std::string& url,
 173                             ImageDimensions size,
 174                             FittingMode::Type fittingMode = FittingMode::DEFAULT,
 175                             SamplingMode::Type samplingMode = SamplingMode::DEFAULT,
 176                             bool orientationCorrection = true ) DALI_DEPRECATED_API;
 177
 178   ///@}
 179
 180   /**
 181    * @DEPRECATED_1_2.41
 182    *
 183    * @brief Downcasts a handle to ResourceImage handle.
 184    *
 185    * If handle points to a ResourceImage object, the
 186    * downcast produces valid handle. If not, the returned handle is left uninitialized.
 187    * @SINCE_1_0.0
 188    * @param[in] handle Handle to an object
 189    * @return Handle to a Image object or an uninitialized handle
 190    */
 191   static ResourceImage DownCast( BaseHandle handle ) DALI_DEPRECATED_API;
 192
 193   /**
 194    * @DEPRECATED_1_2.41
 195    *
 196    * @brief Queries whether the image data has loaded.
 197    *
 198    * The asynchronous loading begins when the Image object is created.
 199    * After the Image object is discarded, the image data will be released from memory.
 200    * @SINCE_1_0.0
 201    * @return The loading state, either Loading, Success or Failed
 202    */
 203   LoadingState GetLoadingState() const DALI_DEPRECATED_API;
 204
 205   /**
 206    * @DEPRECATED_1_2.41
 207    *
 208    * @brief Returns the URL of the image.
 209    *
 210    * @SINCE_1_0.0
 211    * @return The URL of the image file
 212    */
 213   std::string GetUrl() const DALI_DEPRECATED_API;
 214
 215   /**
 216    * @DEPRECATED_1_2.41
 217    *
 218    * @brief Reloads image from filesystem.
 219    *
 220    * The original set of image loading attributes (requested dimensions, scaling
 221    * mode and filter mode) are used when requesting the image again.
 222    * @SINCE_1_0.0
 223    * @note If image is offstage and OnDemand policy is set, the reload request is ignored.
 224    */
 225   void Reload() DALI_DEPRECATED_API;
 226
 227 public: // Signals
 228
 229   /**
 230    * @DEPRECATED_1_2.41
 231    *
 232    * @brief Emitted when the image data loads successfully, or when the loading fails.
 233    *
 234    * @SINCE_1_0.0
 235    * @return A signal object to Connect() with
 236    */
 237   ResourceImageSignal& LoadingFinishedSignal() DALI_DEPRECATED_API;
 238
 239 public: // Not intended for application developers
 240
 241   explicit DALI_INTERNAL ResourceImage( Internal::ResourceImage* );
 242 };
 243
 244 /**
 245  * @}
 246  */
 247 } // namespace Dali
 248
 249 #endif // __DALI_RESOURCE_IMAGE_H__