ppapi/api/dev/ppb_video_capture_dev.idl

   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 };