Add PP_VideoFrame, PPB_VideoReader, and PPB_VideoWriter APIs to Pepper.

ppapi/api/ppb_video_reader.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_VideoReader</code> struct for a video reader
+ * resource.
+ */
+
+ label Chrome {
+   M28 = 1.0
+ };
+
+/**
+ * The <code>PPB_VideoReader</code> interface contains pointers to several
+ * functions for creating video reader resources and using them to consume
+ * streams of video frames.
+ */
+interface PPB_VideoReader {
+  /**
+   * Creates a video reader resource.
+   *
+   * @param[in] instance A <code>PP_Instance</code> identifying one 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 reader.
+   *
+   * @param[in] resource A <code>PP_Resource</code> corresponding to a resource.
+   *
+   * @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.
+   */
+  PP_Bool IsVideoReader([in] PP_Resource resource);
+
+  /**
+   * Opens a video stream with the given id for reading.
+   *
+   * @param[in] reader A <code>PP_Resource</code> corresponding to a video
+   * reader resource.
+   * @param[in] stream_id A <code>PP_Var</code> holding a string uniquely
+   * identifying the stream.

[yzshen1, 2013/04/02 19:28:39]

It is good to comment how to get this ID.

[bbudge, 2013/04/02 20:07:34]

Done.

+   * @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 reader isn't a valid video reader.
+   * Returns PP_ERROR_INPROGRESS if the writer has already opened a stream.

[yzshen1, 2013/04/02 19:28:39]

writer -> reader?

[bbudge, 2013/04/02 20:07:34]

Done.

+   */
+  int32_t Open([in] PP_Resource reader,
+               [in] PP_Var stream_id,
+               [in] PP_CompletionCallback callback);
+
+  /**
+   * Closes the reader's video stream.
+   *
+   * @param[in] reader A <code>PP_Resource</code> corresponding to a video
+   * reader resource.
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
+   * Returns PP_ERROR_BADRESOURCE if reader isn't a valid video reader.
+   * Returns PP_ERROR_FAILED if the reader has not opened a stream.
+   */
+  int32_t Close([in] PP_Resource reader);

[yzshen1, 2013/04/02 19:28:39]

nit:
(1) So far, all Close() methods (FileIO, URLLoader, etc.) have void as output.
Do we need the return value? It doesn't sound very useful.

(2) It looks more consistent to order the methods so that Close() is the last.

[bbudge, 2013/04/02 20:07:34]

Done.

+
+  /**
+   * Gets the next frame of video from the reader's open stream. The image data
+   * resource returned in the frame will have its reference count incremented by
+   * one and must be managed by the plugin.
+   *
+   * @param[in] reader A <code>PP_Resource</code> corresponding to a video
+   * reader resource.
+   * @param[out] frame A <code>PP_VideoFrame</code> to hold a video frame to
+   * read from the open stream.
+   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
+   * completion of GetNextFrame().
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
+   * Returns PP_ERROR_BADRESOURCE if reader isn't a valid video reader.
+   * Returns PP_ERROR_FAILED if the writer has not opened a stream or if the
+   * video frame has an invalid image data resource.
+   */
+  int32_t GetNextFrame([in] PP_Resource reader,
+                       [out] PP_VideoFrame frame,
+                       [in] PP_CompletionCallback callback);
+};
+