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
