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