1 #ifndef __DALI_RESOURCE_IMAGE_H__
2 #define __DALI_RESOURCE_IMAGE_H__
5 * Copyright (c) 2015 Samsung Electronics Co., Ltd.
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
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>
33 * @addtogroup dali_core_images
37 namespace Internal DALI_INTERNAL
43 * @brief ResourceImage is an image loaded using a URL
45 * <h3>ResourceImage Loading</h3>
47 * When the ResourceImage is created, resource loading will be attempted unless a compatible resource is found in cache.
48 * Scaling of images to a desired smaller size can be requested by providing desired dimensions,
49 * scaling mode and filter mode to to ResourceImage::New().
51 * <i>Custom load requests</i>
52 * Size, scaling mode, filter mode, and orientation compensation can be set when requesting an image.
54 * <i>Compatible resources</i>
56 * Before loading a new ResourceImage the internal image resource cache is checked by DALi.
57 * If there is an image already loaded in memory and is deemed "compatible" with the requested image,
58 * that resource is reused.
59 * This happens for example if a loaded image exists with the same URL, scaling and filtering modes,
60 * and the difference between both of the dimensions is less than a few pixels.
62 * <i>Reloading images</i>
64 * The same request used on creating the ResourceImage is re-issued when reloading images.
65 * If the file changed since the last load operation, this might result in a different resource.
66 * Reload only takes effect if the ResourceImage has already finished loading
69 * | %Signal Name | Method |
70 * |----------------------|------------------------------|
71 * | imageLoadingFinished | @ref LoadingFinishedSignal() |
73 class DALI_IMPORT_API ResourceImage : public Image
78 * @deprecated DALi 1.1.3 Image loading starts immediately in the frame when then ResourceImage object is created
80 * @brief LoadPolicy controls the way images are loaded into memory.
84 IMMEDIATE, ///< load image once it is created (default)
85 ON_DEMAND ///< delay loading until the image is being used (a related actor is added to Stage)
89 * @brief Type of signal for LoadingFinished and Uploaded.
91 typedef Signal< void (ResourceImage) > ResourceImageSignal;
96 * @brief Get the size of an image from disk.
98 * This function will read the header info from file on disk and is
99 * synchronous, so it should not be used repeatedly or in tight
102 * @param [in] url The URL of the image file.
103 * @return The width and height in pixels of the image.
105 static ImageDimensions GetImageSize( const std::string& url );
108 * @brief Constructor which creates an empty ResourceImage object.
110 * Use ResourceImage::New(...) to create an initialised object.
117 * This is non-virtual since derived Handle types must not contain data or virtual methods.
122 * @brief This copy constructor is required for (smart) pointer semantics.
124 * @param [in] handle A reference to the copied handle
126 ResourceImage( const ResourceImage& handle );
129 * @brief This assignment operator is required for (smart) pointer semantics.
131 * @param [in] rhs A reference to the copied handle
132 * @return A reference to this
134 ResourceImage& operator=( const ResourceImage& rhs );
137 * @name ResourceImageFactoryFunctions
138 * Create ResourceImage object instances using these functions.
143 * @brief Create an initialised ResourceImage object.
145 * Uses defaults for all options.
147 * @sa Dali::FittingMode::Type Dali::SamplingMode::Type
148 * @param [in] url The URL of the image file to use.
149 * @param [in] orientationCorrection Reorient the image to respect any orientation metadata in its header.
150 * @return A handle to a newly allocated object
152 static ResourceImage New( const std::string& url, bool orientationCorrection = true );
155 * @deprecated DALi 1.1.3 use New( const std::string& url ) instead.
157 * @brief Create an initialised ResourceImage object.
159 * @param [in] url The URL of the image file to use.
160 * @param [in] loadPol The LoadPolicy to apply when loading the image resource.
161 * @param [in] releasePol The ReleasePolicy to apply to Image.
162 * @param [in] orientationCorrection Reorient the image to respect any orientation metadata in its header.
163 * @return A handle to a newly allocated object
165 static ResourceImage New( const std::string& url, LoadPolicy loadPol, ReleasePolicy releasePol, bool orientationCorrection = true );
168 * @brief Create an initialised ResourceImage object.
170 * @param [in] url The URL of the image file to use.
171 * @param [in] size The width and height to fit the loaded image to.
172 * @param [in] fittingMode The method used to fit the shape of the image before loading to the shape defined by the size parameter.
173 * @param [in] samplingMode The filtering method used when sampling pixels from the input image while fitting it to desired size.
174 * @param [in] orientationCorrection Reorient the image to respect any orientation metadata in its header.
175 * @return A handle to a newly allocated object
177 static ResourceImage New( const std::string& url,
178 ImageDimensions size,
179 FittingMode::Type fittingMode = FittingMode::DEFAULT,
180 SamplingMode::Type samplingMode = SamplingMode::DEFAULT,
181 bool orientationCorrection = true );
184 * @deprecated DALi 1.1.3 use New( const std::string& url, ImageDimensions size ) instead.
186 * @brief Create an initialised ResourceImage object.
188 * @param [in] url The URL of the image file to use.
189 * @param [in] loadPol The LoadPolicy to apply when loading the image resource.
190 * @param [in] releasePol The ReleasePolicy to apply to Image.
191 * @param [in] size The width and height to fit the loaded image to.
192 * @param [in] fittingMode The method used to fit the shape of the image before loading to the shape defined by the size parameter.
193 * @param [in] samplingMode The filtering method used when sampling pixels from the input image while fitting it to desired size.
194 * @param [in] orientationCorrection Reorient the image to respect any orientation metadata in its header.
195 * @return A handle to a newly allocated object
197 static ResourceImage New( const std::string& url,
199 ReleasePolicy releasePol,
200 ImageDimensions size,
201 FittingMode::Type fittingMode = FittingMode::DEFAULT,
202 SamplingMode::Type samplingMode = SamplingMode::DEFAULT,
203 bool orientationCorrection = true );
208 * @brief Downcast an Object handle to ResourceImage handle.
210 * If handle points to a ResourceImage object the
211 * downcast produces valid handle. If not the returned handle is left uninitialized.
212 * @param[in] handle to An object
213 * @return handle to a Image object or an uninitialized handle
215 static ResourceImage DownCast( BaseHandle handle );
218 * @deprecated DALi 1.1.3
220 * @brief Return load policy.
222 * @return resource load policy
224 LoadPolicy GetLoadPolicy() const;
227 * @brief Query whether the image data has loaded.
229 * The asynchronous loading begins when the Image object is created.
230 * After the Image object is discarded, the image data will be released from memory.
231 * @return The loading state, either Loading, Success or Failed.
233 LoadingState GetLoadingState() const;
236 * @brief Returns the URL of the image.
238 * @return The URL of the image file.
240 std::string GetUrl() const;
243 * @brief Reload image from filesystem.
245 * The original set of image loading attributes (requested dimensions, scaling
246 * mode and filter mode) are used when requesting the image again.
247 * @note If image is offstage and OnDemand policy is set, the reload request is
255 * @brief Emitted when the image data loads successfully, or when the loading fails.
257 * @return A signal object to Connect() with.
259 ResourceImageSignal& LoadingFinishedSignal();
261 public: // Not intended for application developers
263 explicit DALI_INTERNAL ResourceImage( Internal::ResourceImage* );
271 #endif // __DALI_RESOURCE_IMAGE_H__