1 #ifndef __DALI_INTEGRATION_BITMAP_H__
2 #define __DALI_INTEGRATION_BITMAP_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.
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>
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)
42 DALI_IMPORT_API void ConvertToGlFormat(Pixel::Format pixelformat, unsigned& pixelDataType, unsigned& internalFormat);
45 typedef IntrusivePtr<Bitmap> BitmapPtr;
46 typedef unsigned char PixelBuffer; ///< Pixel data buffers are composed of these
50 * An abstract container for image data.
51 * \sa{BitmapPackedPixel BitmapCompressed BitmapExternal} for concrete
54 class DALI_IMPORT_API Bitmap : public Dali::RefObject
60 * Use the static function Bitmap::New() to create instances.
61 * @param[in] discardable Flag to tell the bitmap if it can delete the buffer with the pixel data.
62 * @param[in] pixBuf External buffer of pixel data or null.
64 Bitmap( ResourcePolicy::Discardable discardable = ResourcePolicy::OWNED_RETAIN, Dali::Integration::PixelBuffer* pixBuf = 0 );
67 * Initializes internal class members
68 * @param[in] pixelFormat pixel format
69 * @param[in] width Image width in pixels
70 * @param[in] height Image height in pixels
72 void Initialize(Pixel::Format pixelFormat,
78 /** Defines the characteristics of the Bitmap returned from the factory
82 /** A 2D array of pixels where each pixel is a whole number of bytes
83 * and each scanline of the backing memory buffer may have additional
84 * bytes off the right edge if requested, and there may be additional
85 * scanlines past the bottom of the image in the buffer if requested.*/
86 BITMAP_2D_PACKED_PIXELS,
87 /** The data for the bitmap is buffered in an opaque form.*/
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 * NOT_OWNED means that the data is managed by an external component and is
102 * guaranteed to remain dereferenceable at least as long as the Bitmap remains alive.
104 static Bitmap* New( Profile profile, ResourcePolicy::Discardable discardable );
106 /** \name GeneralFeatures
107 * Features that are generic between profiles. */
111 * Get the width of the image
112 * @return The width of the image
114 unsigned int GetImageWidth() const
120 * Get the height of the image
121 * @return The height of the image
123 unsigned int GetImageHeight() const
129 * Get the pixel format
130 * @return The pixel format
132 Pixel::Format GetPixelFormat() const
138 * Get the pixel buffer if it's present.
139 * @return The buffer if present, or NULL if there is no pixel buffer.
140 * You can modify its contents.
141 * @sa ReserveBuffer GetBufferSize
143 virtual PixelBuffer* GetBuffer()
149 * Get the pixel buffer size in bytes
150 * @return The buffer size in bytes.
151 * @sa ReserveBuffer GetBuffer
153 virtual size_t GetBufferSize() const = 0;
156 * Queries if the bitmap has an alpha channel
157 * @return true if there is an alpha channel
159 bool HasAlphaChannel() const
161 return mHasAlphaChannel;
165 * Queries if the bitmap has any transparent data
166 * @return true if the bitmap has alpha data
168 bool IsFullyOpaque() const
170 // check pixel format for alpha channel
171 return !(HasAlphaChannel() && mAlphaChannelUsed);
174 /**@}*/ ///< End of generic features
177 /** \name PackedPixelsProfile
178 * Features that are active only if the Bitmap was created with a
179 * BITMAP_2D_PACKED_PIXELS profile. */
182 class PackedPixelsProfile
187 * (Re-)Allocate pixel buffer for the Bitmap. Any previously allocated pixel buffer is deleted.
188 * Dali has ownership of the buffer, but its contents can be modified.
189 * Bitmap stores given size information about the image.
190 * @pre bufferWidth, bufferHeight have to be power of two
191 * @param[in] pixelFormat pixel format
192 * @param[in] width Image width in pixels
193 * @param[in] height Image height in pixels
194 * @param[in] bufferWidth Buffer width (stride) in pixels
195 * @param[in] bufferHeight Buffer height in pixels
196 * @return pixel buffer pointer
198 virtual PixelBuffer* ReserveBuffer(Pixel::Format pixelFormat,
201 unsigned int bufferWidth = 0,
202 unsigned int bufferHeight = 0) = 0;
205 * Assign a pixel buffer. Any previously allocated pixel buffer is deleted.
206 * Dali has ownership of the buffer, but it iss allowable to modify its
207 * contents after it is assigned, but before it is used.
208 * Bitmap stores the provided size information about the image.
210 * The buffer must have been allocated with the C++ array new operator, not
211 * with malloc or as a local or static object. The precise form is as follows:
213 * PixelBuffer * buffer = new PixelBuffer[bufSize];
215 * @pre bufferWidth, bufferHeight have to be power of two
216 * @param[in] pixelFormat pixel format
217 * @param[in] buffer the pixel buffer
218 * @param[in] bufferSize size of the pixel buffer
219 * @param[in] width Image width in pixels
220 * @param[in] height Image height in pixels
221 * @param[in] bufferWidth Buffer width (stride) in pixels
222 * @param[in] bufferHeight Buffer height in pixels
224 virtual void AssignBuffer(Pixel::Format pixelFormat,
226 std::size_t bufferSize,
229 unsigned int bufferWidth = 0,
230 unsigned int bufferHeight = 0) = 0;
232 * Get the width of the buffer (stride)
233 * @return The width of the buffer in pixels
235 virtual unsigned int GetBufferWidth() const = 0;
238 * Get the height of the buffer
239 * @return The height of the buffer in pixels
241 virtual unsigned int GetBufferHeight() const = 0;
244 * Get the pixel buffer stride.
245 * @return The buffer stride (in bytes) if this is bitmap of non-compressed
246 * packed pixels for which a stride is meaningful or 0 otherwise.
248 virtual unsigned int GetBufferStride() const = 0;
251 * Check the bitmap data and test whether it has any transparent pixels.
252 * This property can then be tested for with IsFullyOpaque().
254 virtual void TestForTransparency() = 0;
258 * Get interface to features that are active only if the Bitmap was created
259 * with a BITMAP_2D_PACKED_PIXELS profile. */
260 virtual const PackedPixelsProfile* GetPackedPixelsProfile() const { return 0; }
262 * Get interface to features that are active only if the Bitmap was created
263 * with a BITMAP_2D_PACKED_PIXELS profile. */
264 virtual PackedPixelsProfile* GetPackedPixelsProfile() { return 0; }
266 /**@}*/ ///< End of packed pixel features.
269 /** \name CompressedProfile
270 * Features that only apply to opaque/compressed formats. */
273 class CompressedProfile
277 * (Re-)Allocate pixel buffer for the Bitmap. Any previously allocated pixel buffer
279 * Dali has ownership of the buffer, and contents are opaque and immutable.
280 * Bitmap stores given size information about the image which the client is assumed
281 * to have retrieved from out-of-band image metadata.
282 * @param[in] pixelFormat pixel format
283 * @param[in] width Image width in pixels
284 * @param[in] height Image height in pixels
285 * @param[in] bufferSize Buffer size in bytes
286 * @return pixel buffer pointer
288 virtual PixelBuffer* ReserveBufferOfSize( Pixel::Format pixelFormat,
289 const unsigned width,
290 const unsigned height,
291 const size_t numBytes ) = 0;
294 virtual const CompressedProfile* GetCompressedProfile() const { return 0; }
295 virtual CompressedProfile* GetCompressedProfile() { return 0; }
300 * Inform the bitmap that its pixel buffer is no longer required and can be
301 * deleted to free up memory if the bitmap owns the buffer.
303 void DiscardBuffer();
306 * Check if the pixel buffer can be discarded
307 * @return true if the pixel buffer can be discarded
309 bool IsDiscardable() const
311 return mDiscardable == ResourcePolicy::OWNED_DISCARD;
315 * Transfer ownership of the pixel buffer to the calling function.
316 * @post bitmaps pixel data is set to NULL
317 * @return the bitmaps pixel buffer
319 PixelBuffer* ReleaseBuffer();
321 * Delete the pixel buffer data
323 void DeletePixelBuffer();
326 * A reference counted object may only be deleted by calling Unreference()
332 unsigned int mImageWidth; ///< Image width in pixels
333 unsigned int mImageHeight; ///< Image height in pixels
334 Pixel::Format mPixelFormat; ///< Pixel format
335 bool mHasAlphaChannel; ///< Whether the image has an alpha channel
336 bool mAlphaChannelUsed; ///< Whether the alpha channel is used in case the image owns one.
337 PixelBuffer* mData; ///< Raw pixel data
341 ResourcePolicy::Discardable mDiscardable; ///< Should delete the buffer when discard buffer is called.
343 Bitmap(const Bitmap& other); ///< defined private to prevent use
344 Bitmap& operator = (const Bitmap& other); ///< defined private to prevent use
346 // Changes scope, should be at end of class
347 DALI_LOG_OBJECT_STRING_DECLARATION;
350 } // namespace Integration
354 #endif // __DALI_INTEGRATION_BITMAP_H__