dali/public-api/images/buffer-image.h

   1 #ifndef __DALI_BUFFER_IMAGE_H__
   2 #define __DALI_BUFFER_IMAGE_H__
   3
   4 /*
   5  * Copyright (c) 2018 Samsung Electronics Co., Ltd.
   6  *
   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
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  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.
  18  *
  19  */
  20
  21 // INTERNAL INCLUDES
  22 #include <dali/public-api/images/image.h>
  23 #include <dali/public-api/images/pixel.h>
  24 #include <dali/public-api/math/rect.h>
  25
  26 namespace Dali
  27 {
  28 /**
  29  * @addtogroup dali_core_images
  30  * @{
  31  */
  32
  33 namespace Internal DALI_INTERNAL
  34 {
  35 class BufferImage;
  36 }
  37
  38 typedef uint8_t        PixelBuffer;  ///< pixel data buffer @SINCE_1_0.0
  39 typedef Rect<uint32_t> RectArea;     ///< rectangular area (x,y,w,h) @SINCE_1_0.0
  40
  41
  42 /**
  43  * @DEPRECATED_1_2.41
  44  *
  45  * @brief BufferImage represents an image resource as a pixel data buffer.
  46  *
  47  * Its pixel buffer data is provided by the application developer.
  48  *
  49  * If the pixel format of the pixel buffer contains an alpha channel,
  50  * then the image is considered to be have transparent pixels without
  51  * regard for the actual content of the channel, and will be blended.
  52  *
  53  * @SINCE_1_0.0
  54  */
  55 class DALI_CORE_API BufferImage : public Image
  56 {
  57 public:
  58
  59   /**
  60    * @DEPRECATED_1_2.41
  61    *
  62    * @brief Constructor which creates an uninitialized BufferImage object.
  63    *
  64    * Use BufferImage::New(...) to create an initialized object.
  65    * @SINCE_1_0.0
  66    */
  67   BufferImage() DALI_DEPRECATED_API;
  68
  69   /**
  70    * @DEPRECATED_1_2.41
  71    *
  72    * @brief Creates a new BufferImage.
  73    *
  74    * Also a pixel buffer for image data is allocated.
  75    * Dali has ownership of the buffer.
  76    * For better performance and portability use power of two dimensions.
  77    * The maximum size of the image is limited by GL_MAX_TEXTURE_SIZE.
  78    * @SINCE_1_0.0
  79    * @param[in] width  Image width in pixels
  80    * @param[in] height Image height in pixels
  81    * @param[in] pixelformat The pixel format (rgba 32 bit by default)
  82    * @return A handle to a new instance of BufferImage
  83    * @pre width & height are greater than zero
  84    * @note default resource management policies are Immediate and Never
  85    *
  86    */
  87   static BufferImage New(uint32_t width,
  88                          uint32_t height,
  89                          Pixel::Format pixelformat=Pixel::RGBA8888) DALI_DEPRECATED_API;
  90
  91   /**
  92    * @DEPRECATED_1_2.41
  93    *
  94    * @brief Creates a new BufferImage, which uses an external data source.
  95    *
  96    * The PixelBuffer has to be allocated by application.
  97    *
  98    * The application holds ownership of the buffer. It must not
  99    * destroy the PixelBuffer on a staged image if it has called
 100    * Update() and hasn't received a Image::UploadedSignal, or if it has just
 101    * added it to the stage and has not received a Image::UploadedSignal.
 102    *
 103    * For better performance and portability use power of two dimensions.
 104    * The maximum size of the image is limited by GL_MAX_TEXTURE_SIZE.
 105    *
 106    * @SINCE_1_0.0
 107    * @param[in] pixelBuffer  Pixel buffer has to be allocated by application
 108    * @param[in] width        Image width in pixels
 109    * @param[in] height       Image height in pixels
 110    * @param[in] pixelFormat  The pixel format (rgba 32 bit by default)
 111    * @param[in] stride       The internal stride of the pixelbuffer in pixels
 112    * @return A handle to a new instance of BufferImage
 113    * @pre width & height are greater than zero
 114    */
 115   static BufferImage New(PixelBuffer*  pixelBuffer,
 116                          uint32_t  width,
 117                          uint32_t  height,
 118                          Pixel::Format pixelFormat=Pixel::RGBA8888,
 119                          uint32_t  stride=0) DALI_DEPRECATED_API;
 120
 121   /**
 122    * @DEPRECATED_1_2.41
 123    *
 124    * @brief Downcasts a handle to BufferImage handle.
 125    *
 126    * If the handle points to a BufferImage, the downcast produces valid handle.
 127    * If not, the returned handle is left uninitialized.
 128    *
 129    * @SINCE_1_0.0
 130    * @param[in] handle Handle to an object
 131    * @return Handle to a BufferImage or an uninitialized handle
 132    */
 133   static BufferImage DownCast( BaseHandle handle ) DALI_DEPRECATED_API;
 134
 135   /**
 136    * @DEPRECATED_1_2.41
 137    *
 138    * @brief Destructor.
 139    *
 140    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 141    * @SINCE_1_0.0
 142    */
 143   ~BufferImage() DALI_DEPRECATED_API;
 144
 145   /**
 146    * @DEPRECATED_1_2.41
 147    *
 148    * @brief This copy constructor is required for (smart) pointer semantics.
 149    *
 150    * @SINCE_1_0.0
 151    * @param[in] handle A reference to the copied handle
 152    */
 153   BufferImage(const BufferImage& handle) DALI_DEPRECATED_API;
 154
 155   /**
 156    * @DEPRECATED_1_2.41
 157    *
 158    * @brief This assignment operator is required for (smart) pointer semantics.
 159    *
 160    * @SINCE_1_0.0
 161    * @param[in] rhs A reference to the copied handle
 162    * @return A reference to this
 163    */
 164   BufferImage& operator=(const BufferImage& rhs) DALI_DEPRECATED_API;
 165
 166   /**
 167    * @DEPRECATED_1_2.41
 168    *
 169    * @brief White pixel as image data.
 170    *
 171    * Can be used to create solid color actors.
 172    * @SINCE_1_0.0
 173    * @return 1 white pixel with 32 bit colordepth
 174    */
 175   static const BufferImage WHITE() DALI_DEPRECATED_API;
 176
 177 public:
 178
 179   /**
 180    * @DEPRECATED_1_2.41
 181    *
 182    * @brief Returns the pixel buffer of the Image.
 183    *
 184    * The application can write to the buffer to modify its contents.
 185    *
 186    * Whilst the image is on stage, after writing to the buffer the
 187    * application should call Update() and wait for the
 188    * Image::UploadedSignal() method before writing again.
 189    *
 190    * @SINCE_1_0.0
 191    * @return The pixel buffer
 192    */
 193   PixelBuffer* GetBuffer() DALI_DEPRECATED_API;
 194
 195   /**
 196    * @DEPRECATED_1_2.41
 197    *
 198    * @brief Returns buffer size in bytes.
 199    *
 200    * @SINCE_1_0.0
 201    * @return The buffer size in bytes
 202    */
 203   uint32_t GetBufferSize() const DALI_DEPRECATED_API;
 204
 205   /**
 206    * @DEPRECATED_1_2.41
 207    *
 208    * @brief Returns buffer stride (in bytes).
 209    *
 210    * @SINCE_1_0.0
 211    * @return The buffer stride
 212    */
 213   uint32_t GetBufferStride() const DALI_DEPRECATED_API;
 214
 215   /**
 216    * @DEPRECATED_1_2.41
 217    *
 218    * @brief Returns the pixel format of the contained buffer
 219    *
 220    * @SINCE_1_0.0
 221    * @return The pixel format
 222    */
 223   Pixel::Format GetPixelFormat() const DALI_DEPRECATED_API;
 224
 225   /**
 226    * @DEPRECATED_1_2.41
 227    *
 228    * @brief Inform Dali that the contents of the buffer have changed.
 229    *
 230    * Image::UploadedSignal will be sent in response if the image is on stage
 231    * and the image data has been successfully copied to graphics
 232    * memory. To avoid visual tearing, the application should wait for
 233    * the Image::UploadedSignal before modifying the data.
 234    *
 235    * The application must not destroy an external PixelBuffer on a staged
 236    * image after calling this method until the Image::UploadedSignal has been
 237    * successfully received.
 238    *
 239    * @SINCE_1_0.0
 240    * @note BufferImage::Update might not work with BGR/BGRA formats!
 241    * @note Some GPUs may not support Non power of two buffer updates (for
 242    * example C110/SGX540)
 243    */
 244   void Update() DALI_DEPRECATED_API;
 245
 246   /**
 247    * @DEPRECATED_1_2.41
 248    *
 249    * @copydoc Update()
 250    * @param[in] updateArea Area that has changed in buffer
 251    */
 252   void Update( RectArea updateArea ) DALI_DEPRECATED_API;
 253
 254   /**
 255    * @DEPRECATED_1_2.41
 256    *
 257    * @brief Returns whether BufferImage uses external data source or not.
 258    *
 259    * If not, dali holds ownership of the PixelBuffer, otherwise the application
 260    * is responsible for freeing it.
 261    *
 262    * The application must not destroy an external PixelBuffer on a staged image
 263    * if it has called Update() and hasn't received a Image::UploadedSignal.
 264    *
 265    * @SINCE_1_0.0
 266    * @return @c true if application owns data, @c false otherwise
 267    */
 268   bool IsDataExternal() const DALI_DEPRECATED_API;
 269
 270 public: // Not intended for application developers
 271
 272   explicit DALI_INTERNAL BufferImage(Internal::BufferImage*);
 273 };
 274
 275 /**
 276  * @}
 277  */
 278 } // namespace Dali
 279
 280 #endif // __DALI_BUFFER_IMAGE_H__