X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=dali%2Fpublic-api%2Fimages%2Fbuffer-image.h;h=a6d72ad93f0fa704e2a24d61f091ef19aa35bf0a;hb=646f736e77b085c86e982c0d1d4b895c2a431330;hp=dbcd428349c97eafbe39a1b3b5f7ad8e44145982;hpb=6a51fca768ccd75d552b73c0a67056721dc86e44;p=platform%2Fcore%2Fuifw%2Fdali-core.git diff --git a/dali/public-api/images/buffer-image.h b/dali/public-api/images/buffer-image.h index dbcd428..a6d72ad 100644 --- a/dali/public-api/images/buffer-image.h +++ b/dali/public-api/images/buffer-image.h @@ -2,7 +2,7 @@ #define __DALI_BUFFER_IMAGE_H__ /* - * Copyright (c) 2015 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. @@ -19,276 +19,262 @@ */ // INTERNAL INCLUDES -#include #include #include #include namespace Dali { +/** + * @addtogroup dali_core_images + * @{ + */ namespace Internal DALI_INTERNAL { class BufferImage; } -typedef unsigned char PixelBuffer; ///< pixel data buffer -typedef Rect RectArea; ///< rectangular area (x,y,w,h) +typedef uint8_t PixelBuffer; ///< pixel data buffer @SINCE_1_0.0 +typedef Rect RectArea; ///< rectangular area (x,y,w,h) @SINCE_1_0.0 /** - * @brief BufferImage represents an image resource that can be added to ImageActors. - * Its pixel buffer data is provided by the application developer. + * @DEPRECATED_1_2.41 * - * Care should be taken with pixel data allocated by the application, - * as the data is copied to GL both when the image is added to the - * stage and after a call to Update(). In both of these cases, a - * SignalUploaded will be sent to the application confirming that the - * operation has completed. + * @brief BufferImage represents an image resource as a pixel data buffer. * - * The application can free the pixel data after receiving a - * SignalUploaded. - * - * Similarly, once the image is on stage (i.e. it's being used by an - * ImageActor that is on stage), the application should only write to - * the buffer after receiving a SignalUploaded, then call Update() - * once the write is finished. This avoids the pixel data being changed - * whilst it's being copied to GL. Writing to the buffer without waiting - * for the signal will likely result in visible tearing. + * Its pixel buffer data is provided by the application developer. * * If the pixel format of the pixel buffer contains an alpha channel, * then the image is considered to be have transparent pixels without * regard for the actual content of the channel, and will be blended. * - * If the image is opaque and blending is not required, then the user - * should call ImageActor::SetUseImageAlpha(false) on the containing actor. + * @SINCE_1_0.0 */ -class DALI_IMPORT_API BufferImage : public Image +class DALI_CORE_API BufferImage : public Image { public: - /** - * @brief Constructor which creates an uninitialized BufferImage object. - * - * Use BufferImage::New(...) to create an initialised object. - */ - BufferImage(); /** - * @brief Create a new BufferImage. + * @DEPRECATED_1_2.41 * - * Also a pixel buffer for image data is allocated. - * Dali has ownership of the buffer. - * For better performance and portability use power of two dimensions. - * The maximum size of the image is limited by GL_MAX_TEXTURE_SIZE. - * @note: default resource management policies are Immediate and Never + * @brief Constructor which creates an uninitialized BufferImage object. * - * @pre width & height are greater than zero - * @param [in] width image width in pixels - * @param [in] height image height in pixels - * @param [in] pixelformat the pixel format (rgba 32 bit by default) - * @return a handle to a new instance of BufferImage + * Use BufferImage::New(...) to create an initialized object. + * @SINCE_1_0.0 */ - static BufferImage New(unsigned int width, - unsigned int height, - Pixel::Format pixelformat=Pixel::RGBA8888); + BufferImage() DALI_DEPRECATED_API; /** - * @brief Create a new BufferImage. + * @DEPRECATED_1_2.41 + * + * @brief Creates a new BufferImage. * * Also a pixel buffer for image data is allocated. * Dali has ownership of the buffer. * For better performance and portability use power of two dimensions. * The maximum size of the image is limited by GL_MAX_TEXTURE_SIZE. - * + * @SINCE_1_0.0 + * @param[in] width Image width in pixels + * @param[in] height Image height in pixels + * @param[in] pixelformat The pixel format (rgba 32 bit by default) + * @return A handle to a new instance of BufferImage * @pre width & height are greater than zero - * @param [in] width Image width in pixels - * @param [in] height Image height in pixels - * @param [in] pixelFormat The pixel format - * @param [in] releasePolicy Optionally release memory when image is not visible on screen. - * @return a handle to a new instance of BufferImage + * @note default resource management policies are Immediate and Never + * */ - static BufferImage New(unsigned int width, - unsigned int height, - Pixel::Format pixelFormat, - ReleasePolicy releasePolicy); + static BufferImage New(uint32_t width, + uint32_t height, + Pixel::Format pixelformat=Pixel::RGBA8888) DALI_DEPRECATED_API; /** - * @brief Create a new BufferImage, which uses an external data source. + * @DEPRECATED_1_2.41 + * + * @brief Creates a new BufferImage, which uses an external data source. * * The PixelBuffer has to be allocated by application. * * The application holds ownership of the buffer. It must not * destroy the PixelBuffer on a staged image if it has called - * Update() and hasn't received a SignalUploaded, or if it has just - * added it to the stage and has not received a SignalUploaded. + * Update() and hasn't received a Image::UploadedSignal, or if it has just + * added it to the stage and has not received a Image::UploadedSignal. * * For better performance and portability use power of two dimensions. * The maximum size of the image is limited by GL_MAX_TEXTURE_SIZE. * + * @SINCE_1_0.0 + * @param[in] pixelBuffer Pixel buffer has to be allocated by application + * @param[in] width Image width in pixels + * @param[in] height Image height in pixels + * @param[in] pixelFormat The pixel format (rgba 32 bit by default) + * @param[in] stride The internal stride of the pixelbuffer in pixels + * @return A handle to a new instance of BufferImage * @pre width & height are greater than zero - * @param [in] pixelBuffer pixel buffer. has to be allocated by application. - * @param [in] width image width in pixels - * @param [in] height image height in pixels - * @param [in] pixelFormat the pixel format (rgba 32 bit by default) - * @param [in] stride the internal stride of the pixelbuffer in pixels - * @return a handle to a new instance of BufferImage */ static BufferImage New(PixelBuffer* pixelBuffer, - unsigned int width, - unsigned int height, + uint32_t width, + uint32_t height, Pixel::Format pixelFormat=Pixel::RGBA8888, - unsigned int stride=0); + uint32_t stride=0) DALI_DEPRECATED_API; /** - * @brief Create a new BufferImage, which uses an external data source. + * @DEPRECATED_1_2.41 * - * The PixelBuffer has to be allocated by application. + * @brief Downcasts a handle to BufferImage handle. * - * The application holds ownership of the buffer. It must not - * destroy the PixelBuffer on a staged image if it has called - * Update() and hasn't received a SignalUploaded, or if it has just - * added it to the stage and has not received a SignalUploaded. + * If the handle points to a BufferImage, the downcast produces valid handle. + * If not, the returned handle is left uninitialized. * - * For better performance and portability use power of two dimensions. - * The maximum size of the image is limited by GL_MAX_TEXTURE_SIZE. - * - * @note in case releasePolicy is "Unused", application has to call - * BufferImage::Update() whenever image is re-added to the stage - * - * @pre width & height are greater than zero - * @param [in] pixelBuffer pixel buffer. has to be allocated by application. - * @param [in] width image width in pixels - * @param [in] height image height in pixels - * @param [in] pixelFormat the pixel format - * @param [in] stride the internal stride of the pixelbuffer in pixels - * @param [in] releasePolicy optionally relase memory when image is not visible on screen. - * @return a handle to a new instance of BufferImage + * @SINCE_1_0.0 + * @param[in] handle Handle to an object + * @return Handle to a BufferImage or an uninitialized handle */ - static BufferImage New(PixelBuffer* pixelBuffer, - unsigned int width, - unsigned int height, - Pixel::Format pixelFormat, - unsigned int stride, - ReleasePolicy releasePolicy); + static BufferImage DownCast( BaseHandle handle ) DALI_DEPRECATED_API; /** - * @brief Downcast an Object handle to BufferImage. + * @DEPRECATED_1_2.41 * - * If handle points to a BufferImage the downcast produces valid - * handle. If not the returned handle is left uninitialized. - * - * @param[in] handle to An object - * @return handle to a BufferImage or an uninitialized handle - */ - static BufferImage DownCast( BaseHandle handle ); - - /** - * @brief Destructor + * @brief Destructor. * * This is non-virtual since derived Handle types must not contain data or virtual methods. + * @SINCE_1_0.0 */ - ~BufferImage(); + ~BufferImage() 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 */ - BufferImage(const BufferImage& handle); + BufferImage(const BufferImage& 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 */ - BufferImage& operator=(const BufferImage& rhs); + BufferImage& operator=(const BufferImage& rhs) DALI_DEPRECATED_API; /** + * @DEPRECATED_1_2.41 + * * @brief White pixel as image data. * * Can be used to create solid color actors. + * @SINCE_1_0.0 * @return 1 white pixel with 32 bit colordepth */ - static const BufferImage WHITE(); + static const BufferImage WHITE() DALI_DEPRECATED_API; public: + /** + * @DEPRECATED_1_2.41 + * * @brief Returns the pixel buffer of the Image. * * The application can write to the buffer to modify its contents. * * Whilst the image is on stage, after writing to the buffer the * application should call Update() and wait for the - * SignalUploaded() method before writing again. + * Image::UploadedSignal() method before writing again. * - * @return the pixel buffer + * @SINCE_1_0.0 + * @return The pixel buffer */ - PixelBuffer* GetBuffer(); + PixelBuffer* GetBuffer() DALI_DEPRECATED_API; /** + * @DEPRECATED_1_2.41 + * * @brief Returns buffer size in bytes. * - * @return the buffer size in bytes + * @SINCE_1_0.0 + * @return The buffer size in bytes */ - unsigned int GetBufferSize() const; + uint32_t GetBufferSize() const DALI_DEPRECATED_API; /** + * @DEPRECATED_1_2.41 + * * @brief Returns buffer stride (in bytes). * - * @return the buffer stride + * @SINCE_1_0.0 + * @return The buffer stride */ - unsigned int GetBufferStride() const; + uint32_t GetBufferStride() const DALI_DEPRECATED_API; /** + * @DEPRECATED_1_2.41 + * * @brief Returns the pixel format of the contained buffer * - * @return the pixel format + * @SINCE_1_0.0 + * @return The pixel format */ - Pixel::Format GetPixelFormat() const; + Pixel::Format GetPixelFormat() const DALI_DEPRECATED_API; /** + * @DEPRECATED_1_2.41 + * * @brief Inform Dali that the contents of the buffer have changed. * - * SignalUploaded will be sent in response if the image is on stage + * Image::UploadedSignal will be sent in response if the image is on stage * and the image data has been successfully copied to graphics * memory. To avoid visual tearing, the application should wait for - * the SignalUploaded before modifying the data. + * the Image::UploadedSignal before modifying the data. * * The application must not destroy an external PixelBuffer on a staged - * image after calling this method until the SignalUploaded has been + * image after calling this method until the Image::UploadedSignal has been * successfully received. * - * @note: BufferImage::Update might not work with BGR/BGRA formats! - * @note: Some GPUs may not support Non power of two buffer updates (for + * @SINCE_1_0.0 + * @note BufferImage::Update might not work with BGR/BGRA formats! + * @note Some GPUs may not support Non power of two buffer updates (for * example C110/SGX540) */ - void Update(); + void Update() DALI_DEPRECATED_API; /** + * @DEPRECATED_1_2.41 + * * @copydoc Update() - * @param [in] updateArea area that has changed in buffer + * @param[in] updateArea Area that has changed in buffer */ - void Update( RectArea updateArea ); + void Update( RectArea updateArea ) DALI_DEPRECATED_API; /** + * @DEPRECATED_1_2.41 + * * @brief Returns whether BufferImage uses external data source or not. * * If not, dali holds ownership of the PixelBuffer, otherwise the application * is responsible for freeing it. * * The application must not destroy an external PixelBuffer on a staged image - * if it has called Update() and hasn't received a SignalUploaded. + * if it has called Update() and hasn't received a Image::UploadedSignal. * - * @return true if application owns data, false otherwise + * @SINCE_1_0.0 + * @return @c true if application owns data, @c false otherwise */ - bool IsDataExternal() const; + bool IsDataExternal() const DALI_DEPRECATED_API; public: // Not intended for application developers explicit DALI_INTERNAL BufferImage(Internal::BufferImage*); }; +/** + * @} + */ } // namespace Dali #endif // __DALI_BUFFER_IMAGE_H__