1 #ifndef DALI_INTEGRATION_BITMAP_H
2 #define DALI_INTEGRATION_BITMAP_H
5 * Copyright (c) 2020 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/integration-api/resource-policies.h>
26 #include <dali/public-api/common/intrusive-ptr.h>
27 #include <dali/public-api/images/pixel.h>
28 #include <dali/public-api/object/ref-object.h>
35 * Returns GL data type and internal format for specified pixel format
36 * @param[in] pixelformat pixel format (eg. Pixel::RGBA32)
37 * @param[out] pixelDataType pixel data type (eg. GL_UNSIGNED_BYTE)
38 * @param[out] internalFormat pixel internal format (eg. GL_RGBA)
40 DALI_CORE_API void ConvertToGlFormat(Pixel::Format pixelformat, unsigned& pixelDataType, unsigned& internalFormat);
43 using BitmapPtr = IntrusivePtr<Bitmap>;
44 using PixelBuffer = uint8_t; ///< Pixel data buffers are composed of these
48 * An abstract container for image data.
50 class DALI_CORE_API Bitmap : public Dali::RefObject
55 * Use the static function Bitmap::New() to create instances.
56 * @param[in] discardable Flag to tell the bitmap if it can delete the buffer with the pixel data.
57 * @param[in] pixBuf External buffer of pixel data or null.
59 Bitmap(ResourcePolicy::Discardable discardable = ResourcePolicy::OWNED_RETAIN, Dali::Integration::PixelBuffer* pixBuf = nullptr);
62 * Initializes internal class members
63 * @param[in] pixelFormat pixel format
64 * @param[in] width Image width in pixels
65 * @param[in] height Image height in pixels
67 void Initialize(Pixel::Format pixelFormat,
72 /** Defines the characteristics of the Bitmap returned from the factory
76 /** A 2D array of pixels where each pixel is a whole number of bytes
77 * and each scanline of the backing memory buffer may have additional
78 * bytes off the right edge if requested, and there may be additional
79 * scanlines past the bottom of the image in the buffer if requested.*/
80 BITMAP_2D_PACKED_PIXELS,
81 /** The data for the bitmap is buffered in an opaque form.*/
87 FREE, ///< Use free function to release the buffer
88 DELETE_ARRAY, ///< Use delete[] operator to release the buffer
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.
102 static Bitmap* New(Profile profile, ResourcePolicy::Discardable discardable);
104 /** \name GeneralFeatures
105 * Features that are generic between profiles. */
109 * Get the width of the image
110 * @return The width of the image
112 uint32_t GetImageWidth() const
118 * Get the height of the image
119 * @return The height of the image
121 uint32_t GetImageHeight() const
127 * Get the pixel format
128 * @return The pixel format
130 Pixel::Format GetPixelFormat() const
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
141 virtual PixelBuffer* GetBuffer()
147 * Get the pixel buffer if it's present and take over the ownership.
148 * @note With this function called, the bitmap loses the ownership and is no longer responsible for the release of pixel buffer.
149 * @return The raw pointer pointing to the pixel buffer
151 PixelBuffer* GetBufferOwnership();
154 * Get the pixel buffer size in bytes
155 * @return The buffer size in bytes.
156 * @sa ReserveBuffer GetBuffer
158 virtual uint32_t GetBufferSize() const = 0;
161 * Queries if the bitmap has an alpha channel
162 * @return true if there is an alpha channel
164 bool HasAlphaChannel() const
166 return mHasAlphaChannel;
170 * Queries if the bitmap has any transparent data
171 * @return true if the bitmap has alpha data
173 bool IsFullyOpaque() const
175 // check pixel format for alpha channel
176 return !(HasAlphaChannel() && mAlphaChannelUsed);
180 * Returns which release function has to be called to release the data in the bitmap
181 * @return FREE if memory has been allocated with malloc DELETE_ARRAY if memory has been allocated with new
183 virtual ReleaseFunction GetReleaseFunction() = 0;
185 /**@}*/ ///< End of generic features
187 /** \name PackedPixelsProfile
188 * Features that are active only if the Bitmap was created with a
189 * BITMAP_2D_PACKED_PIXELS profile. */
192 class PackedPixelsProfile
196 * (Re-)Allocate pixel buffer for the Bitmap. Any previously allocated pixel buffer is deleted.
197 * Dali has ownership of the buffer, but its contents can be modified.
198 * Bitmap stores given size information about the image.
199 * @pre bufferWidth, bufferHeight have to be power of two
200 * @param[in] pixelFormat pixel format
201 * @param[in] width Image width in pixels
202 * @param[in] height Image height in pixels
203 * @param[in] bufferWidth Buffer width (stride) in pixels
204 * @param[in] bufferHeight Buffer height in pixels
205 * @return pixel buffer pointer
207 virtual PixelBuffer* ReserveBuffer(Pixel::Format pixelFormat,
210 uint32_t bufferWidth = 0,
211 uint32_t bufferHeight = 0) = 0;
214 * Assign a pixel buffer. Any previously allocated pixel buffer is deleted.
215 * Dali has ownership of the buffer, but it iss allowable to modify its
216 * contents after it is assigned, but before it is used.
217 * Bitmap stores the provided size information about the image.
219 * The buffer must have been allocated with the C++ array new operator, not
220 * with malloc or as a local or static object. The precise form is as follows:
222 * PixelBuffer * buffer = new PixelBuffer[bufSize];
224 * @pre bufferWidth, bufferHeight have to be power of two
225 * @param[in] pixelFormat pixel format
226 * @param[in] buffer the pixel buffer
227 * @param[in] bufferSize size of the pixel buffer
228 * @param[in] width Image width in pixels
229 * @param[in] height Image height in pixels
230 * @param[in] bufferWidth Buffer width (stride) in pixels
231 * @param[in] bufferHeight Buffer height in pixels
233 virtual void AssignBuffer(Pixel::Format pixelFormat,
238 uint32_t bufferWidth = 0,
239 uint32_t bufferHeight = 0) = 0;
241 * Get the width of the buffer (stride)
242 * @return The width of the buffer in pixels
244 virtual uint32_t GetBufferWidth() const = 0;
247 * Get the height of the buffer
248 * @return The height of the buffer in pixels
250 virtual uint32_t GetBufferHeight() const = 0;
253 * Get the pixel buffer stride.
254 * @return The buffer stride (in bytes) if this is bitmap of non-compressed
255 * packed pixels for which a stride is meaningful or 0 otherwise.
257 virtual uint32_t GetBufferStride() const = 0;
260 * Check the bitmap data and test whether it has any transparent pixels.
261 * This property can then be tested for with IsFullyOpaque().
263 virtual void TestForTransparency() = 0;
267 * Virtual destructor, no deletion through this interface
269 virtual ~PackedPixelsProfile() = default;
273 * Get interface to features that are active only if the Bitmap was created
274 * with a BITMAP_2D_PACKED_PIXELS profile. */
275 virtual const PackedPixelsProfile* GetPackedPixelsProfile() const
280 * Get interface to features that are active only if the Bitmap was created
281 * with a BITMAP_2D_PACKED_PIXELS profile. */
282 virtual PackedPixelsProfile* GetPackedPixelsProfile()
287 /**@}*/ ///< End of packed pixel features.
289 /** \name CompressedProfile
290 * Features that only apply to opaque/compressed formats. */
293 class CompressedProfile
297 * (Re-)Allocate pixel buffer for the Bitmap. Any previously allocated pixel buffer
299 * Dali has ownership of the buffer, and contents are opaque and immutable.
300 * Bitmap stores given size information about the image which the client is assumed
301 * to have retrieved from out-of-band image metadata.
302 * @param[in] pixelFormat pixel format
303 * @param[in] width Image width in pixels
304 * @param[in] height Image height in pixels
305 * @param[in] bufferSize Buffer size in bytes
306 * @return pixel buffer pointer
308 virtual PixelBuffer* ReserveBufferOfSize(Pixel::Format pixelFormat,
309 const unsigned width,
310 const unsigned height,
311 const uint32_t numBytes) = 0;
315 * Virtual destructor, no deletion through this interface
317 virtual ~CompressedProfile() = default;
320 virtual const CompressedProfile* GetCompressedProfile() const
324 virtual CompressedProfile* GetCompressedProfile()
331 * Inform the bitmap that its pixel buffer is no longer required and can be
332 * deleted to free up memory if the bitmap owns the buffer.
334 void DiscardBuffer();
337 * Check if the pixel buffer can be discarded
338 * @return true if the pixel buffer can be discarded
340 bool IsDiscardable() const
342 return mDiscardable == ResourcePolicy::OWNED_DISCARD;
346 * Delete the pixel buffer data
348 void DeletePixelBuffer();
352 * A reference counted object may only be deleted by calling Unreference()
357 uint32_t mImageWidth; ///< Image width in pixels
358 uint32_t mImageHeight; ///< Image height in pixels
359 Pixel::Format mPixelFormat; ///< Pixel format
360 bool mHasAlphaChannel; ///< Whether the image has an alpha channel
361 bool mAlphaChannelUsed; ///< Whether the alpha channel is used in case the image owns one.
362 PixelBuffer* mData; ///< Raw pixel data
365 ResourcePolicy::Discardable mDiscardable; ///< Should delete the buffer when discard buffer is called.
367 Bitmap(const Bitmap& other); ///< defined private to prevent use
368 Bitmap& operator=(const Bitmap& other); ///< defined private to prevent use
370 // Changes scope, should be at end of class
371 DALI_LOG_OBJECT_STRING_DECLARATION;
374 } // namespace Integration
378 #endif // DALI_INTEGRATION_BITMAP_H