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