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 #include <dali/public-api/images/pixel.h>
  22 #include <dali/public-api/images/pixel-data.h>
  23 #include <dali/public-api/object/base-handle.h>
  24
  25 namespace Dali
  26 {
  27
  28 namespace Internal
  29 {
  30 namespace Adaptor
  31 {
  32 class PixelBuffer;
  33 }
  34 }
  35
  36 // Use namespace to separate from PixelBuffer typedef in buffer-image.h
  37 namespace Devel
  38 {
  39
  40 /**
  41  * @brief The PixelBuffer object holds a pixel buffer.
  42  *
  43  * The PixelBuffer keeps ownership of it's initial buffer however, the
  44  * user is free to modify the pixel data, either directly, or via
  45  * image operations.
  46  *
  47  * In order to upload the pixel data to texture memory, there are two
  48  * possibilities - either convert it back to a PixelData object, which
  49  * releases the PixelBuffer object, leaving the user with an empty handle
  50  * (ideal for one-time indirect image manipulation), or create a new
  51  * PixelData object from this object, leaving the buffer intact (ideal
  52  * for continuous manipulation)
  53  *
  54  * @SINCE_1_2.46
  55  */
  56 class DALI_IMPORT_API PixelBuffer : public BaseHandle
  57 {
  58 public:
  59
  60   /**
  61    * Create a PixelBuffer with it's own data buffer.
  62    */
  63   static PixelBuffer New( unsigned int width,
  64                           unsigned int height,
  65                           Dali::Pixel::Format pixelFormat );
  66
  67   /**
  68    * @brief Creates an empty handle.
  69    * Use PixelBuffer::New() to create an initialized object.
  70    *
  71    * @SINCE_1_2.46
  72    */
  73   PixelBuffer();
  74
  75   /**
  76    * @brief Destructor.
  77    *
  78    * @SINCE_1_2.46
  79    */
  80   ~PixelBuffer();
  81
  82   /**
  83    * @brief This copy constructor is required for (smart) pointer semantics.
  84    *
  85    * @SINCE_1_2.46
  86    * @param[in] handle A reference to the copied handle
  87    */
  88   PixelBuffer(const PixelBuffer& handle);
  89
  90   /**
  91    * @brief This assignment operator is required for (smart) pointer semantics.
  92    *
  93    * @SINCE_1_2.46
  94    * @param[in] rhs A reference to the copied handle
  95    * @return A reference to this object
  96    */
  97   PixelBuffer& operator=(const PixelBuffer& rhs);
  98
  99   /**
 100    * Convert to a pixel data and release the pixelBuffer's object.
 101    * This handle is left empty.
 102    *
 103    * @warning Any other handles that keep a reference to this object
 104    * will be left with no buffer, trying to access it will return NULL.
 105    *
 106    * @SINCE_1_2.46
 107    * @param[in,out] pixelBuffer
 108    * @return a new PixelData which takes ownership of the PixelBuffer's buffer.
 109    */
 110   static PixelData Convert( PixelBuffer& pixelBuffer );
 111
 112   /**
 113    * Copy the data from this object into a new PixelData object, which could be
 114    * used for uploading to a texture.
 115    * @return a new PixelData object containing a copy of this pixel buffer's data.
 116    */
 117   Dali::PixelData CreatePixelData() const;
 118
 119   /**
 120    * @brief Gets the pixel buffer. This is a pointer to the internal
 121    * pixel buffer.
 122    *
 123    * @warning If there is no pixel buffer (e.g. this object has been
 124    * converted to a PixelData), this method will return NULL.
 125    *
 126    * @SINCE_1_2.46
 127    * @return The pixel buffer, or NULL.
 128    */
 129   unsigned char* GetBuffer();
 130
 131   /**
 132    * @brief Gets the width of the buffer in pixels.
 133    *
 134    * @SINCE_1_2.46
 135    * @return The width of the buffer in pixels
 136    */
 137   unsigned int GetWidth() const;
 138
 139   /**
 140    * @brief Gets the height of the buffer in pixels.
 141    *
 142    * @SINCE_1_2.46
 143    * @return The height of the buffer in pixels
 144    */
 145   unsigned int GetHeight() const;
 146
 147   /**
 148    * @brief Gets the pixel format.
 149    *
 150    * @SINCE_1_2.46
 151    * @return The pixel format
 152    */
 153   Pixel::Format GetPixelFormat() const;
 154
 155   /**
 156    * Apply the mask to this pixel data, and return a new pixel data containing
 157    * the masked image. If this PixelBuffer doesn't have an alpha channel, then
 158    * the resultant PixelBuffer will be converted to a format that supports at
 159    * least the width of the color channels and the alpha channel from the mask.
 160    *
 161    * If cropToMask is set to true, then the contentScale is applied first to
 162    * this buffer, and the target buffer is cropped to the size of the mask. If
 163    * it's set to false, then the mask is scaled to match this buffer's size
 164    * before the mask is applied.
 165    *
 166    * @param[in] mask The mask to apply.
 167    * @param[in] contentScale The scaling factor to apply to the content
 168    * @param[in] cropToMask Whether to crop the output to the mask size (true)
 169    * or scale the mask to the content size (false)
 170    */
 171   void ApplyMask( PixelBuffer mask, float contentScale=1.0f, bool cropToMask=false );
 172
 173   /**
 174    * Apply a Gaussian blur to this pixel data with the given radius.
 175    *
 176    * @note A bigger radius will yield a blurrier image. Only works for pixel data in RGBA format.
 177    *
 178    * @param[in] blurRadius The radius for Gaussian blur. A value of 0 or negative value indicates no blur.
 179    */
 180   void ApplyGaussianBlur( const float blurRadius );
 181
 182 public:
 183
 184   /**
 185    * @brief The constructor.
 186    * @note  Not intended for application developers.
 187    * @SINCE_1_2.46
 188    * @param[in] pointer A pointer to a newly allocated PixelBuffer
 189    */
 190   explicit DALI_INTERNAL PixelBuffer( Internal::Adaptor::PixelBuffer* pointer );
 191 };
 192
 193 } // namespace Devel
 194 } // namespace Dali
 195
 196 #endif // DALI_PIXEL_BUFFER_H