inc/FMediaVideoFrame.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                        FMediaVideoFrame.h
  20  * @brief                       This is the header file for the %VideoFrame class.
  21  *
  22  * This header file contains the declarations of the %VideoFrame class.
  23  */
  24
  25 #ifndef _FMEDIA_VIDEO_FRAME_H_
  26 #define _FMEDIA_VIDEO_FRAME_H_
  27
  28 #include <FBase.h>
  29 #include <FMediaTypes.h>
  30
  31 namespace Tizen { namespace Media
  32 {
  33
  34 /**
  35  * @class       VideoFrame
  36  * @brief       This class has the video frame data.
  37  *
  38  * @final       This class is not intended for extension.
  39  *
  40  * @since               2.1
  41  *
  42  * The %VideoFrame class has the video frame data.
  43  * The frame has several plane components which represents each color of YUV. @n
  44  * This object is delivered to the application by IVideoStreamFilter::ProcessVideoStream() when the video is being streamed.
  45  *
  46  * The following example demonstrates how to use the %VideoFrame class.
  47  *
  48  * @code
  49  * #include <FBase.h>
  50  * #include <FMedia.h>
  51  *
  52  * using namespace Tizen::Graphics;
  53  * using namespace Tizen::Ui;
  54  * using namespace Tizen::Ui::Controls;
  55  * using namespace Tizen::Media;
  56  *
  57  * class VideoFrameSample
  58  *     : public Tizen::Ui::Controls::Form
  59  *     , public Tizen::Media::ICameraEventListener
  60  *     , public Tizen::Media::IVideoStreamFilter
  61  * {
  62  * public:
  63  *     VideoFrameSample(void);
  64  *     result Start(void);
  65  *     void Stop(void);
  66  *
  67  * protected:
  68  *     virtual void OnCameraAutoFocused(bool completeCondition) {}
  69  *     virtual void OnCameraPreviewed( Tizen::Base::ByteBuffer& previewedData, result r) {}
  70  *     virtual void OnCameraCaptured( Tizen::Base::ByteBuffer& capturedData, result r) {}
  71  *     virtual void OnCameraErrorOccurred(CameraErrorReason r ) {}
  72  *     virtual void ProcessVideoStream(VideoFrame &frame);
  73  *
  74  * private:
  75  *     Camera __camera;
  76  *     OverlayRegion * __pOverlay;
  77  * };
  78  *
  79  * VideoFrameSample::VideoFrameSample(void)
  80  * {
  81  *     __pOverlay = null;
  82  * }
  83  *
  84  * result
  85  * VideoFrameSample::Start(void)
  86  * {
  87  *     result r = E_SUCCESS;
  88  *     Rectangle rect(0, 0, 320, 240);
  89  *     bool modified = false;
  90  *     bool isValid = false;
  91  *     BufferInfo bufferInfo;
  92  *
  93  *     r = __camera.Construct(*this, CAMERA_PRIMARY);
  94  *     if (IsFailed(r))
  95  *     {
  96  *         return r;
  97  *     }
  98  *
  99  *     r = __camera.PowerOn();
 100  *     if (IsFailed(r))
 101  *     {
 102  *         return r;
 103  *     }
 104  *
 105  *     r = __camera.AddVideoStreamFilter(*this);
 106  *     if (IsFailed(r))
 107  *     {
 108  *         return r;
 109  *     }
 110  *
 111  *     isValid = OverlayRegion::EvaluateBounds(OVERLAY_REGION_EVALUATION_OPTION_LESS_THAN, rect, modified);
 112  *     if (isValid != true)
 113  *     {
 114  *         return GetLastResult();
 115  *     }
 116  *
 117  *     // Gets OverlayRegion from this Form
 118  *     __pOverlay = GetOverlayRegionN(rect, OVERLAY_REGION_TYPE_PRIMARY_CAMERA);
 119  *     if (__pOverlay == null)
 120  *     {
 121  *         return GetLastResult();
 122  *     }
 123  *
 124  *     __pOverlay->GetBackgroundBufferInfo(bufferInfo);
 125  *
 126  *     r = __camera.StartPreview(&bufferInfo, true);
 127  *     if (IsFailed(r))
 128  *     {
 129  *         goto CATCH;
 130  *     }
 131  *
 132  *     return E_SUCCESS;
 133  * CATCH:
 134  *     if (__pOverlay)
 135  *     {
 136  *         delete __pOverlay;
 137  *         __pOverlay = null;
 138  *     }
 139  *     return r;
 140  *  }
 141  *
 142  * void
 143  * VideoFrameSample::Stop(void)
 144  * {
 145  *     __camera.StopPreview();
 146  *     __camera.PowerOff();
 147  *     if (__pOverlay)
 148  *     {
 149  *         delete __pOverlay;
 150  *         __pOverlay = null;
 151  *     }
 152  * }
 153  *
 154  * void
 155  * VideoFrameSample::ProcessVideoStream(VideoFrame &frame)
 156  * {
 157  *     MediaPixelFormat format = frame.GetPixelFormat();
 158  *     int count = frame.GetPlaneCount();
 159  *     int width = frame.GetWidth();
 160  *     int height = frame.GetHeight();
 161  *
 162  *     for (int i=0; i<count; i++)
 163  *     {
 164  *        switch(frame.GetPlaneType(i))
 165  *        {
 166  *        case VIDEO_PLANE_TYPE_Y:
 167  *           // Manipulates Y plane.
 168  *           break;
 169  *        case VIDEO_PLANE_TYPE_U:
 170  *           // Manipulates U plane.
 171  *            break;
 172  *        case VIDEO_PLANE_TYPE_V:
 173  *           // Manipulates V plane.
 174  *           break;
 175  *        case VIDEO_PLANE_TYPE_YUV:
 176  *           // Manipulates YUV plane, which YUV data exists in linear memory space. Check pixel format to detect the order of YUV data.
 177  *           break;
 178  *        case VIDEO_PLANE_TYPE_UV:
 179  *           // Manipulates UV plane, which UV data exists in linear memory space. Check pixel format to detect the order or UV data.
 180  *           break;
 181  *        default:
 182  *           break;
 183  *     }
 184  * }
 185  *
 186  * @endcode
 187  *
 188  *
 189  */
 190 class _OSP_EXPORT_ VideoFrame
 191         : public Tizen::Base::Object
 192 {
 193 public:
 194         /**
 195          *
 196          * Gets the plane count that the frame data has.
 197          *
 198          * @since               2.1
 199          *
 200          * @return           The plane count
 201          *
 202          */
 203         int GetPlaneCount(void) const;
 204
 205         /**
 206          *
 207          * Gets the video plane type at a specified index from the frame.
 208          *
 209          * @since               2.1
 210          *
 211          * @return       The video plane type, @n
 212          *               else ::VIDEO_PLANE_TYPE_NONE if an error occurred
 213          * @param[in]   index                           The index at which the value is read
 214          * @exception   E_SUCCESS                                       The method is successful.
 215          * @exception   E_OUT_OF_RANGE                          The specified index is out of range.
 216          * @remarks
 217          *                      - The index should be less than the plane count.
 218          *                      - The specific error code can be accessed using the GetLastResult() method.
 219          *
 220          */
 221         VideoPlaneType GetPlaneType(int index) const;
 222
 223         /**
 224          *
 225          * Gets the plane data at a specified index from the frame.
 226          *
 227          * @since               2.1
 228          *
 229          * @return       The plane data, @n
 230          *               else @c null if an error occurred
 231          * @param[in]   index                           The index at which the value is read
 232          * @exception   E_SUCCESS                                       The method is successful.
 233          * @exception   E_OUT_OF_RANGE                          The specified index is out of range.
 234          * @remarks
 235          *                      - The index should be less than the plane count.
 236          *              - The buffer in ByteBuffer is shared with VideoFrame instance.
 237          *                      - The specific error code can be accessed using the GetLastResult() method.
 238          *
 239          */
 240         Tizen::Base::ByteBuffer* GetPlaneData(int index) const;
 241
 242         /**
 243          *
 244          * Gets the bytes count per a line of a specified index plane.
 245          *
 246          * @since               2.1
 247          *
 248          * @return       The number of bytes per a line of the plane, @n
 249          *               else @c 0 if an error occurred
 250          * @param[in]   index                           The index at which the value is read
 251          * @exception   E_SUCCESS                                       The method is successful.
 252          * @exception   E_OUT_OF_RANGE                          The specified index is out of range.
 253          * @remarks
 254          *                      - The index should be less than the plane count.
 255          *                      - The specific error code can be accessed using the GetLastResult() method.
 256          *
 257          */
 258         int GetBytesCountPerLine(int index) const;
 259
 260         /**
 261          *
 262          * Gets the width of the frame.
 263          *
 264          * @since               2.1
 265          *
 266          * @return       The width of the frame
 267          *
 268          */
 269         int GetWidth(void) const;
 270
 271         /**
 272          *
 273          * Gets the height of the frame.
 274          *
 275          * @since               2.1
 276          *
 277          * @return       The height of the frame
 278          *
 279          */
 280         int GetHeight(void) const;
 281
 282         /**
 283          *
 284          * Gets the pixel format of the frame.
 285          *
 286          * @since               2.1
 287          *
 288          * @return       The pixel format of the frame
 289          *
 290          */
 291         MediaPixelFormat GetPixelFormat(void) const;
 292
 293 private:
 294         /**
 295          * This is the default constructor for this class. @n
 296          * The object is not fully constructed after this constructor is called. @n For full construction,
 297          * the Construct() method must be called right after calling this constructor.
 298          *
 299          * @since       2.1
 300          */
 301         VideoFrame(void);
 302
 303         /**
 304          * This is the destructor for this class. @n
 305          * All allocated resources are deallocated by this method. This polymorphic destructor should be overridden if required.
 306          * This way, the destructors of the derived classes are called when the destructor of this interface is called.
 307          *
 308          * @since       2.1
 309          */
 310         virtual ~VideoFrame(void);
 311
 312         /**
 313          * Constructs the instance of this class. @n
 314          *
 315          * @since       2.1
 316          *
 317          * @return          An error code
 318          * @exception   E_SUCCESS       The method is successful.
 319          *
 320          */
 321         result Construct(void);
 322
 323         /**
 324           * This is the copy constructor for this class.
 325           *
 326           * @since              2.1
 327           *
 328           * @remarks        The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 329           */
 330         VideoFrame(const VideoFrame& rhs);
 331
 332         /**
 333           * This is the copy assignment operator for this class.
 334           *
 335           * @since              2.1
 336           *
 337           * @remarks        The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 338           *
 339           */
 340         VideoFrame& operator =(const VideoFrame& rhs);
 341
 342         friend class _VideoStreamCoordinator;
 343         friend class _VideoFrameImpl;
 344         class _VideoFrameImpl* __pImpl;
 345
 346 };
 347
 348 }}// Tizen::Media
 349
 350 #endif