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