inc/FMediaVideoDecoder.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   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
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  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        FMediaVideoDecoder.h
  20  * @brief       This is the header file for the %VideoDecoder class.
  21  *
  22  * This header file contains the declarations of the %VideoDecoder class.
  23  */
  24
  25 #ifndef _FMEDIA_VIDEO_DECODER_H_
  26 #define _FMEDIA_VIDEO_DECODER_H_
  27
  28 #include <FBase.h>
  29 #include <FMediaTypes.h>
  30
  31 namespace Tizen { namespace Media
  32 {
  33
  34 /**
  35  * @class VideoDecoder
  36  * @brief This class decodes a compressed video stream into a raw video data.
  37  *
  38  * @since               2.0
  39  *
  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.
  42  *
  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>.
  44  *
  45  * The following example demonstrates how to use the %VideoDecoder class in H.264 decoding.
  46  * @code
  47  *
  48  * #include <FBase.h>
  49  * #include <FIo.h>
  50  * #include <FApp.h>
  51  * #include <FMedia.h>
  52  *
  53  * using namespace Tizen::Base;
  54  * using namespace Tizen::Base::Collection;
  55  * using namespace Tizen::Io;
  56  * using namespace Tizen::Media;
  57  *
  58  * result
  59  * VideoDecoderSample(void)
  60  * {
  61  *       VideoDecoder dec;
  62  *       result r;
  63  *       ByteBuffer srcBuf, dstBuf;
  64  *       File srcFile;
  65  *       bool gotFrame;
  66  *       int width, height;
  67  *       MediaPixelFormat pixelFormat;
  68  *       String filePath = Tizen::App::App::GetInstance()->GetAppRootPath() + L"data/test.h264";
  69  *       FileAttributes attr;
  70  *
  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
  77  *
  78  *       dec.Construct(CODEC_H264);
  79  *       r = dec.Probe(srcBuf, width, height, pixelFormat);
  80  *       if (IsFailed(r) || (pixelFormat != MEDIA_PIXEL_FORMAT_YUV420P))
  81  *       {
  82  *               return E_INVALID_DATA;
  83  *       }
  84  *
  85  *       dstBuf.Construct(width * height * 3 / 2);
  86  *
  87  *       while (srcBuf.GetRemaining() > 0)
  88  *       {
  89  *               gotFrame = false;
  90  *               r = dec.Decode(srcBuf, dstBuf, gotFrame);
  91  *               if (IsFailed(r))
  92  *               {
  93  *                       return r;
  94  *               }
  95  *
  96  *               if (gotFrame)
  97  *               {
  98  *                       // Adds code handling decoded frame
  99  *               }
 100  *               dstBuf.Clear();
 101  *       }
 102  *
 103  *       return E_SUCCESS;
 104  * }
 105  *
 106  * @endcode
 107  *
 108  *
 109  */
 110 class _OSP_EXPORT_ VideoDecoder
 111         : public Tizen::Base::Object
 112 {
 113 public:
 114         /**
 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.
 116          *
 117          *      @since          2.0
 118          *
 119          *      @remarks        After creating an instance of this class, the Construct() method must be called explicitly to initialize this instance.
 120          *      @see            Construct()
 121          */
 122         VideoDecoder(void);
 123
 124         /**
 125          *      This destructor overrides Tizen::Base::Object::~Object().
 126          *
 127          *      @since          2.0
 128          */
 129         virtual ~VideoDecoder(void);
 130
 131         /**
 132          *      Initializes this instance of %VideoDecoder with the specified parameters.
 133          *
 134          *      @since          2.0
 135          *
 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.
 145          */
 146         result Construct(CodecType type, const Tizen::Base::Collection::HashMap* pOption = null);
 147
 148 public:
 149         /**
 150          *      Probes whether the video data can be decoded and sets the width, height, and pixel format of the video data.
 151          *
 152          *      @since          2.0
 153          *
 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.
 165          */
 166         result Probe(const Tizen::Base::ByteBuffer& srcBuf, int& width, int& height, MediaPixelFormat& pixelFormat);
 167
 168
 169         /**
 170          *      Decodes the video data from the source buffer and stores the decoded data into the destination buffer.
 171          *
 172          *      @since          2.0
 173          *
 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
 178          *                                                                          else @c false
 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.
 185          *      @remarks        The destination buffer must have sufficient free space to store the decoded frame data.
 186          *      @remarks        The decoder starts the decoding of the frame from the current position of the source buffer,
 187          *                              and moves the position of the source buffer to the end of the consumed data.
 188          *                              The decoder also fills the destination buffer with the decoded frame from the current position of the destination buffer,
 189          *                              and moves the position of the destination buffer to the end of the decoded frame.
 190          *  @remarks    When the first decoding begins, the @c E_DIMENSION_CHANGED exception can occur.
 191          *                        An exception can also occur when the dimension of the video frame in the bitstream has changed.
 192          *                        An application should increase the size of @c dstBuf if the @c dstBuf cannot hold the video frame with new dimensions.
 193          *                        The video frame can be received even if the result is @c E_DIMENSION_CHANGED.
 194          *                        The application should check the @c position of the destination buffer and the value of @c gotFrame
 195          *                        when the result is @c E_DIMENSION_CHANGED.
 196          * @remarks     The H.264 video decoder returns data with the width and height in multiples of 16.
 197          *                              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.
 198          *      @see Probe()
 199          */
 200         result Decode(Tizen::Base::ByteBuffer& srcBuf, Tizen::Base::ByteBuffer& dstBuf, bool& gotFrame);
 201
 202         /**
 203          *      Resets the internal state of the video decoder to process a new video stream.
 204          *
 205          *      @since          2.0
 206          *
 207          *      @return         An error code
 208          *      @exception      E_SUCCESS                       The method is successful.
 209          *      @exception      E_SYSTEM                        A system error has occurred.
 210          */
 211         result Reset(void);
 212
 213
 214         /**
 215          *      Gets the specified property value of this instance.
 216          *
 217          *      @since          2.0
 218          *
 219          *      @return          An error code
 220          *      @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
 221          *      @param[out]             value                           The obtained property value
 222          *      @exception      E_SUCCESS                               The method is successful.
 223          *      @exception      E_INVALID_STATE             This instance is in an invalid state for this method.
 224          *      @exception      E_OBJ_NOT_FOUND             The specified @c key is not found.
 225          *      @exception      E_INVALID_ARG                   The specified @c key is not supported.
 226          *      @exception      E_SYSTEM                                A system error has occurred.
 227          *      @remarks        The property whose value is of type enum can be obtained by using this method.
 228          */
 229         result GetValue(MediaPropertyType key, int& value) const;
 230
 231
 232         /**
 233          *      Gets the specified property value of this instance.
 234          *
 235          *      @since          2.0
 236          *
 237          *      @return          An error code
 238          *      @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
 239          *      @param[out]             value                           The obtained property value
 240          *      @exception      E_SUCCESS                               The method is successful.
 241          *      @exception      E_INVALID_STATE                  This instance is in an invalid state for this method.
 242          *      @exception      E_OBJ_NOT_FOUND         The specified @c key is not found.
 243          *      @exception      E_INVALID_ARG                   The specified @c key is not supported.
 244          *      @exception      E_SYSTEM                                A system error has occurred.
 245          *      @remarks        The property whose value is of type enum can be obtained using this method.
 246          */
 247         result GetValue(MediaPropertyType key, float& value) const;
 248
 249         /**
 250          *      Gets the supported properties of this instance.
 251          *
 252          *      @since          2.0
 253          *
 254          *      @return  A list of supported properties, @n
 255          *                              else @c null if no property is supported or if an exception occurs
 256          *      @exception      E_SUCCESS                               The method is successful.
 257          *      @exception      E_OUT_OF_MEMORY          The memory is insufficient.
 258          *      @exception      E_OBJ_NOT_FOUND                 This instance does not support any property.
 259          *      @exception      E_SYSTEM                                A system error has occurred.
 260          *      @remarks        The specific error code can be accessed using the GetLastResult() method.
 261          *      @remarks        The return value must be deleted.
 262          */
 263         Tizen::Base::Collection::IListT<MediaPropertyType>* GetSupportedPropertyListN(void) const;
 264
 265         /**
 266          *      Checks whether the specified property is supported.
 267          *
 268          *      @since          2.0
 269          *
 270          *      @return  @c true if the property is supported, @n
 271          *                              else @c false
 272          *      @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
 273          *      @exception      E_SUCCESS                  The method is successful.
 274          *      @exception      E_OBJ_NOT_FOUND         The specified @c key is not found.
 275          *      @exception      E_SYSTEM                        A system error has occurred.
 276          *      @remarks        The specific error code can be accessed using the GetLastResult() method.
 277          */
 278         bool IsPropertySupported(MediaPropertyType key) const;
 279
 280         /**
 281          * Gets a list of the supported codecs.
 282          *
 283          * @since               2.0
 284          * @return     A list of the codecs supported by the %VideoDecoder class, @n
 285          *             else @c null if an exception occurs
 286          * @exception  E_SUCCESS             The method is successful.
 287          * @exception  E_OUT_OF_MEMORY       The memory is insufficient.
 288          * @remarks    The specific error code can be accessed using the GetLastResult() method.
 289          * @remarks    The return value must be deleted by the caller.
 290          */
 291         static Tizen::Base::Collection::IListT<CodecType>* GetSupportedCodecListN(void);
 292
 293
 294 private:
 295         /**
 296         *       The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 297         *
 298         *       @since          2.0
 299         *
 300         */
 301         VideoDecoder(const VideoDecoder& dec);
 302         /**
 303         *       The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 304         *
 305         *       @since          2.0
 306         *
 307         */
 308         VideoDecoder& operator =(const VideoDecoder& dec);
 309
 310         friend class _VideoDecoderImpl;
 311         class _VideoDecoderImpl* __pImpl;
 312 };
 313
 314 }} // Tizen::Media
 315
 316
 317 #endif