1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
|
/* Copyright (c) 2012 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.
*/
/**
* This file defines the <code>PPB_VideoCapture_Dev</code> interface.
*/
label Chrome {
M19 = 0.2,
M25 = 0.3
};
/**
* Video capture interface. It goes hand-in-hand with PPP_VideoCapture_Dev.
*
* Theory of operation:
* 1- Create a VideoCapture resource using Create.
* 2- Find available video capture devices using EnumerateDevices.
* 3- Open a video capture device. In addition to a device reference (0 can be
* used to indicate the default device), you pass in the requested info
* (resolution, frame rate), as well as suggest a number of buffers you will
* need.
* 4- Start the capture using StartCapture.
* 5- Receive the OnDeviceInfo callback, in PPP_VideoCapture_Dev, which will
* give you the actual capture info (the requested one is not guaranteed), as
* well as an array of buffers allocated by the browser.
* 6- On every frame captured by the browser, OnBufferReady (in
* PPP_VideoCapture_Dev) is called with the index of the buffer from the array
* containing the new frame. The buffer is now "owned" by the plugin, and the
* browser won't reuse it until ReuseBuffer is called.
* 7- When the plugin is done with the buffer, call ReuseBuffer.
* 8- Stop the capture using StopCapture.
* 9- Close the device.
*
* The browser may change the resolution based on the constraints of the system,
* in which case OnDeviceInfo will be called again, with new buffers.
*
* The buffers contain the pixel data for a frame. The format is planar YUV
* 4:2:0, one byte per pixel, tightly packed (width x height Y values, then
* width/2 x height/2 U values, then width/2 x height/2 V values).
*/
interface PPB_VideoCapture_Dev {
/**
* Creates a new VideoCapture.
*/
PP_Resource Create(
[in] PP_Instance instance);
/**
* Returns PP_TRUE if the given resource is a VideoCapture.
*/
PP_Bool IsVideoCapture(
[in] PP_Resource video_capture);
/**
* Enumerates video capture devices. Once the operation is completed
* successfully, |devices| will be set to a PPB_ResourceArray_Dev resource,
* which holds a list of PPB_DeviceRef_Dev resources.
*
* Please note that:
* - this method ignores the previous value pointed to by |devices| (won't
* release reference even if it is not 0);
* - |devices| must be valid until |callback| is called, if the method
* returns PP_OK_COMPLETIONPENDING;
* - the ref count of the returned |devices| has already been increased by 1
* for the caller.
*/
[deprecate=0.3]
int32_t EnumerateDevices(
[in] PP_Resource video_capture,
[out] PP_Resource devices,
[in] PP_CompletionCallback callback);
/**
* Enumerates video capture devices.
*
* @param[in] video_capture A <code>PP_Resource</code> corresponding to a
* video capture resource.
* @param[in] output An output array which will receive
* <code>PPB_DeviceRef_Dev</code> resources on success. Please note that the
* ref count of those resources has already been increased by 1 for the
* caller.
* @param[in] callback A <code>PP_CompletionCallback</code> to run on
* completion.
*
* @return An error code from <code>pp_errors.h</code>.
*/
[version=0.3]
int32_t EnumerateDevices(
[in] PP_Resource video_capture,
[in] PP_ArrayOutput output,
[in] PP_CompletionCallback callback);
/**
* Requests device change notifications.
*
* @param[in] video_capture A <code>PP_Resource</code> corresponding to a
* video capture resource.
* @param[in] callback The callback to receive notifications. If not NULL, it
* will be called once for the currently available devices, and then every
* time the list of available devices changes. All calls will happen on the
* same thread as the one on which MonitorDeviceChange() is called. It will
* receive notifications until <code>video_capture</code> is destroyed or
* <code>MonitorDeviceChange()</code> is called to set a new callback for
* <code>video_capture</code>. You can pass NULL to cancel sending
* notifications.
* @param[inout] user_data An opaque pointer that will be passed to
* <code>callback</code>.
*
* @return An error code from <code>pp_errors.h</code>.
*/
[version=0.3]
int32_t MonitorDeviceChange(
[in] PP_Resource video_capture,
[in] PP_MonitorDeviceChangeCallback callback,
[inout] mem_t user_data);
/**
* Opens a video capture device. |device_ref| identifies a video capture
* device. It could be one of the resource in the array returned by
* |EnumerateDevices()|, or 0 which means the default device.
* |requested_info| is a pointer to a structure containing the requested
* resolution and frame rate. |buffer_count| is the number of buffers
* requested by the plugin. Note: it is only used as advisory, the browser may
* allocate more or fewer based on available resources. How many buffers
* depends on usage. At least 2 to make sure latency doesn't cause lost
* frames. If the plugin expects to hold on to more than one buffer at a time
* (e.g. to do multi-frame processing, like video encoding), it should request
* that many more.
*/
int32_t Open(
[in] PP_Resource video_capture,
[in] PP_Resource device_ref,
[in] PP_VideoCaptureDeviceInfo_Dev requested_info,
[in] uint32_t buffer_count,
[in] PP_CompletionCallback callback);
/**
* Starts the capture.
*
* Returns PP_ERROR_FAILED if called when the capture was already started, or
* PP_OK on success.
*/
int32_t StartCapture(
[in] PP_Resource video_capture);
/**
* Allows the browser to reuse a buffer that was previously sent by
* PPP_VideoCapture_Dev.OnBufferReady. |buffer| is the index of the buffer in
* the array returned by PPP_VideoCapture_Dev.OnDeviceInfo.
*
* Returns PP_ERROR_BADARGUMENT if buffer is out of range (greater than the
* number of buffers returned by PPP_VideoCapture_Dev.OnDeviceInfo), or if it
* is not currently owned by the plugin. Returns PP_OK otherwise.
*/
int32_t ReuseBuffer(
[in] PP_Resource video_capture,
[in] uint32_t buffer);
/**
* Stops the capture.
*
* Returns PP_ERROR_FAILED if the capture wasn't already started, or PP_OK on
* success.
*/
int32_t StopCapture(
[in] PP_Resource video_capture);
/**
* Closes the video capture device, and stops capturing if necessary. It is
* not valid to call |Open()| again after a call to this method.
* If a video capture resource is destroyed while a device is still open, then
* it will be implicitly closed, so you are not required to call this method.
*/
void Close(
[in] PP_Resource video_capture);
};
|
