dali/integration-api/bitmap.h

   1 #ifndef __DALI_INTEGRATION_BITMAP_H__
   2 #define __DALI_INTEGRATION_BITMAP_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 // EXTERNAL INCLUDES
  22
  23 // INTERNAL INCLUDES
  24 #include <dali/integration-api/debug.h>
  25 #include <dali/public-api/common/intrusive-ptr.h>
  26 #include <dali/public-api/images/pixel.h>
  27 #include <dali/public-api/object/ref-object.h>
  28 #include <dali/integration-api/resource-policies.h>
  29
  30 namespace Dali
  31 {
  32
  33 namespace Integration
  34 {
  35
  36 class Bitmap;
  37 typedef IntrusivePtr<Bitmap>    BitmapPtr;
  38 typedef unsigned char                 PixelBuffer;  ///< Pixel data buffers are composed of these
  39
  40 /**
  41  * Bitmap class.
  42  * An abstract container for image data.
  43  */
  44 class DALI_IMPORT_API Bitmap : public Dali::RefObject
  45 {
  46 protected:
  47
  48   /**
  49    * Constructor
  50    * Use the static function Bitmap::New() to create instances.
  51    * @param[in] discardable Flag to tell the bitmap if it can delete the buffer with the pixel data.
  52    * @param[in] pixBuf External buffer of pixel data or null.
  53    */
  54   Bitmap( ResourcePolicy::Discardable discardable = ResourcePolicy::OWNED_RETAIN, Dali::Integration::PixelBuffer* pixBuf = 0 );
  55
  56   /**
  57    * Initializes internal class members
  58    * @param[in] pixelFormat   pixel format
  59    * @param[in] width         Image width in pixels
  60    * @param[in] height        Image height in pixels
  61    */
  62   void Initialize(Pixel::Format pixelFormat,
  63                            unsigned int width,
  64                            unsigned int height);
  65
  66
  67 public:
  68   /** Defines the characteristics of the Bitmap returned from the factory
  69    *  function. */
  70   enum Profile
  71   {
  72     /** A 2D array of pixels where each pixel is a whole number of bytes
  73      * and each scanline of the backing memory buffer may have additional
  74      * bytes off the right edge if requested, and there may be additional
  75      * scanlines past the bottom of the image in the buffer if requested.*/
  76     BITMAP_2D_PACKED_PIXELS,
  77     /** The data for the bitmap is buffered in an opaque form.*/
  78     BITMAP_COMPRESSED
  79   };
  80
  81   enum ReleaseFunction
  82   {
  83     FREE,          ///< Use free function to release the buffer
  84     DELETE_ARRAY,  ///< Use delete[] operator to release the buffer
  85   };
  86
  87   /**
  88    * Create a new instance of a Bitmap with the required profile.
  89    * @return Pointer to created Bitmap subclass. Clients should immediately
  90    * wrap this in a reference-counting smart pointer or store it in a similarly
  91    * automatic owning collection.
  92    * @param[in] profile Defines required features of the bitmap (\sa Profile).
  93    * @param[in] discardable OWNED_DISCARD means that the data is owned by bitmap,
  94    * and may released away after uploading to GPU.
  95    * OWNED_RETAIN means that the data is owned and must be kept in CPU memory
  96    * e.g. for an image that cannot be reloaded from disk.
  97    */
  98   static Bitmap* New( Profile profile, ResourcePolicy::Discardable discardable );
  99
 100   /** \name GeneralFeatures
 101    * Features that are generic between profiles. */
 102   /**@{*/
 103
 104   /**
 105    * Get the width of the image
 106    * @return The width of the image
 107    */
 108   unsigned int GetImageWidth() const
 109   {
 110     return mImageWidth;
 111   }
 112
 113   /**
 114    * Get the height of the image
 115    * @return The height of the image
 116    */
 117   unsigned int GetImageHeight() const
 118   {
 119     return mImageHeight;
 120   }
 121
 122   /**
 123    * Get the pixel format
 124    * @return The pixel format
 125    */
 126   Pixel::Format GetPixelFormat() const
 127   {
 128     return mPixelFormat;
 129   }
 130
 131   /**
 132    * Get the pixel buffer if it's present.
 133    * @return The buffer if present, or NULL if there is no pixel buffer.
 134    * You can modify its contents.
 135    * @sa ReserveBuffer GetBufferSize
 136    */
 137   virtual PixelBuffer* GetBuffer()
 138   {
 139     return mData;
 140   }
 141
 142   /**
 143    * Get the pixel buffer if it's present and take over the ownership.
 144    * @note With this function called, the bitmap loses the ownership and is no longer responsible for the release of pixel buffer.
 145    * @return The raw pointer pointing to the pixel buffer
 146    */
 147   PixelBuffer* GetBufferOwnership();
 148
 149   /**
 150    * Get the pixel buffer size in bytes
 151    * @return The buffer size in bytes.
 152    * @sa ReserveBuffer GetBuffer
 153    */
 154   virtual size_t GetBufferSize() const = 0;
 155
 156   /**
 157    * Queries if the bitmap has an alpha channel
 158    * @return true if there is an alpha channel
 159    */
 160   bool HasAlphaChannel() const
 161   {
 162     return mHasAlphaChannel;
 163   }
 164
 165   /**
 166    * Queries if the bitmap has any transparent data
 167    * @return true if the bitmap has alpha data
 168    */
 169   bool IsFullyOpaque() const
 170   {
 171     // check pixel format for alpha channel
 172     return !(HasAlphaChannel() && mAlphaChannelUsed);
 173   }
 174
 175   /**
 176    * Returns which release function has to be called to release the data in the bitmap
 177    * @return FREE if memory has been allocated with malloc DELETE_ARRAY if memory has been allocated with new
 178    */
 179   virtual ReleaseFunction GetReleaseFunction() = 0;
 180
 181   /**@}*/ ///< End of generic features
 182
 183
 184   /** \name PackedPixelsProfile
 185    * Features that are active only if the Bitmap was created with a
 186    * BITMAP_2D_PACKED_PIXELS profile. */
 187   /**@{*/
 188
 189   class PackedPixelsProfile
 190   {
 191   public:
 192
 193     /**
 194      * (Re-)Allocate pixel buffer for the Bitmap. Any previously allocated pixel buffer is deleted.
 195      * Dali has ownership of the buffer, but its contents can be modified.
 196      * Bitmap stores given size information about the image.
 197      * @pre bufferWidth, bufferHeight have to be power of two
 198      * @param[in] pixelFormat   pixel format
 199      * @param[in] width         Image width in pixels
 200      * @param[in] height        Image height in pixels
 201      * @param[in] bufferWidth   Buffer width (stride) in pixels
 202      * @param[in] bufferHeight  Buffer height in pixels
 203      * @return pixel buffer pointer
 204      */
 205     virtual PixelBuffer* ReserveBuffer(Pixel::Format pixelFormat,
 206                                        unsigned int width,
 207                                        unsigned int height,
 208                                        unsigned int bufferWidth = 0,
 209                                        unsigned int bufferHeight = 0) = 0;
 210
 211     /**
 212      * Assign a pixel buffer. Any previously allocated pixel buffer is deleted.
 213      * Dali has ownership of the buffer, but it iss allowable to modify its
 214      * contents after it is assigned, but before it is used.
 215      * Bitmap stores the provided size information about the image.
 216      *
 217      * The buffer must have been allocated with the C++ array new operator, not
 218      * with malloc or as a local or static object. The precise form is as follows:
 219      *
 220      *    PixelBuffer * buffer = new PixelBuffer[bufSize];
 221      *
 222      * @pre bufferWidth, bufferHeight have to be power of two
 223      * @param[in] pixelFormat   pixel format
 224      * @param[in] buffer        the pixel buffer
 225      * @param[in] bufferSize    size of the pixel buffer
 226      * @param[in] width         Image width in pixels
 227      * @param[in] height        Image height in pixels
 228      * @param[in] bufferWidth   Buffer width (stride) in pixels
 229      * @param[in] bufferHeight  Buffer height in pixels
 230      */
 231     virtual void AssignBuffer(Pixel::Format pixelFormat,
 232                               PixelBuffer* buffer,
 233                               std::size_t bufferSize,
 234                               unsigned int width,
 235                               unsigned int height,
 236                               unsigned int bufferWidth = 0,
 237                               unsigned int bufferHeight = 0) = 0;
 238     /**
 239      * Get the width of the buffer (stride)
 240      * @return The width of the buffer in pixels
 241      */
 242     virtual unsigned int GetBufferWidth() const = 0;
 243
 244     /**
 245      * Get the height of the buffer
 246      * @return The height of the buffer in pixels
 247      */
 248     virtual unsigned int GetBufferHeight() const = 0;
 249
 250     /**
 251      * Get the pixel buffer stride.
 252      * @return The buffer stride (in bytes) if this is bitmap of non-compressed
 253      * packed pixels for which a stride is meaningful or 0 otherwise.
 254      */
 255     virtual unsigned int GetBufferStride() const = 0;
 256
 257     /**
 258      * Check the bitmap data and test whether it has any transparent pixels.
 259      * This property can then be tested for with IsFullyOpaque().
 260      */
 261     virtual void TestForTransparency() = 0;
 262
 263   protected:
 264
 265     /**
 266      * Virtual destructor, no deletion through this interface
 267      */
 268     virtual ~PackedPixelsProfile() {}
 269   };
 270
 271   /**
 272    * Get interface to features that are active only if the Bitmap was created
 273    * with a BITMAP_2D_PACKED_PIXELS profile. */
 274   virtual const PackedPixelsProfile* GetPackedPixelsProfile() const { return 0; }
 275   /**
 276    * Get interface to features that are active only if the Bitmap was created
 277    * with a BITMAP_2D_PACKED_PIXELS profile. */
 278   virtual PackedPixelsProfile* GetPackedPixelsProfile() { return 0; }
 279
 280   /**@}*/ ///< End of packed pixel features.
 281
 282
 283   /** \name CompressedProfile
 284    * Features that only apply to opaque/compressed formats. */
 285   /**@{*/
 286
 287   class CompressedProfile
 288   {
 289   public:
 290     /**
 291      * (Re-)Allocate pixel buffer for the Bitmap. Any previously allocated pixel buffer
 292      * is deleted.
 293      * Dali has ownership of the buffer, and contents are opaque and immutable.
 294      * Bitmap stores given size information about the image which the client is assumed
 295      * to have retrieved from out-of-band image metadata.
 296      * @param[in] pixelFormat   pixel format
 297      * @param[in] width         Image width in pixels
 298      * @param[in] height        Image height in pixels
 299      * @param[in] bufferSize    Buffer size in bytes
 300      * @return pixel buffer pointer
 301      */
 302     virtual PixelBuffer* ReserveBufferOfSize( Pixel::Format pixelFormat,
 303                                        const unsigned width,
 304                                        const unsigned height,
 305                                        const size_t numBytes ) = 0;
 306   protected:
 307
 308     /**
 309      * Virtual destructor, no deletion through this interface
 310      */
 311     virtual ~CompressedProfile() {}
 312   };
 313
 314   virtual const CompressedProfile* GetCompressedProfile() const { return 0; }
 315   virtual CompressedProfile* GetCompressedProfile() { return 0; }
 316   /**@}*/
 317
 318
 319   /**
 320    * Inform the bitmap that its pixel buffer is no longer required and can be
 321    * deleted to free up memory if the bitmap owns the buffer.
 322    */
 323   void DiscardBuffer();
 324
 325   /**
 326    * Check if the pixel buffer can be discarded
 327    * @return true if the pixel buffer can be discarded
 328    */
 329   bool IsDiscardable() const
 330   {
 331     return mDiscardable == ResourcePolicy::OWNED_DISCARD;
 332   }
 333
 334   /**
 335    * Delete the pixel buffer data
 336    */
 337   void DeletePixelBuffer();
 338
 339 protected:
 340
 341   /**
 342    * A reference counted object may only be deleted by calling Unreference()
 343    */
 344   virtual ~Bitmap();
 345
 346 protected:
 347
 348   unsigned int  mImageWidth;          ///< Image width in pixels
 349   unsigned int  mImageHeight;         ///< Image height in pixels
 350   Pixel::Format mPixelFormat;         ///< Pixel format
 351   bool          mHasAlphaChannel;   ///< Whether the image has an alpha channel
 352   bool          mAlphaChannelUsed;  ///< Whether the alpha channel is used in case the image owns one.
 353   PixelBuffer*  mData;            ///< Raw pixel data
 354
 355 private:
 356
 357   ResourcePolicy::Discardable mDiscardable; ///< Should delete the buffer when discard buffer is called.
 358
 359   Bitmap(const Bitmap& other);  ///< defined private to prevent use
 360   Bitmap& operator = (const Bitmap& other); ///< defined private to prevent use
 361
 362   // Changes scope, should be at end of class
 363   DALI_LOG_OBJECT_STRING_DECLARATION;
 364 };
 365
 366 } // namespace Integration
 367
 368 } // namespace Dali
 369
 370 #endif // __DALI_INTEGRATION_BITMAP_H__