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