1 #ifndef __DALI_INTEGRATION_IMAGE_DATA_H__
2 #define __DALI_INTEGRATION_IMAGE_DATA_H__
5 * Copyright (c) 2014 Samsung Electronics Co., Ltd.
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
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>
37 typedef IntrusivePtr<ImageData> ImageDataPtr;
39 typedef uint8_t PixelBuffer;
42 * Used to avoid accidentally mixing the order of parameters where some are uint
43 * dimensions and one is a buffer size.
48 explicit BufferSize(size_t size) : bufferSize( size )
50 operator size_t() const { return bufferSize; }
51 const size_t bufferSize;
55 * @brief A simple container for image data.
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().
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.
68 class DALI_IMPORT_API ImageData : public Dali::RefObject
72 * @brief Three values for the information about the alpha values in the
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.
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
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.
97 ImageData( const size_t numBytes, const unsigned imageWidth, const unsigned imageHeight, const Pixel::Format pixelFormat );
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.
107 ImageData( uint8_t * const imageBuffer, const size_t numBytes, const unsigned imageWidth, const unsigned imageHeight, const Pixel::Format pixelFormat );
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.
123 static ImageDataPtr New( const BufferSize numBytes, unsigned imageWidth, unsigned imageHeight, Pixel::Format pixelFormat );
125 /** Allocate and initialise a fresh ImageData object, taking ownership of the
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.
135 static ImageDataPtr New( uint8_t * const imageBuffer, const BufferSize numBytes, unsigned imageWidth, unsigned imageHeight, Pixel::Format pixelFormat );
137 /** Access the buffer of image data. */
138 const uint8_t * GetBuffer() const { return mData; }
140 /** Access the buffer of image data. */
141 uint8_t * GetBuffer() { return mData; }
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
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.
151 uint8_t * ReleaseImageBuffer() { uint8_t * const data = mData; mData = 0; return data; }
154 * @brief Get whether the alpha channel in the pixels is used.
156 AlphaUsage GetAlphaUsage() const { return mAlphaChannelUsed; }
159 * @brief Set whether the alpha channel in the pixels is used.
161 void SetAlphaUsed( const bool alphaUsed ) { mAlphaChannelUsed = alphaUsed ? ALPHA_USAGE_SOME_TRANSLUCENT : ALPHA_USAGE_ALL_OPAQUE; }
165 ImageData(const ImageData& other); ///< defined private to prevent use
166 ImageData& operator = (const ImageData& other); ///< defined private to prevent use
168 /** Pointer to the buffer of image data. */
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
178 AlphaUsage mAlphaChannelUsed;
180 // Changes scope, should be at end of class
181 DALI_LOG_OBJECT_STRING_DECLARATION;
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.
191 DALI_IMPORT_API ImageDataPtr NewBitmapImageData( unsigned imageWidth, unsigned imageHeight, Pixel::Format pixelFormat );
193 } // namespace Integration
197 #endif // __DALI_INTEGRATION_IMAGE_DATA_H__