dali/integration-api/bitmap.h

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