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);
+
+  /**
+   * 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
+   * <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(

[llandwerlin-old, 2015/01/15 11:19:15]

Do we need to prevent concurrent calls to this method?

[bbudge, 2015/01/15 12:31:50]

It's simpler, so yes. We can return INPROGRESS if they call again before
completion.

+      [in] PP_Resource video_encoder,
+      [in] PP_ArrayOutput output,
+      [in] PP_CompletionCallback callback);
+
+  /**
+   * Initializes a video encoder resource. This should be called after Create()
+   * and GetSupportedProfiles() and before any 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.
+   * Returns PP_ERROR_NOMEMORY if frame and bitstream buffers can't be created.
+   */
+  int32_t Initialize(
+      [in] PP_Resource video_encoder,
+      [in] PP_VideoFrame_Format input_format,
+      [in] PP_Size input_visible_size,

[llandwerlin-old, 2015/01/15 11:32:53]

I forgot, but I think we might also need to add a method to report the
input_coded_size from media::VideoEncodeAccelerator : 

https://code.google.com/p/chromium/codesearch#chromium/src/media/video/video_...

[bbudge, 2015/01/15 12:31:50]

This brings up some interesting questions:
1) Can VEA::Client::RequireBitstreamBuffers be called multiple times (i.e. not
just at Initialization)?
2) Is input_coded_size useful if the client is encoding frames from
MediaStreamVideoTrack?
3) Does PPB_VideoFrame expose this or would we have to modify it?

[llandwerlin-old, 2015/01/15 14:04:43]

1) Only at initialization. 

2) My understanding is that the hardware is going to work on frames of the same
size or slightly larger (depending on the constraints) to not loose any content
from the input frames. The bitstream will contain informations about how to crop
decoded frames so the decoder can display frames correctly.
It seems we need to match the hardware's constraints. The thing is, the frames
are going to be copied again (in the gpu-process) because most hardwares don't
work with I420 (which is what chromium always uses), but NV12 instead. So in
practice, the constraints probably don't matter.
That being said, input_coded_size is useful to reconfigure the
MediaStreamVideoTrack at the right size :
https://code.google.com/p/chromium/codesearch#chromium/src/ppapi/api/ppb_medi...

3) With the current implementation, the width of the PPB_VideoFrame is equal to
its stride, so I don't think we need more information about that class.

+      [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. This must be called after Initialize().
+   *
+   * @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>.
+   */
+  int32_t GetInputFramesRequired(

[llandwerlin-old, 2015/01/15 11:22:27]

We should also add here that it's going to fail unless Initialize() has
succeeded.

[bbudge, 2015/01/15 21:51:08]

Done.

+      [in] PP_Resource video_encoder);
+
+  /**
+   * 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>.
+   */
+  int32_t GetVideoFrame(

[llandwerlin-old, 2015/01/15 11:22:28]

We should also add here that it's going to fail unless Initialize() has
succeeded.

[bbudge, 2015/01/15 21:51:09]

Done.

+      [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.
+   * @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>.
+   */
+  int32_t Encode(

[llandwerlin-old, 2015/01/15 11:22:28]

Will fail unless Initialize succeeds.

[bbudge, 2015/01/15 21:51:09]

Done.

+      [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>.
+   */

[llandwerlin-old, 2015/01/15 11:19:15]

We should add that multiple calls without waiting for the callback to be fired
will trigger an error, like GetPicture() on PPB_VideoDecoder :

https://code.google.com/p/chromium/codesearch#chromium/src/ppapi/api/ppb_vide...

[bbudge, 2015/01/15 21:51:09]

Done.

+  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);
+};