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