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