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