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    * Create a new instance of a Bitmap with the profile asked for.
  90    * @return Pointer to created Bitmap subclass. Clients should immediately
  91    * wrap this in a reference-counting smart pointer or store it in a similarly
  92    * automatic owning collection.
  93    * @param[in] profile Defines required features of the bitmap (\sa Profile).
  94    * @param[in] managePixelBuffer If true, the bitmap object owns it's own
  95    * buffer of pixel data and can delete it, else the lifetime of the pixel
  96    * buffer is managed by an external component and is guaranteed to remain
  97    * dereferenceable at least as long as the Bitmap remains alive.
  98    **/
  99   static Bitmap* New(Profile profile, bool managePixelBuffer);
 100
 101   /** \name GeneralFeatures
 102    * Features that are generic between profiles. */
 103   /**@{*/
 104
 105   /**
 106    * Get the width of the image
 107    * @return The width of the image
 108    */
 109   unsigned int GetImageWidth() const
 110   {
 111     return mImageWidth;
 112   }
 113
 114   /**
 115    * Get the height of the image
 116    * @return The height of the image
 117    */
 118   unsigned int GetImageHeight() const
 119   {
 120     return mImageHeight;
 121   }
 122
 123   /**
 124    * Get the pixel format
 125    * @return The pixel format
 126    */
 127   Pixel::Format GetPixelFormat() const
 128   {
 129     return mPixelFormat;
 130   }
 131
 132   /**
 133    * Get the pixel buffer
 134    * @return The buffer. You can modify its contents.
 135    * @sa ReserveBuffer GetBufferSize
 136    */
 137   virtual PixelBuffer* GetBuffer()
 138   {
 139     DALI_ASSERT_DEBUG(mData != NULL);
 140     return mData;
 141   }
 142
 143   /**
 144    * Get the pixel buffer size in bytes
 145    * @return The buffer size in bytes.
 146    * @sa ReserveBuffer GetBuffer
 147    */
 148   virtual size_t GetBufferSize() const = 0;
 149
 150   /**
 151    * Queries if the bitmap has an alpha channel
 152    * @return true if there is an alpha channel
 153    */
 154   bool HasAlphaChannel() const
 155   {
 156     return mHasAlphaChannel;
 157   }
 158
 159   /**
 160    * Queries if the bitmap has any transparent data
 161    * @return true if the bitmap has alpha data
 162    */
 163   bool IsFullyOpaque() const
 164   {
 165     // check pixel format for alpha channel
 166     return !(HasAlphaChannel() && mAlphaChannelUsed);
 167   }
 168
 169   /**@}*/ ///< End of generic features
 170
 171
 172   /** \name PackedPixelsProfile
 173    * Features that are active only if the Bitmap was created with a
 174    * BITMAP_2D_PACKED_PIXELS profile. */
 175   /**@{*/
 176
 177   class PackedPixelsProfile
 178   {
 179   public:
 180
 181     /**
 182      * (Re-)Allocate pixel buffer for the Bitmap. Any previously allocated pixel buffer is deleted.
 183      * Dali has ownership of the buffer, but its contents can be modified.
 184      * Bitmap stores given size information about the image.
 185      * @pre bufferWidth, bufferHeight have to be power of two
 186      * @param[in] pixelFormat   pixel format
 187      * @param[in] width         Image width in pixels
 188      * @param[in] height        Image height in pixels
 189      * @param[in] bufferWidth   Buffer width (stride) in pixels
 190      * @param[in] bufferHeight  Buffer height in pixels
 191      * @return pixel buffer pointer
 192      */
 193     virtual PixelBuffer* ReserveBuffer(Pixel::Format pixelFormat,
 194                                        unsigned int width,
 195                                        unsigned int height,
 196                                        unsigned int bufferWidth = 0,
 197                                        unsigned int bufferHeight = 0) = 0;
 198
 199     /**
 200      * Assign a pixel buffer. Any previously allocated pixel buffer is deleted.
 201      * Dali has ownership of the buffer, but it iss allowable to modify its
 202      * contents after it is assigned, but before it is used.
 203      * Bitmap stores the provided size information about the image.
 204      *
 205      * The buffer must have been allocated with the C++ array new operator, not
 206      * with malloc or as a local or static object. The precise form is as follows:
 207      *
 208      *    PixelBuffer * buffer = new PixelBuffer[bufSize];
 209      *
 210      * @pre bufferWidth, bufferHeight have to be power of two
 211      * @param[in] pixelFormat   pixel format
 212      * @param[in] buffer        the pixel buffer
 213      * @param[in] bufferSize    size of the pixel buffer
 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      */
 219     virtual void AssignBuffer(Pixel::Format pixelFormat,
 220                               PixelBuffer* buffer,
 221                               std::size_t bufferSize,
 222                               unsigned int width,
 223                               unsigned int height,
 224                               unsigned int bufferWidth = 0,
 225                               unsigned int bufferHeight = 0) = 0;
 226     /**
 227      * Get the width of the buffer (stride)
 228      * @return The width of the buffer in pixels
 229      */
 230     virtual unsigned int GetBufferWidth() const = 0;
 231
 232     /**
 233      * Get the height of the buffer
 234      * @return The height of the buffer in pixels
 235      */
 236     virtual unsigned int GetBufferHeight() const = 0;
 237
 238     /**
 239      * Get the pixel buffer stride.
 240      * @return The buffer stride (in bytes) if this is bitmap of non-compressed
 241      * packed pixels for which a stride is meaningful or 0 otherwise.
 242      */
 243     virtual unsigned int GetBufferStride() const = 0;
 244
 245     /**
 246      * Check the bitmap data and test whether it has any transparent pixels.
 247      * This property can then be tested for with IsFullyOpaque().
 248      */
 249     virtual void TestForTransparency() = 0;
 250   };
 251
 252   /**
 253    * Get interface to features that are active only if the Bitmap was created
 254    * with a BITMAP_2D_PACKED_PIXELS profile. */
 255   virtual const PackedPixelsProfile* GetPackedPixelsProfile() const { return 0; }
 256   /**
 257    * Get interface to features that are active only if the Bitmap was created
 258    * with a BITMAP_2D_PACKED_PIXELS profile. */
 259   virtual PackedPixelsProfile* GetPackedPixelsProfile() { return 0; }
 260
 261   /**@}*/ ///< End of packed pixel features.
 262
 263
 264   /** \name CompressedProfile
 265    * Features that only apply to opaque/compressed formats. */
 266   /**@{*/
 267
 268   class CompressedProfile
 269   {
 270   public:
 271     /**
 272      * (Re-)Allocate pixel buffer for the Bitmap. Any previously allocated pixel buffer
 273      * is deleted.
 274      * Dali has ownership of the buffer, and contents are opaque and immutable.
 275      * Bitmap stores given size information about the image which the client is assumed
 276      * to have retrieved from out-of-band image metadata.
 277      * @param[in] pixelFormat   pixel format
 278      * @param[in] width         Image width in pixels
 279      * @param[in] height        Image height in pixels
 280      * @param[in] bufferSize    Buffer size in bytes
 281      * @return pixel buffer pointer
 282      */
 283     virtual PixelBuffer* ReserveBufferOfSize( Pixel::Format pixelFormat,
 284                                        const unsigned width,
 285                                        const unsigned height,
 286                                        const size_t numBytes ) = 0;
 287   };
 288
 289   virtual const CompressedProfile* GetCompressedProfile() const { return 0; }
 290   virtual CompressedProfile* GetCompressedProfile() { return 0; }
 291   /**@}*/
 292
 293
 294   /**
 295    * Inform the bitmap that its pixel buffer is no longer required and can be
 296    * deleted to free up memory if the bitmap owns the buffer.
 297    */
 298   void DiscardBuffer();
 299
 300   /**
 301    * @return True if the buffer of pixel data is owned by this Bitmap itself,
 302    * or false if the buffer is owned by an external component.
 303    **/
 304   bool BufferIsOwned() const
 305   {
 306     return mDataIsOwned;
 307   }
 308
 309  /**
 310    * Transfer ownership of the pixel buffer to the calling function.
 311    * @post bitmaps pixel data is set to NULL
 312    * @return the bitmaps pixel buffer
 313    */
 314   PixelBuffer* ReleaseBuffer();
 315   /**
 316    * Delete the pixel buffer data
 317    */
 318   void DeletePixelBuffer();
 319
 320   /**
 321    * A reference counted object may only be deleted by calling Unreference()
 322    */
 323   virtual ~Bitmap();
 324
 325 protected:
 326
 327   unsigned int  mImageWidth;          ///< Image width in pixels
 328   unsigned int  mImageHeight;         ///< Image height in pixels
 329   Pixel::Format mPixelFormat;         ///< Pixel format
 330   bool          mHasAlphaChannel;   ///< Whether the image has an alpha channel
 331   bool          mAlphaChannelUsed;  ///< Whether the alpha channel is used in case the image owns one.
 332   PixelBuffer*  mData;            ///< Raw pixel data
 333
 334 private:
 335
 336   bool          mDataIsOwned;     ///< Should delete the buffer when discard buffer is called.
 337
 338   Bitmap(const Bitmap& other);  ///< defined private to prevent use
 339   Bitmap& operator = (const Bitmap& other); ///< defined private to prevent use
 340
 341   // Changes scope, should be at end of class
 342   DALI_LOG_OBJECT_STRING_DECLARATION;
 343 };
 344
 345 } // namespace Integration
 346
 347 } // namespace Dali
 348
 349 #endif // __DALI_INTEGRATION_BITMAP_H__