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 */
63struct 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
161typedef struct PPB_VideoCapture_Dev_0_3 PPB_VideoCapture_Dev;
162/**
163 * @}
164 */
165
166#endif  /* PPAPI_C_DEV_PPB_VIDEO_CAPTURE_DEV_H_ */
167
168