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