Add PP_VideoFrame, PPB_VideoReader, and PPB_VideoWriter APIs to Pepper.

ppapi/cpp/video.h

+// 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.
+
+#ifndef PPAPI_CPP_VIDEO_H_
+#define PPAPI_CPP_VIDEO_H_
+
+#include "ppapi/c/pp_time.h"
+#include "ppapi/c/pp_video_frame.h"
+#include "ppapi/cpp/completion_callback.h"
+#include "ppapi/cpp/image_data.h"
+#include "ppapi/cpp/pass_ref.h"
+#include "ppapi/cpp/resource.h"
+
+/// @file
+/// This file defines the API to create and use video stream readers and
+/// writers.
+
+namespace pp {
+
+class InstanceHandle;
+
+// TrueTypeFontDesc_Dev --------------------------------------------------------

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

Please update the comments.

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

Done.

+
+/// The <code>TrueTypeFontDesc_Dev</code> class represents a TrueType font
+/// descriptor, used to Create and Describe fonts.
+class VideoFrame {
+ public:
+  /// Default constructor for creating a <code>VideoFrame</code> object.
+  VideoFrame();
+  /// Constructor that takes an existing <code>PP_VideoFrame</code> structure.
+  /// The 'image_data' PP_Resource field in the structure will be managed by
+  /// this instance.
+  VideoFrame(PassRef, const PP_VideoFrame& pp_video_frame);
+  /// The copy constructor for <code>VideoFrame</code>.
+  ///
+  /// @param[in] other A reference to a <code>VideoFrame</code>.
+  VideoFrame(const VideoFrame& other);
+  ~VideoFrame();
+
+  VideoFrame& operator=(const VideoFrame& other);
+
+  const PP_VideoFrame& pp_video_frame() const {
+    return video_frame_;
+  }
+
+  ImageData image_data() const {
+    return image_data_;
+  }
+  void set_image_data(const ImageData& image_data) {
+    image_data_ = image_data;
+    // The assignment above manages the underlying PP_Resources. Copy the new
+    // one into our internal video frame struct.
+    video_frame_.image_data = image_data_.pp_resource();
+  }
+
+  PP_TimeTicks timestamp() const { return video_frame_.timestamp; }
+  void set_timestamp(PP_TimeTicks timestamp) {
+    video_frame_.timestamp = timestamp;
+  }
+
+ private:
+  friend class VideoReader;
+  friend class VideoWriter;
+
+  ImageData image_data_;  // This manages the PP_Resource in video_frame_.
+  PP_VideoFrame video_frame_;
+};
+
+// VideoReader -----------------------------------------------------------------
+
+/// The <code>VideoReader</code> class represents a video reader resource.
+class VideoReader : public Resource {
+ public:
+  /// Default constructor for creating a <code>VideoReader</code> object.
+  VideoReader();
+
+  /// Constructor for creating a <code>VideoReader</code> for an instance.
+  VideoReader(const InstanceHandle& instance);

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

explicit, please.

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

Done.

+
+  /// The copy constructor for <code>VideoReader</code>.
+  ///
+  /// @param[in] other A reference to a <code>VideoReader</code>.
+  VideoReader(const VideoReader& other);
+
+  /// A constructor used when you have received a PP_Resource as a return
+  /// value that has had its reference count incremented for you.
+  ///
+  /// @param[in] resource A PP_Resource corresponding to a video reader.
+  VideoReader(PassRef, PP_Resource resource);
+
+  /// Opens a stream for reading video and associates it with the given id.
+  ///
+  /// @param[in] stream_id A <code>Var</code> uniquely identifying the stream
+  /// to read from.
+  /// @param[in] callback A <code>CompletionCallback</code> to be called upon
+  /// completion of Open.
+  ///
+  /// @return A return code from <code>pp_errors.h</code>.
+  int32_t Open(const pp::Var& stream_id,
+               const CompletionCallback& cc);
+
+  /// Closes the reader's current stream.
+  ///
+  /// @return A return code from <code>pp_errors.h</code>.
+  int32_t Close();
+
+  /// Gets the next frame of video from the reader's stream.
+  ///
+  /// @param[in] callback A <code>CompletionCallbackWithOutput</code> to be
+  /// called upon completion of GetNextFrame.
+  ///
+  /// @return A return code from <code>pp_errors.h</code>.
+  int32_t GetNextFrame(const CompletionCallbackWithOutput<VideoFrame>& cc);
+};
+
+// VideoWriter -----------------------------------------------------------------
+
+/// The <code>VideoWriter</code> class represents a video writer resource.
+class VideoWriter : public Resource {

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

Shall we split them into separate files?

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

I thought about this. If we put each class in its own file, then we should
probably put the VideoFrame struct in its own file too. I decided to follow the
precedent of InputEvent, where closely related APIs are bundled together. The
file names 'video.h' and 'video.cc' are a bit too generic and thought about
calling them 'video_stream.*' but that would suggest we name these APIs
VideoStreamReader and VideoStreamWriter, and that seems too much. I'll split
these out into separate files if people feel strongly about it.

On 2013/04/02 19:28:39, yzshen1 wrote:

+ public:
+  /// Default constructor for creating a <code>VideoWriter</code> object.
+  VideoWriter();
+
+  /// The copy constructor for <code>VideoWriter</code>.
+  ///
+  /// @param[in] other A reference to a <code>VideoWriter</code>.
+  VideoWriter(const VideoReader& other);
+
+  /// A constructor used when you have received a PP_Resource as a return
+  /// value that has had its reference count incremented for you.
+  ///
+  /// @param[in] resource A PP_Resource corresponding to a video writer.
+  VideoWriter(PassRef, PP_Resource resource);
+
+  /// Opens a stream for writing video and associates it with the given id.
+  ///
+  /// @param[in] stream_id A <code>Var</code> uniquely identifying the stream
+  /// to write to.
+  /// @param[in] callback A <code>CompletionCallback</code> to be called upon
+  /// completion of Open.
+  ///
+  /// @return A return code from <code>pp_errors.h</code>.
+  int32_t Open(const pp::Var& stream_id,
+               const CompletionCallback& cc);
+
+  /// Closes the writer's current stream.
+  ///
+  /// @return A return code from <code>pp_errors.h</code>.
+  int32_t Close();
+
+  /// Emits the next frame of video to the writer's stream.
+  ///
+  /// @param[in] frame A <code>VideoFrame</code> containing the frame to write
+  /// to the open stream.
+  ///
+  /// @return A return code from <code>pp_errors.h</code>.
+  int32_t EmitFrame(const VideoFrame& frame);
+};
+
+namespace internal {
+
+// A specialization of CallbackOutputTraits to provide the callback system the
+// information on how to handle pp::VideoFrame. This converts PP_VideoFrame to
+// pp::VideoFrame when passing to the plugin, and specifically manages the
+// PP_Resource embedded in the video_frame_ field.
+template<>
+struct CallbackOutputTraits<pp::VideoFrame> {
+  typedef PP_VideoFrame* APIArgType;
+  typedef PP_VideoFrame StorageType;
+
+  static inline APIArgType StorageToAPIArg(StorageType& t) {
+    return &t;
+  }
+
+  static inline pp::VideoFrame StorageToPluginArg(StorageType& t) {
+    return pp::VideoFrame(PASS_REF, t);
+  }
+};
+
+}  // namespace internal
+
+}  // namespace pp
+
+#endif  // PPAPI_CPP_VIDEO_H_