dali/integration-api/image-data.h

   1 #ifndef __DALI_INTEGRATION_IMAGE_DATA_H__
   2 #define __DALI_INTEGRATION_IMAGE_DATA_H__
   3
   4 //
   5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
   6 //
   7 // Licensed under the Flora License, Version 1.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://floralicense.org/license/
  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 // INTERNAL INCLUDES
  21 #include <dali/integration-api/debug.h> // For DALI_LOG_OBJECT_STRING_DECLARATION
  22 #include <dali/public-api/object/ref-object.h>
  23 #include <dali/public-api/common/intrusive-ptr.h>
  24 #include <dali/public-api/images/pixel.h>
  25
  26 // EXTERNAL INCLUDES
  27 #include <stdint.h>
  28
  29 namespace Dali
  30 {
  31
  32 namespace Integration
  33 {
  34
  35 class ImageData;
  36 typedef IntrusivePtr<ImageData> ImageDataPtr;
  37
  38 typedef uint8_t PixelBuffer;
  39
  40 /**
  41  * Used to avoid accidentally mixing the order of parameters where some are uint
  42  * dimensions and one is a buffer size.
  43  **/
  44 class BufferSize
  45 {
  46 public:
  47   explicit BufferSize(size_t size) : bufferSize( size )
  48   { }
  49   operator size_t() const { return bufferSize; }
  50   const size_t bufferSize;
  51 };
  52
  53 /**
  54  * @brief A simple container for image data.
  55  *
  56  * Just a pointer to a buffer and some minimal metadata. It always owns the
  57  * buffer of image data that it points to until it is destroyed or the buffer
  58  * is released with ReleaseImageBuffer().
  59  *
  60  * The width and height stored are the logical image values. Compressed formats
  61  * such as ETC group pixels into blocks (ETC = 4*4) and these logical width and
  62  * height may indicate, for example for ETC, that 1 to 3 pixels in the rightmost
  63  * column of blocks or bottom row are ignored for rendering.
  64  * For simple uncompressed images, the buffer is exactly width * height *
  65  * bytes-per-pixel in size with no spare bytes at right or bottom edge.
  66  */
  67 class DALI_IMPORT_API ImageData : public Dali::RefObject
  68 {
  69 public:
  70   /**
  71    * @brief Three values for the information about the alpha values in the
  72    * pixels.
  73    *
  74    * Alpha in pixels with the channel can be undetermined, it can be all-ones,
  75    * or it can have at least one pixel that is translucent with an alpha < 1.0.
  76    **/
  77   enum AlphaUsage
  78   {
  79     /** Alpha not yet been tested.*/
  80     ALPHA_USAGE_UNDETERMINED,
  81     /** Alpha == 1.0 in every pixel.*/
  82     ALPHA_USAGE_ALL_OPAQUE,
  83     /** Alpha < 1.0 in at least one pixel.*/
  84     ALPHA_USAGE_SOME_TRANSLUCENT
  85   };
  86
  87 private:
  88
  89   /**
  90    * Construct an instance and allocate a buffer owned by it.
  91    * @param[in] numBytes The number of bytes to allocate to hold the image data.
  92    * @param[in] imageWidth The width in pixels of the image.
  93    * @param[in] imageHeight The height in pixels of the image.
  94    * @param[in] pixelFormat The format of the image data in the buffer.
  95    */
  96   ImageData( const size_t numBytes, const unsigned imageWidth, const unsigned imageHeight, const Pixel::Format pixelFormat );
  97
  98   /**
  99    * Construct an instance and have it take ownership of the buffer passed in.
 100    * @param[in] imageBuffer A buffer of pixel data that should have been allocated using <code>new uint8_t[]</code>.
 101    * @param[in] numBytes The number of bytes in the buffer pointed to by imageBuffer.
 102    * @param[in] imageWidth The width in pixels of the image.
 103    * @param[in] imageHeight The height in pixels of the image.
 104    * @param[in] pixelFormat The format of the image data in the buffer.
 105    */
 106   ImageData( uint8_t * const imageBuffer, const size_t numBytes, const unsigned imageWidth, const unsigned imageHeight, const Pixel::Format pixelFormat );
 107
 108   ~ImageData();
 109
 110 public:
 111
 112   /** Allocate and initialize a fresh ImageData object pointing at a new buffer,
 113    * returning a smart pointer owning it.
 114    * @note Clients can alternatively use the helper function NewBitmapImageData() to
 115    * calculate the buffer size from other parameters if the image data represents
 116    * a bitmap (a 2d grid of addressable pixels).
 117    * @param[in] numBytes The number of bytes to allocate to hold the image data.
 118    * @param[in] imageWidth The width in pixels of the image.
 119    * @param[in] imageHeight The height in pixels of the image.
 120    * @param[in] pixelFormat The format of the image data in the buffer.
 121    **/
 122   static ImageDataPtr New( const BufferSize numBytes, unsigned imageWidth, unsigned imageHeight, Pixel::Format pixelFormat );
 123
 124   /** Allocate and initialise a fresh ImageData object, taking ownership of the
 125    * buffer passed in.
 126    * @param[in] imageBuffer A block of memory allocated with
 127    * <code>new uint8_t[]</code>. <em>This is owned by the new ImageData instance
 128    * on successful return and should be forgotten by the caller</em>.
 129    * @param[in] numBytes The number of bytes in the buffer pointed to by imageBuffer.
 130    * @param[in] imageWidth The width in pixels of the image.
 131    * @param[in] imageHeight The height in pixels of the image.
 132    * @param[in] pixelFormat The format of the image data in the buffer.
 133    **/
 134   static ImageDataPtr New( uint8_t * const imageBuffer, const BufferSize numBytes, unsigned imageWidth, unsigned imageHeight, Pixel::Format pixelFormat );
 135
 136   /** Access the buffer of image data. */
 137   const uint8_t * GetBuffer() const { return mData; }
 138
 139   /** Access the buffer of image data. */
 140   uint8_t * GetBuffer() { return mData; }
 141
 142   /**
 143    * Pass ownership of the buffer of pixel-level data that this instance
 144    * currently owns to the caller, and forget about the buffer here as a
 145    * side effect.
 146    * @returns A pointer to the underlying buffer of pixel-level image data.
 147    * The caller takes ownership of the buffer and is responsible for calling
 148    * delete[] on it eventually.
 149    **/
 150   uint8_t * ReleaseImageBuffer() { uint8_t * const data = mData; mData = 0; return data; }
 151
 152   /**
 153    * @brief Get whether the alpha channel in the pixels is used.
 154    */
 155   AlphaUsage GetAlphaUsage() const { return mAlphaChannelUsed; }
 156
 157   /**
 158    * @brief Set whether the alpha channel in the pixels is used.
 159    */
 160   void SetAlphaUsed( const bool alphaUsed ) { mAlphaChannelUsed = alphaUsed ? ALPHA_USAGE_SOME_TRANSLUCENT : ALPHA_USAGE_ALL_OPAQUE; }
 161
 162 private:
 163
 164   ImageData(const ImageData& other);  ///< defined private to prevent use
 165   ImageData& operator = (const ImageData& other); ///< defined private to prevent use
 166
 167   /** Pointer to the buffer of image data. */
 168   uint8_t*     mData;
 169
 170 public:
 171   const size_t        dataSize;   ///< Number of bytes in buffer pointed at by mData
 172   const uint16_t      imageWidth;  ///< Image logical width in pixels
 173   const uint16_t      imageHeight; ///< Image logical height in pixels
 174   const Pixel::Format pixelFormat; ///< Pixel format
 175
 176 private:
 177   AlphaUsage mAlphaChannelUsed;
 178
 179   // Changes scope, should be at end of class
 180   DALI_LOG_OBJECT_STRING_DECLARATION;
 181 };
 182
 183 /**
 184  * A convenience function for creating the common case of an uncompressed image
 185  * having width * height pixels in the buffer.
 186  * @param[in] imageWidth The width in pixels of the image.
 187  * @param[in] imageHeight The height in pixels of the image.
 188  * @param[in] pixelFormat The format of the image data in the buffer.
 189  */
 190 DALI_IMPORT_API ImageDataPtr NewBitmapImageData( unsigned imageWidth, unsigned imageHeight, Pixel::Format pixelFormat );
 191
 192 } // namespace Integration
 193
 194 } // namespace Dali
 195
 196 #endif // __DALI_INTEGRATION_IMAGE_DATA_H__