[PPAPI] API definition for video media stream artifacts

ppapi/cpp/media_stream_video_track.h

+// Copyright (c) 2013 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef PPAPI_CPP_MEDIA_STREAM_VIDEO_TRACK_H_
+#define PPAPI_CPP_MEDIA_STREAM_VIDEO_TRACK_H_
+
+#include <string>
+
+#include "ppapi/c/pp_stdint.h"
+#include "ppapi/cpp/resource.h"
+
+/// @file
+/// This file defines the <code>MediaStreamTrackVideo</code> interface for a
+/// video source resource, which receives video frames from a MediaStream video
+/// track in the browser.
+
+namespace pp {
+
+class VideoFrame;
+template <typename T> class CompletionCallbackWithOutput;
+
+/// The <code>MediaStreamVideoTrack</code> class contains methods for
+/// receiving video frames from a MediaStream video track in the browser.
+class MediaStreamVideoTrack : public Resource {
+ public:
+  /// Default constructor for creating an is_null()
+  /// <code>MediaStreamVideoTrack</code> object.
+  MediaStreamVideoTrack();
+
+  /// A constructor used when you have received a <code>PP_Resource</code> as a
+  /// return value that has had 1 ref added for you.
+  ///
+  /// @param[in] resource A <code>PPB_ MediaStreamVideoTrack</code> resource.
+  MediaStreamVideoTrack(PassRef, PP_Resource resource);
+
+  /// The destructor.
+  ~MediaStreamVideoTrack();
+
+  /// Configure underlayer frame buffers for incoming frames. The provided
+  /// |frame_buffer_size| is provided in terms of the number of frames to use
+  /// for incoming frames. Should not be less than 1. If the application doesn't
+  /// want to drop frames, then the |frame_buffer_size| should be chosen such
+  /// that inter-frame processing time variability won't overrun the ring
+  /// buffer. If the buffer is overfilled, then frames will be dropped.
+  /// The application can detect this by examining the timestamp on returned
+  /// frames.
+  /// If |Configure()| is not used, default settings will be used.
+  int32_t Configure(uint32_t frame_buffer_size);
+
+  /// Returns the ID of this track.
+  std::string GetId() const;
+
+  /// Returns true if the track has ended.
+  bool HasEnded() const;
+
+  /// This async call will notify the given CompletionCallback when
+  /// the next frame is delivered on the video track. Note that if internal
+  /// processing is slower than the incoming frame rate, frames will be
+  /// dropped from the incoming stream. Once the input buffer is full,
+  /// frames will be dropped until |ReuseFrame()| is called to free a spot for
+  /// another frame to be buffered.
+  ///
+  /// @param[in] cc A CompletionCallback which will receive the next
+  /// VideoFrame in the track.
+  ///
+  /// @return An int32_t containing a result code from <code>pp_errors.h</code>.
+  /// Returns PP_ERROR_BADRESOURCE if resource isn't a valid video source.
+  /// Returns PP_ERROR_NOMEMORY if |frame_buffer_size| frames buffer was not
+  /// allocated successfully.
+  /// Returns PP_ERROR_FAILED if the source is not open, or if some other
+  /// browser error occurs.
+  int32_t GetFrame(
+      const CompletionCallbackWithOutput<VideoFrame>& cc);
+
+  /// Release a frame got from |GetFrame()|, so the track can reuse it for
+  /// new frames.Gets the next video frame from the MediaStream track.
+  ///
+  /// @param[in] frame A VideoFrame got from |GetFrame()|.
+  ///
+  /// @return An int32_t containing a result code from <code>pp_errors.h</code>.
+  /// Returns PP_ERROR_BADRESOURCE if resource isn't a valid video source.
+  /// Retruns PP_ERROR_BADARGUMENT if frame isn't a vaild video frame got from
+  /// |GetFrame()|.
+  /// Returns PP_ERROR_FAILED if the source is not open, or if some other
+  /// browser error occurs.
+  int32_t ReuseFrame(const VideoFrame& frame);
+};
+
+}  // namespace pp
+
+#endif  // PPAPI_CPP_MEDIA_STREAM_VIDEO_TRACK_H_