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