ppapi/c/dev/ppb_video_capture_dev.h

   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