2 // Open Service Platform
3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
5 // Licensed under the Apache License, Version 2.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://www.apache.org/licenses/LICENSE-2.0
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.
19 * @file FMediaImageBuffer.h
20 * @brief This is the header file for the %ImageBuffer class.
22 * This header file contains the declarations of the %ImageBuffer class.
25 #ifndef _FMEDIA_IMAGEBUFFER_H_
26 #define _FMEDIA_IMAGEBUFFER_H_
28 #include <FMediaImage.h>
30 namespace Tizen { namespace Media
34 * @brief This class is used for handling decoded image data.
37 * @remarks The minimum dimension is 16x16 for JPEG encoding and 8x8 for PNG encoding.
39 * The %ImageBuffer class is used for handling decoded image data, including image decoding and encoding.
41 * The following example demonstrates how to use the %ImageBuffer class to decode and encode image.
47 using namespace Tizen::Base;
48 using namespace Tizen::Media;
56 // Constructs an image buffer instance with an image file
57 r = img.Construct(Tizen::App::App::GetInstance()->GetAppRootPath() + L"data/test.bmp");
62 // Encodes the image buffer into compressed data
63 r = img.EncodeToFile(Tizen::App::App::GetInstance()->GetAppRootPath()+L"data/test.jpg", IMG_FORMAT_JPG, true, 70);
70 class _OSP_EXPORT_ ImageBuffer
71 : public Tizen::Base::Object
75 * This is the default constructor for this class. @n
76 * The object is not fully constructed after this constructor is called.
77 * For full construction, the Construct() method must be called right after
78 * calling this constructor.
87 * This is the destructor for this class. @n
88 * This destructor overrides Tizen::Base::Object::~Object().
94 virtual ~ImageBuffer(void);
97 * Initializes this instance of %ImageBuffer with the specified parameters.
101 * @return An error code
102 * @param[in] width The width of the image
103 * @param[in] height The height of the image
104 * @param[in] pixelFormat The pixel format of the image should be one of the values returned by GetSupportedPixelFormatListN()
105 * @param[in] pData The raw pixel data of the image @n If @c pData is not @c null, then it is copied into the internal buffer of this instance.
106 * If @c null, then the default color data is filled.
107 * @param[in] length The size of the data
108 * @exception E_SUCCESS The method is successful.
109 * @exception E_INVALID_ARG A specified input parameter is invalid.
110 * @exception E_UNSUPPORTED_FORMAT The specified @c pixelFormat is not supported.
111 * @exception E_OUT_OF_MEMORY The memory is insufficient.
112 * @remarks There is a high probability for an occurrence of an out-of-memory exception. If possible, check whether the exception is @c E_OUT_OF_MEMORY or not.
113 * For more information on how to handle the out-of-memory exception, refer <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.
114 * @see GetSupportedPixelFormatListN()
116 result Construct(int width, int height, MediaPixelFormat pixelFormat, const byte* pData = null, int length = 0);
119 * Initializes this instance of %ImageBuffer with the decoded data of the given image path.
123 * @return An error code
124 * @param[in] srcImagePath The source image path
125 * @param[in] pDecodingRegion The region that is decoded @n If this is @c null, then the whole image is decoded.
126 * @param[in] autoRotate If @c true the image is rotated automatically based on the EXIF orientation tag before decoding @n
127 * If @c false the image is decoded without rotation.
128 * @exception E_SUCCESS The method is successful.
129 * @exception E_INVALID_ARG A specified input parameter is invalid.
130 * @exception E_UNSUPPORTED_FORMAT The specified format is not supported.
131 * @exception E_OVERFLOW The specified input instance exceeds the supported maximum file size or dimension.
132 * @exception E_OUT_OF_MEMORY The memory is insufficient.
133 * @exception E_FILE_NOT_FOUND The specified file cannot be found or accessed.
134 * @remarks There is a high probability for an occurrence of an out-of-memory exception. If possible, check whether the exception is @c E_OUT_OF_MEMORY or not.
135 * For more information on how to handle the out-of-memory exception, refer <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.
137 result Construct(const Tizen::Base::String &srcImagePath, const Tizen::Graphics::Rectangle *pDecodingRegion = null, bool autoRotate = true);
140 * Initializes this instance of %ImageBuffer with the decoded data of the given image buffer.
144 * @return An error code
145 * @param[in] srcImageBuf The buffer that contains the compressed image data
146 * @param[in] pDecodingRegion The region that is decoded @n If this is @c null, then the whole image is decoded.
147 * @param[in] autoRotate If @c true the image is rotated automatically based on the EXIF orientation tag before decoding @n
148 * If @c false the image is decoded without rotation.
149 * @exception E_SUCCESS The method is successful.
150 * @exception E_INVALID_ARG A specified input parameter is invalid.
151 * @exception E_UNSUPPORTED_FORMAT The specified format is not supported.
152 * @exception E_OVERFLOW The specified input instance exceeds the supported maximum file size or dimension.
153 * @exception E_OUT_OF_MEMORY The memory is insufficient.
154 * @remarks There is a high probability for an occurrence of an out-of-memory exception. If possible, check whether the exception is @c E_OUT_OF_MEMORY or not.
155 * For more information on how to handle the out-of-memory exception, refer <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.
157 result Construct(const Tizen::Base::ByteBuffer &srcImageBuf, const Tizen::Graphics::Rectangle *pDecodingRegion = null, bool autoRotate = true);
160 * Initializes this instance of %ImageBuffer with the given bitmap data. @n
161 * The %Construct() method copies the raw RGB data from the @c srcBitmap,
162 * so the dimension of this instance can be different from that of @c srcBitmap if the @c srcBitmap is an auto-scaled bitmap.
166 * @return An error code
167 * @param[in] srcBitmap The source bitmap data
168 * @exception E_SUCCESS The method is successful.
169 * @exception E_INVALID_ARG The specified input parameter is invalid.
170 * @exception E_OVERFLOW The specified input instance exceeds the supported maximum file size or dimension.
171 * @exception E_OUT_OF_MEMORY The memory is insufficient.
173 result Construct(const Tizen::Graphics::Bitmap &srcBitmap);
176 * Initializes this instance of %ImageBuffer that is decoded with the data of the given image path with the specified parameters.
180 * @return An error code
181 * @param[in] srcImagePath The source image path
182 * @param[in] destWidth The intended width of the image
183 * @param[in] destHeight The intended height of the image
184 * @param[in] scalingMethod The scaling method
185 * @exception E_SUCCESS The method is successful.
186 * @exception E_INVALID_ARG A specified input parameter is invalid.
187 * @exception E_UNSUPPORTED_FORMAT The specified format is not supported.
188 * @exception E_OUT_OF_MEMORY The memory is insufficient.
189 * @exception E_FILE_NOT_FOUND The specified file cannot be found or accessed.
190 * @remarks There is a high probability for an occurrence of an out-of-memory exception.
191 * If possible, check whether the exception is E_OUT_OF_MEMORY or not. @n
192 * For more information on how to handle the out-of-memory exception, refer
193 * <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.
194 * @remarks This method does not retain the aspect ratio of the original image.
196 result Construct(const Tizen::Base::String &srcImagePath, int destWidth, int destHeight, ImageScalingMethod scalingMethod);
199 * Initializes this instance of %ImageBuffer that is decoded with the data of the given image buffer with the specified parameters.
203 * @return An error code
204 * @param[in] srcImageBuf The buffer that contains the compressed image data
205 * @param[in] destWidth The intended width of the image
206 * @param[in] destHeight The intended height of the image
207 * @param[in] scalingMethod The scaling method
208 * @exception E_SUCCESS The method is successful.
209 * @exception E_INVALID_ARG A specified input parameter is invalid.
210 * @exception E_UNSUPPORTED_FORMAT The specified format is not supported.
211 * @exception E_OUT_OF_MEMORY The memory is insufficient.
212 * @remarks There is a high probability for an occurrence of an out-of-memory exception.
213 * If possible, check whether the exception is E_OUT_OF_MEMORY or not. @n
214 * For more information on how to handle the out-of-memory exception, refer
215 * <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.
216 * @remarks This method does not retain the aspect ratio of the original image.
218 result Construct(const Tizen::Base::ByteBuffer &srcImageBuf, int destWidth, int destHeight, ImageScalingMethod scalingMethod);
221 * Gets the current exif orientation of the image data. @n
222 * If automatic rotation is enabled during Construct() then the orientation is reset to the default value.
226 * @return The orientation information of the current image data
228 ExifOrientation GetExifOrientation(void) const;
232 * Converts an instance of the Tizen::Base::Object class to an instance of %ImageBuffer and then
233 * compares it with the calling %ImageBuffer instance.
237 * @return @c true if the value of @c rhs matches the value of the calling %ImageBuffer instance, @n
239 * @param[in] rhs A reference to the Tizen::Base::Object instance that is to compare with the calling %ImageBuffer instance
240 * @see Tizen::Base::Object::Equals()
242 virtual bool Equals(const Object& rhs) const;
245 * Gets the hash value of the current instance by overriding the GetHashCode() method in the Tizen::Base::Object class.
249 * @return The hash value of the current instance
251 virtual int GetHashCode(void) const;
254 * Gets the height of the image buffer.
258 * @return The height of the image buffer
260 int GetHeight(void) const;
263 * Gets the width of the image buffer.
267 * @return The width of the image buffer
269 int GetWidth(void) const;
272 * Gets the current pixel format.
276 * @return The pixel format of the media
278 MediaPixelFormat GetPixelFormat(void) const;
281 * Encodes the data of this instance into a byte buffer. @n
282 * The supported encoding formats are JPEG, BMP, and PNG.
286 * @return A pointer to the Tizen::Base::ByteBuffer instance containing the encoded image data
287 * @param[in] destImageFormat The intended image format
288 * @param[in] quality The encoding quality @n
289 * Valid range of this parameter is @c 1 to @c 100.
290 * @exception E_SUCCESS The method is successful.
291 * @exception E_OUT_OF_RANGE A specified input parameter is out of range.
292 * @exception E_UNSUPPORTED_FORMAT The specified format is not supported.
293 * @exception E_OUT_OF_MEMORY The memory is insufficient.
294 * @remarks The specific error code can be accessed using the GetLastResult() method.
296 Tizen::Base::ByteBuffer* EncodeToBufferN(ImageFormat destImageFormat, int quality = 90) const;
299 * Encodes the data of this instance to a file. @n
300 * The supported encoding formats are JPEG, BMP, and PNG.
304 * @return An error code
305 * @param[in] destImagePath The intended name of the encoded image file
306 * @param[in] destImageFormat The intended image format
307 * @param[in] overwrite Set to @c true to overwrite the file, @n
309 * @param[in] quality The encoding quality @n
310 * Valid range of this parameter is @c 1 to @c 100.
311 * @exception E_SUCCESS The method is successful.
312 * @exception E_UNSUPPORTED_FORMAT The specified format is not supported.
313 * @exception E_OUT_OF_MEMORY The memory is insufficient.
314 * @exception E_ILLEGAL_ACCESS The specified file cannot be found or accessed.
315 * @exception E_FILE_ALREADY_EXIST The specified file already exists and the value of @c overwrite is @c false.
316 * @exception E_OUT_OF_RANGE A specified input parameter is out of range.
317 * @remarks The application should use Tizen::Content::ContentManager::CreateContent() to
318 * register the created file into the Contents database.
320 result EncodeToFile(const Tizen::Base::String &destImagePath, ImageFormat destImageFormat, bool overwrite, int quality = 90) const;
323 * Gets an instance of Tizen::Graphics::Bitmap with the data of this instance.
327 * @return A pointer to the Tizen::Graphics::Bitmap instance
328 * @param[in] pixelFormat The bitmap pixel format
329 * @param[in] bufferScaling The buffer scaling type
330 * @exception E_SUCCESS The method is successful.
331 * @exception E_INVALID_ARG A specified input parameter is invalid.
332 * @exception E_UNSUPPORTED_FORMAT The specified format is not supported.
333 * @exception E_OUT_OF_MEMORY The memory is insufficient.
334 * @remarks The specific error code can be accessed using the GetLastResult() method.
336 Tizen::Graphics::Bitmap* GetBitmapN(Tizen::Graphics::BitmapPixelFormat pixelFormat, Tizen::Graphics::BufferScaling bufferScaling) const;
339 * Gets an instance of Tizen::Graphics::Bitmap with the data of this instance after resizing it as per the specified width and height
343 * @return A pointer to the Tizen::Graphics::Bitmap instance with the specified destination width and height.
344 * @param[in] pixelFormat The bitmap pixel format
345 * @param[in] destWidth The intended width of the image.
346 * @param[in] destHeight The intended height of the image.
347 * @exception E_SUCCESS The method is successful.
348 * @exception E_INVALID_ARG A specified input parameter is invalid.
349 * @exception E_UNSUPPORTED_FORMAT The specified format is not supported.
350 * @exception E_OUT_OF_MEMORY The memory is insufficient.
351 * @remarks The specific error code can be accessed using the GetLastResult() method.
352 * @remarks This method returns auto scaled bitmap to support logical coordinate system,
353 * so the actual dimension of the returned bitmap can be vary depending on the physical dimension of target device.
355 Tizen::Graphics::Bitmap* GetBitmapN(Tizen::Graphics::BitmapPixelFormat pixelFormat, float destWidth, float destHeight) const;
358 * Gets an instance of Tizen::Base::ByteBuffer with the data of this instance.
362 * @return A pointer to the Tizen::Base::ByteBuffer instance
363 * @param[in] pixelFormat The pixel format
364 * @exception E_SUCCESS The method is successful.
365 * @exception E_INVALID_ARG The specified input parameter is invalid.
366 * @exception E_UNSUPPORTED_FORMAT The specified format is not supported.
367 * @exception E_OUT_OF_MEMORY The memory is insufficient.
368 * @remarks The specific error code can be accessed using the GetLastResult() method.
369 * @see GetSupportedPixelFormatListN()
371 Tizen::Base::ByteBuffer* GetByteBufferN(MediaPixelFormat pixelFormat) const;
374 * Creates and returns a copy of this instance.
378 * @return A copy of this instance
379 * @exception E_SUCCESS The method is successful.
380 * @exception E_OUT_OF_MEMORY The memory is insufficient.
381 * @remarks The specific error code can be accessed using the GetLastResult() method.
383 virtual ImageBuffer* CloneN(void) const;
386 * Gets a new %ImageBuffer with the converted pixel format of the current image data.
390 * @return A pointer to the %ImageBuffer instance containing the converted %ImageBuffer by the specified MediaPixelFormat
391 * @param[in] pixelFormat The pixel format for returned %ImageBuffer
392 * @exception E_SUCCESS The method is successful.
393 * @exception E_UNSUPPORTED_FORMAT The specified format is not supported.
394 * @exception E_INVALID_DATA The current data is invalid for this operation. @n
395 * This will happen when the width or height is not even value,
396 * and the requested pixel format is sub-sampled pixel format like @c MEDIA_PIXEL_FORMAT_YUV420P.
397 * @remarks The specific error code can be accessed using the GetLastResult() method.
398 * @remarks There is a high probability for an occurrence of an out-of-memory exception. If possible, check whether the exception is @c E_OUT_OF_MEMORY or not.
399 * For more information on how to handle the out-of-memory exception, refer <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.
401 ImageBuffer* ConvertPixelFormatN(MediaPixelFormat pixelFormat) const;
404 * Gets a resized %ImageBuffer with the current image data. @n
405 * The aspect ratio of the data will not be preserved.
409 * @return A pointer to the %ImageBuffer instance containing the resized image data
410 * @param[in] width The width of the destination image
411 * @param[in] height The height of the destination image
412 * @exception E_SUCCESS The method is successful.
413 * @exception E_OUT_OF_RANGE A specified input parameter is out of range.
414 * @exception E_OUT_OF_MEMORY The memory is insufficient.
415 * @exception E_INVALID_DATA The current data is invalid for this operation. @n
416 * This will happen when the current pixel format is sub-sampled pixel format like @c MEDIA_PIXEL_FORMAT_YUV420P
417 * and the requested @c width or @c height is not even value.
418 * @remarks The specific error code can be accessed using the GetLastResult() method.
419 * @remarks There is a high probability for an occurrence of an out-of-memory exception. If possible, check whether the exception is @c E_OUT_OF_MEMORY or not.
420 * For more information on how to handle the out-of-memory exception, refer <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.
422 ImageBuffer* ResizeN(int width, int height) const;
425 * Gets a horizontally or vertically flipped image from the current instance.
429 * @return A pointer to the %ImageBuffer instance containing the flipped image data
430 * @param[in] flipType The flip type
431 * @exception E_SUCCESS The method is successful.
432 * @exception E_INVALID_ARG The specified input parameter is invalid.
433 * @exception E_OUT_OF_MEMORY The memory is insufficient.
434 * @remarks The specific error code can be accessed using the GetLastResult() method.
435 * @remarks There is a high probability for an occurrence of an out-of-memory exception. If possible, check whether the exception is @c E_OUT_OF_MEMORY or not.
436 * For more information on how to handle the out-of-memory exception, refer <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.
438 ImageBuffer* FlipN(ImageFlipType flipType) const;
441 * Gets a rotated image in clockwise direction from the current image.
445 * @return A pointer to the %ImageBuffer instance containing the rotated image data
446 * @param[in] rotateType The rotation type
447 * @exception E_SUCCESS The method is successful.
448 * @exception E_INVALID_ARG The specified input parameter is invalid.
449 * @exception E_INVALID_DATA The current data is invalid for this operation. @n
450 * This will happen when the current pixel format is sub-sampled pixel format like @c MEDIA_PIXEL_FORMAT_YUYV422
451 * and the height is odd value and the requested rotation type is @c IMAGE_ROTATION_90 or @c IMAGE_ROTATION_270.
452 * @exception E_OUT_OF_MEMORY The memory is insufficient.
453 * @remarks The specific error code can be accessed using the GetLastResult() method.
454 * @remarks There is a high probability for an occurrence of an out-of-memory exception. If possible, check whether the exception is @c E_OUT_OF_MEMORY or not.
455 * For more information on how to handle the out-of-memory exception, refer <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.
457 ImageBuffer* RotateN(ImageRotationType rotateType) const;
460 * Crops the region of the current %ImageBuffer instance.
464 * @return A pointer to the %ImageBuffer instance containing the cropped image data
465 * @param[in] x The x position
466 * @param[in] y The y position
467 * @param[in] width The width of the destination image
468 * @param[in] height The height of the destination image
469 * @exception E_SUCCESS The method is successful.
470 * @exception E_OUT_OF_RANGE A specified input parameter is out of range.
471 * @exception E_INVALID_DATA The current data is invalid for this operation. @n
472 * This will happen when the current pixel format is sub-sampled pixel format like @c MEDIA_PIXEL_FORMAT_YUV420P
473 * and the requested @c x, @c y, @c width, or @c height is not even value.
474 * @remarks The specific error code can be accessed using the GetLastResult() method.
475 * @remarks There is a high probability for an occurrence of an out-of-memory exception. If possible, check whether the exception is @c E_OUT_OF_MEMORY or not.
476 * For more information on how to handle the out-of-memory exception, refer <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.
478 ImageBuffer* CropN(int x, int y, int width, int height) const;
481 * Gets the image information.
485 * @return An error code
486 * @param[in] srcImagePath The source image path
487 * @param[out] imageFormat The format of the image
488 * @param[out] width The width of the image
489 * @param[out] height The height of the image
490 * @exception E_SUCCESS The method is successful.
491 * @exception E_UNSUPPORTED_FORMAT The specified format is not supported.
492 * @exception E_OUT_OF_MEMORY The memory is insufficient.
493 * @exception E_FILE_NOT_FOUND The specified file cannot be found or accessed.
494 * @exception E_SYSTEM A system error has occurred.
496 static result GetImageInfo(const Tizen::Base::String& srcImagePath, ImageFormat &imageFormat, int &width, int &height);
499 * Gets the image information.
503 * @return An error code
504 * @param[in] srcImageBuf The buffer that contains the compressed image data
505 * @param[out] imageFormat The format of the image
506 * @param[out] width The width of the image
507 * @param[out] height The height of the image
508 * @exception E_SUCCESS The method is successful.
509 * @exception E_UNSUPPORTED_FORMAT The specified format is not supported.
510 * @exception E_OUT_OF_MEMORY The memory is insufficient.
511 * @exception E_SYSTEM A system error has occurred.
513 static result GetImageInfo(const Tizen::Base::ByteBuffer& srcImageBuf, ImageFormat &imageFormat, int &width, int &height);
516 * Gets a list of the supported pixel formats.
520 * @return A list of the pixel formats supported by the %ImageBuffer class, @n
521 * else @c null if an exception occurs
522 * @exception E_SUCCESS The method is successful.
523 * @exception E_OUT_OF_MEMORY The memory is insufficient.
524 * @exception E_SYSTEM A system error has occurred.
525 * @remarks The specific error code can be accessed using the GetLastResult() method.
527 * @see GetByteBufferN()
529 static Tizen::Base::Collection::IListT<MediaPixelFormat>* GetSupportedPixelFormatListN(void);
534 * The implementation of this copy constructor is intentionally blank
535 * and declared as private to prohibit copying of objects.
537 ImageBuffer(const ImageBuffer& rhs);
540 * The implementation of this copy assignment operator is intentionally blank
541 * and declared as private to prohibit copying of objects.
542 * Use CloneN() to get an exact copy of this instance.
543 * Use Equals() to compare contents of one instance with the other.
545 ImageBuffer& operator =(const ImageBuffer& rhs);
547 friend class _ImageBufferImpl;
548 class _ImageBufferImpl* __pImpl;
553 #endif // _FMEDIA_IMAGEBUFFER_H_