2 // Open Service Platform
3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
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
9 // http://floralicense.org/license/
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.
20 * @brief This is the header file for the %Bitmap class.
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.
28 #ifndef _FGRP_BITMAP_H_
29 #define _FGRP_BITMAP_H_
33 #include <FBaseObject.h>
34 #include <FBaseByteBuffer.h>
35 #include <FGrpPoint.h>
36 #include <FGrpFloatPoint.h>
37 #include <FGrpDimension.h>
38 #include <FGrpFloatDimension.h>
39 #include <FGrpRectangle.h>
40 #include <FGrpFloatRectangle.h>
41 #include <FGrpColor.h>
42 #include <FGrpBufferInfo.h>
43 #include <FGrpBitmapCommon.h>
45 namespace Tizen { namespace Media
50 namespace Tizen { namespace Graphics
56 * @brief This class encapsulates a bitmap.
60 * @final This class is not intended for extension.
62 * The %Bitmap class encapsulates a bitmap, which consists of the pixel data
63 * for an image and its attributes.
65 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/graphics/bitmap.htm">Bitmaps</a>.
69 class _OSP_EXPORT_ Bitmap
70 : public Tizen::Base::Object
74 * This is the default constructor for this class.
77 * @remarks After creating an instance of this class, one of the
78 * Construct() methods must be called explicitly to initialize this instance.
84 * This is the destructor for this class.
88 virtual ~Bitmap(void);
91 * Initializes this instance of %Bitmap by copying a rectangular area of the Frame.
95 * @return An error code
96 * @param[in] rect The rectangular area of the Frame to be copied into bitmap @n
97 * The width and height of the rectangle must be greater than @c 0. @n
98 * The area defined by @c rect is clipped to the edges of the Frame so that
99 * the rectangle does not fall outside the edges of the Frame. @n
100 * The rectangle must not fall outside the edges of the Frame entirely. @n
101 * If these conditions are not satisfied, an E_OUT_OF_RANGE exception is returned.
102 * @exception E_SUCCESS The method is successful.
103 * @exception E_OUT_OF_RANGE The value of the argument is outside the valid range defined by the method.
104 * @exception E_INVALID_ARG A specified input parameter is invalid.
107 result Construct(const Rectangle& rect);
110 * Initializes this instance of %Bitmap with the specified dimensions and pixel format.
114 * @return An error code
115 * @param[in] dim The dimensions of the bitmap @n
116 * The width and height must be greater than @c 0.
117 * @param[in] format The pixel format
118 * @exception E_SUCCESS The method is successful.
119 * @exception E_OUT_OF_RANGE The value of the argument is outside the valid range defined by the method.
120 * @exception E_INVALID_ARG A specified input parameter is invalid.
123 result Construct(const Dimension& dim, BitmapPixelFormat format);
126 * Initializes this instance of %Bitmap by copying the specified rectangular area of the specified canvas.
130 * @return An error code
131 * @param[in] canvas The canvas to copy @n
132 * The canvas must be constructed successfully before it is passed into this method. @n
133 * If not, an E_INVALID_ARG exception is returned.
134 * @param[in] rect The rectangular area of the canvas to be copied into a bitmap @n
135 * The width and height of the rectangle must be greater than @c 0. @n
136 * The rectangle defined by @c rect is clipped to the edges of the canvas so that
137 * the rectangle does not fall outside the edges of the canvas. @n
138 * The rectangle must not fall outside the edges of the canvas entirely. @n
139 * If these conditions are not satisfied, an E_OUT_OF_RANGE exception is returned.
140 * @exception E_SUCCESS The method is successful.
141 * @exception E_OUT_OF_RANGE The value of the argument is outside the valid range defined by the method.
142 * @exception E_INVALID_ARG A specified input parameter is invalid.
145 result Construct(const Canvas& canvas, const Tizen::Graphics::Rectangle& rect);
148 * Initializes this instance of %Bitmap by copying a rectangular area of the specified bitmap.
152 * @return An error code
153 * @param[in] bitmap The source bitmap @n
154 * The bitmap must be constructed successfully before it is passed into this method. @n
155 * If not, an E_INVALID_ARG exception is returned.
156 * @param[in] rect The rectangular area of the source bitmap to be copied into this bitmap @n
157 * The width and height of the rectangle must be greater than @c 0. @n
158 * The rectangle defined by @c rect is clipped to the edges of the source bitmap so that
159 * the rectangle does not fall outside the edges of the source bitmap. @n
160 * The rectangle must not fall outside the edges of the source bitmap entirely. @n
161 * If these conditions are not satisfied, an E_OUT_OF_RANGE exception is returned.
162 * @exception E_SUCCESS The method is successful.
163 * @exception E_OUT_OF_RANGE The value of the argument is outside the valid range defined by the method.
164 * @exception E_INVALID_ARG A specified input parameter is invalid.
167 result Construct(const Bitmap& bitmap, const Tizen::Graphics::Rectangle& rect);
170 * Initializes this instance of %Bitmap by using a buffer that contains raw data.
174 * @return An error code
175 * @param[in] buffer The buffer containing raw data
176 * @param[in] dim The dimensions of the bitmap @n
177 * The width and height must be greater than @c 0.
178 * @param[in] pixelFormat The pixel format of raw data
179 * @exception E_SUCCESS The method is successful.
180 * @exception E_OUT_OF_RANGE The value of the argument is outside the valid range defined by the method.
181 * @exception E_INVALID_ARG A specified input parameter is invalid.
182 * @remarks The position property of ByteBuffer can be changed.
185 result Construct(const Tizen::Base::ByteBuffer& buffer, const Dimension& dim, BitmapPixelFormat pixelFormat);
188 * Initializes this instance of %Bitmap by using a buffer that contains raw data.
192 * @return An error code
193 * @param[in] buffer The buffer containing raw data
194 * @param[in] dim The dimensions of the bitmap @n
195 * The width and height must be greater than @c 0.
196 * @param[in] pixelFormat The pixel format of raw data
197 * @param[in] bufferScaling The buffer scaling type
198 * @exception E_SUCCESS The method is successful.
199 * @exception E_INVALID_ARG The specified input parameter is invalid.
200 * @exception E_UNSUPPORTED_FORMAT The specified format is not supported.
201 * @remarks The position property of %ByteBuffer can be changed.
204 result Construct(const Tizen::Base::ByteBuffer& buffer, const Dimension& dim, BitmapPixelFormat pixelFormat, BufferScaling bufferScaling);
207 * Initializes this instance of %Bitmap by copying a rectangular area of the Frame.
211 * @return An error code
212 * @param[in] rect The rectangular area of the Frame to be copied into bitmap @n
213 * The width and height of the rectangle must be greater than @c 0. @n
214 * The area defined by @c rect is clipped to the edges of the Frame so that
215 * the rectangle does not fall outside the edges of the Frame. @n
216 * The rectangle must not fall outside the edges of the Frame entirely. @n
217 * If these conditions are not satisfied, an E_OUT_OF_RANGE exception is returned.
218 * @exception E_SUCCESS The method is successful.
219 * @exception E_OUT_OF_RANGE The value of the argument is outside the valid range defined by the method.
220 * @exception E_INVALID_ARG A specified input parameter is invalid.
223 result Construct(const FloatRectangle& rect);
226 * Initializes this instance of %Bitmap with the specified dimensions and pixel format.
230 * @return An error code
231 * @param[in] dim The dimensions of the bitmap @n
232 * The width and height must be greater than @c 0.
233 * @param[in] format The pixel format
234 * @exception E_SUCCESS The method is successful.
235 * @exception E_OUT_OF_RANGE The value of the argument is outside the valid range defined by the method.
236 * @exception E_INVALID_ARG A specified input parameter is invalid.
239 result Construct(const FloatDimension& dim, BitmapPixelFormat format);
242 * Initializes this instance of %Bitmap by copying the specified rectangular area of the specified canvas.
246 * @return An error code
247 * @param[in] canvas The canvas to copy @n
248 * The canvas must be constructed successfully before it is passed into this method. @n
249 * If not, an E_INVALID_ARG exception is returned.
250 * @param[in] rect The rectangular area of the canvas to be copied into a bitmap @n
251 * The width and height of the rectangle must be greater than @c 0. @n
252 * The rectangle defined by @c rect is clipped to the edges of the canvas so that
253 * the rectangle does not fall outside the edges of the canvas. @n
254 * The rectangle must not fall outside the edges of the canvas entirely. @n
255 * If these conditions are not satisfied, an E_OUT_OF_RANGE exception is returned.
256 * @exception E_SUCCESS The method is successful.
257 * @exception E_OUT_OF_RANGE The value of the argument is outside the valid range defined by the method.
258 * @exception E_INVALID_ARG A specified input parameter is invalid.
261 result Construct(const Canvas& canvas, const FloatRectangle& rect);
264 * Initializes this instance of %Bitmap by copying a rectangular area of the specified bitmap.
268 * @return An error code
269 * @param[in] bitmap The source bitmap @n
270 * The bitmap must be constructed successfully before it is passed into this method. @n
271 * If not, an E_INVALID_ARG exception is returned.
272 * @param[in] rect The rectangular area of the source bitmap to be copied into this bitmap @n
273 * The width and height of the rectangle must be greater than @c 0. @n
274 * The rectangle defined by @c rect is clipped to the edges of the source bitmap so that
275 * the rectangle does not fall outside the edges of the source bitmap. @n
276 * The rectangle must not fall outside the edges of the source bitmap entirely. @n
277 * If these conditions are not satisfied, an E_OUT_OF_RANGE exception is returned.
278 * @exception E_SUCCESS The method is successful.
279 * @exception E_OUT_OF_RANGE The value of the argument is outside the valid range defined by the method.
280 * @exception E_INVALID_ARG A specified input parameter is invalid.
283 result Construct(const Bitmap& bitmap, const FloatRectangle& rect);
287 * Scales the bitmap to the specified width and height.
291 * @return An error code
292 * @param[in] dim The dimensions of the specified rectangular area @n
293 * The width and height must be greater than @c 0.
294 * @exception E_SUCCESS The method is successful.
295 * @exception E_OUT_OF_RANGE The value of the argument is outside the valid range defined by the method.
298 result Scale(const Dimension& dim);
301 * Scales the bitmap to the specified width and height.
305 * @return An error code
306 * @param[in] dim The dimensions of the specified rectangular area @n
307 * The width and height must be greater than @c 0.
308 * @exception E_SUCCESS The method is successful.
309 * @exception E_OUT_OF_RANGE The value of the argument is outside the valid range defined by the method.
312 result Scale(const FloatDimension& dim);
315 * Merges the specified area of the source bitmap into the calling bitmap at the given Point.
319 * @return An error code
320 * @param[in] destPoint The X and Y coordinate of the top-left corner of the destination area in the calling bitmap instance
321 * @param[in] srcBitmap The source bitmap instance to copy from
322 * @param[in] srcRect The rectangular area to copy from the source bitmap @n
323 The width and height of the rectangle must be greater than or equal to @c 0.
324 * @exception E_SUCCESS The method is successful.
325 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: @n
326 * - The value of the argument is outside the valid range defined by the method. @n
327 * - The destX, destY, srcX, or srcY has a negative value. @n
328 * - The specified @c srcWidth or @c srcHeight is less than @c 0.
329 * @exception E_INVALID_ARG A specified input parameter is invalid.
332 result Merge(const Point& destPoint, const Bitmap& srcBitmap, const Rectangle& srcRect);
335 * Merges the specified area of the source bitmap into the calling bitmap at the given Point.
339 * @return An error code
340 * @param[in] destPoint The X and Y coordinate of the top-left corner of the destination area in the calling bitmap instance
341 * @param[in] srcBitmap The source bitmap instance to copy from
342 * @param[in] srcRect The rectangular area to copy from the source bitmap @n
343 The width and height of the rectangle must be greater than or equal to @c 0.
344 * @exception E_SUCCESS The method is successful.
345 * @exception E_OUT_OF_RANGE Either of the following conditions has occurred: @n
346 * - The value of the argument is outside the valid range defined by the method. @n
347 * - The destX, destY, srcX, or srcY has a negative value. @n
348 * - The specified @c srcWidth or @c srcHeight is less than @c 0.
349 * @exception E_INVALID_ARG A specified input parameter is invalid.
352 result Merge(const FloatPoint& destPoint, const Bitmap& srcBitmap, const FloatRectangle& srcRect);
355 * Gets the height of the bitmap.
359 * @return The height of the bitmap, @n
360 * else @c -1 if the method fails
363 int GetHeight(void) const;
366 * Gets the height of the bitmap.
370 * @return The height of the bitmap, @n
371 * else @c -1 if the method fails
374 float GetHeightF(void) const;
377 * Gets the actual height of the bitmap.
381 * @return The actual height of the bitmap, @n
382 * else @c -1.0f if the method fails
385 float GetActualHeight(void) const;
388 * Gets the width of the bitmap.
392 * @return The width of the bitmap, @n
393 * else @c -1 if the method fails
396 int GetWidth(void) const;
399 * Gets the width of the bitmap.
403 * @return The width of the bitmap, @n
404 * else @c -1 if the method fails
407 float GetWidthF(void) const;
410 * Gets the actual width of the bitmap.
414 * @return The actual width of the bitmap, @n
415 * else @c -1.0f if the method fails
418 float GetActualWidth(void) const;
421 * Gets the number of bits per pixel of the bitmap.
425 * @return The bits per pixel, @n
426 * else @c -1 if the method fails
429 int GetBitsPerPixel(void) const;
432 * Gets the pixel color format of the bitmap.
436 * @return The pixel color format
439 BitmapPixelFormat GetPixelColorFormat(void) const;
442 * Sets the scaling quality to be used for bitmap scaling.
446 * @return An error code
447 * @param[in] quality The scaling quality to use for bitmap scaling.
448 * @exception E_SUCCESS The method is successful.
449 * @exception E_INVALID_ARG A specified input parameter is invalid.
452 result SetScalingQuality(BitmapScalingQuality quality);
455 * Gets the current scaling quality.
459 * @return The scaling quality
460 * @remarks The default value is BITMAP_SCALING_QUALITY_LOW.
463 BitmapScalingQuality GetScalingQuality(void) const;
466 * Sets the specified color as masking color. @n
467 * All pixels with this color are treated as transparent.
471 * @return An error code
472 * @param[in] pColor The color that is treated as transparent @n
473 * If the parameter is set to @c null, the masking color is removed from this bitmap. @n
474 * Only BitmapPixelFormat::BITMAP_PIXEL_FORMAT_RGB565 is supported.
475 * @exception E_SUCCESS The method is successful.
476 * @exception E_INVALID_ARG A specified input parameter is invalid.
479 result SetMaskingColor(const Color* pColor);
482 * Gets a masking color.
486 * @return An error code
487 * @param[out] color The color that is treated as transparent
488 * @exception E_SUCCESS The method is successful.
489 * @exception E_INVALID_DATA The masking color is not defined.
492 result GetMaskingColor(Color& color) const;
495 * Sets the alpha constant.
498 * @param[in] opacity The opacity of the bitmap @n
499 * This value ranges from @c 0 to @c 255.
500 * @remarks The alpha constant is used for the Canvas::DrawBitmap() method.
502 void SetAlphaConstant(int opacity);
505 * Gets the alpha constant.
509 * @return The alpha constant, @n
510 * else @c -1 if the method fails
512 int GetAlphaConstant(void) const;
515 * Checks whether the instance is nine patched bitmap.
519 * @return @c true if the instance is nine patched bitmap, @n
522 bool IsNinePatchedBitmap(void) const;
525 * Locks a bitmap for direct pixel access. @n
526 * It sets up a bitmap for accessing the pixels directly. Between the calls to Bitmap::Lock and Bitmap::Unlock,
527 * you can write to and read from the bitmap's pixels. After you are done accessing the bitmap's pixels,
528 * you must call Bitmap::Unlock to release the lock.
532 * @return An error code
533 * @param[out] info The extra information of the bitmap
534 * @param[in] timeout The time in milliseconds @n
535 * This value determines the time the caller waits for the lock to be obtained. @n
536 * If the lock attempt fails, E_TIMEOUT is returned. @n
537 * The default value is @c INFINITE, which means that the method does not return a value until the lock is acquired.
538 * @exception E_SUCCESS The method is successful.
539 * @exception E_TIMEOUT The operation is not completed within the specified time period.
540 * @exception E_SYSTEM An unknown operating system error has occurred.
543 result Lock(BufferInfo& info, long timeout = INFINITE);
546 * Unlocks a bitmap. @n
547 * A bitmap that is locked using Bitmap::Lock() must be unlocked using Bitmap::Unlock().
548 * The bitmap buffer can be modified when the bitmap is locked, but is applied only when the bitmap is unlocked.
549 * Therefore, all locked bitmap operations can only be used after the bitmap is unlocked using Bitmap::Unlock().
553 * @return An error code
554 * @exception E_SUCCESS The method is successful.
555 * @exception E_SYSTEM An unknown operating system error has occurred.
561 * Gets a non scaled bitmap.
565 * @return The non scaled bitmap, @n
566 * else @c null if an exception occurs
567 * @param[in] buffer The buffer containing raw data
568 * @param[in] dim The dimensions of the bitmap @n
569 * The width and height must be greater than @c 0.
570 * @param[in] pixelFormat The pixel format of raw data
571 * @exception E_SUCCESS The method is successful.
572 * @exception E_INVALID_ARG The specified input parameter is invalid.
573 * @exception E_UNSUPPORTED_FORMAT The specified format is not supported.
575 * @remarks The specific error code can be accessed using the GetLastResult() method.
577 static Bitmap* GetNonScaledBitmapN(const Tizen::Base::ByteBuffer& buffer, const Dimension& dim, BitmapPixelFormat pixelFormat);
581 // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
583 Bitmap(const Bitmap& rhs);
586 // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
588 Bitmap& operator =(const Bitmap& rhs);
591 // This method is for internal use only.
592 // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
594 // Initializes this instance of %Bitmap by using a buffer that contains raw data.
598 // @return An error code
599 // @param[in] buffer The buffer containing raw bitmap data
600 // @param[in] dim The dimensions of the bitmap @n
601 // The width and height must be greater than @c 0.
602 // @param[in] pixelFormat The pixel format of the raw bitmap buffer
603 // @param[in] autoScaling Set to @c true to automatically scale the bitmap, @n
605 // @exception E_SUCCESS The method is successful.
606 // @exception E_INVALID_ARG A specified input parameter is invalid.
607 // @exception E_UNSUPPORTED_FORMAT The specified format is not supported.
609 result Construct(const Tizen::Base::ByteBuffer& buffer, const Dimension& dim, BitmapPixelFormat pixelFormat, bool autoScaling);
612 // This method is for internal use only.
613 // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
615 // Initializes this instance of %Bitmap by using a buffer that contains raw data.
619 // @return An error code
620 // @param[in] pBuffer A pointer to the raw bitmap buffer
621 // @param[in] bufferSize The size of the raw bitmap buffer
622 // @param[in] dim The dimensions of the bitmap @n
623 // The width and height must be greater than @c 0.
624 // @param[in] pixelFormat The pixel format of the raw bitmap buffer
625 // @param[in] autoScaling Set to @c true to automatically scale the bitmap, @n
627 // @exception E_SUCCESS The method is successful.
628 // @exception E_INVALID_ARG A specified input parameter is invalid.
629 // @exception E_UNSUPPORTED_FORMAT The specified format is not supported
631 result Construct(const byte* pBuffer, int bufferSize, const Dimension& dim, BitmapPixelFormat pixelFormat, bool autoScaling);
634 friend class Tizen::Media::Image;
637 friend class _BitmapImpl;
640 // This variable is for internal use only.
641 // Using this variable can cause behavioral, security-related, and consistency-related issues in the application.
645 class _BitmapImpl* __pImpl;
649 }} // Tizen::Graphics
651 #endif //_FGRP_BITMAP_H_