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.
4 */
5
6/* From ppb_media_stream_video_track.idl modified Mon Apr  7 15:25:56 2014. */
7
8#ifndef PPAPI_C_PPB_MEDIA_STREAM_VIDEO_TRACK_H_
9#define PPAPI_C_PPB_MEDIA_STREAM_VIDEO_TRACK_H_
10
11#include "ppapi/c/pp_bool.h"
12#include "ppapi/c/pp_completion_callback.h"
13#include "ppapi/c/pp_instance.h"
14#include "ppapi/c/pp_macros.h"
15#include "ppapi/c/pp_resource.h"
16#include "ppapi/c/pp_stdint.h"
17#include "ppapi/c/pp_var.h"
18
19#define PPB_MEDIASTREAMVIDEOTRACK_INTERFACE_0_1 "PPB_MediaStreamVideoTrack;0.1"
20#define PPB_MEDIASTREAMVIDEOTRACK_INTERFACE_1_0 \
21    "PPB_MediaStreamVideoTrack;1.0" /* dev */
22#define PPB_MEDIASTREAMVIDEOTRACK_INTERFACE \
23    PPB_MEDIASTREAMVIDEOTRACK_INTERFACE_0_1
24
25/**
26 * @file
27 * Defines the <code>PPB_MediaStreamVideoTrack</code> interface. Used for
28 * receiving video frames from a MediaStream video track in the browser.
29 */
30
31
32/**
33 * @addtogroup Enums
34 * @{
35 */
36/**
37 * This enumeration contains video track attributes which are used by
38 * <code>Configure()</code>.
39 */
40typedef enum {
41  /**
42   * Attribute list terminator.
43   */
44  PP_MEDIASTREAMVIDEOTRACK_ATTRIB_NONE = 0,
45  /**
46   * The maximum number of frames to hold in the input buffer.
47   * Note: this is only used as advisory; the browser may allocate more or fewer
48   * based on available resources. How many frames to buffer depends on usage -
49   * request at least 2 to make sure latency doesn't cause lost frames. If
50   * the plugin expects to hold on to more than one frame at a time (e.g. to do
51   * multi-frame processing), it should request that many more.
52   * If this attribute is not specified or value 0 is specified for this
53   * attribute, the default value will be used.
54   */
55  PP_MEDIASTREAMVIDEOTRACK_ATTRIB_BUFFERED_FRAMES = 1,
56  /**
57   * The width of video frames in pixels. It should be a multiple of 4.
58   * If the specified size is different from the video source (webcam),
59   * frames will be scaled to specified size.
60   * If this attribute is not specified or value 0 is specified, the original
61   * frame size of the video track will be used.
62   *
63   * Maximum value: 4096 (4K resolution).
64   */
65  PP_MEDIASTREAMVIDEOTRACK_ATTRIB_WIDTH = 2,
66  /**
67   * The height of video frames in pixels. It should be a multiple of 4.
68   * If the specified size is different from the video source (webcam),
69   * frames will be scaled to specified size.
70   * If this attribute is not specified or value 0 is specified, the original
71   * frame size of the video track will be used.
72   *
73   * Maximum value: 4096 (4K resolution).
74   */
75  PP_MEDIASTREAMVIDEOTRACK_ATTRIB_HEIGHT = 3,
76  /**
77   * The format of video frames. The attribute value is
78   * a <code>PP_VideoFrame_Format</code>. If the specified format is different
79   * from the video source (webcam), frames will be converted to specified
80   * format.
81   * If this attribute is not specified or value
82   * <code>PP_VIDEOFRAME_FORMAT_UNKNOWN</code> is specified, the orignal frame
83   * format of the video track will be used.
84   */
85  PP_MEDIASTREAMVIDEOTRACK_ATTRIB_FORMAT = 4
86} PP_MediaStreamVideoTrack_Attrib;
87/**
88 * @}
89 */
90
91/**
92 * @addtogroup Interfaces
93 * @{
94 */
95struct PPB_MediaStreamVideoTrack_1_0 { /* dev */
96  /**
97   * Creates a PPB_MediaStreamVideoTrack resource for video output. Call this
98   * when you will be creating frames and putting them to the track.
99   *
100   * @param[in] instance A <code>PP_Instance</code> identifying one instance of
101   * a module.
102   *
103   * @return A <code>PP_Resource</code> corresponding to a
104   * PPB_MediaStreamVideoTrack resource if successful, 0 if failed.
105   */
106  PP_Resource (*Create)(PP_Instance instance);
107  /**
108   * Determines if a resource is a MediaStream video track resource.
109   *
110   * @param[in] resource The <code>PP_Resource</code> to test.
111   *
112   * @return A <code>PP_Bool</code> with <code>PP_TRUE</code> if the given
113   * resource is a Mediastream video track resource or <code>PP_FALSE</code>
114   * otherwise.
115   */
116  PP_Bool (*IsMediaStreamVideoTrack)(PP_Resource resource);
117  /**
118   * Configures underlying frame buffers for incoming frames.
119   * If the application doesn't want to drop frames, then the
120   * <code>PP_MEDIASTREAMVIDEOTRACK_ATTRIB_BUFFERED_FRAMES</code> should be
121   * chosen such that inter-frame processing time variability won't overrun the
122   * input buffer. If the buffer is overfilled, then frames will be dropped.
123   * The application can detect this by examining the timestamp on returned
124   * frames. If some attributes are not specified, default values will be used
125   * for those unspecified attributes. If <code>Configure()</code> is not
126   * called, default settings will be used.
127   * Example usage from plugin code:
128   * @code
129   * int32_t attribs[] = {
130   *     PP_MEDIASTREAMVIDEOTRACK_ATTRIB_BUFFERED_FRAMES, 4,
131   *     PP_MEDIASTREAMVIDEOTRACK_ATTRIB_NONE};
132   * track_if->Configure(track, attribs, callback);
133   * @endcode
134   *
135   * @param[in] video_track A <code>PP_Resource</code> corresponding to a video
136   * resource.
137   * @param[in] attrib_list A list of attribute name-value pairs in which each
138   * attribute is immediately followed by the corresponding desired value.
139   * The list is terminated by
140   * <code>PP_MEDIASTREAMVIDEOTRACK_ATTRIB_NONE</code>.
141   * @param[in] callback <code>PP_CompletionCallback</code> to be called upon
142   * completion of <code>Configure()</code>.
143   *
144   * @return An int32_t containing a result code from <code>pp_errors.h</code>.
145   * Returns <code>PP_ERROR_INPROGRESS</code> if there is a pending call of
146   * <code>Configure()</code> or <code>GetFrame()</code>, or the plugin
147   * holds some frames which are not recycled with <code>RecycleFrame()</code>.
148   * If an error is returned, all attributes and the underlying buffer will not
149   * be changed.
150   */
151  int32_t (*Configure)(PP_Resource video_track,
152                       const int32_t attrib_list[],
153                       struct PP_CompletionCallback callback);
154  /**
155   * Gets attribute value for a given attribute name.
156   *
157   * @param[in] video_track A <code>PP_Resource</code> corresponding to a video
158   * resource.
159   * @param[in] attrib A <code>PP_MediaStreamVideoTrack_Attrib</code> for
160   * querying.
161   * @param[out] value A int32_t for storing the attribute value on success.
162   * Otherwise, the value will not be changed.
163   *
164   * @return An int32_t containing a result code from <code>pp_errors.h</code>.
165   */
166  int32_t (*GetAttrib)(PP_Resource video_track,
167                       PP_MediaStreamVideoTrack_Attrib attrib,
168                       int32_t* value);
169  /**
170   * Returns the track ID of the underlying MediaStream video track.
171   *
172   * @param[in] video_track The <code>PP_Resource</code> to check.
173   *
174   * @return A <code>PP_Var</code> containing the MediaStream track ID as
175   * a string.
176   */
177  struct PP_Var (*GetId)(PP_Resource video_track);
178  /**
179   * Checks whether the underlying MediaStream track has ended.
180   * Calls to GetFrame while the track has ended are safe to make and will
181   * complete, but will fail.
182   *
183   * @param[in] video_track The <code>PP_Resource</code> to check.
184   *
185   * @return A <code>PP_Bool</code> with <code>PP_TRUE</code> if the given
186   * MediaStream track has ended or <code>PP_FALSE</code> otherwise.
187   */
188  PP_Bool (*HasEnded)(PP_Resource video_track);
189  /**
190   * Gets the next video frame from the MediaStream track.
191   * If internal processing is slower than the incoming frame rate, new frames
192   * will be dropped from the incoming stream. Once the input buffer is full,
193   * frames will be dropped until <code>RecycleFrame()</code> is called to free
194   * a spot for another frame to be buffered.
195   * If there are no frames in the input buffer,
196   * <code>PP_OK_COMPLETIONPENDING</code> will be returned immediately and the
197   * <code>callback</code> will be called when a new frame is received or an
198   * error happens.
199   *
200   * @param[in] video_track A <code>PP_Resource</code> corresponding to a video
201   * resource.
202   * @param[out] frame A <code>PP_Resource</code> corresponding to a VideoFrame
203   * resource.
204   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
205   * completion of GetFrame().
206   *
207   * @return An int32_t containing a result code from <code>pp_errors.h</code>.
208   * Returns PP_ERROR_NOMEMORY if <code>max_buffered_frames</code> frames buffer
209   * was not allocated successfully.
210   */
211  int32_t (*GetFrame)(PP_Resource video_track,
212                      PP_Resource* frame,
213                      struct PP_CompletionCallback callback);
214  /**
215   * Recycles a frame returned by <code>GetFrame()</code>, so the track can
216   * reuse the underlying buffer of this frame. And the frame will become
217   * invalid. The caller should release all references it holds to
218   * <code>frame</code> and not use it anymore.
219   *
220   * @param[in] video_track A <code>PP_Resource</code> corresponding to a video
221   * resource.
222   * @param[in] frame A <code>PP_Resource</code> corresponding to a VideoFrame
223   * resource returned by <code>GetFrame()</code>.
224   *
225   * @return An int32_t containing a result code from <code>pp_errors.h</code>.
226   */
227  int32_t (*RecycleFrame)(PP_Resource video_track, PP_Resource frame);
228  /**
229   * Closes the MediaStream video track and disconnects it from video source.
230   * After calling <code>Close()</code>, no new frames will be received.
231   *
232   * @param[in] video_track A <code>PP_Resource</code> corresponding to a
233   * MediaStream video track resource.
234   */
235  void (*Close)(PP_Resource video_track);
236  /**
237   * Gets a free frame for output. The frame is allocated by
238   * <code>Configure()</code>. The caller should fill it with frame data, and
239   * then use |PutFrame()| to send the frame back.
240   */
241  int32_t (*GetEmptyFrame)(PP_Resource video_track,
242                           PP_Resource* frame,
243                           struct PP_CompletionCallback callback);
244  /**
245   * Sends a frame returned by |GetEmptyFrame()| to the output track.
246   * After this function, the |frame| should not be used anymore and the
247   * caller should release the reference that it holds.
248   */
249  int32_t (*PutFrame)(PP_Resource video_track, PP_Resource frame);
250};
251
252struct PPB_MediaStreamVideoTrack_0_1 {
253  PP_Bool (*IsMediaStreamVideoTrack)(PP_Resource resource);
254  int32_t (*Configure)(PP_Resource video_track,
255                       const int32_t attrib_list[],
256                       struct PP_CompletionCallback callback);
257  int32_t (*GetAttrib)(PP_Resource video_track,
258                       PP_MediaStreamVideoTrack_Attrib attrib,
259                       int32_t* value);
260  struct PP_Var (*GetId)(PP_Resource video_track);
261  PP_Bool (*HasEnded)(PP_Resource video_track);
262  int32_t (*GetFrame)(PP_Resource video_track,
263                      PP_Resource* frame,
264                      struct PP_CompletionCallback callback);
265  int32_t (*RecycleFrame)(PP_Resource video_track, PP_Resource frame);
266  void (*Close)(PP_Resource video_track);
267};
268
269typedef struct PPB_MediaStreamVideoTrack_0_1 PPB_MediaStreamVideoTrack;
270/**
271 * @}
272 */
273
274#endif  /* PPAPI_C_PPB_MEDIA_STREAM_VIDEO_TRACK_H_ */
275
276