ppapi/cpp/media_stream_video_track.h

   1 // Copyright 2014 The Chromium Authors
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef PPAPI_CPP_MEDIA_STREAM_VIDEO_TRACK_H_
   6 #define PPAPI_CPP_MEDIA_STREAM_VIDEO_TRACK_H_
   7
   8 #include <stdint.h>
   9
  10 #include <string>
  11
  12 #include "ppapi/c/ppb_media_stream_video_track.h"
  13 #include "ppapi/cpp/resource.h"
  14 #include "ppapi/cpp/var.h"
  15
  16 /// @file
  17 /// This file defines the <code>MediaStreamVideoTrack</code> interface for a
  18 /// video source resource, which receives video frames from a MediaStream video
  19 /// track in the browser.
  20
  21 namespace pp {
  22
  23 class VideoFrame;
  24 class CompletionCallback;
  25 template <typename T> class CompletionCallbackWithOutput;
  26
  27 /// The <code>MediaStreamVideoTrack</code> class contains methods for
  28 /// receiving video frames from a MediaStream video track in the browser.
  29 class MediaStreamVideoTrack : public Resource {
  30  public:
  31   /// Default constructor for creating an is_null()
  32   /// <code>MediaStreamVideoTrack</code> object.
  33   MediaStreamVideoTrack();
  34
  35   /// The copy constructor for <code>MediaStreamVideoTrack</code>.
  36   ///
  37   /// @param[in] other A reference to a <code>MediaStreamVideoTrack</code>.
  38   MediaStreamVideoTrack(const MediaStreamVideoTrack& other);
  39
  40   /// Constructs a <code>MediaStreamVideoTrack</code> from
  41   /// a <code>Resource</code>.
  42   ///
  43   /// @param[in] resource A <code>PPB_MediaStreamVideoTrack</code> resource.
  44   explicit MediaStreamVideoTrack(const Resource& resource);
  45
  46   /// Constructs a <code>MediaStreamVideoTrack</code> that outputs given frames
  47   /// to a new video track, which will be consumed by Javascript.
  48   explicit MediaStreamVideoTrack(const InstanceHandle& instance);
  49
  50   /// A constructor used when you have received a <code>PP_Resource</code> as a
  51   /// return value that has had 1 ref added for you.
  52   ///
  53   /// @param[in] resource A <code>PPB_MediaStreamVideoTrack</code> resource.
  54   MediaStreamVideoTrack(PassRef, PP_Resource resource);
  55
  56   ~MediaStreamVideoTrack();
  57
  58   /// Configures underlying frame buffers for incoming frames.
  59   /// If the application doesn't want to drop frames, then the
  60   /// <code>PP_MEDIASTREAMVIDEOTRACK_ATTRIB_BUFFERED_FRAMES</code> should be
  61   /// chosen such that inter-frame processing time variability won't overrun the
  62   /// input buffer. If the buffer is overfilled, then frames will be dropped.
  63   /// The application can detect this by examining the timestamp on returned
  64   /// frames. If some attributes are not specified, default values will be used
  65   /// for those unspecified attributes. If <code>Configure()</code> is not
  66   /// called, default settings will be used.
  67   /// Example usage from plugin code:
  68   /// @code
  69   /// int32_t attribs[] = {
  70   ///     PP_MEDIASTREAMVIDEOTRACK_ATTRIB_BUFFERED_FRAMES, 4,
  71   ///     PP_MEDIASTREAMVIDEOTRACK_ATTRIB_NONE};
  72   /// track.Configure(attribs, callback);
  73   /// @endcode
  74   ///
  75   /// @param[in] attrib_list A list of attribute name-value pairs in which each
  76   /// attribute is immediately followed by the corresponding desired value.
  77   /// The list is terminated by
  78   /// <code>PP_MEDIASTREAMVIDEOTRACK_ATTRIB_NONE</code>.
  79   /// @param[in] callback A <code>CompletionCallback</code> to be called upon
  80   /// completion of <code>Configure()</code>.
  81   ///
  82   /// @return An int32_t containing a result code from <code>pp_errors.h</code>.
  83   /// Returns <code>PP_ERROR_INPROGRESS</code> if there is a pending call of
  84   /// <code>Configure()</code> or <code>GetFrame()</code>, or the plugin
  85   /// holds some frames which are not recycled with <code>RecycleFrame()</code>.
  86   /// If an error is returned, all attributes and the underlying buffer will not
  87   /// be changed.
  88   int32_t Configure(const int32_t attributes[],
  89                     const CompletionCallback& callback);
  90
  91   /// Gets attribute value for a given attribute name.
  92   ///
  93   /// @param[in] attrib A <code>PP_MediaStreamVideoTrack_Attrib</code> for
  94   /// querying.
  95   /// @param[out] value A int32_t for storing the attribute value.
  96   ///
  97   /// @return An int32_t containing a result code from <code>pp_errors.h</code>.
  98   int32_t GetAttrib(PP_MediaStreamVideoTrack_Attrib attrib,
  99                     int32_t* value);
 100
 101   /// Returns the track ID of the underlying MediaStream video track.
 102   std::string GetId() const;
 103
 104   /// Checks whether the underlying MediaStream track has ended.
 105   /// Calls to GetFrame while the track has ended are safe to make and will
 106   /// complete, but will fail.
 107   bool HasEnded() const;
 108
 109   /// Gets the next video frame from the MediaStream track.
 110   /// If internal processing is slower than the incoming frame rate, new frames
 111   /// will be dropped from the incoming stream. Once the input buffer is full,
 112   /// frames will be dropped until <code>RecycleFrame()</code> is called to free
 113   /// a spot for another frame to be buffered.
 114   /// If there are no frames in the input buffer,
 115   /// <code>PP_OK_COMPLETIONPENDING</code> will be returned immediately and the
 116   /// <code>callback</code> will be called when a new frame is received or some
 117   /// error happens.
 118   ///
 119   /// @param[in] callback A <code>CompletionCallbackWithOutput</code> to be
 120   /// called upon completion of <code>GetFrame()</code>. If success,
 121   /// a VideoFrame will be passed into the completion callback function.
 122   ///
 123   /// @return An int32_t containing a result code from <code>pp_errors.h</code>.
 124   /// Returns PP_ERROR_NOMEMORY if <code>max_buffered_frames</code> frames
 125   /// buffer was not allocated successfully.
 126   int32_t GetFrame(
 127       const CompletionCallbackWithOutput<VideoFrame>& callback);
 128
 129   /// Recycles a frame returned by <code>GetFrame()</code>, so the track can
 130   /// reuse the underlying buffer of this frame. And the frame will become
 131   /// invalid. The caller should release all references it holds to
 132   /// <code>frame</code> and not use it anymore.
 133   ///
 134   /// @param[in] frame A VideoFrame returned by <code>GetFrame()</code>.
 135   ///
 136   /// @return An int32_t containing a result code from <code>pp_errors.h</code>.
 137   int32_t RecycleFrame(const VideoFrame& frame);
 138
 139   /// Closes the MediaStream video track, and disconnects it from video source.
 140   /// After calling <code>Close()</code>, no new frames will be received.
 141   void Close();
 142
 143   // Gets a free frame for output. The frame is allocated by
 144   // <code>Configure()</code>. The caller should fill it with frame data, and
 145   // then use |PutFrame()| to send the frame back.
 146   int32_t GetEmptyFrame(
 147       const CompletionCallbackWithOutput<VideoFrame>& callback);
 148
 149   // Sends a frame returned by |GetEmptyFrame()| to the output track.
 150   // After this function, the |frame| should not be used anymore and the
 151   // caller should release the reference that it holds.
 152   int32_t PutFrame(const VideoFrame& frame);
 153
 154   /// Checks whether a <code>Resource</code> is a MediaStream video track,
 155   /// to test whether it is appropriate for use with the
 156   /// <code>MediaStreamVideoTrack</code> constructor.
 157   ///
 158   /// @param[in] resource A <code>Resource</code> to test.
 159   ///
 160   /// @return True if <code>resource</code> is a MediaStream video track.
 161   static bool IsMediaStreamVideoTrack(const Resource& resource);
 162 };
 163
 164 }  // namespace pp
 165
 166 #endif  // PPAPI_CPP_MEDIA_STREAM_VIDEO_TRACK_H_