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