dali/integration-api/bitmap.h

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