inc/FGrpBitmap.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Flora License, Version 1.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://floralicense.org/license/
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an AS IS BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file        FGrpBitmap.h
  20  * @brief       This is the header file for the %Bitmap class.
  21  *
  22  * This header file contains the declarations of the %Bitmap class. @n
  23  * The class encapsulates a bitmap, which consists of the pixel data
  24  * for a graphics image and its attributes.
  25  *
  26  */
  27
  28 #ifndef _FGRP_BITMAP_H_
  29 #define _FGRP_BITMAP_H_
  30
  31 #include <FBase.h>
  32
  33 #include <FBaseObject.h>
  34 #include <FBaseByteBuffer.h>
  35 #include <FGrpPoint.h>
  36 #include <FGrpDimension.h>
  37 #include <FGrpRectangle.h>
  38 #include <FGrpColor.h>
  39 #include <FGrpBufferInfo.h>
  40 #include <FGrpBitmapCommon.h>
  41
  42 namespace Tizen { namespace Media
  43 {
  44 class Image;
  45 } }
  46
  47 namespace Tizen { namespace Graphics
  48 {
  49 class Canvas;
  50
  51 /**
  52  * @class       Bitmap
  53  * @brief       This class encapsulates a bitmap.
  54  *
  55  * @since       2.0
  56  *
  57  * @final       This class is not intended for extension.
  58  *
  59  * The %Bitmap class encapsulates a bitmap, which consists of the pixel data
  60  * for an image and its attributes.
  61  * @n
  62  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/graphics/bitmap.htm">Bitmaps</a>.
  63  *
  64  *
  65  */
  66 class _OSP_EXPORT_ Bitmap
  67         : public Tizen::Base::Object
  68 {
  69 public:
  70         /**
  71          * This is the default constructor for this class.
  72          *
  73          * @since                       2.0
  74          * @remarks             After creating an instance of this class, one of the
  75          *              Construct() methods must be called explicitly to initialize this instance.
  76          *
  77          */
  78         Bitmap(void);
  79
  80         /**
  81          * This is the destructor for this class.
  82          *
  83          * @since       2.0
  84          */
  85         virtual ~Bitmap(void);
  86
  87         /**
  88          * Initializes this instance of %Bitmap by copying a rectangular area of the Frame.
  89          *
  90          * @since                       2.0
  91          *
  92          * @return              An error code
  93          * @param[in]   rect            The rectangular area of the Frame to be copied into bitmap @n
  94          *                                                      The width and height of the rectangle must be greater than @c 0. @n
  95          *                                                      The area defined by @c rect is clipped to the edges of the Frame so that
  96          *                                                      the rectangle does not fall outside the edges of the Frame. @n
  97          *                                                      The rectangle must not fall outside the edges of the Frame entirely. @n
  98          *                                                      If these conditions are not satisfied, an E_OUT_OF_RANGE exception is returned.
  99          * @exception   E_SUCCESS                       The method is successful.
 100          * @exception   E_OUT_OF_RANGE          The value of the argument is outside the valid range defined by the method.
 101          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 102          *
 103          */
 104         result Construct(const Rectangle& rect);
 105
 106         /**
 107          * Initializes this instance of %Bitmap with the specified dimensions and pixel format.
 108          *
 109          * @since                       2.0
 110          *
 111          * @return              An error code
 112          * @param[in]   dim                     The dimensions of the bitmap @n
 113          *                                                      The width and height must be greater than @c 0.
 114          * @param[in]   format          The pixel format
 115          * @exception   E_SUCCESS                       The method is successful.
 116          * @exception   E_OUT_OF_RANGE          The value of the argument is outside the valid range defined by the method.
 117          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 118          *
 119          */
 120         result Construct(const Dimension& dim, BitmapPixelFormat format);
 121
 122         /**
 123          * Initializes this instance of %Bitmap by copying the specified rectangular area of the specified canvas.
 124          *
 125          * @since                       2.0
 126          *
 127          * @return              An error code
 128          * @param[in]   canvas          The canvas to copy @n
 129          *                                                      The canvas must be constructed successfully before it is passed into this method. @n
 130          *                                                      If not, an E_INVALID_ARG exception is returned.
 131          * @param[in]   rect            The rectangular area of the canvas to be copied into a bitmap @n
 132          *                                                      The width and height of the rectangle must be greater than @c 0. @n
 133          *                                                      The rectangle defined by @c rect is clipped to the edges of the canvas so that
 134          *                                                      the rectangle does not fall outside the edges of the canvas. @n
 135          *                                                      The rectangle must not fall outside the edges of the canvas entirely. @n
 136          *                                                      If these conditions are not satisfied, an E_OUT_OF_RANGE exception is returned.
 137          * @exception   E_SUCCESS                       The method is successful.
 138          * @exception   E_OUT_OF_RANGE          The value of the argument is outside the valid range defined by the method.
 139          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 140          *
 141          */
 142         result Construct(const Canvas& canvas, const Tizen::Graphics::Rectangle& rect);
 143
 144         /**
 145          * Initializes this instance of %Bitmap by copying a rectangular area of the specified bitmap.
 146          *
 147          * @since                       2.0
 148          *
 149          * @return              An error code
 150          * @param[in]   bitmap          The source bitmap @n
 151          *                                                      The bitmap must be constructed successfully before it is passed into this method. @n
 152          *                                                      If not, an E_INVALID_ARG exception is returned.
 153          * @param[in]   rect            The rectangular area of the source bitmap to be copied into this bitmap @n
 154          *                                                      The width and height of the rectangle must be greater than @c 0. @n
 155          *                                                      The rectangle defined by @c rect is clipped to the edges of the source bitmap so that
 156          *                                                      the rectangle does not fall outside the edges of the source bitmap. @n
 157          *                                                      The rectangle must not fall outside the edges of the source bitmap entirely. @n
 158          *                                                      If these conditions are not satisfied, an E_OUT_OF_RANGE exception is returned.
 159          * @exception   E_SUCCESS                       The method is successful.
 160          * @exception   E_OUT_OF_RANGE          The value of the argument is outside the valid range defined by the method.
 161          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 162          *
 163          */
 164         result Construct(const Bitmap& bitmap, const Tizen::Graphics::Rectangle& rect);
 165
 166         /**
 167          * Initializes this instance of %Bitmap by using a buffer that contains raw data.
 168          *
 169          * @since                       2.0
 170          *
 171          * @return              An error code
 172          * @param[in]           buffer          The buffer containing raw data
 173          * @param[in]   dim                     The dimensions of the bitmap @n
 174          *                                                      The width and height must be greater than @c 0.
 175          * @param[in]   pixelFormat     The pixel format of raw data
 176          * @exception   E_SUCCESS               The method is successful.
 177          * @exception   E_OUT_OF_RANGE  The value of the argument is outside the valid range defined by the method.
 178          * @exception   E_INVALID_ARG   A specified input parameter is invalid.
 179          * @remarks The position property of ByteBuffer can be changed.
 180          *
 181          */
 182         result Construct(const Tizen::Base::ByteBuffer& buffer, const Dimension& dim, BitmapPixelFormat pixelFormat);
 183
 184         /**
 185          * Initializes this instance of %Bitmap by using a buffer that contains raw data.
 186          *
 187          * @since       2.0
 188          *
 189          * @return     An error code
 190          * @param[in]  buffer          The buffer containing raw data
 191          * @param[in]  dim             The dimensions of the bitmap @n
 192          *                             The width and height must be greater than @c 0.
 193          * @param[in]  pixelFormat     The pixel format of raw data
 194          * @param[in]  bufferScaling   The buffer scaling type
 195          * @exception  E_SUCCESS       The method is successful.
 196          * @exception  E_INVALID_ARG   The specified input parameter is invalid.
 197          * @exception  E_UNSUPPORTED_FORMAT The specified format is not supported.
 198          * @remarks The position property of %ByteBuffer can be changed.
 199          *
 200          */
 201         result Construct(const Tizen::Base::ByteBuffer& buffer, const Dimension& dim, BitmapPixelFormat pixelFormat, BufferScaling bufferScaling);
 202
 203 public:
 204         /**
 205          * Scales the bitmap to the specified width and height.
 206          *
 207          * @since                       2.0
 208          *
 209          * @return              An error code
 210          * @param[in]   dim         The dimensions of the specified rectangular area @n
 211          *                                              The width and height must be greater than @c 0.
 212          * @exception   E_SUCCESS                       The method is successful.
 213          * @exception   E_OUT_OF_RANGE          The value of the argument is outside the valid range defined by the method.
 214          *
 215          */
 216         result Scale(const Dimension& dim);
 217
 218         /**
 219          * Merges the specified area of the source bitmap into the calling bitmap at the given Point.
 220          *
 221          * @since                       2.0
 222          *
 223          * @return              An error code
 224          * @param[in]   destPoint               The X and Y coordinate of the top-left corner of the destination area in the calling bitmap instance
 225          * @param[in]   srcBitmap               The source bitmap instance to copy from
 226          * @param[in]   srcRect             The rectangular area to copy from the source bitmap @n
 227                                         The width and height of the rectangle must be greater than or equal to @c 0.
 228          * @exception   E_SUCCESS                       The method is successful.
 229          * @exception   E_OUT_OF_RANGE          Either of the following conditions has occurred: @n
 230          *                                                                      - The value of the argument is outside the valid range defined by the method. @n
 231          *                                                                      - The destX, destY, srcX, or srcY has a negative value. @n
 232          *                                                                      - The specified @c srcWidth or @c srcHeight is less than @c 0.
 233          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 234          *
 235          */
 236         result Merge(const Point& destPoint, const Bitmap& srcBitmap, const Rectangle& srcRect);
 237
 238         /**
 239          * Gets the height of the bitmap.
 240          *
 241          * @since               2.0
 242          *
 243          * @return      The height of the bitmap, @n
 244          *                      else @c -1 if the method fails
 245          *
 246          */
 247         int GetHeight(void) const;
 248
 249         /**
 250          * Gets the width of the bitmap.
 251          *
 252          * @since               2.0
 253          *
 254          * @return      The width of the bitmap, @n
 255          *                      else @c -1 if the method fails
 256          *
 257          */
 258         int GetWidth(void) const;
 259
 260         /**
 261          * Gets the number of bits per pixel of the bitmap.
 262          *
 263          * @since               2.0
 264          *
 265          * @return      The bits per pixel, @n
 266          *                      else @c -1 if the method fails
 267          *
 268          */
 269         int GetBitsPerPixel(void) const;
 270
 271         /**
 272          * Gets the pixel color format of the bitmap.
 273          *
 274          * @since               2.0
 275          *
 276          * @return      The pixel color format
 277          *
 278          */
 279         BitmapPixelFormat GetPixelColorFormat(void) const;
 280
 281         /**
 282          * Sets the scaling quality to be used for bitmap scaling.
 283          *
 284          * @since 2.0
 285          *
 286          * @return              An error code
 287          * @param[in]   quality The scaling quality to use for bitmap scaling.
 288          * @exception   E_SUCCESS               The method is successful.
 289          * @exception   E_INVALID_ARG   A specified input parameter is invalid.
 290          *
 291          */
 292         result SetScalingQuality(BitmapScalingQuality quality);
 293
 294         /**
 295          * Gets the current scaling quality.
 296          *
 297          * @since 2.0
 298          *
 299          * @return      The scaling quality
 300          * @remarks The default value is BITMAP_SCALING_QUALITY_LOW.
 301          *
 302          */
 303         BitmapScalingQuality GetScalingQuality(void) const;
 304
 305         /**
 306          * Sets the specified color as masking color. @n
 307          * All pixels with this color are treated as transparent.
 308          *
 309          * @since                       2.0
 310          *
 311          * @return              An error code
 312          * @param[in]   pColor  The color that is treated as transparent @n
 313          *                                              If the parameter is set to @c null, the masking color is removed from this bitmap. @n
 314          *                                              Only BitmapPixelFormat::BITMAP_PIXEL_FORMAT_RGB565 is supported.
 315          * @exception   E_SUCCESS               The method is successful.
 316          * @exception   E_INVALID_ARG   A specified input parameter is invalid.
 317          *
 318          */
 319         result SetMaskingColor(const Color* pColor);
 320
 321         /**
 322          * Gets a masking color.
 323          *
 324          * @since                       2.0
 325          *
 326          * @return              An error code
 327          * @param[out]  color   The color that is treated as transparent
 328          * @exception   E_SUCCESS               The method is successful.
 329          * @exception   E_INVALID_DATA  The masking color is not defined.
 330          *
 331          */
 332         result GetMaskingColor(Color& color) const;
 333
 334         /**
 335          * Sets the alpha constant.
 336          *
 337          * @since                       2.0
 338          * @param[in]   opacity         The opacity of the bitmap @n
 339          *                                          This value ranges from @c 0 to @c 255.
 340          * @remarks The alpha constant is used for the Canvas::DrawBitmap() method.
 341          */
 342         void SetAlphaConstant(int opacity);
 343
 344         /**
 345          * Gets the alpha constant.
 346          *
 347          * @since               2.0
 348          *
 349          * @return      The alpha constant, @n
 350          *                      else @c -1 if the method fails
 351          */
 352         int GetAlphaConstant(void) const;
 353
 354         /**
 355          * Checks whether the instance is nine patched bitmap.
 356          *
 357          * @since                       2.0
 358          *
 359          * @return    @c true if the instance is nine patched bitmap, @n
 360          *                else @c false
 361          */
 362         bool IsNinePatchedBitmap(void) const;
 363
 364         /**
 365          * Locks a bitmap for direct pixel access. @n
 366          * It sets up a bitmap for accessing the pixels directly. Between the calls to Bitmap::Lock and Bitmap::Unlock,
 367          * you can write to and read from the bitmap's pixels. After you are done accessing the bitmap's pixels,
 368          * you must call Bitmap::Unlock to release the lock.
 369          *
 370          * @since                       2.0
 371          *
 372          * @return              An error code
 373          * @param[out]  info            The extra information of the bitmap
 374          * @param[in]   timeout         The time in milliseconds @n
 375          *                          This value determines the time the caller waits for the lock to be obtained. @n
 376          *                                                      If the lock attempt fails, E_TIMEOUT is returned. @n
 377          *                                                      The default value is @c INFINITE, which means that the method does not return a value until the lock is acquired.
 378          * @exception   E_SUCCESS               The method is successful.
 379          * @exception   E_TIMEOUT               The operation is not completed within the specified time period.
 380          * @exception   E_SYSTEM                An unknown operating system error has occurred.
 381          *
 382          */
 383         result Lock(BufferInfo& info, long timeout = INFINITE);
 384
 385         /**
 386          * Unlocks a bitmap. @n
 387          * A bitmap that is locked using Bitmap::Lock() must be unlocked using Bitmap::Unlock().
 388          * The bitmap buffer can be modified when the bitmap is locked, but is applied only when the bitmap is unlocked.
 389          * Therefore, all locked bitmap operations can only be used after the bitmap is unlocked using Bitmap::Unlock().
 390          *
 391          * @since                       2.0
 392          *
 393          * @return              An error code
 394          * @exception   E_SUCCESS               The method is successful.
 395          * @exception   E_SYSTEM                An unknown operating system error has occurred.
 396          *
 397          */
 398         result Unlock(void);
 399
 400         /**
 401          * Gets a non scaled bitmap.
 402          *
 403          * @since       2.0
 404          *
 405          * @return      The non scaled bitmap, @n
 406          *          else @c null if an exception occurs
 407          * @param[in]   buffer          The buffer containing raw data
 408          * @param[in]   dim                     The dimensions of the bitmap @n
 409          *                                                      The width and height must be greater than @c 0.
 410          * @param[in]   pixelFormat     The pixel format of raw data
 411          * @exception   E_SUCCESS            The method is successful.
 412          * @exception   E_INVALID_ARG        The specified input parameter is invalid.
 413          * @exception   E_UNSUPPORTED_FORMAT The specified format is not supported.
 414          *
 415          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 416          */
 417         static Bitmap* GetNonScaledBitmapN(const Tizen::Base::ByteBuffer& buffer, const Dimension& dim, BitmapPixelFormat pixelFormat);
 418
 419 private:
 420         //
 421         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 422         //
 423         Bitmap(const Bitmap& rhs);
 424
 425         //
 426         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 427         //
 428         Bitmap& operator =(const Bitmap& rhs);
 429
 430         //
 431         // This method is for internal use only.
 432         // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 433         //
 434         // Initializes this instance of %Bitmap by using a buffer that contains raw data.
 435         //
 436         // @since       2.0
 437         //
 438         // @return     An error code
 439         // @param[in]  buffer          The buffer containing raw bitmap data
 440         // @param[in]  dim             The dimensions of the bitmap @n
 441         //                             The width and height must be greater than @c 0.
 442         // @param[in]  pixelFormat     The pixel format of the raw bitmap buffer
 443         // @param[in]  autoScaling     Set to @c true to automatically scale the bitmap, @n
 444         //                                                                      else @c false
 445         // @exception  E_SUCCESS       The method is successful.
 446         // @exception  E_INVALID_ARG   A specified input parameter is invalid.
 447         // @exception  E_UNSUPPORTED_FORMAT The specified format is not supported.
 448         //
 449         result Construct(const Tizen::Base::ByteBuffer& buffer, const Dimension& dim, BitmapPixelFormat pixelFormat, bool autoScaling);
 450
 451         //
 452         // This method is for internal use only.
 453         // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 454         //
 455         // Initializes this instance of %Bitmap by using a buffer that contains raw data.
 456         //
 457         // @since       2.0
 458         //
 459         // @return     An error code
 460         // @param[in]  pBuffer         A pointer to the raw bitmap buffer
 461         // @param[in]  bufferSize      The size of the raw bitmap buffer
 462         // @param[in]  dim             The dimensions of the bitmap @n
 463         //                             The width and height must be greater than @c 0.
 464         // @param[in]  pixelFormat     The pixel format of the raw bitmap buffer
 465         // @param[in]  autoScaling     Set to @c true to automatically scale the bitmap, @n
 466         //                                                                      else @c false
 467         // @exception  E_SUCCESS       The method is successful.
 468         // @exception  E_INVALID_ARG   A specified input parameter is invalid.
 469         // @exception  E_UNSUPPORTED_FORMAT The specified format is not supported
 470         //
 471         result Construct(const byte* pBuffer, int bufferSize, const Dimension& dim, BitmapPixelFormat pixelFormat, bool autoScaling);
 472
 473         friend class Canvas;
 474         friend class Tizen::Media::Image;
 475
 476 private:
 477         friend class _BitmapImpl;
 478
 479         //
 480         // This variable is for internal use only.
 481         // Using this variable can cause behavioral, security-related, and consistency-related issues in the application.
 482         //
 483         // @since 2.0
 484         //
 485         class _BitmapImpl* __pImpl;
 486
 487 }; // Bitmap
 488
 489 }} // Tizen::Graphics
 490
 491 #endif //_FGRP_BITMAP_H_