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