use modern construct 'nullptr' instead of 'NULL' or '0'
[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) 2019 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_CORE_API void ConvertToGlFormat(Pixel::Format pixelformat, unsigned& pixelDataType, unsigned& internalFormat);
43
44 class Bitmap;
45 using BitmapPtr   = IntrusivePtr<Bitmap>;
46 using PixelBuffer = uint8_t; ///< Pixel data buffers are composed of these
47
48 /**
49  * Bitmap class.
50  * An abstract container for image data.
51  */
52 class DALI_CORE_API Bitmap : public Dali::RefObject
53 {
54 protected:
55
56   /**
57    * Constructor
58    * Use the static function Bitmap::New() to create instances.
59    * @param[in] discardable Flag to tell the bitmap if it can delete the buffer with the pixel data.
60    * @param[in] pixBuf External buffer of pixel data or null.
61    */
62   Bitmap( ResourcePolicy::Discardable discardable = ResourcePolicy::OWNED_RETAIN, Dali::Integration::PixelBuffer* pixBuf = nullptr );
63
64   /**
65    * Initializes internal class members
66    * @param[in] pixelFormat   pixel format
67    * @param[in] width         Image width in pixels
68    * @param[in] height        Image height in pixels
69    */
70   void Initialize(Pixel::Format pixelFormat,
71                            uint32_t width,
72                            uint32_t height);
73
74
75 public:
76   /** Defines the characteristics of the Bitmap returned from the factory
77    *  function. */
78   enum Profile
79   {
80     /** A 2D array of pixels where each pixel is a whole number of bytes
81      * and each scanline of the backing memory buffer may have additional
82      * bytes off the right edge if requested, and there may be additional
83      * scanlines past the bottom of the image in the buffer if requested.*/
84     BITMAP_2D_PACKED_PIXELS,
85     /** The data for the bitmap is buffered in an opaque form.*/
86     BITMAP_COMPRESSED
87   };
88
89   enum ReleaseFunction
90   {
91     FREE,          ///< Use free function to release the buffer
92     DELETE_ARRAY,  ///< Use delete[] operator to release the buffer
93   };
94
95   /**
96    * Create a new instance of a Bitmap with the required profile.
97    * @return Pointer to created Bitmap subclass. Clients should immediately
98    * wrap this in a reference-counting smart pointer or store it in a similarly
99    * automatic owning collection.
100    * @param[in] profile Defines required features of the bitmap (\sa Profile).
101    * @param[in] discardable OWNED_DISCARD means that the data is owned by bitmap,
102    * and may released away after uploading to GPU.
103    * OWNED_RETAIN means that the data is owned and must be kept in CPU memory
104    * e.g. for an image that cannot be reloaded from disk.
105    */
106   static Bitmap* New( Profile profile, ResourcePolicy::Discardable discardable );
107
108   /** \name GeneralFeatures
109    * Features that are generic between profiles. */
110   /**@{*/
111
112   /**
113    * Get the width of the image
114    * @return The width of the image
115    */
116   uint32_t GetImageWidth() const
117   {
118     return mImageWidth;
119   }
120
121   /**
122    * Get the height of the image
123    * @return The height of the image
124    */
125   uint32_t GetImageHeight() const
126   {
127     return mImageHeight;
128   }
129
130   /**
131    * Get the pixel format
132    * @return The pixel format
133    */
134   Pixel::Format GetPixelFormat() const
135   {
136     return mPixelFormat;
137   }
138
139   /**
140    * Get the pixel buffer if it's present.
141    * @return The buffer if present, or NULL if there is no pixel buffer.
142    * You can modify its contents.
143    * @sa ReserveBuffer GetBufferSize
144    */
145   virtual PixelBuffer* GetBuffer()
146   {
147     return mData;
148   }
149
150   /**
151    * Get the pixel buffer if it's present and take over the ownership.
152    * @note With this function called, the bitmap loses the ownership and is no longer responsible for the release of pixel buffer.
153    * @return The raw pointer pointing to the pixel buffer
154    */
155   PixelBuffer* GetBufferOwnership();
156
157   /**
158    * Get the pixel buffer size in bytes
159    * @return The buffer size in bytes.
160    * @sa ReserveBuffer GetBuffer
161    */
162   virtual uint32_t GetBufferSize() const = 0;
163
164   /**
165    * Queries if the bitmap has an alpha channel
166    * @return true if there is an alpha channel
167    */
168   bool HasAlphaChannel() const
169   {
170     return mHasAlphaChannel;
171   }
172
173   /**
174    * Queries if the bitmap has any transparent data
175    * @return true if the bitmap has alpha data
176    */
177   bool IsFullyOpaque() const
178   {
179     // check pixel format for alpha channel
180     return !(HasAlphaChannel() && mAlphaChannelUsed);
181   }
182
183   /**
184    * Returns which release function has to be called to release the data in the bitmap
185    * @return FREE if memory has been allocated with malloc DELETE_ARRAY if memory has been allocated with new
186    */
187   virtual ReleaseFunction GetReleaseFunction() = 0;
188
189   /**@}*/ ///< End of generic features
190
191
192   /** \name PackedPixelsProfile
193    * Features that are active only if the Bitmap was created with a
194    * BITMAP_2D_PACKED_PIXELS profile. */
195   /**@{*/
196
197   class PackedPixelsProfile
198   {
199   public:
200
201     /**
202      * (Re-)Allocate pixel buffer for the Bitmap. Any previously allocated pixel buffer is deleted.
203      * Dali has ownership of the buffer, but its contents can be modified.
204      * Bitmap stores given size information about the image.
205      * @pre bufferWidth, bufferHeight have to be power of two
206      * @param[in] pixelFormat   pixel format
207      * @param[in] width         Image width in pixels
208      * @param[in] height        Image height in pixels
209      * @param[in] bufferWidth   Buffer width (stride) in pixels
210      * @param[in] bufferHeight  Buffer height in pixels
211      * @return pixel buffer pointer
212      */
213     virtual PixelBuffer* ReserveBuffer(Pixel::Format pixelFormat,
214                                        uint32_t width,
215                                        uint32_t height,
216                                        uint32_t bufferWidth = 0,
217                                        uint32_t bufferHeight = 0) = 0;
218
219     /**
220      * Assign a pixel buffer. Any previously allocated pixel buffer is deleted.
221      * Dali has ownership of the buffer, but it iss allowable to modify its
222      * contents after it is assigned, but before it is used.
223      * Bitmap stores the provided size information about the image.
224      *
225      * The buffer must have been allocated with the C++ array new operator, not
226      * with malloc or as a local or static object. The precise form is as follows:
227      *
228      *    PixelBuffer * buffer = new PixelBuffer[bufSize];
229      *
230      * @pre bufferWidth, bufferHeight have to be power of two
231      * @param[in] pixelFormat   pixel format
232      * @param[in] buffer        the pixel buffer
233      * @param[in] bufferSize    size of the pixel buffer
234      * @param[in] width         Image width in pixels
235      * @param[in] height        Image height in pixels
236      * @param[in] bufferWidth   Buffer width (stride) in pixels
237      * @param[in] bufferHeight  Buffer height in pixels
238      */
239     virtual void AssignBuffer(Pixel::Format pixelFormat,
240                               PixelBuffer* buffer,
241                               uint32_t bufferSize,
242                               uint32_t width,
243                               uint32_t height,
244                               uint32_t bufferWidth = 0,
245                               uint32_t bufferHeight = 0) = 0;
246     /**
247      * Get the width of the buffer (stride)
248      * @return The width of the buffer in pixels
249      */
250     virtual uint32_t GetBufferWidth() const = 0;
251
252     /**
253      * Get the height of the buffer
254      * @return The height of the buffer in pixels
255      */
256     virtual uint32_t GetBufferHeight() const = 0;
257
258     /**
259      * Get the pixel buffer stride.
260      * @return The buffer stride (in bytes) if this is bitmap of non-compressed
261      * packed pixels for which a stride is meaningful or 0 otherwise.
262      */
263     virtual uint32_t GetBufferStride() const = 0;
264
265     /**
266      * Check the bitmap data and test whether it has any transparent pixels.
267      * This property can then be tested for with IsFullyOpaque().
268      */
269     virtual void TestForTransparency() = 0;
270
271   protected:
272
273     /**
274      * Virtual destructor, no deletion through this interface
275      */
276     virtual ~PackedPixelsProfile() {}
277   };
278
279   /**
280    * Get interface to features that are active only if the Bitmap was created
281    * with a BITMAP_2D_PACKED_PIXELS profile. */
282   virtual const PackedPixelsProfile* GetPackedPixelsProfile() const { return nullptr; }
283   /**
284    * Get interface to features that are active only if the Bitmap was created
285    * with a BITMAP_2D_PACKED_PIXELS profile. */
286   virtual PackedPixelsProfile* GetPackedPixelsProfile() { return nullptr; }
287
288   /**@}*/ ///< End of packed pixel features.
289
290
291   /** \name CompressedProfile
292    * Features that only apply to opaque/compressed formats. */
293   /**@{*/
294
295   class CompressedProfile
296   {
297   public:
298     /**
299      * (Re-)Allocate pixel buffer for the Bitmap. Any previously allocated pixel buffer
300      * is deleted.
301      * Dali has ownership of the buffer, and contents are opaque and immutable.
302      * Bitmap stores given size information about the image which the client is assumed
303      * to have retrieved from out-of-band image metadata.
304      * @param[in] pixelFormat   pixel format
305      * @param[in] width         Image width in pixels
306      * @param[in] height        Image height in pixels
307      * @param[in] bufferSize    Buffer size in bytes
308      * @return pixel buffer pointer
309      */
310     virtual PixelBuffer* ReserveBufferOfSize( Pixel::Format pixelFormat,
311                                        const unsigned width,
312                                        const unsigned height,
313                                        const uint32_t numBytes ) = 0;
314   protected:
315
316     /**
317      * Virtual destructor, no deletion through this interface
318      */
319     virtual ~CompressedProfile() {}
320   };
321
322   virtual const CompressedProfile* GetCompressedProfile() const { return nullptr; }
323   virtual CompressedProfile* GetCompressedProfile() { return nullptr; }
324   /**@}*/
325
326
327   /**
328    * Inform the bitmap that its pixel buffer is no longer required and can be
329    * deleted to free up memory if the bitmap owns the buffer.
330    */
331   void DiscardBuffer();
332
333   /**
334    * Check if the pixel buffer can be discarded
335    * @return true if the pixel buffer can be discarded
336    */
337   bool IsDiscardable() const
338   {
339     return mDiscardable == ResourcePolicy::OWNED_DISCARD;
340   }
341
342   /**
343    * Delete the pixel buffer data
344    */
345   void DeletePixelBuffer();
346
347 protected:
348
349   /**
350    * A reference counted object may only be deleted by calling Unreference()
351    */
352   virtual ~Bitmap();
353
354 protected:
355
356   uint32_t  mImageWidth;          ///< Image width in pixels
357   uint32_t  mImageHeight;         ///< Image height in pixels
358   Pixel::Format mPixelFormat;         ///< Pixel format
359   bool          mHasAlphaChannel;   ///< Whether the image has an alpha channel
360   bool          mAlphaChannelUsed;  ///< Whether the alpha channel is used in case the image owns one.
361   PixelBuffer*  mData;            ///< Raw pixel data
362
363 private:
364
365   ResourcePolicy::Discardable mDiscardable; ///< Should delete the buffer when discard buffer is called.
366
367   Bitmap(const Bitmap& other);  ///< defined private to prevent use
368   Bitmap& operator = (const Bitmap& other); ///< defined private to prevent use
369
370   // Changes scope, should be at end of class
371   DALI_LOG_OBJECT_STRING_DECLARATION;
372 };
373
374 } // namespace Integration
375
376 } // namespace Dali
377
378 #endif // DALI_INTEGRATION_BITMAP_H