Merge "Stability/Performance for update buffer index" into devel/master
[platform/core/uifw/dali-core.git] / dali / integration-api / bitmap.h
1 #ifndef __DALI_INTEGRATION_BITMAP_H__
2 #define __DALI_INTEGRATION_BITMAP_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 // EXTERNAL INCLUDES
22
23 // INTERNAL INCLUDES
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>
29
30 namespace Dali
31 {
32
33 namespace Integration
34 {
35
36 /**
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)
41  */
42 DALI_IMPORT_API void ConvertToGlFormat(Pixel::Format pixelformat, unsigned& pixelDataType, unsigned& internalFormat);
43
44 class Bitmap;
45 typedef IntrusivePtr<Bitmap>    BitmapPtr;
46 typedef unsigned char                 PixelBuffer;  ///< Pixel data buffers are composed of these
47
48 /**
49  * Bitmap class.
50  * An abstract container for image data.
51  * \sa{BitmapPackedPixel BitmapCompressed BitmapExternal} for concrete
52  * subclasses.
53  */
54 class DALI_IMPORT_API Bitmap : public Dali::RefObject
55 {
56 protected:
57
58   /**
59    * Constructor
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.
63    */
64   Bitmap( ResourcePolicy::Discardable discardable = ResourcePolicy::OWNED_RETAIN, Dali::Integration::PixelBuffer* pixBuf = 0 );
65
66   /**
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
71    */
72   void Initialize(Pixel::Format pixelFormat,
73                            unsigned int width,
74                            unsigned int height);
75
76
77 public:
78   /** Defines the characteristics of the Bitmap returned from the factory
79    *  function. */
80   enum Profile
81   {
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.*/
88     BITMAP_COMPRESSED
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   unsigned int 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   unsigned int 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 size in bytes
148    * @return The buffer size in bytes.
149    * @sa ReserveBuffer GetBuffer
150    */
151   virtual size_t GetBufferSize() const = 0;
152
153   /**
154    * Queries if the bitmap has an alpha channel
155    * @return true if there is an alpha channel
156    */
157   bool HasAlphaChannel() const
158   {
159     return mHasAlphaChannel;
160   }
161
162   /**
163    * Queries if the bitmap has any transparent data
164    * @return true if the bitmap has alpha data
165    */
166   bool IsFullyOpaque() const
167   {
168     // check pixel format for alpha channel
169     return !(HasAlphaChannel() && mAlphaChannelUsed);
170   }
171
172   /**@}*/ ///< End of generic features
173
174
175   /** \name PackedPixelsProfile
176    * Features that are active only if the Bitmap was created with a
177    * BITMAP_2D_PACKED_PIXELS profile. */
178   /**@{*/
179
180   class PackedPixelsProfile
181   {
182   public:
183
184     /**
185      * (Re-)Allocate pixel buffer for the Bitmap. Any previously allocated pixel buffer is deleted.
186      * Dali has ownership of the buffer, but its contents can be modified.
187      * Bitmap stores given size information about the image.
188      * @pre bufferWidth, bufferHeight have to be power of two
189      * @param[in] pixelFormat   pixel format
190      * @param[in] width         Image width in pixels
191      * @param[in] height        Image height in pixels
192      * @param[in] bufferWidth   Buffer width (stride) in pixels
193      * @param[in] bufferHeight  Buffer height in pixels
194      * @return pixel buffer pointer
195      */
196     virtual PixelBuffer* ReserveBuffer(Pixel::Format pixelFormat,
197                                        unsigned int width,
198                                        unsigned int height,
199                                        unsigned int bufferWidth = 0,
200                                        unsigned int bufferHeight = 0) = 0;
201
202     /**
203      * Assign a pixel buffer. Any previously allocated pixel buffer is deleted.
204      * Dali has ownership of the buffer, but it iss allowable to modify its
205      * contents after it is assigned, but before it is used.
206      * Bitmap stores the provided size information about the image.
207      *
208      * The buffer must have been allocated with the C++ array new operator, not
209      * with malloc or as a local or static object. The precise form is as follows:
210      *
211      *    PixelBuffer * buffer = new PixelBuffer[bufSize];
212      *
213      * @pre bufferWidth, bufferHeight have to be power of two
214      * @param[in] pixelFormat   pixel format
215      * @param[in] buffer        the pixel buffer
216      * @param[in] bufferSize    size of the pixel buffer
217      * @param[in] width         Image width in pixels
218      * @param[in] height        Image height in pixels
219      * @param[in] bufferWidth   Buffer width (stride) in pixels
220      * @param[in] bufferHeight  Buffer height in pixels
221      */
222     virtual void AssignBuffer(Pixel::Format pixelFormat,
223                               PixelBuffer* buffer,
224                               std::size_t bufferSize,
225                               unsigned int width,
226                               unsigned int height,
227                               unsigned int bufferWidth = 0,
228                               unsigned int bufferHeight = 0) = 0;
229     /**
230      * Get the width of the buffer (stride)
231      * @return The width of the buffer in pixels
232      */
233     virtual unsigned int GetBufferWidth() const = 0;
234
235     /**
236      * Get the height of the buffer
237      * @return The height of the buffer in pixels
238      */
239     virtual unsigned int GetBufferHeight() const = 0;
240
241     /**
242      * Get the pixel buffer stride.
243      * @return The buffer stride (in bytes) if this is bitmap of non-compressed
244      * packed pixels for which a stride is meaningful or 0 otherwise.
245      */
246     virtual unsigned int GetBufferStride() const = 0;
247
248     /**
249      * Check the bitmap data and test whether it has any transparent pixels.
250      * This property can then be tested for with IsFullyOpaque().
251      */
252     virtual void TestForTransparency() = 0;
253   };
254
255   /**
256    * Get interface to features that are active only if the Bitmap was created
257    * with a BITMAP_2D_PACKED_PIXELS profile. */
258   virtual const PackedPixelsProfile* GetPackedPixelsProfile() const { return 0; }
259   /**
260    * Get interface to features that are active only if the Bitmap was created
261    * with a BITMAP_2D_PACKED_PIXELS profile. */
262   virtual PackedPixelsProfile* GetPackedPixelsProfile() { return 0; }
263
264   /**@}*/ ///< End of packed pixel features.
265
266
267   /** \name CompressedProfile
268    * Features that only apply to opaque/compressed formats. */
269   /**@{*/
270
271   class CompressedProfile
272   {
273   public:
274     /**
275      * (Re-)Allocate pixel buffer for the Bitmap. Any previously allocated pixel buffer
276      * is deleted.
277      * Dali has ownership of the buffer, and contents are opaque and immutable.
278      * Bitmap stores given size information about the image which the client is assumed
279      * to have retrieved from out-of-band image metadata.
280      * @param[in] pixelFormat   pixel format
281      * @param[in] width         Image width in pixels
282      * @param[in] height        Image height in pixels
283      * @param[in] bufferSize    Buffer size in bytes
284      * @return pixel buffer pointer
285      */
286     virtual PixelBuffer* ReserveBufferOfSize( Pixel::Format pixelFormat,
287                                        const unsigned width,
288                                        const unsigned height,
289                                        const size_t numBytes ) = 0;
290   };
291
292   virtual const CompressedProfile* GetCompressedProfile() const { return 0; }
293   virtual CompressedProfile* GetCompressedProfile() { return 0; }
294   /**@}*/
295
296
297   /**
298    * Inform the bitmap that its pixel buffer is no longer required and can be
299    * deleted to free up memory if the bitmap owns the buffer.
300    */
301   void DiscardBuffer();
302
303   /**
304    * Check if the pixel buffer can be discarded
305    * @return true if the pixel buffer can be discarded
306    */
307   bool IsDiscardable() const
308   {
309     return mDiscardable == ResourcePolicy::OWNED_DISCARD;
310   }
311
312   /**
313    * Delete the pixel buffer data
314    */
315   void DeletePixelBuffer();
316
317   /**
318    * A reference counted object may only be deleted by calling Unreference()
319    */
320   virtual ~Bitmap();
321
322 protected:
323
324   unsigned int  mImageWidth;          ///< Image width in pixels
325   unsigned int  mImageHeight;         ///< Image height in pixels
326   Pixel::Format mPixelFormat;         ///< Pixel format
327   bool          mHasAlphaChannel;   ///< Whether the image has an alpha channel
328   bool          mAlphaChannelUsed;  ///< Whether the alpha channel is used in case the image owns one.
329   PixelBuffer*  mData;            ///< Raw pixel data
330
331 private:
332
333   ResourcePolicy::Discardable mDiscardable; ///< Should delete the buffer when discard buffer is called.
334
335   Bitmap(const Bitmap& other);  ///< defined private to prevent use
336   Bitmap& operator = (const Bitmap& other); ///< defined private to prevent use
337
338   // Changes scope, should be at end of class
339   DALI_LOG_OBJECT_STRING_DECLARATION;
340 };
341
342 } // namespace Integration
343
344 } // namespace Dali
345
346 #endif // __DALI_INTEGRATION_BITMAP_H__