inc/FMediaVideoFrameExtractor.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   FMediaVideoFrameExtractor.h
  20  * @brief  This is the header file for the %VideoFrameExtractor class.
  21  *
  22  * This header file contains the declarations of the %VideoFrameExtractor class.
  23  */
  24
  25 #ifndef _FMEDIA_VIDEO_FRAME_EXTRACTOR_H_
  26 #define _FMEDIA_VIDEO_FRAME_EXTRACTOR_H_
  27
  28 #include <FBaseObject.h>
  29 #include <FMediaImageBuffer.h>
  30 #include <FMediaRecorderTypes.h>
  31
  32 namespace Tizen { namespace Media {
  33
  34 /**
  35  * @class  VideoFrameExtractor
  36  * @brief  This class is used to extract video frame from video file.
  37  *
  38  * @since               2.0
  39  *
  40  * The %VideoFrameExtractor class is used to extract video frame from video file.
  41  *
  42  * The following example demonstrates how to use the %VideoFrameExtractor class to extract video frame from video file.
  43  *
  44  * @code
  45  * #include <FMedia.h>
  46  * #include <FApp.h>
  47  * #include <FGraphics.h>
  48  *
  49  * using namespace Tizen::Base;
  50  * using namespace Tizen::Media;
  51  * using namespace Tizen::Graphics;
  52  *
  53  *  result
  54
  55  * TestVideoFrameExtractor(void)
  56  * {
  57  *    VideoFrameExtractor extractor;
  58  *    String path = Tizen::App::App::GetInstance()->GetAppRootPath() + L"data/test.mp4";
  59  *    result r = extractor.Construct(path, MEDIA_PIXEL_FORMAT_BGRA8888);
  60  *    long duration = extractor.GetDuration();
  61  *
  62  *    // Extracts video frames from the video file
  63
  64  *    for (int i = 0; i < 10; i++)
  65  *    {
  66  *        ImageBuffer* pImage = extractor.GetFrameN(duration*i/10);
  67  *
  68  *        // Adds some codes that handles extracted video frame
  69  *
  70  *        delete pImage;
  71  *    }
  72  *    return E_SUCCESS;
  73  * }
  74  * @endcode
  75  */
  76 class _OSP_EXPORT_ VideoFrameExtractor
  77         : public Tizen::Base::Object
  78 {
  79 public:
  80         /**
  81          * This is the default constructor for this class.
  82          *
  83          * @since               2.0
  84          *
  85          * @see    Construct()
  86          */
  87         VideoFrameExtractor(void);
  88
  89         /**
  90          * This destructor overrides Tizen::Base::Object::~Object().
  91          *
  92          * @since               2.0
  93          *
  94          * @see    Construct()
  95          */
  96         virtual ~VideoFrameExtractor(void);
  97
  98         /**
  99          * Initializes this instance of %VideoFrameExtractor with the specified parameters.
 100          *
 101          * @since               2.0
 102          *
 103          * @return     An error code
 104          * @param[in]  filePath              The video file path
 105          * @param[in]  pixelFormat           The pixel format of output image data.
 106          * @exception  E_SUCCESS             The method is successful.
 107          * @exception  E_INVALID_ARG         A specified input parameter is invalid.
 108          * @exception  E_UNSUPPORTED_FORMAT  The specified format is not supported.
 109          * @exception  E_OUT_OF_MEMORY       The memory is insufficient.
 110          * @exception  E_FILE_NOT_FOUND      The specified file cannot be found or accessed.
 111          */
 112         result Construct(const Tizen::Base::String &filePath, MediaPixelFormat pixelFormat);
 113
 114         /**
 115          * Gets the width of the video frame.
 116          *
 117          * @since               2.0
 118          *
 119          * @return  The width of video frame
 120          */
 121         int GetWidth(void) const;
 122
 123         /**
 124          * Gets the height of the video frame.
 125          *
 126          * @since               2.0
 127          *
 128          * @return  The height of the video frame
 129          */
 130         int GetHeight(void) const;
 131
 132         /**
 133          * Gets the duration of the video in millisecond.
 134          *
 135          * @since               2.0
 136          *
 137          * @return  The duration of the video in millisecond
 138          */
 139         long GetDuration(void) const;
 140
 141         /**
 142          * Extracts video frame at the specified position.
 143          *
 144          * @since               2.0
 145          *
 146          * @return     A pointer to ImageBuffer containing the extracted video frame
 147          * @param[in]  timestamp             The timestamp of video frame to extract
 148          * @exception  E_SUCCESS             The method is successful.
 149          * @exception  E_OUT_OF_RANGE        The specified @c timestamp is out of range.
 150          * @exception  E_OUT_OF_MEMORY       The memory is insufficient.
 151          * @exception  E_OPERATION_FAILED    Video frame at given position is not found or extraction is failed.
 152          * @exception  E_UNSUPPORTED_FORMAT  The specified pixel format is not supported.
 153          * @remarks
 154          *           - The specific error code can be accessed using the GetLastResult() method.
 155          *           - The extracted frame may not be exact frame of given timestamp,
 156          *             so that the same frame can be returned even if the timestamp is different.
 157          *           - Frames near the end of contents may not be extracted if no key-frame is found after timestamp.
 158          */
 159         ImageBuffer* GetFrameN(long timestamp);
 160
 161         /**
 162          * Extracts video thumbnail from the specified position.
 163          *
 164          * @since               2.0
 165          *
 166          * @return     A pointer to ImageBuffer containing the extracted video frame
 167          * @param[in]  path                  The video file path
 168          * @param[in]  timestamp             The timestamp of video frame that want to extract
 169          * @param[in]  pixelFormat           The pixel format of output image data.
 170          * @exception  E_SUCCESS             The method is successful.
 171          * @exception  E_INVALID_ARG         A specified input parameter is invalid.
 172          * @exception  E_OUT_OF_RANGE        The specified @c timestamp is out of range.
 173          * @exception  E_OUT_OF_MEMORY       The memory is insufficient.
 174          * @exception  E_OPERATION_FAILED    Video frame at given position is not found or extraction is failed.
 175          * @exception  E_UNSUPPORTED_FORMAT  The specified pixel format is not supported.
 176          * @remarks
 177          *           - The specific error code can be accessed using the GetLastResult() method.
 178          *           - The extracted frame may not be exact frame of given timestamp,
 179          *             so that the same frame can be returned even if the timestamp is different.
 180          *           - Frames near the end of contents may not be extracted if no key-frame is found after timestamp.
 181          */
 182         static ImageBuffer* GetFrameN(const Tizen::Base::String& path, MediaPixelFormat pixelFormat, long timestamp);
 183
 184         /**
 185         * Gets the current recording rotation of the video data.
 186         *
 187         * @since 2.1
 188         *
 189         * @return The recording rotation information of the current video data
 190         */
 191         RecordingRotation GetRecordingRotation(void) const;
 192
 193
 194 private:
 195         /**
 196          * This is the copy constructor for this class.
 197          */
 198         VideoFrameExtractor(const VideoFrameExtractor& rhs);
 199
 200         /**
 201          * This is the assignment operator.
 202          */
 203         VideoFrameExtractor& operator =(const VideoFrameExtractor& rhs);
 204
 205 private:
 206         friend class _VideoFrameExtractorImpl;
 207         class _VideoFrameExtractorImpl* __pImpl;
 208 };
 209
 210 }} // Tizen::Media
 211
 212 #endif // _FMEDIA_VIDEO_FRAME_EXTRACTOR_H_
 213