dali/internal/event/images/buffer-image-impl.h

   1 #ifndef __DALI_INTERNAL_BUFFER_IMAGE_H__
   2 #define __DALI_INTERNAL_BUFFER_IMAGE_H__
   3
   4 /*
   5  * Copyright (c) 2015 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/integration-api/bitmap.h> // For Integration::BitmapPtr
  23 #include <dali/public-api/object/ref-object.h>
  24 #include <dali/internal/event/images/image-impl.h>
  25 #include <dali/public-api/images/image.h>
  26 #include <dali/public-api/images/buffer-image.h>
  27
  28 namespace Dali
  29 {
  30
  31 namespace Internal
  32 {
  33
  34 class BufferImage;
  35 typedef IntrusivePtr<BufferImage> BufferImagePtr;
  36
  37 class ResourceClient;
  38 class ResourceManager;
  39
  40 /**
  41  * BufferImage represents an image resource that can be added to actors etc.
  42  * Its pixel buffer data is provided by the application developer.
  43  * Pixel buffer memory allocation can be handled by dali or application.
  44  */
  45 class BufferImage : public Image
  46 {
  47 public:
  48   /**
  49    * Create a new BufferImage.
  50    * Also a pixel buffer for image data is allocated.
  51    * Dali has ownership of the buffer.
  52    * For better performance and portability use power of two dimensions.
  53    * The maximum size of the image is limited by GL_MAX_TEXTURE_SIZE.
  54    * @param [in] width       image width in pixels
  55    * @param [in] height      image height in pixels
  56    * @param [in] pixelformat the pixel format (rgba 32 bit by default)
  57    * @param [in] releasePol  optionally relase memory when image is not visible on screen (default: keep image data until Image object is alive).
  58    */
  59   static BufferImagePtr New( unsigned int width,
  60                              unsigned int height,
  61                              Pixel::Format pixelformat,
  62                              ReleasePolicy releasePol = IMAGE_RELEASE_POLICY_DEFAULT );
  63
  64   /**
  65    * @deprecated Support for externally owned Pixel Buffers is due to be removed TBA. It is recommended that a BufferImage owned Buffer be used instead.
  66    *
  67    * @brief Create a new BufferImage, which uses external data source.
  68    *
  69    * Pixel buffer has to be allocated by application.
  70    * An internal copy is made of the Pixel Buffer, which can then be freed by the Application, unless if there will be a call to Update() later.
  71    * The buffer should only be freed when there is no chance of an Update() being called again.
  72    * Obtaining the buffer with GetBuffer() and altering the contents, then Update() will not work with externally owned buffers.
  73    * For better performance and portability use power of two dimensions.
  74    * The maximum size of the image is limited by GL_MAX_TEXTURE_SIZE.
  75    *
  76    * @param [in] pixBuf      pixel buffer. has to be allocated by application.
  77    * @param [in] width       image width in pixels
  78    * @param [in] height      image height in pixels
  79    * @param [in] pixelformat the pixel format (rgba 32 bit by default)
  80    * @param [in] stride      the internal stride of the pixelbuffer in pixels
  81    * @param [in] releasePol  optionally relase memory when image is not visible on screen (default: keep image data until Image object is alive).
  82    */
  83   static BufferImagePtr New( PixelBuffer* pixBuf,
  84                              unsigned int width,
  85                              unsigned int height,
  86                              Pixel::Format pixelformat,
  87                              unsigned int stride,
  88                              ReleasePolicy releasePol = IMAGE_RELEASE_POLICY_DEFAULT );
  89
  90   /**
  91    * Create a new BufferImage.
  92    * Also a pixel buffer for image data is allocated.
  93    * Dali has ownership of the buffer.
  94    * For better performance use power of two dimensions.
  95    * The maximum size of the image is limited by GL_MAX_TEXTURE_SIZE.
  96    * @param [in] width image width in pixels
  97    * @param [in] height image height in pixels
  98    * @param [in] pixelformat the pixel format (rgba 32 bit by default)
  99    * @param [in] releasePol optionally release memory when image is not visible on screen (default: keep image data until Image object is alive).
 100    */
 101   BufferImage(unsigned int width,
 102               unsigned int height,
 103               Pixel::Format pixelformat,
 104               ReleasePolicy releasePol = IMAGE_RELEASE_POLICY_DEFAULT);
 105
 106   /**
 107    * Create a new BufferImage, which uses external data source.
 108    * Pixel buffer has to be allocated by application.
 109    * An internal copy is made of the Pixel Buffer, which can then be freed by the Application, unless if there will be a call to Update() later.
 110    * The buffer should only be freed when there is no chance of Update() being called again.
 111    * Note: obtaining the buffer with GetBuffer(), writing changes, then Update() will cause any changes to be lost.
 112    * In this case, the BufferImage will update from the external buffer and so changes should be written there.
 113    * For better performance and portability use power of two dimensions.
 114    * The maximum size of the image is limited by GL_MAX_TEXTURE_SIZE.
 115    * @param [in] pixBuf      pixel buffer. has to be allocated by application.
 116    * @param [in] width       image width in pixels
 117    * @param [in] height      image height in pixels
 118    * @param [in] pixelformat the pixel format (rgba 32 bit by default)
 119    * @param [in] stride      the internal stride of the pixelbuffer in pixels
 120    * @param [in] releasePol  optionally relase memory when image is not visible on screen (default: keep image data until Image object is alive).
 121    */
 122   BufferImage(PixelBuffer* pixBuf,
 123               unsigned int width,
 124               unsigned int height,
 125               Pixel::Format pixelformat,
 126               unsigned int stride,
 127               ReleasePolicy releasePol = IMAGE_RELEASE_POLICY_DEFAULT);
 128
 129 protected:
 130   /**
 131    * A reference counted object may only be deleted by calling Unreference()
 132    */
 133   virtual ~BufferImage();
 134
 135 public:
 136   /**
 137    * Notify Dali that the contents of the buffer have changed.
 138    * @param [in] updateArea area that has changed in buffer. An empty rect means the whole buffer has changed.
 139    */
 140   void Update (RectArea& updateArea);
 141
 142   /**
 143    * @copydoc Dali::BufferImage::IsDataExternal
 144    */
 145   bool IsDataExternal() const;
 146
 147   /**
 148    * Returns the pixel buffer of the Image.
 149    * The application developer can write to the buffer.
 150    * Upload the modified contents with Update().
 151    * @return the pixel buffer
 152    */
 153   PixelBuffer* GetBuffer() const
 154   {
 155     return ( mExternalBuffer ? mExternalBuffer : mInternalBuffer );
 156   }
 157
 158   /**
 159    * Returns buffer size in bytes.
 160    * @return the buffer size in bytes
 161    */
 162   unsigned int GetBufferSize() const
 163   {
 164     return mBufferSize;
 165   }
 166
 167   /**
 168    * Returns buffer stride (in bytes).
 169    * @return the buffer stride
 170    */
 171   unsigned int GetBufferStride() const
 172   {
 173     return mByteStride;
 174   }
 175
 176   /**
 177    * Get the pixel format
 178    * @return The pixel format
 179    */
 180   Pixel::Format GetPixelFormat() const
 181   {
 182     return mPixelFormat;
 183   }
 184
 185   /**
 186    * @brief Upload pixel data to another resource at an offset
 187    *
 188    * @param destId ResourceId of the destination
 189    * @param xOffset x offset in the destination
 190    * @param yOffset y offset in the destination
 191    */
 192   void UploadBitmap( ResourceId destId, std::size_t xOffset, std::size_t yOffset );
 193
 194 protected: // From Image
 195   /**
 196    * @copydoc Dali::Internal::Image::Connect
 197    */
 198   virtual void Connect();
 199
 200   /**
 201    * @copydoc Dali::Internal::Image::Disconnect
 202    */
 203   virtual void Disconnect();
 204
 205 private:
 206
 207   void SetupBuffer( unsigned int width,
 208                     unsigned int height,
 209                     Pixel::Format pixelformat,
 210                     unsigned int byteStride,
 211                     ReleasePolicy releasePol );
 212
 213   void CreateHostBitmap();
 214
 215   void UploadArea( ResourceId destId, const RectArea& area );
 216
 217   void UpdateBufferArea( PixelBuffer* src, PixelBuffer* dest, const RectArea& area );
 218
 219 private:
 220
 221   PixelBuffer*                 mInternalBuffer;       ///< NULL if the data is supplied by an external buffer.
 222   PixelBuffer*                 mExternalBuffer;       ///< NULL if there is no external pixel data (this is never owned by BufferImage).
 223   ResourceClient*              mResourceClient;       ///< pointer to the resource client.
 224   uint32_t                     mBufferSize;           ///< size of the pixel buffer.
 225   uint32_t                     mByteStride;           ///< width of the pixel buffer in bytes.
 226   uint32_t                     mBytesPerPixel;        ///< width of a pixel in bytes.
 227   uint32_t                     mBufferWidth;          ///< cached pixel width of bitmap used for transport.
 228   Pixel::Format                mPixelFormat;          ///< pixel format of bitmap.
 229   ResourcePolicy::Discardable  mResourcePolicy;       ///< whether to discard the pixel buffer when removed from the stage or to retain the data.
 230 };
 231
 232 } // namespace Internal
 233
 234 /**
 235  * Helper methods for public API.
 236  */
 237 inline Internal::BufferImage& GetImplementation(Dali::BufferImage& image)
 238 {
 239   DALI_ASSERT_ALWAYS( image && "BufferImage handle is empty" );
 240
 241   BaseObject& handle = image.GetBaseObject();
 242
 243   return static_cast<Internal::BufferImage&>(handle);
 244 }
 245
 246 inline const Internal::BufferImage& GetImplementation(const Dali::BufferImage& image)
 247 {
 248   DALI_ASSERT_ALWAYS( image && "BufferImage handle is empty" );
 249
 250   const BaseObject& handle = image.GetBaseObject();
 251
 252   return static_cast<const Internal::BufferImage&>(handle);
 253 }
 254
 255 } // namespace Dali
 256
 257 #endif // __DALI_INTERNAL_BUFFER_IMAGE_H__