1 #ifndef __DALI_IMAGE_H__
2 #define __DALI_IMAGE_H__
5 * Copyright (c) 2014 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/pixel.h>
27 #include <dali/public-api/object/base-handle.h>
28 #include <dali/public-api/signals/dali-signal-v2.h>
34 namespace Internal DALI_INTERNAL
40 class ImageAttributes;
44 * @brief An Image object represents an image resource that can be added to ImageActors.
46 * Image objects can also handle custom requests for image loading and are responsible for
47 * the underlying resource's lifetime.
49 * <h3>Image Loading</h3>
51 * When the Image object is created, resource loading will be attempted unless
52 * the Image object is created with OnDemand loading policy or a compatible resource is found in cache.
53 * In case of loading images on demand, resource loading will only be attempted if the associated ImageActor
55 * Custom loading requests can be made by providing an ImageAttributes object to Image::New().
58 * - Immediate: acquire image resource when creating Image object.
59 * - OnDemand: only load in case the associated ImageActor is put on Stage
61 * <i>ReleasePolicies</i>
62 * - Unused: release resource once ImageActor using it is taken off stage.
63 * - Never: keep resource alive until Image object is thrown away.
65 * <i>Resolution of conflicting policies</i>
66 * If the same image is created more than once with conflicting policies, LoadPolicy "Immediate" overrides "OnDemand"
67 * and ReleasePolicy "Never" overrides "Unused".
69 * <i>Custom load requests</i>
70 * Size, scaling mode, orientation compensation can be set when requesting an image resource.
71 * See ImageAttributes for more details.
73 * <i>Compatible resources</i>
75 * Before loading a new image the internal image resource cache is checked by dali.
76 * If there is an Image already loaded in memory and is deemed "compatible" with the requested Image,
77 * that resource is reused.
78 * This happens for example if a loaded image exists with the same filename, and the difference between both
79 * of the dimensions is less than 50%.
81 * <i>Reloading Images</i>
83 * The same request used on creating the Image is re-issued when reloading Images.
84 * If the file changed since the last load operation, this might result in a different resource.
85 * Reload only takes effect if both of these conditions apply:
86 * - The Image has already finished loading
87 * - The Image is either on Stage or using Immediate load policy
89 * <h3>Image resource lifetime</h3>
91 * Image objects can be shared between ImageActors. This is practical if you have a visual element on screen
92 * which is repeatedly used. An example would be a button background image.
93 * The image resource is discarded when all ImageActors using the Image object are discarded or in case they
94 * were created with ReleasePolicy::Unused, taken off stage.
95 * Note: if a resource was shared between Image objects it exists until its last reference is gone.
98 class DALI_IMPORT_API Image : public BaseHandle
102 * @brief Resource management options.
106 * @brief LoadPolicy controls the way images are loaded into memory.
110 Immediate, ///< load image once it is created (default)
111 OnDemand ///< delay loading until the image is being used (a related actor is added to Stage)
115 * @brief ReleasePolicy controls the way images are deleted from memory.
119 Unused, ///< release resource once image is not in use anymore (eg. all actors using it become offstage). Reload when resource is required again.
120 Never ///< keep image data for the lifetime of the object. (default)
124 * @brief Type of signal for LoadingFinished and Uploaded.
126 typedef SignalV2< void (Image) > ImageSignalV2;
129 static const char* const SIGNAL_IMAGE_LOADING_FINISHED; ///< Name of LoadingFinished signal
130 static const char* const SIGNAL_IMAGE_UPLOADED; ///< Name of Uploaded signal
135 * @brief Get the size of an image from disk.
137 * This function will read the header info from file on disk and is
138 * synchronous, so it should not be used repeatedly or in tight
141 * @param [in] filename of the image file to use.
142 * @return The width and height in pixels of the image.
144 static Vector2 GetImageSize(const std::string filename);
147 * @brief Constructor which creates an empty Image object.
149 * Use Image::New(...) to create an initialised object.
156 * This is non-virtual since derived Handle types must not contain data or virtual methods.
161 * @brief This copy constructor is required for (smart) pointer semantics.
163 * @param [in] handle A reference to the copied handle
165 Image(const Image& handle);
168 * @brief This assignment operator is required for (smart) pointer semantics.
170 * @param [in] rhs A reference to the copied handle
171 * @return A reference to this
173 Image& operator=(const Image& rhs);
176 * @brief This method is defined to allow assignment of the NULL value,
177 * and will throw an exception if passed any other value.
179 * Assigning to NULL is an alias for Reset().
180 * @param [in] rhs A NULL pointer
181 * @return A reference to this handle
183 Image& operator=(BaseHandle::NullType* rhs);
186 * @brief Create an initialised image object.
188 * @param [in] filename The filename of the image file to use.
189 * @return A handle to a newly allocated object
191 static Image New(const std::string& filename);
194 * @brief Create an initialised image object.
196 * @param [in] filename The filename of the image file to use.
197 * @param [in] loadPol The LoadPolicy to apply when loading the image resource.
198 * @param [in] releasePol The ReleasePolicy to apply to Image.
199 * @return A handle to a newly allocated object
201 static Image New(const std::string& filename, LoadPolicy loadPol, ReleasePolicy releasePol);
204 * @brief Create an initialised image object.
206 * @param [in] filename The filename of the image file to use.
207 * @param [in] attributes Requested parameters for loading (size, scaling etc.).
208 * @return A handle to a newly allocated object
210 static Image New(const std::string& filename, const ImageAttributes& attributes);
213 * @brief Create an initialised image object.
215 * @param [in] filename The filename of the image file to use.
216 * @param [in] attributes Requested parameters for loading (size, scaling etc.).
217 * @param [in] loadPol The LoadPolicy to apply when loading the image resource.
218 * @param [in] releasePol The ReleasePolicy to apply to Image.
219 * @return A handle to a newly allocated object
221 static Image New(const std::string& filename, const ImageAttributes& attributes, LoadPolicy loadPol, ReleasePolicy releasePol);
224 * @brief Create an initialised image object.
226 * @param [in] filename The filename of the image file to use.
227 * @return A handle to a newly allocated object
229 static Image NewDistanceField(const std::string& filename);
232 * @brief Create an initialised image object.
234 * @param [in] filename The filename of the image file to use.
235 * @param [in] loadPol The LoadPolicy to apply when loading the image resource.
236 * @param [in] releasePol The ReleasePolicy to apply to Image.
237 * @return A handle to a newly allocated object
239 static Image NewDistanceField(const std::string& filename, LoadPolicy loadPol, ReleasePolicy releasePol);
242 * @brief Create an initialised image object.
244 * @param [in] filename The filename of the image file to use.
245 * @param [in] attributes The minimum search radius to check for differing pixels
246 * @return A handle to a newly allocated object
248 static Image NewDistanceField(const std::string& filename, const ImageAttributes& attributes );
251 * @brief Create an initialised image object.
253 * @param [in] filename The filename of the image file to use.
254 * @param [in] attributes The minimum search radius to check for differing pixels
255 * @param [in] loadPol The LoadPolicy to apply when loading the image resource.
256 * @param [in] releasePol The ReleasePolicy to apply to Image.
257 * @return A handle to a newly allocated object
259 static Image NewDistanceField(const std::string& filename, const ImageAttributes& attributes, LoadPolicy loadPol, ReleasePolicy releasePol);
262 * @brief Creates object with already loaded NativeImage.
264 * The maximum size of the image is limited by GL_MAX_TEXTURE_SIZE
265 * @pre nativeImg should be initialised
266 * @param [in] nativeImg already initialised NativeImage
267 * @return A handle to a newly allocated object
269 static Image New(NativeImage& nativeImg);
272 * @brief Downcast an Object handle to Image handle.
274 * If handle points to a Image object the
275 * downcast produces valid handle. If not the returned handle is left uninitialized.
276 * @param[in] handle to An object
277 * @return handle to a Image object or an uninitialized handle
279 static Image DownCast( BaseHandle handle );
282 * @brief Query whether the image data has loaded.
284 * The asynchronous loading begins when the Image object is created.
285 * After the Image object is discarded, the image data will be released from memory.
286 * @return The loading state, either Loading, Success or Failed.
288 LoadingState GetLoadingState() const;
291 * @brief Returns the filename of the image if the image is created from a file.
293 * @return the image filename or empty string
295 std::string GetFilename() const;
298 * @brief Return load policy.
300 * @return resource load policy
302 LoadPolicy GetLoadPolicy () const;
305 * @brief Return resource release policy.
307 * @return resource release policy
309 ReleasePolicy GetReleasePolicy () const;
312 * @brief Reload image from filesystem.
314 * The set ImageAttributes are used when requesting the image again.
315 * @note if Image is offstage and OnDemand policy is set, reload request is ignored.
320 * @brief Returns the width of the image.
322 * Returns either the requested width or the actual loaded width if no specific size was requested.
324 * @return width of the image in pixels.
326 unsigned int GetWidth() const;
329 * @brief Returns the height of the image.
331 * Returns either the requested height or the actual loaded height if no specific size was requested.
333 * @return height of the image in pixels.
335 unsigned int GetHeight() const;
338 * @brief Get the attributes of an image.
340 * Only to be used after the image has finished loading.
341 * (Ticket's LoadingSucceeded callback was called)
342 * The returned value will reflect the true image dimensions once the asynchronous loading has finished.
343 * Connect to SignalLoadingFinished or use GetLoadingState to make sure this value is actual.
344 * @pre image should be loaded
345 * @return a copy of the attributes
347 ImageAttributes GetAttributes() const;
352 * @brief Emitted when the image data loads successfully, or when the loading fails.
354 * @return A signal object to Connect() with.
356 ImageSignalV2& LoadingFinishedSignal();
359 * @brief This signal is emitted when the image data gets uploaded to GL.
361 * It Will be sent after an actor using the image is added to
362 * the stage, when such a staged image is reloaded, or when a staged
363 * BitmapImage calls Update().
364 * @return A signal object to Connect() with.
366 ImageSignalV2& UploadedSignal();
368 public: // Not intended for application developers
370 explicit DALI_INTERNAL Image(Internal::Image*);
375 #endif // __DALI_IMAGE_H__