X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=dali%2Fpublic-api%2Fimages%2Fresource-image.h;h=35feec22c4655f0845ab1b1972cfaf0700dc2df4;hb=baad1726f5f7f05d98da7ca591f24dbe3c49dab2;hp=4ea879efd88bb378cd20e6b098bfa1c425166f5e;hpb=78c80936161ebb30fa31975419dd62af884d98b8;p=platform%2Fcore%2Fuifw%2Fdali-core.git diff --git a/dali/public-api/images/resource-image.h b/dali/public-api/images/resource-image.h index 4ea879e..35feec2 100644 --- a/dali/public-api/images/resource-image.h +++ b/dali/public-api/images/resource-image.h @@ -1,8 +1,8 @@ -#ifndef __DALI_RESOURCE_IMAGE_H__ -#define __DALI_RESOURCE_IMAGE_H__ +#ifndef DALI_RESOURCE_IMAGE_H +#define DALI_RESOURCE_IMAGE_H /* - * Copyright (c) 2015 Samsung Electronics Co., Ltd. + * Copyright (c) 2019 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. @@ -25,11 +25,14 @@ #include #include #include +#include namespace Dali { -struct Vector2; -class ImageAttributes; +/** + * @addtogroup dali_core_images + * @{ + */ namespace Internal DALI_INTERNAL { @@ -37,217 +40,210 @@ class ResourceImage; } /** - * @brief ResourceImage is an image loaded using a URL - * - *

ResourceImage Loading

- * - * When the ResourceImage is created, resource loading will be attempted unless - * the ResourceImage is created with IMMEDIATE 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 ResourceImage::New(). - * - * LoadPolicies - * - IMMEDIATE: acquire image resource when creating ResourceImage. - * - ON_DEMAND: only load in case the associated ImageActor is put on Stage + * @DEPRECATED_1_2.41 * - * Resolution of conflicting policies - * If the same image is created more than once with conflicting policies, LoadPolicy "IMMEDIATE" overrides "ON_DEMAND". + * @brief ResourceImage is an image loaded using a URL. * - * Custom load requests - * Size, scaling mode, orientation compensation can be set when requesting an image. - * See ImageAttributes for more details. + * Customizing load requests * - * Compatible resources - * - * Before loading a new ResourceImage 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 URL, and the difference between both - * of the dimensions is less than 50%. + * Size, scaling mode, filter mode, and orientation compensation can be set when requesting an image. * * Reloading images * * The same request used on creating the ResourceImage 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 ResourceImage has already finished loading - * - The ResourceImage is either on Stage or using IMMEDIATE load policy + * Reload only takes effect if the ResourceImage has already finished loading. * * Signals - * | %Signal Name | Method | - * |------------------------|------------------------------| - * | image-loading-finished | @ref LoadingFinishedSignal() | + * | %Signal Name | Method | + * |----------------------|------------------------------| + * | imageLoadingFinished | @ref LoadingFinishedSignal() | + * @SINCE_1_0.0 */ -class DALI_IMPORT_API ResourceImage : public Image +class DALI_CORE_API ResourceImage : public Image { 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) - ON_DEMAND ///< delay loading until the image is being used (a related actor is added to Stage) - }; /** + * @DEPRECATED_1_2.41 + * * @brief Type of signal for LoadingFinished and Uploaded. + * @SINCE_1_0.0 */ typedef Signal< void (ResourceImage) > ResourceImageSignal; public: /** - * @brief Get the size of an image from disk. + * @DEPRECATED_1_2.41 + * + * @brief Gets the size of an image from disk. * * 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. * - * @param [in] url The URL of the image file. - * @return The width and height in pixels of the image. + * @SINCE_1_0.0 + * @REMARK_STORAGE + * @param[in] url The URL of the image file + * @return The width and height in pixels of the image */ - static Vector2 GetImageSize( const std::string& url ); + static ImageDimensions GetImageSize( const std::string& url ) DALI_DEPRECATED_API; /** + * @DEPRECATED_1_2.41 + * * @brief Constructor which creates an empty ResourceImage object. * * Use ResourceImage::New(...) to create an initialised object. + * @SINCE_1_0.0 */ - ResourceImage(); + ResourceImage() DALI_DEPRECATED_API; /** - * @brief Destructor + * @DEPRECATED_1_2.41 + * + * @brief Destructor. * * This is non-virtual since derived Handle types must not contain data or virtual methods. + * @SINCE_1_0.0 */ - ~ResourceImage(); + ~ResourceImage() 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 */ - ResourceImage( const ResourceImage& handle ); + ResourceImage( const ResourceImage& 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 */ - ResourceImage& operator=( const ResourceImage& rhs ); + ResourceImage& operator=( const ResourceImage& rhs ) DALI_DEPRECATED_API; /** - * @brief Create an initialised ResourceImage object. - * - * @param [in] url The URL of the image file to use. - * @return A handle to a newly allocated object + * @name ResourceImageFactoryFunctions + * Creates ResourceImage object instances using these functions. */ - static ResourceImage New( const std::string& url ); + ///@{ /** - * @brief Create an initialised ResourceImage object. + * @DEPRECATED_1_2.41 * - * @param [in] url The URL 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 ResourceImage New( const std::string& url, LoadPolicy loadPol, ReleasePolicy releasePol ); - - /** - * @brief Create an initialised ResourceImage object. + * @brief Creates an initialized ResourceImage object. + * + * Uses defaults for all options. * - * @param [in] url The URL of the image file to use. - * @param [in] attributes Requested parameters for loading (size, scaling etc.). + * @sa Dali::FittingMode::Type Dali::SamplingMode::Type + * @SINCE_1_0.0 + * @REMARK_INTERNET + * @REMARK_STORAGE + * @param[in] url The URL of the image file to use + * @param[in] orientationCorrection Reorient the image to respect any orientation metadata in its header * @return A handle to a newly allocated object */ - static ResourceImage New( const std::string& url, const ImageAttributes& attributes ); + static ResourceImage New( const std::string& url, bool orientationCorrection = true ) DALI_DEPRECATED_API; /** - * @brief Create an initialised ResourceImage object. + * @DEPRECATED_1_2.41 * - * @param [in] url The URL 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. + * @brief Creates an initialized ResourceImage object. + * + * @SINCE_1_0.0 + * @REMARK_INTERNET + * @REMARK_STORAGE + * @param[in] url The URL of the image file to use + * @param[in] size The width and height to fit the loaded image to + * @param[in] fittingMode The method used to fit the shape of the image before loading to the shape defined by the size parameter + * @param[in] samplingMode The filtering method used when sampling pixels from the input image while fitting it to desired size + * @param[in] orientationCorrection Reorient the image to respect any orientation metadata in its header * @return A handle to a newly allocated object */ - static ResourceImage New( const std::string& url, const ImageAttributes& attributes, LoadPolicy loadPol, ReleasePolicy releasePol ); + static ResourceImage New( const std::string& url, + ImageDimensions size, + FittingMode::Type fittingMode = FittingMode::DEFAULT, + SamplingMode::Type samplingMode = SamplingMode::DEFAULT, + bool orientationCorrection = true ) DALI_DEPRECATED_API; - /** - * @brief Downcast an Object handle to ResourceImage handle. - * - * If handle points to a ResourceImage 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 ResourceImage DownCast( BaseHandle handle ); + ///@} /** - * @brief Return load policy. + * @DEPRECATED_1_2.41 + * + * @brief Downcasts a handle to ResourceImage handle. * - * @return resource load policy + * If handle points to a ResourceImage 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 */ - LoadPolicy GetLoadPolicy() const; + static ResourceImage DownCast( BaseHandle handle ) DALI_DEPRECATED_API; /** - * @brief Query whether the image data has loaded. + * @DEPRECATED_1_2.41 + * + * @brief Queries 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. + * @SINCE_1_0.0 + * @return The loading state, either Loading, Success or Failed */ - LoadingState GetLoadingState() const; + LoadingState GetLoadingState() const DALI_DEPRECATED_API; /** + * @DEPRECATED_1_2.41 + * * @brief Returns the URL of the image. * - * @return The URL of the image file. + * @SINCE_1_0.0 + * @return The URL of the image file */ - std::string GetUrl() const; + std::string GetUrl() const 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 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 + * @brief Reloads image from filesystem. + * + * The original set of image loading attributes (requested dimensions, scaling + * mode and filter mode) are used when requesting the image again. + * @SINCE_1_0.0 + * @note If image is offstage and OnDemand policy is set, the reload request is ignored. */ - ImageAttributes GetAttributes() const; + void Reload() DALI_DEPRECATED_API; public: // Signals /** + * @DEPRECATED_1_2.41 + * * @brief Emitted when the image data loads successfully, or when the loading fails. * - * @return A signal object to Connect() with. + * @SINCE_1_0.0 + * @return A signal object to Connect() with */ - ResourceImageSignal& LoadingFinishedSignal(); + ResourceImageSignal& LoadingFinishedSignal() DALI_DEPRECATED_API; public: // Not intended for application developers explicit DALI_INTERNAL ResourceImage( Internal::ResourceImage* ); }; +/** + * @} + */ } // namespace Dali -#endif // __DALI_RESOURCE_IMAGE_H__ +#endif // DALI_RESOURCE_IMAGE_H