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

   1 #ifndef DALI_PIXEL_BUFFER_H
   2 #define DALI_PIXEL_BUFFER_H
   3
   4 /*
   5  * Copyright (c) 2017 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 namespace Dali
  27 {
  28
  29 namespace Internal
  30 {
  31 namespace Adaptor
  32 {
  33 class PixelBuffer;
  34 }
  35 }
  36
  37
  38 // Use namespace to separate from PixelBuffer typedef in buffer-image.h
  39 namespace Devel
  40 {
  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_IMPORT_API PixelBuffer : public BaseHandle
  59 {
  60 public:
  61
  62   /**
  63    * Create a PixelBuffer with it's own data buffer.
  64    */
  65   static PixelBuffer New( unsigned int width,
  66                           unsigned int height,
  67                           Dali::Pixel::Format pixelFormat );
  68
  69   /**
  70    * @brief Creates an empty handle.
  71    * Use PixelBuffer::New() to create an initialized object.
  72    *
  73    * @SINCE_1_2.46
  74    */
  75   PixelBuffer();
  76
  77   /**
  78    * @brief Destructor.
  79    *
  80    * @SINCE_1_2.46
  81    */
  82   ~PixelBuffer();
  83
  84   /**
  85    * @brief This copy constructor is required for (smart) pointer semantics.
  86    *
  87    * @SINCE_1_2.46
  88    * @param[in] handle A reference to the copied handle
  89    */
  90   PixelBuffer(const PixelBuffer& handle);
  91
  92   /**
  93    * @brief This assignment operator is required for (smart) pointer semantics.
  94    *
  95    * @SINCE_1_2.46
  96    * @param[in] rhs A reference to the copied handle
  97    * @return A reference to this object
  98    */
  99   PixelBuffer& operator=(const PixelBuffer& rhs);
 100
 101   /**
 102    * Convert to a pixel data and release the pixelBuffer's object.
 103    * This handle is left empty.
 104    *
 105    * @warning Any other handles that keep a reference to this object
 106    * will be left with no buffer, trying to access it will return NULL.
 107    *
 108    * @SINCE_1_2.46
 109    * @param[in,out] pixelBuffer
 110    * @return a new PixelData which takes ownership of the PixelBuffer's buffer.
 111    */
 112   static PixelData Convert( PixelBuffer& pixelBuffer );
 113
 114   /**
 115    * Copy the data from this object into a new PixelData object, which could be
 116    * used for uploading to a texture.
 117    * @return a new PixelData object containing a copy of this pixel buffer's data.
 118    */
 119   Dali::PixelData CreatePixelData() const;
 120
 121   /**
 122    * @brief Gets the pixel buffer. This is a pointer to the internal
 123    * pixel buffer.
 124    *
 125    * @warning If there is no pixel buffer (e.g. this object has been
 126    * converted to a PixelData), this method will return NULL.
 127    *
 128    * @SINCE_1_2.46
 129    * @return The pixel buffer, or NULL.
 130    */
 131   unsigned char* GetBuffer();
 132
 133   /**
 134    * @brief Gets the width of the buffer in pixels.
 135    *
 136    * @SINCE_1_2.46
 137    * @return The width of the buffer in pixels
 138    */
 139   unsigned int GetWidth() const;
 140
 141   /**
 142    * @brief Gets the height of the buffer in pixels.
 143    *
 144    * @SINCE_1_2.46
 145    * @return The height of the buffer in pixels
 146    */
 147   unsigned int GetHeight() const;
 148
 149   /**
 150    * @brief Gets the pixel format.
 151    *
 152    * @SINCE_1_2.46
 153    * @return The pixel format
 154    */
 155   Pixel::Format GetPixelFormat() const;
 156
 157   /**
 158    * Apply the mask to this pixel data, and return a new pixel data containing
 159    * the masked image. If this PixelBuffer doesn't have an alpha channel, then
 160    * the resultant PixelBuffer will be converted to a format that supports at
 161    * least the width of the color channels and the alpha channel from the mask.
 162    *
 163    * If cropToMask is set to true, then the contentScale is applied first to
 164    * this buffer, and the target buffer is cropped to the size of the mask. If
 165    * it's set to false, then the mask is scaled to match this buffer's size
 166    * before the mask is applied.
 167    *
 168    * @param[in] mask The mask to apply.
 169    * @param[in] contentScale The scaling factor to apply to the content
 170    * @param[in] cropToMask Whether to crop the output to the mask size (true)
 171    * or scale the mask to the content size (false)
 172    */
 173   void ApplyMask( PixelBuffer mask, float contentScale=1.0f, bool cropToMask=false );
 174
 175   /**
 176    * Apply a Gaussian blur to this pixel data with the given radius.
 177    *
 178    * @note A bigger radius will yield a blurrier image. Only works for pixel data in RGBA format.
 179    *
 180    * @param[in] blurRadius The radius for Gaussian blur. A value of 0 or negative value indicates no blur.
 181    */
 182   void ApplyGaussianBlur( const float blurRadius );
 183
 184   /**
 185    * @brief Crops this buffer to the given crop rectangle.
 186    *
 187    * The crop rectangle will be clamped to the edges of the buffer if it is larger.
 188    * @param[in] x The top left corner's X
 189    * @param[in] y The top left corner's y
 190    * @param[in] width The crop width
 191    * @param[in] height The crop height
 192    */
 193   void Crop( uint16_t x, uint16_t y, uint16_t width, uint16_t height );
 194
 195   /**
 196    * @brief Resizes the buffer to the given dimensions.
 197    *
 198    * Uses either Lanczos4 for downscaling or Mitchell for upscaling
 199    * @param[in] width The new width
 200    * @param[in] height The new height
 201    */
 202   void Resize( uint16_t width, uint16_t height );
 203
 204   /**
 205    * Returns Exif metadata as a property map
 206    *
 207    * @param[out] metadata Property map object to write into
 208    * @return True on success
 209    */
 210   bool GetMetadata( Property::Map& metadata ) const;
 211
 212   /**
 213    * Multiplies the image's color values by the alpha value. This provides better
 214    * blending capability.
 215    */
 216   void MultiplyColorByAlpha();
 217
 218 public:
 219
 220   /**
 221    * @brief The constructor.
 222    * @note  Not intended for application developers.
 223    * @SINCE_1_2.46
 224    * @param[in] pointer A pointer to a newly allocated PixelBuffer
 225    */
 226   explicit DALI_INTERNAL PixelBuffer( Internal::Adaptor::PixelBuffer* pointer );
 227 };
 228
 229 } // namespace Devel
 230 } // namespace Dali
 231
 232 #endif // DALI_PIXEL_BUFFER_H