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