Rename PPAPI Video Stream APIs.

ppapi/api/private/ppb_video_destination_private.idl

 /* Copyright (c) 2013 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_VideoWriter</code> struct for a video writer
- * resource.
+ * This file defines the <code>PPB_VideoDestination_Private</code> interface
+ * for a video destination resource. A video destination sends video frames to
+ * a MediaStream video track.
  */
 
  label Chrome {
    M28 = 0.1
  };
 
 /**
- * The <code>PPB_VideoWriter</code> interface contains pointers to several
- * functions for creating video writer resources and using them to generate
- * streams of video frames.
+ * The <code>PPB_VideoDestination_Private</code> interface contains pointers to
+ * several functions for creating video destination resources and using them to
+ * send video frames to a MediaStream in the browser.
  */
-interface PPB_VideoWriter {
+interface PPB_VideoDestination_Private {
   /**
-   * Creates a video writer resource.
+   * Creates a video destination resource.
    *
-   * @param[in] instance A <code>PP_Instance</code> identifying one instance
-   * of a module.
+   * @param[in] instance A <code>PP_Instance</code> identifying an instance of
+   * a module.
    *
    * @return A <code>PP_Resource</code> with a nonzero ID on success or zero on
    * failure. Failure means the instance was invalid.
    */
   PP_Resource Create([in] PP_Instance instance);
 
   /**
-   * Determines if a given resource is a video writer.
+   * Determines if a resource is a video destination resource.
    *
-   * @param[in] resource A <code>PP_Resource</code> corresponding to a resource.
+   * @param[in] resource The <code>PP_Resource</code> to test.
    *
    * @return A <code>PP_Bool</code> with <code>PP_TRUE</code> if the given
-   * resource is a video writer or <code>PP_FALSE</code> otherwise.
+   * resource is a video destination resource or <code>PP_FALSE</code>
+   * otherwise.
    */
-  PP_Bool IsVideoWriter([in] PP_Resource resource);
+  PP_Bool IsVideoDestination([in] PP_Resource resource);
 
   /**
-   * Opens a video stream with the given id for writing.
+   * Opens a video destination to receive frames.
    *
-   * @param[in] writer A <code>PP_Resource</code> corresponding to a video
-   * writer resource.
-   * @param[out] stream_id A <code>PP_Var</code> holding a string uniquely
-   * identifying the stream. This string is generated by the host.
+   * @param[in] destination A <code>PP_Resource</code> corresponding to a video
+   * destination resource.
+   * @param[in] stream_url A <code>PP_Var</code> string holding a URL
+   * identifying a MediaStream.
    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
    * completion of Open().
    *
-   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
-   * Returns PP_ERROR_BADRESOURCE if writer isn't a valid video writer.
-   * Returns PP_ERROR_INPROGRESS if the writer has already opened a stream.
+   * @return An int32_t containing a result code from <code>pp_errors.h</code>.
+   * Returns PP_ERROR_BADRESOURCE if destination isn't a valid video
+   * destination.
+   * Returns PP_ERROR_INPROGRESS if destination is already open.
+   * Returns PP_ERROR_FAILED if the MediaStream doesn't exist or if there is
+   * some other browser error.
    */
-  int32_t Open([in] PP_Resource writer,
-               [out] PP_Var stream_id,
+  int32_t Open([in] PP_Resource destination,
+               [in] PP_Var stream_url,
                [in] PP_CompletionCallback callback);
 
   /**
-   * Puts a frame of video to the writer's open stream.
+   * Passes a frame from the plugin to the video destination.
    *
    * After this call, you should take care to release your references to the
    * image embedded in the video frame. If you paint to the image after
-   * PutFrame(), there is the possibility of artifacts because the browser may
+   * SendFrame(), there is the possibility of artifacts because the browser may
    * still be copying the frame to the stream.
    *
-   * @param[in] writer A <code>PP_Resource</code> corresponding to a video
-   * writer resource.
-   * @param[in] frame A <code>PP_VideoFrame</code> holding a video frame to
-   * write to the open stream.
+   * @param[in] destination A <code>PP_Resource</code> corresponding to a video
+   * destination resource.
+   * @param[in] frame A <code>PP_VideoFrame_Private</code> holding the video
+   * frame to send to the destination.
    *
-   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
-   * Returns PP_ERROR_BADRESOURCE if writer isn't a valid video writer.
-   * Returns PP_ERROR_FAILED if the writer has not opened a stream, if the video
-   * frame has an invalid image data resource, or if some other error occurs.
+   * @return An int32_t containing a result code from <code>pp_errors.h</code>.
+   * Returns PP_ERROR_BADRESOURCE if destination isn't a valid video
+   * destination.
+   * Returns PP_ERROR_FAILED if destination is not open, if the video frame has
+   * an invalid image data resource, or if some other browser error occurs.
    */
-  int32_t PutFrame([in] PP_Resource writer,
-                   [in] PP_VideoFrame frame);
+  int32_t ReceiveFrame([in] PP_Resource destination,

[dmichael (off chromium), 2013/04/25 18:15:54]

I think this should still be SendFrame, but the class name should be VideoSource

(or change the parameters around... these params make sense only for sending a
frame, I think)

[bbudge, 2013/04/25 18:21:12]

Yeah, this is something that has confused me. From the plugin's point of view,
it's sending a frame. But if we think about a VideoDestination as an object, and
ReceiveFrame as a method, then the destination is receiving a frame.

If I have this backwards and misinterpreted your comment Justin, please correct
me.

[Ronghua Wu (Left Chromium), 2013/04/25 18:22:48]

Agree this should be SendFrame or PutFrame not receive.

+                       [in] PP_VideoFrame_Private frame);
 
   /**
-   * Closes the writer's video stream.
+   * Closes the video destination.
    *
-   * @param[in] writer A <code>PP_Resource</code> corresponding to a video
-   * writer resource.
+   * @param[in] destination A <code>PP_Resource</code> corresponding to a video
+   * destination.
    */
-  void Close([in] PP_Resource writer);
+  void Close([in] PP_Resource destination);
 };