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