inc/FMediaVideoEncoder.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   FMediaVideoEncoder.h
  20  *      @brief  This is the header file for the %VideoEncoder class.
  21  *
  22  *      This header file contains the declarations of the %VideoEncoder class.
  23  */
  24
  25 #ifndef _FMEDIA_VIDEO_ENCODER_H_
  26 #define _FMEDIA_VIDEO_ENCODER_H_
  27
  28 #include <FBase.h>
  29 #include <FMediaTypes.h>
  30
  31 namespace Tizen { namespace Media
  32 {
  33
  34 /**
  35  * @class VideoEncoder
  36  * @brief This class encodes a raw video stream into a compressed video data.
  37  *
  38  * @since               2.0
  39  *
  40  * The %VideoEncoder class encodes a raw video stream into a compressed video data. The video encoders such as H.263, MPEG4 Part 2 are supported.
  41  *
  42  * 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>.
  43  *
  44  * The following example demonstrates how to use the %VideoEncoder class in H.263 encoding.
  45  * @code
  46  *
  47  * #include <FBase.h>
  48  * #include <FIo.h>
  49  * #include <FMedia.h>
  50  *
  51  * using namespace Tizen::Base;
  52  * using namespace Tizen::Base::Collection;
  53  * using namespace Tizen::Io;
  54  * using namespace Tizen::Media;
  55  *
  56  * result
  57  * VideoEncoderSample(void)
  58  * {
  59  *       VideoEncoder enc;
  60  *       result r;
  61  *       ByteBuffer srcBuf, dstBuf;
  62  *       int width = 352;
  63  *       int height = 288;
  64  *       int bitRate = 512000; // 512 Kbps
  65  *       int frameRate = 15;
  66  *       MediaPixelFormat pixelFormat = MEDIA_PIXEL_FORMAT_YUV420P;
  67  *       HashMap option;
  68  *       byte* pBuf = null;
  69  *       int srcBufSize = width * height * 3 / 2;
  70  *
  71  *       option.Construct();
  72  *       option.Add(*(new Integer(MEDIA_PROPERTY_VIDEO_WIDTH)), *(new Integer(width)));
  73  *       option.Add(*(new Integer(MEDIA_PROPERTY_VIDEO_HEIGHT)), *(new Integer(height)));
  74  *       option.Add(*(new Integer(MEDIA_PROPERTY_VIDEO_PIXEL_FORMAT)), *(new Integer(pixelFormat)));
  75  *       option.Add(*(new Integer(MEDIA_PROPERTY_VIDEO_FRAME_RATE)), *(new Integer(frameRate)));
  76  *       option.Add(*(new Integer(MEDIA_PROPERTY_VIDEO_BIT_RATE)), *(new Integer(bitRate)));
  77  *
  78  *       pBuf = new byte[srcBufSize];
  79  *       srcBuf.Construct(pBuf, 0, srcBufSize, srcBufSize);
  80  *       dstBuf.Construct(width * height * 3 / 2);
  81  *
  82  *       enc.Construct(CODEC_H263, &option);
  83  *
  84  *       for (int i = 0; i < 255; i += 25)
  85  *       {
  86  *               // Fills source buffer with a gray color
  87  *               memset(pBuf, i, width * height);                                          // Y
  88  *               memset(pBuf + width * height, 128, width * height / 4);          // Cb
  89  *               memset(pBuf + width * height * 5 / 4, 128, width * height / 4);  // Cr
  90  *
  91  *               srcBuf.SetPosition(0);
  92  *               srcBuf.SetLimit(srcBufSize);
  93  *
  94  *               r = enc.Encode(srcBuf, dstBuf);
  95  *               if (IsFailed(r))
  96  *               {
  97  *                       break;
  98  *               }
  99  *
 100  *               // Adds code handling encoded data
 101  *
 102  *               dstBuf.Clear();
 103  *       }
 104  *
 105  *       delete pBuf;
 106  *       return r;
 107  * }
 108  *
 109  * @endcode
 110  *
 111  */
 112 class _OSP_EXPORT_ VideoEncoder
 113         : public Tizen::Base::Object
 114 {
 115 public:
 116         /**
 117          *      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.
 118          *
 119          *      @since          2.0
 120          *
 121          *      @remarks                 After creating an instance of this class, the Construct() method must be
 122          *                                       called explicitly to initialize this instance.
 123          *      @see            Construct()
 124          */
 125         VideoEncoder(void);
 126
 127         /**
 128          *      This destructor overrides Tizen::Base::Object::~Object().
 129          *
 130          *      @since          2.0
 131          */
 132         virtual ~VideoEncoder(void);
 133
 134         /**
 135          *      Initializes an instance of %VideoEncoder with the specified parameters.
 136          *
 137          *      @since          2.0
 138          *
 139          *      @return         An error code
 140          *      @param[in]      type                            The codec type
 141          *      @param[in]      pOption                         The <a href="../org.tizen.native.appprogramming/html/guide/media/encoding_decoding_video.htm#encoding_video">optional parameters</a>
 142          *      @exception      E_SUCCESS                       The method is successful.
 143          *      @exception      E_UNSUPPORTED_CODEC The specified encoder is not supported.
 144          *      @exception      E_INVALID_ARG           A specified input parameter has invalid data.
 145          *      @exception      E_OUT_OF_MEMORY         The memory is insufficient.
 146          *      @exception      E_SYSTEM                        A system error has occurred.
 147          *      @remarks
 148          *                        - The key type of the specified option is Tizen::Base::Integer and the value type varies depending
 149          *                              on the key type.
 150          *                              The unsupported keys in @c pOption are ignored.
 151          *                              If specified @c pOption has an invalid value, @c E_INVALID_ARG is returned.
 152          *                        - The supported codec types can vary depending on the device model or platform version.
 153          */
 154         result Construct(CodecType type, const Tizen::Base::Collection::HashMap* pOption = null);
 155
 156 public:
 157         /**
 158          *      Encodes the video data from the source buffer and stores the encoded data in the destination buffer.
 159          *
 160          *      @since          2.0
 161          *
 162          *      @return  An error code
 163          *      @param[in]      srcBuf                                  The source buffer that stores the raw video data
 164          *      @param[out]     dstBuf                                  The destination buffer that stores the encoded video data
 165          *      @exception      E_SUCCESS                               The method is successful.
 166          *      @exception      E_INVALID_ARG                   The specified source or destination buffer is invalid or has insufficient memory.
 167          *      @exception      E_OUT_OF_MEMORY                 The memory is insufficient.
 168          *      @exception      E_SYSTEM                                A system error has occurred.
 169          *      @remarks
 170          *                        - The destination buffer must have sufficient free space to store the encoded frame data.
 171          *                        - The position of the source buffer is moved to the end of the consumed data and the position of the destination buffer is moved to the end of the written data.
 172          */
 173         result Encode(Tizen::Base::ByteBuffer& srcBuf, Tizen::Base::ByteBuffer& dstBuf);
 174
 175         /**
 176          *      Resets the internal state of the video encoder to process a new video stream.
 177
 178          *      @since          2.0
 179          *
 180          *      @return         An error code
 181          *      @exception      E_SUCCESS                       The method is successful.
 182          *      @exception      E_SYSTEM                        A system error has occurred.
 183          *      @remarks        This method resets the properties that were set after the execution of the Construct() method.
 184          */
 185         result Reset(void);
 186
 187         /**
 188          *      Sets the specified property value of this instance.
 189          *
 190          *      @since          2.0
 191          *
 192          *      @return          An error code
 193          *      @param[in]              key                                     The <a href="../org.tizen.native.appprogramming/html/guide/media/encoding_decoding_video.htm#encoding_video">key</a> value to set
 194          *      @param[in]              value                           The property value to set
 195          *      @exception      E_SUCCESS                               The method is successful.
 196          *      @exception      E_INVALID_STATE          This instance is in an invalid state for this method.
 197          *      @exception      E_OBJ_NOT_FOUND                 The specified @c key is not found.
 198          *      @exception      E_INVALID_ARG                   A specified input parameter is invalid.
 199          *      @exception      E_SYSTEM                                A system error has occurred.
 200          *      @remarks        The media property that has the value of type enum can be set using this method.
 201          */
 202         result SetValue(MediaPropertyType key, int value);
 203
 204         /**
 205          *      Sets the specified property value of this instance.
 206          *
 207          *      @since          2.0
 208          *
 209          *      @return          An error code
 210          *      @param[in]              key                                     The <a href="../org.tizen.native.appprogramming/html/guide/media/encoding_decoding_video.htm#encoding_video">key</a> value to set
 211          *      @param[in]              value                           The property value to set
 212          *      @exception      E_SUCCESS                               The method is successful.
 213          *      @exception      E_INVALID_STATE          This instance is in an invalid state for this method.
 214          *      @exception      E_OBJ_NOT_FOUND                 The specified @c key is not found.
 215          *      @exception      E_INVALID_ARG                   A specified input parameter is invalid.
 216          *      @exception      E_SYSTEM                                A system error has occurred.
 217          *      @remarks        The media property that has the value of type enum can be set using this method.
 218          */
 219         result SetValue(MediaPropertyType key, bool value);
 220
 221         /**
 222          *      Gets the properties supported by this instance.
 223          *
 224          *      @since          2.0
 225          *
 226          *      @return  A list of the supported properties, @n
 227          *                              else @c null if no property is supported or if an exception occurs
 228          *      @exception      E_SUCCESS                               The method is successful.
 229          *      @exception      E_OUT_OF_MEMORY          The memory is insufficient.
 230          *      @exception      E_SYSTEM                                A system error has occurred.
 231          *      @exception      E_OBJ_NOT_FOUND                 This instance does not support any property.
 232          *      @remarks        The specific error code can be accessed using the GetLastResult() method.
 233          *                              The returned value must be deleted.
 234          */
 235         Tizen::Base::Collection::IListT<MediaPropertyType>* GetSupportedPropertyListN(void) const;
 236
 237         /**
 238          *      Checks whether the specified property is supported.
 239          *
 240          *      @since          2.0
 241          *
 242          *      @return  @c true if the property is supported, @n
 243          *                              else @c false
 244          *      @param[in]      key                                     The <a href="../org.tizen.native.appprogramming/html/guide/media/encoding_decoding_video.htm#encoding_video">key</a> value
 245          *      @exception      E_SUCCESS                  The method is successful.
 246          *      @exception      E_OBJ_NOT_FOUND         The specified @c key is not found.
 247          *      @exception      E_SYSTEM                        A system error has occurred.
 248          *      @remarks        The specific error code can be accessed using the GetLastResult() method.
 249          */
 250         bool IsPropertySupported(MediaPropertyType key) const;
 251
 252         /**
 253          * Gets a list of the supported codecs.
 254          *
 255          * @since               2.0
 256          *
 257          * @return     A list of the codecs supported by the %VideoEncoder class, @n
 258          *             else @c null if an exception occurs
 259          * @exception  E_SUCCESS             The method is successful.
 260          * @exception  E_OUT_OF_MEMORY       The memory is insufficient.
 261          * @remarks
 262          *                       - The specific error code can be accessed using the GetLastResult() method.
 263          *                       - The return value must be deleted by the caller.
 264          */
 265         static Tizen::Base::Collection::IListT<CodecType>* GetSupportedCodecListN(void);
 266
 267 private:
 268         /**
 269          *      The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 270          *
 271          *      @since          2.0
 272          *
 273          */
 274         VideoEncoder(const VideoEncoder& enc);
 275
 276         /**
 277          *      The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 278          *
 279          *      @since          2.0
 280          *
 281          */
 282         VideoEncoder& operator =(const VideoEncoder& enc);
 283
 284         friend class _VideoEncoderImpl;
 285         class _VideoEncoderImpl* __pImpl;
 286 };
 287
 288 }} // Tizen::Media
 289
 290 #endif