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 FMediaVideoDecoder.h
20 * @brief This is the header file for the %VideoDecoder class.
22 * This header file contains the declarations of the %VideoDecoder class.
25 #ifndef _FMEDIA_VIDEO_DECODER_H_
26 #define _FMEDIA_VIDEO_DECODER_H_
29 #include <FMediaTypes.h>
31 namespace Tizen { namespace Media
36 * @brief This class decodes a compressed video stream into a raw video data.
40 * The %VideoDecoder class decodes a compressed video stream into a raw video data.
41 * The video decoding formats, such as CODEC_H263, CODEC_MPEG4, and CODEC_H264 are supported.
43 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/media/encoding_decoding_video.htm">Encoding and Decoding Video</a>.
45 * The following example demonstrates how to use the %VideoDecoder class in H.264 decoding.
53 * using namespace Tizen::Base;
54 * using namespace Tizen::Base::Collection;
55 * using namespace Tizen::Io;
56 * using namespace Tizen::Media;
59 * VideoDecoderSample(void)
63 * ByteBuffer srcBuf, dstBuf;
67 * MediaPixelFormat pixelFormat;
68 * String filePath = Tizen::App::App::GetInstance()->GetAppRootPath() + L"data/test.h264";
69 * FileAttributes attr;
71 * // Loads data from src file
72 * File::GetAttributes(filePath, attr);
73 * srcBuf.Construct(attr.GetFileSize());
74 * srcFile.Construct(filePath, "rb");
75 * srcFile.Read(srcBuf);
76 * srcBuf.Flip(); // Sets the position of source buffer to zero
78 * dec.Construct(CODEC_H264);
79 * r = dec.Probe(srcBuf, width, height, pixelFormat);
80 * if (IsFailed(r) || (pixelFormat != MEDIA_PIXEL_FORMAT_YUV420P))
82 * return E_INVALID_DATA;
85 * dstBuf.Construct(width * height * 3 / 2);
87 * while (srcBuf.GetRemaining() > 0)
90 * r = dec.Decode(srcBuf, dstBuf, gotFrame);
98 * // Adds code handling decoded frame
110 class _OSP_EXPORT_ VideoDecoder
111 : public Tizen::Base::Object
115 * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
119 * @remarks After creating an instance of this class, the Construct() method must be called explicitly to initialize this instance.
125 * This destructor overrides Tizen::Base::Object::~Object().
129 virtual ~VideoDecoder(void);
132 * Initializes this instance of %VideoDecoder with the specified parameters.
136 * @return An error code
137 * @param[in] type The codec type
138 * @param[in] pOption The <a href="../org.tizen.native.appprogramming/html/guide/media/encoding_decoding_video.htm#decoding_video">optional parameters</a>
139 * @exception E_SUCCESS The method is successful.
140 * @exception E_UNSUPPORTED_CODEC The specified decoder is not supported.
141 * @exception E_OUT_OF_RANGE A specified input parameter has a value that is out of range.
142 * @exception E_OUT_OF_MEMORY The memory is insufficient.
143 * @exception E_SYSTEM A system error has occurred.
144 * @remarks The key type of the specified option is Tizen::Base::Integer and the value type varies depending on the key type.
146 result Construct(CodecType type, const Tizen::Base::Collection::HashMap* pOption = null);
150 * Probes whether the video data can be decoded and sets the width, height, and pixel format of the video data.
154 * @return An error code
155 * @param[in] srcBuf The source buffer that stores the compressed video data
156 * @param[out] width The width of the decoded video frame
157 * @param[out] height The height of the decoded video frame
158 * @param[out] pixelFormat The pixel format of the decoded video frame
159 * @exception E_SUCCESS The method is successful.
160 * @exception E_INVALID_ARG The specified @c srcBuf is invalid.
161 * @exception E_UNSUPPORTED_FORMAT The input data is not in a supported format.
162 * @exception E_OUT_OF_MEMORY The memory is insufficient.
163 * @exception E_SYSTEM A system error has occurred.
164 * @remarks This method resets the internal state of the video decoder.
166 result Probe(const Tizen::Base::ByteBuffer& srcBuf, int& width, int& height, MediaPixelFormat& pixelFormat);
170 * Decodes the video data from the source buffer and stores the decoded data into the destination buffer.
174 * @return An error code
175 * @param[in] srcBuf The source buffer that stores the compressed video data
176 * @param[out] dstBuf The destination buffer that stores the decoded video data
177 * @param[out] gotFrame @c true when a frame is decoded, @n
179 * @exception E_SUCCESS The method is successful.
180 * @exception E_INVALID_ARG The specified @c srcBuf or @c dstBuf is invalid.
181 * @exception E_UNSUPPORTED_FORMAT The input data is not in a supported format.
182 * @exception E_OUT_OF_MEMORY The destination buffer has insufficient memory.
183 * @exception E_DIMENSION_CHANGED The dimension of video stream has changed.
184 * @exception E_SYSTEM A system error has occurred.
186 * - The destination buffer must have sufficient free space to store the decoded frame data.
187 * - The decoder starts the decoding of the frame from the current position of the source buffer,
188 * and moves the position of the source buffer to the end of the consumed data.
189 * The decoder also fills the destination buffer with the decoded frame from the current position of the destination buffer,
190 * and moves the position of the destination buffer to the end of the decoded frame.
191 * - When the first decoding begins, the @c E_DIMENSION_CHANGED exception can occur.
192 * An exception can also occur when the dimension of the video frame in the bitstream has changed.
193 * An application should increase the size of @c dstBuf if the @c dstBuf cannot hold the video frame with new dimensions.
194 * The video frame can be received even if the result is @c E_DIMENSION_CHANGED.
195 * The application should check the @c position of the destination buffer and the value of @c gotFrame
196 * when the result is @c E_DIMENSION_CHANGED.
197 * - The H.264 video decoder returns data with the width and height in multiples of 16.
198 * The application should detect the width and height of the frame and crop the decoder's output data if the original dimension is not a multiple of @c 16.
201 result Decode(Tizen::Base::ByteBuffer& srcBuf, Tizen::Base::ByteBuffer& dstBuf, bool& gotFrame);
204 * Resets the internal state of the video decoder to process a new video stream.
208 * @return An error code
209 * @exception E_SUCCESS The method is successful.
210 * @exception E_SYSTEM A system error has occurred.
216 * Gets the specified property value of this instance.
220 * @return An error code
221 * @param[in] key The <a href="../org.tizen.native.appprogramming/html/guide/media/encoding_decoding_video.htm#decoding_video">key</a> whose value is required
222 * @param[out] value The obtained property value
223 * @exception E_SUCCESS The method is successful.
224 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
225 * @exception E_OBJ_NOT_FOUND The specified @c key is not found.
226 * @exception E_INVALID_ARG The specified @c key is not supported.
227 * @exception E_SYSTEM A system error has occurred.
228 * @remarks The property whose value is of type enum can be obtained by using this method.
230 result GetValue(MediaPropertyType key, int& value) const;
234 * Gets the specified property value of this instance.
238 * @return An error code
239 * @param[in] key The <a href="../org.tizen.native.appprogramming/html/guide/media/encoding_decoding_video.htm#decoding_video">key</a> whose value is required
240 * @param[out] value The obtained property value
241 * @exception E_SUCCESS The method is successful.
242 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
243 * @exception E_OBJ_NOT_FOUND The specified @c key is not found.
244 * @exception E_INVALID_ARG The specified @c key is not supported.
245 * @exception E_SYSTEM A system error has occurred.
246 * @remarks The property whose value is of type enum can be obtained using this method.
248 result GetValue(MediaPropertyType key, float& value) const;
251 * Gets the supported properties of this instance.
255 * @return A list of supported properties, @n
256 * else @c null if no property is supported or if an exception occurs
257 * @exception E_SUCCESS The method is successful.
258 * @exception E_OUT_OF_MEMORY The memory is insufficient.
259 * @exception E_OBJ_NOT_FOUND This instance does not support any property.
260 * @exception E_SYSTEM A system error has occurred.
262 * - The specific error code can be accessed using the GetLastResult() method.
263 * - The return value must be deleted.
265 Tizen::Base::Collection::IListT<MediaPropertyType>* GetSupportedPropertyListN(void) const;
268 * Checks whether the specified property is supported.
272 * @return @c true if the property is supported, @n
274 * @param[in] key The <a href="../org.tizen.native.appprogramming/html/guide/media/encoding_decoding_video.htm#decoding_video">key</a> whose value is required
275 * @exception E_SUCCESS The method is successful.
276 * @exception E_OBJ_NOT_FOUND The specified @c key is not found.
277 * @exception E_SYSTEM A system error has occurred.
278 * @remarks The specific error code can be accessed using the GetLastResult() method.
280 bool IsPropertySupported(MediaPropertyType key) const;
283 * Gets a list of the supported codecs.
286 * @return A list of the codecs supported by the %VideoDecoder class, @n
287 * else @c null if an exception occurs
288 * @exception E_SUCCESS The method is successful.
289 * @exception E_OUT_OF_MEMORY The memory is insufficient.
291 * - The specific error code can be accessed using the GetLastResult() method.
292 * - The return value must be deleted by the caller.
294 static Tizen::Base::Collection::IListT<CodecType>* GetSupportedCodecListN(void);
299 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
304 VideoDecoder(const VideoDecoder& dec);
306 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
311 VideoDecoder& operator =(const VideoDecoder& dec);
313 friend class _VideoDecoderImpl;
314 class _VideoDecoderImpl* __pImpl;