X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=dali%2Fpublic-api%2Fimages%2Fimage.h;h=7c649a2530f0465cd9dbb99100c24070e925ac75;hb=646f736e77b085c86e982c0d1d4b895c2a431330;hp=5eb086efad6947dd38e09824a483957d4b4f6b2e;hpb=4db25a3da1c48b1c45b2d73a4aaf4945e7e40ca8;p=platform%2Fcore%2Fuifw%2Fdali-core.git diff --git a/dali/public-api/images/image.h b/dali/public-api/images/image.h index 5eb086e..7c649a2 100644 --- a/dali/public-api/images/image.h +++ b/dali/public-api/images/image.h @@ -2,7 +2,7 @@ #define __DALI_IMAGE_H__ /* - * Copyright (c) 2014 Samsung Electronics Co., Ltd. + * Copyright (c) 2018 Samsung Electronics Co., Ltd. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -20,346 +20,162 @@ // EXTERNAL INCLUDES #include +#include // uint32_t // INTERNAL INCLUDES -#include -#include #include -#include +#include namespace Dali { -struct Vector2; +/** + * @addtogroup dali_core_images + * @{ + */ namespace Internal DALI_INTERNAL { class Image; } -class NativeImage; -class ImageAttributes; - - /** - * @brief An Image object represents an image resource that can be added to ImageActors. - * - * Image objects can also handle custom requests for image loading and are responsible for - * the underlying resource's lifetime. - * - *

Image Loading

- * - * When the Image object is created, resource loading will be attempted unless - * the Image object is created with OnDemand loading policy or a compatible resource is found in cache. - * In case of loading images on demand, resource loading will only be attempted if the associated ImageActor - * is put on Stage. - * Custom loading requests can be made by providing an ImageAttributes object to Image::New(). - * - * LoadPolicies - * - Immediate: acquire image resource when creating Image object. - * - OnDemand: only load in case the associated ImageActor is put on Stage - * - * ReleasePolicies - * - Unused: release resource once ImageActor using it is taken off stage. - * - Never: keep resource alive until Image object is thrown away. - * - * Resolution of conflicting policies - * If the same image is created more than once with conflicting policies, LoadPolicy "Immediate" overrides "OnDemand" - * and ReleasePolicy "Never" overrides "Unused". - * - * Custom load requests - * Size, scaling mode, orientation compensation can be set when requesting an image resource. - * See ImageAttributes for more details. - * - * Compatible resources + * @DEPRECATED_1_2.41 * - * Before loading a new image the internal image resource cache is checked by dali. - * If there is an Image already loaded in memory and is deemed "compatible" with the requested Image, - * that resource is reused. - * This happens for example if a loaded image exists with the same filename, and the difference between both - * of the dimensions is less than 50%. + * @brief An Image object represents an image resource that can be used for rendering. * - * Reloading Images + * Image objects can be shared between Actors. This is practical if you have a visual element on screen + * which is repeatedly used. * - * The same request used on creating the Image is re-issued when reloading Images. - * If the file changed since the last load operation, this might result in a different resource. - * Reload only takes effect if both of these conditions apply: - * - The Image has already finished loading - * - The Image is either on Stage or using Immediate load policy + * The image resource is released as soon as the last Image handle is released. + * @SINCE_1_0.0 + * @note If a resource was shared between Image objects it exists until its last reference is gone. * - *

Image resource lifetime

- * - * Image objects can be shared between ImageActors. This is practical if you have a visual element on screen - * which is repeatedly used. An example would be a button background image. - * The image resource is discarded when all ImageActors using the Image object are discarded or in case they - * were created with ReleasePolicy::Unused, taken off stage. - * Note: if a resource was shared between Image objects it exists until its last reference is gone. + * Image objects are responsible for the underlying resource's lifetime. * + * Signals + * | %Signal Name | Method | + * |------------------------|------------------------------| + * | uploaded | @ref UploadedSignal() | + * @SINCE_1_0.0 */ -class DALI_IMPORT_API Image : public BaseHandle +class DALI_CORE_API Image : public BaseHandle { public: - /** - * @brief Resource management options. - */ - - /** - * @brief LoadPolicy controls the way images are loaded into memory. - */ - enum LoadPolicy - { - Immediate, ///< load image once it is created (default) - OnDemand ///< delay loading until the image is being used (a related actor is added to Stage) - }; /** - * @brief ReleasePolicy controls the way images are deleted from memory. - */ - enum ReleasePolicy - { - Unused, ///< release resource once image is not in use anymore (eg. all actors using it become offstage). Reload when resource is required again. - Never ///< keep image data for the lifetime of the object. (default) - }; - - /** - * @brief Type of signal for LoadingFinished and Uploaded. + * @DEPRECATED_1_2.41 + * + * @brief Type of signal for Image Uploaded. + * @SINCE_1_0.0 */ - typedef SignalV2< void (Image) > ImageSignalV2; - - // Signal Names - static const char* const SIGNAL_IMAGE_LOADING_FINISHED; ///< Name of LoadingFinished signal - static const char* const SIGNAL_IMAGE_UPLOADED; ///< Name of Uploaded signal + typedef Signal< void (Image) > ImageSignalType; public: /** - * @brief Get the size of an image from disk. + * @DEPRECATED_1_2.41 * - * This function will read the header info from file on disk and is - * synchronous, so it should not be used repeatedly or in tight - * loops. + * @brief Constructor which creates an empty Image handle. * - * @param [in] filename of the image file to use. - * @return The width and height in pixels of the image. + * This class has no New method. + * Use the appropriate New method of its subclasses to create an initialized handle. + * (Dali::BufferImage::New(), Dali::EncodedBufferImage::New(), Dali::FrameBufferImage::New(), + * Dali::NativeImage::New(), Dali::ResourceImage::New()). + * @SINCE_1_0.0 */ - static Vector2 GetImageSize(const std::string filename); + Image() DALI_DEPRECATED_API; /** - * @brief Constructor which creates an empty Image object. + * @DEPRECATED_1_2.41 * - * Use Image::New(...) to create an initialised object. - */ - Image(); - - /** - * @brief Destructor + * @brief Destructor. * * This is non-virtual since derived Handle types must not contain data or virtual methods. + * @SINCE_1_0.0 */ - ~Image(); + ~Image() DALI_DEPRECATED_API; /** + * @DEPRECATED_1_2.41 + * * @brief This copy constructor is required for (smart) pointer semantics. * - * @param [in] handle A reference to the copied handle + * @SINCE_1_0.0 + * @param[in] handle A reference to the copied handle */ - Image(const Image& handle); + Image(const Image& handle) DALI_DEPRECATED_API; /** + * @DEPRECATED_1_2.41 + * * @brief This assignment operator is required for (smart) pointer semantics. * - * @param [in] rhs A reference to the copied handle + * @SINCE_1_0.0 + * @param[in] rhs A reference to the copied handle * @return A reference to this */ - Image& operator=(const Image& rhs); - - /** - * @brief Create an initialised image object. - * - * @param [in] filename The filename of the image file to use. - * @return A handle to a newly allocated object - */ - static Image New(const std::string& filename); - - /** - * @brief Create an initialised image object. - * - * @param [in] filename The filename of the image file to use. - * @param [in] loadPol The LoadPolicy to apply when loading the image resource. - * @param [in] releasePol The ReleasePolicy to apply to Image. - * @return A handle to a newly allocated object - */ - static Image New(const std::string& filename, LoadPolicy loadPol, ReleasePolicy releasePol); - - /** - * @brief Create an initialised image object. - * - * @param [in] filename The filename of the image file to use. - * @param [in] attributes Requested parameters for loading (size, scaling etc.). - * @return A handle to a newly allocated object - */ - static Image New(const std::string& filename, const ImageAttributes& attributes); - - /** - * @brief Create an initialised image object. - * - * @param [in] filename The filename of the image file to use. - * @param [in] attributes Requested parameters for loading (size, scaling etc.). - * @param [in] loadPol The LoadPolicy to apply when loading the image resource. - * @param [in] releasePol The ReleasePolicy to apply to Image. - * @return A handle to a newly allocated object - */ - static Image New(const std::string& filename, const ImageAttributes& attributes, LoadPolicy loadPol, ReleasePolicy releasePol); - - /** - * @brief Create an initialised image object. - * - * @param [in] filename The filename of the image file to use. - * @return A handle to a newly allocated object - */ - static Image NewDistanceField(const std::string& filename); - - /** - * @brief Create an initialised image object. - * - * @param [in] filename The filename of the image file to use. - * @param [in] loadPol The LoadPolicy to apply when loading the image resource. - * @param [in] releasePol The ReleasePolicy to apply to Image. - * @return A handle to a newly allocated object - */ - static Image NewDistanceField(const std::string& filename, LoadPolicy loadPol, ReleasePolicy releasePol); - - /** - * @brief Create an initialised image object. - * - * @param [in] filename The filename of the image file to use. - * @param [in] attributes The minimum search radius to check for differing pixels - * @return A handle to a newly allocated object - */ - static Image NewDistanceField(const std::string& filename, const ImageAttributes& attributes ); - - /** - * @brief Create an initialised image object. - * - * @param [in] filename The filename of the image file to use. - * @param [in] attributes The minimum search radius to check for differing pixels - * @param [in] loadPol The LoadPolicy to apply when loading the image resource. - * @param [in] releasePol The ReleasePolicy to apply to Image. - * @return A handle to a newly allocated object - */ - static Image NewDistanceField(const std::string& filename, const ImageAttributes& attributes, LoadPolicy loadPol, ReleasePolicy releasePol); - - /** - * @brief Creates object with already loaded NativeImage. - * - * The maximum size of the image is limited by GL_MAX_TEXTURE_SIZE - * @pre nativeImg should be initialised - * @param [in] nativeImg already initialised NativeImage - * @return A handle to a newly allocated object - */ - static Image New(NativeImage& nativeImg); - - /** - * @brief Downcast an Object handle to Image handle. - * - * If handle points to a Image object the - * downcast produces valid handle. If not the returned handle is left uninitialized. - * @param[in] handle to An object - * @return handle to a Image object or an uninitialized handle - */ - static Image DownCast( BaseHandle handle ); - - /** - * @brief Query whether the image data has loaded. - * - * The asynchronous loading begins when the Image object is created. - * After the Image object is discarded, the image data will be released from memory. - * @return The loading state, either Loading, Success or Failed. - */ - LoadingState GetLoadingState() const; - - /** - * @brief Returns the filename of the image if the image is created from a file. - * - * @return the image filename or empty string - */ - std::string GetFilename() const; + Image& operator=(const Image& rhs) DALI_DEPRECATED_API; /** - * @brief Return load policy. + * @DEPRECATED_1_2.41 * - * @return resource load policy - */ - LoadPolicy GetLoadPolicy () const; - - /** - * @brief Return resource release policy. + * @brief Downcasts a handle to Image handle. * - * @return resource release policy + * If handle points to a Image object, the + * downcast produces valid handle. If not, the returned handle is left uninitialized. + * @SINCE_1_0.0 + * @param[in] handle Handle to an object + * @return Handle to a Image object or an uninitialized handle */ - ReleasePolicy GetReleasePolicy () const; + static Image DownCast( BaseHandle handle ) DALI_DEPRECATED_API; /** - * @brief Reload image from filesystem. + * @DEPRECATED_1_2.41 * - * The set ImageAttributes are used when requesting the image again. - * @note if Image is offstage and OnDemand policy is set, reload request is ignored. - */ - void Reload(); - - /** * @brief Returns the width of the image. * * Returns either the requested width or the actual loaded width if no specific size was requested. * - * @return width of the image in pixels. + * @SINCE_1_0.0 + * @return Width of the image in pixels */ - unsigned int GetWidth() const; + uint32_t GetWidth() const DALI_DEPRECATED_API; /** + * @DEPRECATED_1_2.41 + * * @brief Returns the height of the image. * * Returns either the requested height or the actual loaded height if no specific size was requested. * - * @return height of the image in pixels. - */ - unsigned int GetHeight() const; - - /** - * @brief Get the attributes of an image. - * - * Only to be used after the image has finished loading. - * (Ticket's LoadingSucceeded callback was called) - * The returned value will reflect the true image dimensions once the asynchronous loading has finished. - * Connect to SignalLoadingFinished or use GetLoadingState to make sure this value is actual. - * @pre image should be loaded - * @return a copy of the attributes + * @SINCE_1_0.0 + * @return Height of the image in pixels */ - ImageAttributes GetAttributes() const; + uint32_t GetHeight() const DALI_DEPRECATED_API; public: // Signals /** - * @brief Emitted when the image data loads successfully, or when the loading fails. + * @DEPRECATED_1_2.41 * - * @return A signal object to Connect() with. - */ - ImageSignalV2& LoadingFinishedSignal(); - - /** * @brief This signal is emitted when the image data gets uploaded to GL. * * It Will be sent after an actor using the image is added to * the stage, when such a staged image is reloaded, or when a staged - * BitmapImage calls Update(). - * @return A signal object to Connect() with. + * BufferImage calls Update(). + * @SINCE_1_0.0 + * @return A signal object to Connect() with */ - ImageSignalV2& UploadedSignal(); + ImageSignalType& UploadedSignal() DALI_DEPRECATED_API; public: // Not intended for application developers explicit DALI_INTERNAL Image(Internal::Image*); }; +/** + * @} + */ } // namespace Dali #endif // __DALI_IMAGE_H__