Pepper VideoDecoder API definition.

ppapi/api/ppb_media_codec_video_decoder.idl

+/* Copyright (c) 2014 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_MediaCodecVideoDecoder</code> interface.
+ */
+
+[generate_thunk]
+
+label Chrome {
+  [channel=dev] M36 = 0.1
+};
+
+/**
+ * Video decoder interface.
+ *
+ * Typical usage:
+ * - Call Create() to create a new video decoder resource.
+ * - Call Initialize() to initialize it with a 3d graphics context.
+ * - Call Decode() to send a bitstream buffer to the decoder.
+ * - Call GetPictureBuffer() to get the next decoded picture.
+ * - To signal end of stream to the decoder: call Flush() and wait for the
+ *   callback.
+ * - To reset the decoder (e.g. to implement Seek): call Reset() and wait for
+ *   the callback.
+ */
+interface PPB_MediaCodecVideoDecoder {
+  /**
+   * Creates a new video decoder resource.
+   *
+   * @param[in] instance A <code>PP_Instance</code> identifying the instance
+   * with the video decoder.
+   *
+   * @return A <code>PP_Resource</code> corresponding to a video decoder if
+   * successful or 0 otherwise.
+   */
+  PP_Resource Create(
+      [in] PP_Instance instance);
+
+  /**
+   * Determines if the given resource is a video decoder.
+   *
+   * @param[in] resource A <code>PP_Resource</code> identifying a resource.
+   *
+   * @return <code>PP_TRUE</code> if the resource is a
+   * <code>PPB_MediaCodecVideoDecoder</code>, <code>PP_FALSE</code> if the
+   * resource is invalid or some other type.
+   */
+  PP_Bool IsMediaCodecVideoDecoder(
+      [in] PP_Resource resource);
+
+  /**
+   * Initializes a video decoder resource. This should only be called once,
+   * after Create() and before any other functions. Video decoding is not
+   * supported on all platforms.
+   *
+   * @param[in] video_decoder A <code>PP_Resource</code> identifying the video
+   * decoder.
+   * @param[in] graphics3d_context A <code>PPB_Graphics3D</code> resource to use
+   * during decoding.
+   * @param[in] profile A <code>PP_MediaCodec_Profile</code> specifying the
+   * video stream profile.
+   * @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 here or to the callback if video decoding is
+   * not available.
+   */
+  int32_t Initialize(
+      [in] PP_Resource video_decoder,
+      [in] PP_Resource context,
+      [in] PP_MediaCodec_Profile profile,

[igorc, 2014/04/11 22:13:18]

Could we have a function that returns the list of supported profiles? That would
save us from trying to init-then-close a bunch of decoders.

[bbudge, 2014/04/16 00:51:05]

See the comments on patchset #1. In short, the plugin analyzes its video to
determine the codec profile, then tries to Initialize. I don't know of an easy
way to determine the supported profiles on the current platform, or even if it's
possible to do so.

+      [in] PP_CompletionCallback callback);
+
+  /**
+   * Decodes a bitstream buffer. Copies |size| bytes of data from the plugin's
+   * |buffer|. The plugin should maintain the buffer until the callback is run.
+   * If the bitstream buffer results in a picture, the |picture_id| parameter
+   * will be copied into the picture buffer that is returned by
+   * GetPictureBuffer(). This can be used to associate Decode calls with decoded
+   * pictures (e.g. to associate timestamps with pictures.) The plugin can use
+   * the callback to throttle calls to Decode to some constant number to avoid

[igorc, 2014/04/11 22:13:18]

Could you clarify (or provide an API) to help determine that number?

[bbudge, 2014/04/16 00:51:05]

I've changed the behavior of Decode. Now only a single pending call is allowed.
The plugin has wait until the decoder signals completion (either by returning
PP_OK or running the callback) before it can release its buffer and make another
call. The proxy is not doing the throttling (necessary to limit the number of
shm memory buffers that are created.

+   * over consuming system resources.
+   *
+   * @param[in] video_decoder A <code>PP_Resource</code> identifying the video
+   * decoder.
+   * @param[in] picture_id An identifier that can be used to associate calls to
+   * Decode() with decoded pictures returned by GetPictureBuffer().
+   * @param[in] size Buffer size in bytes.
+   * @param[in] buffer Starting address of buffer.
+   * @param[in] callback A <code>PP_CompletionCallback</code> to be called when
+   * the decoder has finished reading the buffer.

[igorc, 2014/04/11 22:13:18]

Does it mean I cannot free picture_id->timestamp mapping at the time of
callback, because GetPictureBuffer() may happen even later?

If so, given that GetPictureBuffer() may not happen at all for a particular
buffer - how do I know when to free picture_id->timestamp mapping?

If callback can only happen after both GetPictureBuffer() and
RecyclePictureBuffer() have completed, then we could use Decode's callback to
free the mapping.

[bbudge, 2014/04/16 00:51:05]

True, not every Decode results in a picture. Since pictures are returned in
order, the plugin would need a way to determine which id's are older and
therefore never going to be received in a picture.

I'll try to add this to the example to get a feel for difficulty.

+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>.

[igorc, 2014/04/11 22:13:18]

Could you add clarifications - in which cases I should Reset() vs. re-create the
decoder vs. forget about the video? My goal is to be able to skip some frames
and continue when it makes sense.

[bbudge, 2014/04/16 00:51:05]

In that case, it's better to call Reset, since all the textures and shm buffers
can be reused. But either approach works. See the improved comments on Flush and
Reset.

[igorc, 2014/04/21 23:12:48]

Could you add it to the comments? Basically that a failed Decode() call should
be followed by a Reset() rather than by more Decode() calls. In other words -
that there's no recovery after even one failed Decode() call.

[bbudge, 2014/04/21 23:29:05]

Good idea. I'll add them in a later CL, when it becomes clearer what the errors
can be. I think it will require some new PP_Error codes. Also, I think it makes
sense for them to be returned by the GetPicture function, since from the
plugin's point of view, Decodes succeed before the gpu gets the bitstream
buffer.

+   */
+  int32_t Decode(
+      [in] PP_Resource video_decoder,
+      [in] uint32_t picture_id,
+      [in] uint32_t size,
+      [in] mem_t buffer,
+      [in] PP_CompletionCallback callback);
+
+  /**
+   * Gets the next picture buffer from the decoder. When the plugin is finished

[igorc, 2014/04/11 22:13:18]

Would be nice to clarify that the picture is available upon the invocation of
the callback.

[bbudge, 2014/04/16 00:51:05]

Good you bring this up. The plugin may fall behind so we buffer pictures we
receive in the proxy. So it's possible for this to return immediately with
PP_OK. Updated the comment.

+   * with the picture, it should call RecyclePictureBuffer() to return it to the
+   * system. The plugin can call GetPictureBuffer() again at any time after

[igorc, 2014/04/11 22:13:18]

I'm not sure I understand the significance of this statement... Is it OK to have
multiple concurrent GetPictureBuffer() calls outstanding?

What happens if several of them are outstanding? Will callbacks be somehow
invoked in the order of Decode calls? Or the callbacks can be called in a random
order (which implies that I have to watch out and order them myself)?

Should we discourage this pattern?

Would be great to document.

[bbudge, 2014/04/16 00:51:05]

Only 1 GetPictureBuffer call may be outstanding. Calling again will return
PP_ERROR_INPROGRESS. I'll try to make this clearer.

+   * |callback| is called. In particular, the plugin can call it from within
+   * |callback| to request another picture.
+   *
+   * @param[in] video_decoder A <code>PP_Resource</code> identifying the video
+   * decoder.
+   * @param[out] picture_buffer A <code>PP_MediaCodec_PictureBuffer</code> to
+   * hold the decoded picture.
+   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
+   * completion. |picture_buffer| will describe the buffer if successful.
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
+   */
+  int32_t GetPictureBuffer(
+      [in] PP_Resource video_decoder,
+      [out] PP_MediaCodec_PictureBuffer picture_buffer,
+      [in] PP_CompletionCallback callback);
+
+  /**
+   * Recycles a picture buffer that the plugin has received from the decoder.
+   * The plugin should call this as soon as it has finished using the texture so
+   * the system can decode more pictures.
+   *
+   * @param[in] video_decoder A <code>PP_Resource</code> identifying the video
+   * decoder.
+   * @param[in] picture_buffer A <code>PP_MediaCodec_PictureBuffer</code> to
+   * return to the system.
+   */
+  void RecyclePictureBuffer(
+      [in] PP_Resource video_decoder,
+      [in] PP_MediaCodec_PictureBuffer picture_buffer);
+
+  /**
+   * Flushes the decoder.  Any pending calls to the decoder are completed,
+   * including callbacks to the plugin. Once flushed, the decoder will call
+   * |callback|. While flushing, the plugin should not make any calls to the
+   * decoder. The plugin should call Flush() to signal end of stream to the
+   * decoder.
+   *
+   * @param[in] video_decoder A <code>PP_Resource</code> identifying the video
+   * decoder.
+   * @param[in] callback A <code>PP_CompletionCallback</code> to be called when
+   * flushing is complete.
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
+   */
+  int32_t Flush(
+      [in] PP_Resource video_decoder,
+      [in] PP_CompletionCallback callback);
+
+  /**
+   * Resets the decoder as quickly as possible.  Pending calls are aborted,
+   * causing callbacks to run with PP_ERROR_ABORTED. The decoder is put back
+   * into a state ready to receive further Decode calls and |callback| is
+   * called. While resetting, the plugin should not make any calls to the
+   * decoder. The plugin can use Reset() when it needs to seek to a new position
+   * in the stream.
+   *
+   * @param[in] video_decoder A <code>PP_Resource</code> identifying the video
+   * decoder.
+   * @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 Reset(
+      [in] PP_Resource video_decoder,
+      [in] PP_CompletionCallback callback);
+};