dali/devel-api/adaptor-framework/pixel-buffer.h

   1 #ifndef DALI_PIXEL_BUFFER_H
   2 #define DALI_PIXEL_BUFFER_H
   3
   4 /*
   5  * Copyright (c) 2024 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 // INTERNAL INCLUDES
  22 #include <dali/public-api/images/pixel-data.h>
  23 #include <dali/public-api/images/pixel.h>
  24 #include <dali/public-api/object/base-handle.h>
  25
  26 // INTERNAL INCLUDES
  27 #include <dali/public-api/dali-adaptor-common.h>
  28
  29 namespace Dali
  30 {
  31 namespace Internal
  32 {
  33 namespace Adaptor
  34 {
  35 class PixelBuffer;
  36 }
  37 } // namespace Internal
  38
  39 // Use namespace to separate from PixelBuffer typedef in buffer-image.h
  40 namespace Devel
  41 {
  42 /**
  43  * @brief The PixelBuffer object holds a pixel buffer.
  44  *
  45  * The PixelBuffer keeps ownership of it's initial buffer however, the
  46  * user is free to modify the pixel data, either directly, or via
  47  * image operations.
  48  *
  49  * In order to upload the pixel data to texture memory, there are two
  50  * possibilities - either convert it back to a PixelData object, which
  51  * releases the PixelBuffer object, leaving the user with an empty handle
  52  * (ideal for one-time indirect image manipulation), or create a new
  53  * PixelData object from this object, leaving the buffer intact (ideal
  54  * for continuous manipulation)
  55  *
  56  * @SINCE_1_2.46
  57  */
  58 class DALI_ADAPTOR_API PixelBuffer : public BaseHandle
  59 {
  60 public:
  61   /**
  62    * Create a PixelBuffer with it's own data buffer.
  63    */
  64   static PixelBuffer New(uint32_t            width,
  65                          uint32_t            height,
  66                          Dali::Pixel::Format pixelFormat);
  67
  68   /**
  69    * @brief Creates an empty handle.
  70    * Use PixelBuffer::New() to create an initialized object.
  71    *
  72    * @SINCE_1_2.46
  73    */
  74   PixelBuffer();
  75
  76   /**
  77    * @brief Destructor.
  78    *
  79    * @SINCE_1_2.46
  80    */
  81   ~PixelBuffer();
  82
  83   /**
  84    * @brief This copy constructor is required for (smart) pointer semantics.
  85    *
  86    * @SINCE_1_2.46
  87    * @param[in] handle A reference to the copied handle
  88    */
  89   PixelBuffer(const PixelBuffer& handle);
  90
  91   /**
  92    * @brief This assignment operator is required for (smart) pointer semantics.
  93    *
  94    * @SINCE_1_2.46
  95    * @param[in] rhs A reference to the copied handle
  96    * @return A reference to this object
  97    */
  98   PixelBuffer& operator=(const PixelBuffer& rhs);
  99
 100   /**
 101    * @brief This move constructor is required for (smart) pointer semantics.
 102    *
 103    * @SINCE_2_1.45
 104    * @param[in] handle A reference to the moved handle
 105    */
 106   PixelBuffer(PixelBuffer&& handle);
 107
 108   /**
 109    * @brief This move assignment operator is required for (smart) pointer semantics.
 110    *
 111    * @SINCE_2_1.45
 112    * @param[in] rhs A reference to the moved handle
 113    * @return A reference to this object
 114    */
 115   PixelBuffer& operator=(PixelBuffer&& rhs);
 116
 117   /**
 118    * Convert to a pixel data and release the pixelBuffer's object.
 119    * This handle is left empty.
 120    *
 121    * @warning Any other handles that keep a reference to this object
 122    * will be left with no buffer, trying to access it will return NULL.
 123    *
 124    * @SINCE_1_2.46
 125    * @param[in,out] pixelBuffer
 126    * @return a new PixelData which takes ownership of the PixelBuffer's buffer.
 127    */
 128   static PixelData Convert(PixelBuffer& pixelBuffer);
 129
 130   /**
 131    * Convert to a pixel data and release the pixelBuffer's object.
 132    * This handle is left empty.
 133    *
 134    * @warning Any other handles that keep a reference to this object
 135    * will be left with no buffer, trying to access it will return NULL.
 136    *
 137    * @SINCE_2_3.6
 138    * @param[in,out] pixelBuffer
 139    * @param[in] releaseAfterUpload Whether converted PixelData released after upload or not.
 140    * @return a new PixelData which takes ownership of the PixelBuffer's buffer.
 141    */
 142   static PixelData Convert(PixelBuffer& pixelBuffer, bool releaseAfterUpload);
 143
 144   /**
 145    * Copy the data from this object into a new PixelData object, which could be
 146    * used for uploading to a texture.
 147    * @return a new PixelData object containing a copy of this pixel buffer's data.
 148    */
 149   Dali::PixelData CreatePixelData() const;
 150
 151   /**
 152    * @brief Gets the pixel buffer. This is a pointer to the internal
 153    * pixel buffer.
 154    *
 155    * @warning If there is no pixel buffer (e.g. this object has been
 156    * converted to a PixelData), this method will return NULL.
 157    *
 158    * @SINCE_1_2.46
 159    * @return The pixel buffer, or NULL.
 160    */
 161   uint8_t* GetBuffer();
 162
 163   /**
 164    * @brief Gets the pixel buffer. This is a pointer to the internal
 165    * pixel buffer.
 166    *
 167    * @warning If there is no pixel buffer (e.g. this object has been
 168    * converted to a PixelData), this method will return NULL.
 169    *
 170    * @return The pixel buffer, or NULL.
 171    */
 172   const uint8_t* GetBuffer() const;
 173
 174   /**
 175    * @brief Gets the width of the buffer in pixels.
 176    *
 177    * @SINCE_1_2.46
 178    * @return The width of the buffer in pixels
 179    */
 180   uint32_t GetWidth() const;
 181
 182   /**
 183    * @brief Gets the height of the buffer in pixels.
 184    *
 185    * @SINCE_1_2.46
 186    * @return The height of the buffer in pixels
 187    */
 188   uint32_t GetHeight() const;
 189
 190   /**
 191    * @brief Gets the stride of the buffer in pixels.
 192    *
 193    * @SINCE_2_1.17
 194    * @return The stride of the buffer in pixels. 0 means the buffer is tightly packed.
 195    */
 196   uint32_t GetStride() const;
 197
 198   /**
 199    * @brief Gets the pixel format.
 200    *
 201    * @SINCE_1_2.46
 202    * @return The pixel format
 203    */
 204   Pixel::Format GetPixelFormat() const;
 205
 206   /**
 207    * Apply the mask to this pixel data, and return a new pixel data containing
 208    * the masked image. If this PixelBuffer doesn't have an alpha channel, then
 209    * the resultant PixelBuffer will be converted to a format that supports at
 210    * least the width of the color channels and the alpha channel from the mask.
 211    *
 212    * If cropToMask is set to true, then the contentScale is applied first to
 213    * this buffer, and the target buffer is cropped to the size of the mask. If
 214    * it's set to false, then the mask is scaled to match this buffer's size
 215    * before the mask is applied.
 216    *
 217    * @param[in] mask The mask to apply.
 218    * @param[in] contentScale The scaling factor to apply to the content
 219    * @param[in] cropToMask Whether to crop the output to the mask size (true)
 220    * or scale the mask to the content size (false)
 221    */
 222   void ApplyMask(PixelBuffer mask, float contentScale = 1.0f, bool cropToMask = false);
 223
 224   /**
 225    * Apply a Gaussian blur to this pixel data with the given radius.
 226    *
 227    * @note A bigger radius will yield a blurrier image. Only works for pixel data in RGBA format.
 228    *
 229    * @param[in] blurRadius The radius for Gaussian blur. A value of 0 or negative value indicates no blur.
 230    */
 231   void ApplyGaussianBlur(const float blurRadius);
 232
 233   /**
 234    * @brief Crops this buffer to the given crop rectangle.
 235    *
 236    * The crop rectangle will be clamped to the edges of the buffer if it is larger.
 237    * @param[in] x The top left corner's X
 238    * @param[in] y The top left corner's y
 239    * @param[in] width The crop width
 240    * @param[in] height The crop height
 241    */
 242   void Crop(uint16_t x, uint16_t y, uint16_t width, uint16_t height);
 243
 244   /**
 245    * @brief Resizes the buffer to the given dimensions.
 246    *
 247    * Uses either Lanczos4 for downscaling or Mitchell for upscaling
 248    * @param[in] width The new width
 249    * @param[in] height The new height
 250    */
 251   void Resize(uint16_t width, uint16_t height);
 252
 253   /**
 254    * @brief Returns Exif metadata as a property map
 255    *
 256    * @param[out] metadata Property map object to write into
 257    * @return True on success
 258    */
 259   bool GetMetadata(Property::Map& metadata) const;
 260
 261   /**
 262    * @brief Multiplies the image's color values by the alpha value. This provides better
 263    * blending capability.
 264    */
 265   void MultiplyColorByAlpha();
 266
 267   /**
 268    * @brief Rotates the pixel buffer by the given angle.
 269    *
 270    * @note Operation valid for pixel formats: A8, L8, LA88, RGB888, RGB8888, BGR8888, RGBA8888 and BGRA8888. Fails otherwise.
 271    * @note The operation does nothing for angles equivalent to 0 degrees: -360, 360, 720, etc.
 272    * @note If the pixel buffer does rotate, all the pointers to the internal pixel buffer retrieved by the method GetPixelBuffer() become invalid.
 273    *
 274    * @param[in] angle The angle in degrees.
 275    *
 276    * @return @e false if the rotation fails (invalid pixel format or memory issues).
 277    */
 278   bool Rotate(Degree angle);
 279
 280   /**
 281    * @brief Returns pixel-buffer is premultiplied or not.
 282    * @return true if alpha is pre-multiplied.
 283    */
 284   bool IsAlphaPreMultiplied() const;
 285
 286   /**
 287    * @brief Get the brightness of the pixel buffer.
 288    * @note The range is 255 to 0. The closer to 255, the brighter. 0 is not bright.
 289    * @return brightness of the pixel buffer.
 290    */
 291   uint32_t GetBrightness() const;
 292
 293 public:
 294   /**
 295    * @brief The constructor.
 296    * @note  Not intended for application developers.
 297    * @SINCE_1_2.46
 298    * @param[in] pointer A pointer to a newly allocated PixelBuffer
 299    */
 300   explicit DALI_INTERNAL PixelBuffer(Internal::Adaptor::PixelBuffer* pointer);
 301 };
 302
 303 } // namespace Devel
 304 } // namespace Dali
 305
 306 #endif // DALI_PIXEL_BUFFER_H