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 // EXTERNAL INCLUDES
  22 #include <stdint.h> // for uint32_t
  23
  24 // INTERNAL INCLUDES
  25 #include <dali/integration-api/bitmap.h> // For Integration::BitmapPtr
  26 #include <dali/public-api/object/ref-object.h>
  27 #include <dali/internal/event/images/image-impl.h>
  28 #include <dali/public-api/images/image.h>
  29 #include <dali/public-api/images/buffer-image.h>
  30
  31 namespace Dali
  32 {
  33
  34 namespace Internal
  35 {
  36
  37 class BufferImage;
  38 typedef IntrusivePtr<BufferImage> BufferImagePtr;
  39
  40 class ResourceManager;
  41
  42 /**
  43  * BufferImage represents an image resource that can be added to actors etc.
  44  * Its pixel buffer data is provided by the application developer.
  45  * Pixel buffer memory allocation can be handled by dali or application.
  46  */
  47 class BufferImage : public Image
  48 {
  49 public:
  50   /**
  51    * Create a new BufferImage.
  52    * Also a pixel buffer for image data is allocated.
  53    * Dali has ownership of the buffer.
  54    * For better performance and portability use power of two dimensions.
  55    * The maximum size of the image is limited by GL_MAX_TEXTURE_SIZE.
  56    * @param [in] width       image width in pixels
  57    * @param [in] height      image height in pixels
  58    * @param [in] pixelformat the pixel format (rgba 32 bit by default)
  59    */
  60   static BufferImagePtr New( unsigned int width,
  61                              unsigned int height,
  62                              Pixel::Format pixelformat );
  63
  64   /**
  65    * @DEPRECATED_1_1.5. 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    */
  82   static BufferImagePtr New( PixelBuffer* pixBuf,
  83                              unsigned int width,
  84                              unsigned int height,
  85                              Pixel::Format pixelformat,
  86                              unsigned int stride );
  87
  88   /**
  89    * Create a new BufferImage.
  90    * Also a pixel buffer for image data is allocated.
  91    * Dali has ownership of the buffer.
  92    * For better performance use power of two dimensions.
  93    * The maximum size of the image is limited by GL_MAX_TEXTURE_SIZE.
  94    * @param [in] width image width in pixels
  95    * @param [in] height image height in pixels
  96    * @param [in] pixelformat the pixel format (rgba 32 bit by default)
  97    */
  98   BufferImage(unsigned int width,
  99               unsigned int height,
 100               Pixel::Format pixelformat );
 101
 102   /**
 103    * Create a new BufferImage, which uses external data source.
 104    * Pixel buffer has to be allocated by application.
 105    * 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.
 106    * The buffer should only be freed when there is no chance of Update() being called again.
 107    * Note: obtaining the buffer with GetBuffer(), writing changes, then Update() will cause any changes to be lost.
 108    * In this case, the BufferImage will update from the external buffer and so changes should be written there.
 109    * For better performance and portability use power of two dimensions.
 110    * The maximum size of the image is limited by GL_MAX_TEXTURE_SIZE.
 111    * @param [in] pixBuf      pixel buffer. has to be allocated by application.
 112    * @param [in] width       image width in pixels
 113    * @param [in] height      image height in pixels
 114    * @param [in] pixelformat the pixel format (rgba 32 bit by default)
 115    * @param [in] stride      the internal stride of the pixelbuffer in pixels
 116    */
 117   BufferImage(PixelBuffer* pixBuf,
 118               unsigned int width,
 119               unsigned int height,
 120               Pixel::Format pixelformat,
 121               unsigned int stride );
 122
 123 protected:
 124   /**
 125    * A reference counted object may only be deleted by calling Unreference()
 126    */
 127   virtual ~BufferImage();
 128
 129 public:
 130   /**
 131    * Notify Dali that the contents of the buffer have changed.
 132    * @param [in] updateArea area that has changed in buffer. An empty rect means the whole buffer has changed.
 133    */
 134   void Update( const RectArea& updateArea);
 135
 136   /**
 137    * @copydoc Dali::BufferImage::IsDataExternal
 138    */
 139   bool IsDataExternal() const;
 140
 141   /**
 142    * Returns the pixel buffer of the Image.
 143    * The application developer can write to the buffer.
 144    * Upload the modified contents with Update().
 145    * @return the pixel buffer
 146    */
 147   PixelBuffer* GetBuffer() const
 148   {
 149     return ( mExternalBuffer ? mExternalBuffer : mInternalBuffer );
 150   }
 151
 152   /**
 153    * Returns buffer size in bytes.
 154    * @return the buffer size in bytes
 155    */
 156   unsigned int GetBufferSize() const
 157   {
 158     return mBufferSize;
 159   }
 160
 161   /**
 162    * Returns buffer stride (in bytes).
 163    * @return the buffer stride
 164    */
 165   unsigned int GetBufferStride() const
 166   {
 167     return mByteStride;
 168   }
 169
 170   /**
 171    * Get the pixel format
 172    * @return The pixel format
 173    */
 174   Pixel::Format GetPixelFormat() const
 175   {
 176     return mPixelFormat;
 177   }
 178
 179 private:
 180
 181   void SetupBuffer( unsigned int width,
 182                     unsigned int height,
 183                     Pixel::Format pixelformat,
 184                     unsigned int byteStride );
 185
 186   void UploadArea( const RectArea& area );
 187
 188   void UpdateBufferArea( PixelBuffer* src, PixelBuffer* dest, const RectArea& area );
 189
 190 private:
 191
 192   PixelBuffer*                 mInternalBuffer;       ///< NULL if the data is supplied by an external buffer.
 193   PixelBuffer*                 mExternalBuffer;       ///< NULL if there is no external pixel data (this is never owned by BufferImage).
 194   uint32_t                     mBufferSize;           ///< size of the pixel buffer.
 195   uint32_t                     mByteStride;           ///< width of the pixel buffer in bytes.
 196   uint32_t                     mBytesPerPixel;        ///< width of a pixel in bytes.
 197   uint32_t                     mBufferWidth;          ///< cached pixel width of bitmap used for transport.
 198   Pixel::Format                mPixelFormat;          ///< pixel format of bitmap.
 199   ResourcePolicy::Discardable  mResourcePolicy;       ///< whether to discard the pixel buffer when removed from the stage or to retain the data.
 200 };
 201
 202 } // namespace Internal
 203
 204 /**
 205  * Helper methods for public API.
 206  */
 207 inline Internal::BufferImage& GetImplementation(Dali::BufferImage& image)
 208 {
 209   DALI_ASSERT_ALWAYS( image && "BufferImage handle is empty" );
 210
 211   BaseObject& handle = image.GetBaseObject();
 212
 213   return static_cast<Internal::BufferImage&>(handle);
 214 }
 215
 216 inline const Internal::BufferImage& GetImplementation(const Dali::BufferImage& image)
 217 {
 218   DALI_ASSERT_ALWAYS( image && "BufferImage handle is empty" );
 219
 220   const BaseObject& handle = image.GetBaseObject();
 221
 222   return static_cast<const Internal::BufferImage&>(handle);
 223 }
 224
 225 } // namespace Dali
 226
 227 #endif // __DALI_INTERNAL_BUFFER_IMAGE_H__