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 Dec 12 15:36:11 2013. */ 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_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 */ 63 struct PPB_VideoCapture_Dev_0_3 { 64 /** 65 * Creates a new VideoCapture. 66 */ 67 PP_Resource (*Create)(PP_Instance instance); 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, 108 PP_MonitorDeviceChangeCallback callback, 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 161 typedef struct PPB_VideoCapture_Dev_0_3 PPB_VideoCapture_Dev; 162 /** 163 * @} 164 */ 165 166 #endif /* PPAPI_C_DEV_PPB_VIDEO_CAPTURE_DEV_H_ */ 167 168