/* Copyright (c) 2012 The Chromium Authors. All rights reserved.
 * Use of this source code is governed by a BSD-style license that can be
 * found in the LICENSE file.
 */

/**
 * This file defines the <code>PPB_VideoCapture_Dev</code> interface.
 */
label Chrome {
  M25 = 0.3
};

/**
 * Video capture interface. It goes hand-in-hand with PPP_VideoCapture_Dev.
 *
 * Theory of operation:
 * 1- Create a VideoCapture resource using Create.
 * 2- Find available video capture devices using EnumerateDevices.
 * 3- Open a video capture device. In addition to a device reference (0 can be
 * used to indicate the default device), you pass in the requested info
 * (resolution, frame rate), as well as suggest a number of buffers you will
 * need.
 * 4- Start the capture using StartCapture.
 * 5- Receive the OnDeviceInfo callback, in PPP_VideoCapture_Dev, which will
 * give you the actual capture info (the requested one is not guaranteed), as
 * well as an array of buffers allocated by the browser.
 * 6- On every frame captured by the browser, OnBufferReady (in
 * PPP_VideoCapture_Dev) is called with the index of the buffer from the array
 * containing the new frame. The buffer is now "owned" by the plugin, and the
 * browser won't reuse it until ReuseBuffer is called.
 * 7- When the plugin is done with the buffer, call ReuseBuffer.
 * 8- Stop the capture using StopCapture.
 * 9- Close the device.
 *
 * The browser may change the resolution based on the constraints of the system,
 * in which case OnDeviceInfo will be called again, with new buffers.
 *
 * The buffers contain the pixel data for a frame. The format is planar YUV
 * 4:2:0, one byte per pixel, tightly packed (width x height Y values, then
 * width/2 x height/2 U values, then width/2 x height/2 V values).
 */
interface PPB_VideoCapture_Dev {
  /**
   * Creates a new VideoCapture.
   */
  PP_Resource Create(
      [in] PP_Instance instance);

  /**
   * Returns PP_TRUE if the given resource is a VideoCapture.
   */
  PP_Bool IsVideoCapture(
      [in] PP_Resource video_capture);

  /**
   * Enumerates video capture devices.
   *
   * @param[in] video_capture A <code>PP_Resource</code> corresponding to a
   * video capture resource.
   * @param[in] output An output array which will receive
   * <code>PPB_DeviceRef_Dev</code> resources on success. Please note that the
   * ref count of those resources has already been increased by 1 for the
   * caller.
   * @param[in] callback A <code>PP_CompletionCallback</code> to run on
   * completion.
   *
   * @return An error code from <code>pp_errors.h</code>.
   */
  [version=0.3]
  int32_t EnumerateDevices(
      [in] PP_Resource video_capture,
      [in] PP_ArrayOutput output,
      [in] PP_CompletionCallback callback);

  /**
   * Requests device change notifications.
   *
   * @param[in] video_capture A <code>PP_Resource</code> corresponding to a
   * video capture resource.
   * @param[in] callback The callback to receive notifications. If not NULL, it
   * will be called once for the currently available devices, and then every
   * time the list of available devices changes. All calls will happen on the
   * same thread as the one on which MonitorDeviceChange() is called. It will
   * receive notifications until <code>video_capture</code> is destroyed or
   * <code>MonitorDeviceChange()</code> is called to set a new callback for
   * <code>video_capture</code>. You can pass NULL to cancel sending
   * notifications.
   * @param[inout] user_data An opaque pointer that will be passed to
   * <code>callback</code>.
   *
   * @return An error code from <code>pp_errors.h</code>.
   */
  [version=0.3]
  int32_t MonitorDeviceChange(
      [in] PP_Resource video_capture,
      [in] PP_MonitorDeviceChangeCallback callback,
      [inout] mem_t user_data);

  /**
   * Opens a video capture device. |device_ref| identifies a video capture
   * device. It could be one of the resource in the array returned by
   * |EnumerateDevices()|, or 0 which means the default device.
   * |requested_info| is a pointer to a structure containing the requested
   * resolution and frame rate. |buffer_count| is the number of buffers
   * requested by the plugin. Note: it is only used as advisory, the browser may
   * allocate more or fewer based on available resources. How many buffers
   * depends on usage. At least 2 to make sure latency doesn't cause lost
   * frames. If the plugin expects to hold on to more than one buffer at a time
   * (e.g. to do multi-frame processing, like video encoding), it should request
   * that many more.
   */
  int32_t Open(
      [in] PP_Resource video_capture,
      [in] PP_Resource device_ref,
      [in] PP_VideoCaptureDeviceInfo_Dev requested_info,
      [in] uint32_t buffer_count,
      [in] PP_CompletionCallback callback);

  /**
   * Starts the capture.
   *
   * Returns PP_ERROR_FAILED if called when the capture was already started, or
   * PP_OK on success.
   */
  int32_t StartCapture(
      [in] PP_Resource video_capture);

  /**
   * Allows the browser to reuse a buffer that was previously sent by
   * PPP_VideoCapture_Dev.OnBufferReady. |buffer| is the index of the buffer in
   * the array returned by PPP_VideoCapture_Dev.OnDeviceInfo.
   *
   * Returns PP_ERROR_BADARGUMENT if buffer is out of range (greater than the
   * number of buffers returned by PPP_VideoCapture_Dev.OnDeviceInfo), or if it
   * is not currently owned by the plugin. Returns PP_OK otherwise.
   */
  int32_t ReuseBuffer(
      [in] PP_Resource video_capture,
      [in] uint32_t buffer);

  /**
   * Stops the capture.
   *
   * Returns PP_ERROR_FAILED if the capture wasn't already started, or PP_OK on
   * success.
   */
  int32_t StopCapture(
      [in] PP_Resource video_capture);

  /**
   * Closes the video capture device, and stops capturing if necessary. It is
   * not valid to call |Open()| again after a call to this method.
   * If a video capture resource is destroyed while a device is still open, then
   * it will be implicitly closed, so you are not required to call this method.
   */
  void Close(
      [in] PP_Resource video_capture);
};