dali/integration-api/bitmap.h

   1 #ifndef DALI_INTEGRATION_BITMAP_H
   2 #define DALI_INTEGRATION_BITMAP_H
   3
   4 /*
   5  * Copyright (c) 2019 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_CORE_API void ConvertToGlFormat(Pixel::Format pixelformat, unsigned& pixelDataType, unsigned& internalFormat);
  43
  44 class Bitmap;
  45 using BitmapPtr   = IntrusivePtr<Bitmap>;
  46 using PixelBuffer = uint8_t; ///< Pixel data buffers are composed of these
  47
  48 /**
  49  * Bitmap class.
  50  * An abstract container for image data.
  51  */
  52 class DALI_CORE_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 = nullptr );
  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                            uint32_t width,
  72                            uint32_t 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   uint32_t 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   uint32_t 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 uint32_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                                        uint32_t width,
 215                                        uint32_t height,
 216                                        uint32_t bufferWidth = 0,
 217                                        uint32_t 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                               uint32_t bufferSize,
 242                               uint32_t width,
 243                               uint32_t height,
 244                               uint32_t bufferWidth = 0,
 245                               uint32_t bufferHeight = 0) = 0;
 246     /**
 247      * Get the width of the buffer (stride)
 248      * @return The width of the buffer in pixels
 249      */
 250     virtual uint32_t GetBufferWidth() const = 0;
 251
 252     /**
 253      * Get the height of the buffer
 254      * @return The height of the buffer in pixels
 255      */
 256     virtual uint32_t 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 uint32_t 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   protected:
 272
 273     /**
 274      * Virtual destructor, no deletion through this interface
 275      */
 276     virtual ~PackedPixelsProfile() {}
 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 nullptr; }
 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 nullptr; }
 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 uint32_t numBytes ) = 0;
 314   protected:
 315
 316     /**
 317      * Virtual destructor, no deletion through this interface
 318      */
 319     virtual ~CompressedProfile() {}
 320   };
 321
 322   virtual const CompressedProfile* GetCompressedProfile() const { return nullptr; }
 323   virtual CompressedProfile* GetCompressedProfile() { return nullptr; }
 324   /**@}*/
 325
 326
 327   /**
 328    * Inform the bitmap that its pixel buffer is no longer required and can be
 329    * deleted to free up memory if the bitmap owns the buffer.
 330    */
 331   void DiscardBuffer();
 332
 333   /**
 334    * Check if the pixel buffer can be discarded
 335    * @return true if the pixel buffer can be discarded
 336    */
 337   bool IsDiscardable() const
 338   {
 339     return mDiscardable == ResourcePolicy::OWNED_DISCARD;
 340   }
 341
 342   /**
 343    * Delete the pixel buffer data
 344    */
 345   void DeletePixelBuffer();
 346
 347 protected:
 348
 349   /**
 350    * A reference counted object may only be deleted by calling Unreference()
 351    */
 352   virtual ~Bitmap();
 353
 354 protected:
 355
 356   uint32_t  mImageWidth;          ///< Image width in pixels
 357   uint32_t  mImageHeight;         ///< Image height in pixels
 358   Pixel::Format mPixelFormat;         ///< Pixel format
 359   bool          mHasAlphaChannel;   ///< Whether the image has an alpha channel
 360   bool          mAlphaChannelUsed;  ///< Whether the alpha channel is used in case the image owns one.
 361   PixelBuffer*  mData;            ///< Raw pixel data
 362
 363 private:
 364
 365   ResourcePolicy::Discardable mDiscardable; ///< Should delete the buffer when discard buffer is called.
 366
 367   Bitmap(const Bitmap& other);  ///< defined private to prevent use
 368   Bitmap& operator = (const Bitmap& other); ///< defined private to prevent use
 369
 370   // Changes scope, should be at end of class
 371   DALI_LOG_OBJECT_STRING_DECLARATION;
 372 };
 373
 374 } // namespace Integration
 375
 376 } // namespace Dali
 377
 378 #endif // DALI_INTEGRATION_BITMAP_H