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 video frame data.
  37  *
  38  * @final       This class is not intended for extension.
  39  *
  40  * @since               2.1
  41  *
  42  * The %VideoFrame class has video frame data.
  43  * The frame has several plane components which represent 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  * #include <FUi.h>
  52  *
  53  * using namespace Tizen::Graphics;
  54  * using namespace Tizen::Ui;
  55  * using namespace Tizen::Ui::Controls;
  56  * using namespace Tizen::Media;
  57  *
  58  * class VideoFrameSample
  59  *     : public Tizen::Ui::Controls::Form
  60  *     , public Tizen::Media::ICameraEventListener
  61  *     , public Tizen::Media::IVideoStreamFilter
  62  * {
  63  * public:
  64  *     VideoFrameSample(void);
  65  *     result Start(void);
  66  *     void Stop(void);
  67  *
  68  * protected:
  69  *     virtual void OnCameraAutoFocused(bool completeCondition) {}
  70  *     virtual void OnCameraPreviewed( Tizen::Base::ByteBuffer& previewedData, result r) {}
  71  *     virtual void OnCameraCaptured( Tizen::Base::ByteBuffer& capturedData, result r) {}
  72  *     virtual void OnCameraErrorOccurred(CameraErrorReason r ) {}
  73  *     virtual void ProcessVideoStream(VideoFrame &frame);
  74  *
  75  * private:
  76  *     Camera __camera;
  77  *     OverlayRegion * __pOverlay;
  78  * };
  79  *
  80  * VideoFrameSample::VideoFrameSample(void)
  81  * {
  82  *     __pOverlay = null;
  83  * }
  84  *
  85  * result
  86  * VideoFrameSample::Start(void)
  87  * {
  88  *     result r = E_SUCCESS;
  89  *     Rectangle rect(0, 0, 320, 240);
  90  *     bool modified = false;
  91  *     bool isValid = false;
  92  *     BufferInfo bufferInfo;
  93  *
  94  *     r = __camera.Construct(*this, CAMERA_PRIMARY);
  95  *     if (IsFailed(r))
  96  *     {
  97  *         return r;
  98  *     }
  99  *
 100  *     r = __camera.PowerOn();
 101  *     if (IsFailed(r))
 102  *     {
 103  *         return r;
 104  *     }
 105  *
 106  *     r = __camera.AddVideoStreamFilter(*this);
 107  *     if (IsFailed(r))
 108  *     {
 109  *         return r;
 110  *     }
 111  *
 112  *     isValid = OverlayRegion::EvaluateBounds(OVERLAY_REGION_EVALUATION_OPTION_LESS_THAN, rect, modified);
 113  *     if (isValid != true)
 114  *     {
 115  *         return GetLastResult();
 116  *     }
 117  *
 118  *     // Gets OverlayRegion from this Form
 119  *     __pOverlay = GetOverlayRegionN(rect, OVERLAY_REGION_TYPE_PRIMARY_CAMERA);
 120  *     if (__pOverlay == null)
 121  *     {
 122  *         return GetLastResult();
 123  *     }
 124  *
 125  *     __pOverlay->GetBackgroundBufferInfo(bufferInfo);
 126  *
 127  *     r = __camera.StartPreview(&bufferInfo, true);
 128  *     if (IsFailed(r))
 129  *     {
 130  *         goto CATCH;
 131  *     }
 132  *
 133  *     return E_SUCCESS;
 134  * CATCH:
 135  *     if (__pOverlay)
 136  *     {
 137  *         delete __pOverlay;
 138  *         __pOverlay = null;
 139  *     }
 140  *     return r;
 141  *  }
 142  *
 143  * void
 144  * VideoFrameSample::Stop(void)
 145  * {
 146  *     __camera.StopPreview();
 147  *     __camera.PowerOff();
 148  *     if (__pOverlay)
 149  *     {
 150  *         delete __pOverlay;
 151  *         __pOverlay = null;
 152  *     }
 153  * }
 154  *
 155  * void
 156  * VideoFrameSample::ProcessVideoStream(VideoFrame &frame)
 157  * {
 158  *     MediaPixelFormat format = frame.GetPixelFormat();
 159  *     int count = frame.GetPlaneCount();
 160  *     int width = frame.GetWidth();
 161  *     int height = frame.GetHeight();
 162  *
 163  *         AppLog("frame plane count is %d", count);
 164  *         AppLog("frame plane width is %d and height is %d", width, height);
 165  *         AppLog("frame Pixel Format is %d", format);
 166  *
 167  *     for (int i=0; i<count; i++)
 168  *     {
 169  *        switch(frame.GetPlaneType(i))
 170  *        {
 171  *        case VIDEO_PLANE_TYPE_Y:
 172  *           // Manipulates Y plane.
 173  *           break;
 174  *        case VIDEO_PLANE_TYPE_U:
 175  *           // Manipulates U plane.
 176  *            break;
 177  *        case VIDEO_PLANE_TYPE_V:
 178  *           // Manipulates V plane.
 179  *           break;
 180  *        case VIDEO_PLANE_TYPE_YUV:
 181  *           // Manipulates YUV plane, which YUV data exists in linear memory space. Check pixel format to detect the order of YUV data.
 182  *           break;
 183  *        case VIDEO_PLANE_TYPE_UV:
 184  *           // Manipulates UV plane, which UV data exists in linear memory space. Check pixel format to detect the order or UV data.
 185  *           break;
 186  *        default:
 187  *           break;
 188  *           }
 189  *     }
 190  * }
 191  *
 192  * @endcode
 193  *
 194  *
 195  */
 196 class _OSP_EXPORT_ VideoFrame
 197         : public Tizen::Base::Object
 198 {
 199 public:
 200    /**
 201         * Gets the plane count of the frame data.
 202         *
 203         * @since                2.1
 204         *
 205         * @return       The plane count
 206         *
 207         */
 208         int GetPlaneCount(void) const;
 209
 210    /**
 211         * Gets the video plane type at the specified index from the frame.
 212         *
 213         * @since                2.1
 214         *
 215         * @return       The video plane type, @n
 216         *               else ::VIDEO_PLANE_TYPE_NONE if an error occurs
 217         * @param[in]    index                           The index at which the value is read
 218         * @exception    E_SUCCESS                       The method is successful.
 219         * @exception    E_OUT_OF_RANGE          The specified @c index is out of the valid range.
 220         * @remarks
 221         *                       - The index should be less than the plane count.
 222         *                       - The specific error code can be accessed using the GetLastResult() method.
 223         *
 224         */
 225         VideoPlaneType GetPlaneType(int index) const;
 226
 227    /**
 228         *
 229         * Gets the plane data at the specified index from the frame.
 230         *
 231         * @since                2.1
 232         *
 233         * @return       The plane data, @n
 234         *               else @c null if an error occurs
 235         * @param[in]    index                           The index at which the value is read
 236         * @exception    E_SUCCESS                       The method is successful.
 237         * @exception    E_OUT_OF_RANGE          The specified @c index is out of the valid range.
 238         * @remarks
 239         *                       - The index should be less than the plane count.
 240         *                       - The buffer in Tizen::Base::ByteBuffer is shared with the %VideoFrame instance.
 241         *                       - The specific error code can be accessed using the GetLastResult() method.
 242         *
 243         */
 244         Tizen::Base::ByteBuffer* GetPlaneData(int index) const;
 245
 246    /**
 247         * Gets the byte count per line of the specified index plane.
 248         *
 249         * @since                2.1
 250         *
 251         * @return       The number of bytes per line of the plane, @n
 252         *               else @c 0 if an error occurs
 253         * @param[in]    index                           The index at which the value is read
 254         * @exception    E_SUCCESS                       The method is successful.
 255         * @exception    E_OUT_OF_RANGE          The specified @c index is out of the valid range.
 256         * @remarks
 257         *                       - The index should be less than the plane count.
 258         *                       - The specific error code can be accessed using the GetLastResult() method.
 259         *
 260         */
 261         int GetBytesCountPerLine(int index) const;
 262
 263    /**
 264         * Gets the width of the frame.
 265         *
 266         * @since         2.1
 267         *
 268         * @return    The width of the frame
 269         *
 270         */
 271         int GetWidth(void) const;
 272
 273    /**
 274         * Gets the height of the frame.
 275         *
 276         * @since         2.1
 277         *
 278         * @return    The height of the frame
 279         *
 280         */
 281         int GetHeight(void) const;
 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