Implement device enumeration for PPB_VideoCapture_Dev.

ppapi/api/dev/ppb_video_capture_dev.idl

 /* 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 {
-  M14 = 0.1
+  M14 = 0.1,
+  M18 = 0.2
 };
 
 /**
  * Video capture interface. It goes hand-in-hand with PPP_VideoCapture_Dev.
  *
  * Theory of operation:
  * 1- Create a VideoCapture resource using Create.
  * 2- Start the capture using StartCapture. You pass in the requested info
  * (resolution, frame rate), as well as suggest a number of buffers you will
  * need.
@@ skipping 24 matching lines @@
   /**
    * Returns PP_TRUE if the given resource is a VideoCapture.
    */
   PP_Bool IsVideoCapture(
       [in] PP_Resource video_capture);
 
   /**
    * Starts the capture. |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 of fewer based on available resources.
+   * 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.
    *
    * Returns PP_ERROR_FAILED if called when the capture was already started, or
    * PP_OK on success.
    */
+  [version=0.1]
   int32_t StartCapture(
       [in] PP_Resource video_capture,
       [in] PP_VideoCaptureDeviceInfo_Dev requested_info,
       [in] uint32_t buffer_count);
 
   /**
+   * Enumerates video capture devices. Once the operation is completed
+   * successfully. |GetDevices()| can be used to retrieve the devices.
+   */
+  [version=0.2]
+  int32_t EnumerateDevices(

[brettw, 2012/02/06 21:51:52]

Thinking about this, I think it would be better to have one function rather than
two (one to queue up the list, and one to get the list). This also makes it a
lot more natural to do PP_BlockUntilComplete for the call (one function instead
of two).

So let's just make GetDevices look like this:

int32_t GetDevices(PP_Resource video_capture, PP_Resource* out_device_list,
CompletionCallback callback);

[yzshen1, 2012/02/06 22:42:56]

I agree that this is more intuitive. However, it is more painful to manage the
lifespan of |out_device_list|.
It can not live on the stack. Moreover, callback factory doesn't actually ask
the proxy/impl to abort when it goes away, so it doesn't help to stop writing to
out parameters in this case.

It seems to me that the only way to use this interface is to create an
|out_device_list| on the heap, use a |callback| that is *not* created from a
callback factory (when callback factory gets away, |callback| is not called and
we leak memory), and then delete |out_device_list| in the callback.

This seems a little bit strange. Maybe we should re-visit the implementation of
completion callback and callback factory to work better with such cases.

What do you think?

[brettw, 2012/02/06 23:01:42]

Yeah, I agree. The other way to do this is the way that
PPB_Transport_Dev.GetNextAddress works. In this function, it returns
COMPLETIONPENDING and you call the function again to get the result.

If you want to try this way, I'm happy to. I'm kind of on the fence. I
originally suggested doing the transport function that way since I was concerned
about exactly what you're saying here, and even suggested doing that in a
previous draft of this comment.

But then I got concerned that this model will be confusing to developers. In
some places like URLLoader we need to use the "I fill into your buffer" approach
because we want to avoid extra copies. And then we have some places like
WebSocket.ReceiveMessage that fill into a user buffer also, and I thought that
it would be confusing to use both approaches.

[yzshen1, 2012/02/07 00:15:01]

IMHO, the way how PPB_Transport_Dev.GetNextAddress works is also a little bit
strange.
:(

Have you considered to make the callback factory more powerful and handle more
flexible callbacks for users?
I haven't looked into the details, but maybe that will solve the issue.
We could use template to do the work just as base::Bind/Callback does. For
example,

In C:
// |out_param| must be alive till cb is called!
int32_t Foo(PP_resource bar, Param* out_param, PP_CompletionCallback cb);

In C++:
typedef CompletionCallback<void (int32_t /*result*/, Param* /* param */)>
FooCallback;
int32_t Foo(const FooCallback& cb);

Usage (roughly):
// |param| won't be deleted until the callback is called. It works even if
|callback_factory| goes away earlier.
Param* param = new Param();
FooCallback cb = callback_factory.CreateCallback<FooCallback>(some_class_member,
param);
bar.Foo(cb);

+      [in] PP_Resource video_capture,
+      [in] PP_CompletionCallback callback);
+
+  /**
+   * Gets video capture devices. The returned value is a PPB_ResourceArray_Dev
+   * resource if successful, which holds a list of PPB_DeviceRef_Dev resources.
+   */
+  [version=0.2]
+  PP_Resource GetDevices(
+      [in] PP_Resource video_capture);
+
+  /**
+   * Starts the capture. |device_ref| identifies a video capture device. It
+   * could be one of the resource in the array returned by |GetDevices()|, 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.
+   *
+   * Returns PP_ERROR_FAILED if called when the capture was already started, or
+   * PP_OK on success.
+   */
+  [version=0.2]
+  int32_t StartCapture(
+      [in] PP_Resource video_capture,
+      [in] PP_Resource device_ref,
+      [in] PP_VideoCaptureDeviceInfo_Dev requested_info,
+      [in] uint32_t buffer_count);
+
+  /**
    * 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);
 };