Pepper: Define PPB_VideoEncoder API.

ppapi/api/ppb_video_encoder.idl

+/* Copyright (c) 2015 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_VideoEncoder</code> interface.
+ */
+
+[generate_thunk]
+
+label Chrome {
+  M42 = 0.1
+};
+
+/**
+ * Video encoder interface.
+ *
+ * Typical usage:
+ * - Call Create() to create a new video encoder resource.
+ * - Call GetSupportedFormats() to determine which codecs and profiles are
+ *   available.
+ * - Call Initialize() to initialize the encoder for a supported profile.
+ * - Call GetVideoFrame() to get a blank frame and fill it in, or get a video
+ *   frame from another resource, e.g. <code>PPB_MediaStreamVideoTrack</code>.
+ * - Call Encode() to push the video frame to the encoder. If an external frame
+ *   is pushed, wait for completion to recycle the frame.
+ * - Call GetBitstreamBuffer() continuously (waiting for each previous call to
+ *   complete) to pull encoded pictures from the encoder.
+ * - Call RecycleBitstreamBuffer() after consuming the data in the bitstream
+ *   buffer.
+ * - To destroy the encoder, the plugin should release all of its references to
+ *   it. Any pending callbacks will abort before the encoder is destroyed.
+ *
+ * Available video codecs vary by platform.
+ * All: theora, vorbis, vp8.
+ * Chrome and ChromeOS: h264.
+ * ChromeOS: mpeg4.
+ */
+interface PPB_VideoEncoder {
+  /**
+   * Creates a new video encoder resource.
+   *
+   * @param[in] instance A <code>PP_Instance</code> identifying the instance
+   * with the video encoder.
+   *
+   * @return A <code>PP_Resource</code> corresponding to a video encoder if
+   * successful or 0 otherwise.
+   */
+  PP_Resource Create(
+      [in] PP_Instance instance);

[dmichael (off chromium), 2015/02/03 23:26:08]

tiny nit: I don't know why we do this style in so many of the IDL files, but I'd
rather we styled them the same as we do C/C++ code. I.e., if the parameter fits,
put it on the same line as the function declaration.

[bbudge, 2015/02/04 13:56:40]

Done.

+
+  /**
+   * Determines if the given resource is a video encoder.
+   *
+   * @param[in] resource A <code>PP_Resource</code> identifying a resource.
+   *
+   * @return <code>PP_TRUE</code> if the resource is a
+   * <code>PPB_VideoEncoder</code>, <code>PP_FALSE</code> if the resource is
+   * invalid or some other type.
+   */
+  PP_Bool IsVideoEncoder(
+      [in] PP_Resource resource);
+
+  /**
+   * Gets an array of supported video encoder profiles.
+   * These can be used to choose a profile before calling Initialize().
+   *
+   * @param[in] video_encoder A <code>PP_Resource</code> identifying the video
+   * encoder.
+   * @param[in] output A <code>PP_ArrayOutput</code> to hold the supported

[dmichael (off chromium), 2015/02/03 23:26:08]

nit: s/hold/receive?
The ArrayOutput doesn't really hold it, so that wording might be confusing...

[bbudge, 2015/02/04 13:56:40]

Done.

+   * <code>PP_SupportedVideoProfile</code> structs.
+   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
+   * completion.
+   *
+   * @return If >= 0, the number of supported profiles returned, otherwise an
+   * error code from <code>pp_errors.h</code>.
+   */
+  int32_t GetSupportedProfiles(
+      [in] PP_Resource video_encoder,
+      [in] PP_ArrayOutput output,
+      [in] PP_CompletionCallback callback);
+
+  /**
+   * Initializes a video encoder resource. The plugin should call Initialize()
+   * successfully before calling any of the functions below.
+   *
+   * @param[in] video_encoder A <code>PP_Resource</code> identifying the video
+   * encoder.
+   * @param[in] input_format The <code>PP_VideoFrame_Format</code> of the
+   * frames which will be encoded.
+   * @param[in] input_visible_size A <code>PP_Size</code> specifying the
+   * dimensions of the visible part of the input frames.
+   * @param[in] output_profile A <code>PP_VideoProfile</code> specifying the
+   * codec profile of the encoded output stream.
+   * @param[in] acceleration A <code>PP_HardwareAcceleration</code> specifying
+   * whether to use a hardware accelerated or a software implementation.
+   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
+   * completion.
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
+   * Returns PP_ERROR_NOTSUPPORTED if video encoding is not available, or the
+   * requested codec profile is not supported.
+   */
+  int32_t Initialize(
+      [in] PP_Resource video_encoder,
+      [in] PP_VideoFrame_Format input_format,
+      [in] PP_Size input_visible_size,
+      [in] PP_VideoProfile output_profile,
+      [in] uint32_t initial_bitrate,
+      [in] PP_HardwareAcceleration acceleration,
+      [in] PP_CompletionCallback callback);
+
+  /**
+   * Gets the number of input video frames that the encoder may hold while
+   * encoding. If the plugin is providing the video frames, it should have at
+   * least this many available.
+   *
+   * @param[in] video_encoder A <code>PP_Resource</code> identifying the video
+   * encoder.
+   * @return An int32_t containing the number of frames required, or an error
+   * code from <code>pp_errors.h</code>.
+   * Returns PP_ERROR_FAILED if Initialize() has not successfully completed.
+   */
+  int32_t GetFramesRequired(
+      [in] PP_Resource video_encoder);
+
+  /**
+   * Gets the coded size of the video frames required by the encoder. Coded
+   * size is the logical size of the input frames, in pixels.  The encoder may
+   * have hardware alignment requirements that make this different from
+   * |input_visible_size|, as requested in the call to Initialize().

[dmichael (off chromium), 2015/02/03 23:26:08]

Does that mean that the plugin is responsible for scaling the frames? It would
be good to not require that, but if the scaling is done by the browser, I'm not
sure why this function would be needed.

[llandwerlin-old, 2015/02/04 01:01:52]

That means that frames returned through GetVideoFrame might be a bit bigger to
accommodate the hardware constraints. Meaning that the remaining width/height
will be cropped. Therefore, when you write into frames returned from
GetVideoFrame, you should take care of some kind of "stride" which is the coded
size.

+   *
+   * @param[in] video_encoder A <code>PP_Resource</code> identifying the video
+   * encoder.
+   * @param[in] coded_size A <code>PP_Size</code> to hold the coded size.
+   * @return An int32_t containing a result code from <code>pp_errors.h</code>.
+   * Returns PP_ERROR_FAILED if Initialize() has not successfully completed.
+   */
+  int32_t GetFrameCodedSize(
+      [in] PP_Resource video_encoder,
+      [out] PP_Size coded_size);
+
+  /**
+   * Gets a blank video frame which can be filled with video data and passed
+   * to the encoder.
+   *
+   * @param[in] video_encoder A <code>PP_Resource</code> identifying the video
+   * encoder.
+   * @param[out] video_frame A blank <code>PPB_VideoFrame</code> resource.
+   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
+   * completion.
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
+   * Returns PP_ERROR_FAILED if Initialize() has not successfully completed.
+   */
+  int32_t GetVideoFrame(
+      [in] PP_Resource video_encoder,
+      [out] PP_Resource video_frame,
+      [in] PP_CompletionCallback callback);
+
+  /**
+   * Encodes a video frame.
+   *
+   * @param[in] video_encoder A <code>PP_Resource</code> identifying the video
+   * encoder.
+   * @param[in] video_frame The <code>PPB_VideoFrame</code> to be encoded.

[dmichael (off chromium), 2015/02/03 23:26:08]

Do we "neuter" the frame resource so that the plugin can't do anything with it
anymore? That would seem like a nice property, so that they can't write to the
frame while it's in transit?

[llandwerlin-old, 2015/02/04 01:01:52]

That's currently what the implementation does, the frame is invalidated after
Encode() returns.
While this prevents any call on the video_frame resource to return any valid
value, if you've keep a pointer to the buffer prior to call Encode, you might
still be able to write to the frame before it's actually encoded.

[dmichael (off chromium), 2015/02/04 17:31:16]

Makes sense. I'm glad there's at least some protection against mistakes.

+   * @param[in] force_keyframe A <code>PP_Bool> specifying whether the encoder
+   * should emit a key frame for this video frame.
+   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
+   * completion. Plugins that pass <code>PPB_VideoFrame</code> resources owned
+   * by other resources should wait for completion before reusing them.
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
+   * Returns PP_ERROR_FAILED if Initialize() has not successfully completed.
+   */
+  int32_t Encode(
+      [in] PP_Resource video_encoder,
+      [in] PP_Resource video_frame,
+      [in] PP_Bool force_keyframe,
+      [in] PP_CompletionCallback callback);
+
+  /**
+   * Gets the next encoded bitstream buffer from the encoder.
+   *
+   * @param[in] video_encoder A <code>PP_Resource</code> identifying the video
+   * encoder.
+   * @param[out] bitstream_buffer A <code>PP_BitstreamBuffer</code> containing
+   * encoded video data.
+   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
+   * completion. The plugin can call GetBitstreamBuffer from the callback in
+   * order to continuously "pull" bitstream buffers from the encoder.
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
+   * Returns PP_ERROR_FAILED if Initialize() has not successfully completed.
+   * Returns PP_ERROR_INPROGRESS if a prior call to GetBitstreamBuffer() has
+   * not completed.
+   */
+  int32_t GetBitstreamBuffer(
+      [in] PP_Resource video_encoder,
+      [out] PP_BitstreamBuffer bitstream_buffer,
+      [in] PP_CompletionCallback callback);
+
+  /**
+   * Recycles a bitstream buffer back to the encoder.
+   *
+   * @param[in] video_encoder A <code>PP_Resource</code> identifying the video
+   * encoder.
+   * @param[in] bitstream_buffer A <code>PP_BitstreamBuffer</code> that is no
+   * longer needed by the plugin.
+   */
+  void RecycleBitstreamBuffer(
+      [in] PP_Resource video_encoder,
+      [in] PP_BitstreamBuffer bitstream_buffer);
+
+  /**
+   * Requests a change to encoding parameters. This is only a request,
+   * fulfilled on a best-effort basis.
+   *
+   * @param[in] video_encoder A <code>PP_Resource</code> identifying the video
+   * encoder.
+   * @param[in] bitrate The requested new bitrate, in bits per second.
+   * @param[in] framerate The requested new framerate, in frames per second.
+   */
+  void RequestEncodingParametersChange(
+      [in] PP_Resource video_encoder,
+      [in] uint32_t bitrate,
+      [in] uint32_t framerate);
+};

[dmichael (off chromium), 2015/02/03 23:26:08]

We may want a Close() (or Reset) to make it easy to stop encoding and cause
callbacks to Abort. It seems to be a useful pattern in other APIs, since it
might not always be as convenient for the plugin to get the ref-count to zero
(e.g., if a ref-count is owned on another thread).

[llandwerlin-old, 2015/02/04 01:01:52]

I've argued for that, but it's up to bbudge@.

[bbudge, 2015/02/04 13:56:40]

We've talked about a Destroy() method, but that isn't consistent with Pepper
conventions. Reset would be confusing, as the VideoDecoder api has that method,
but it means something else.

I added a Close method, which can call the VEA::Destroy method.