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 and the
+ *   desired codec profile.
+ * - Call Decode() to send a bitstream buffer to the decoder.
+ * - Call GetPicture() to get the next decoded picture.
+ * - To signal end of stream to the decoder and shut down gracefully, call
+ *   Flush() and wait for the callback.
+ * - To reset the decoder (e.g. to implement Seek), call Reset() and wait for
+ *   the callback.
+ * - After Flush or Reset, the plugin can release any references on the decoder

[dmichael (off chromium), 2014/04/17 20:23:26]

any->all ?

[bbudge, 2014/04/18 17:03:17]

Done.

+ *   to destroy it.
+ */
+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's codec 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 if video decoding is not available, or the
+   * requested profile is not supported.
+   */
+  int32_t Initialize(
+      [in] PP_Resource video_decoder,
+      [in] PP_Resource context,
+      [in] PP_MediaCodec_VideoProfile profile,
+      [in] PP_CompletionCallback callback);
+
+  /**
+   * Decodes a bitstream buffer. Copies |size| bytes of data from the plugin's
+   * |buffer|. The plugin must maintain the buffer and not call Decode() again
+   * until the decoder signals completion by returning PP_OK or running the
+   * |callback|.
+   * If the call to Decode() eventually causes GetPicture() to return a picture,
+   * the |user_id| parameter will be copied into the picture that is returned.
+   * The plugin can use this to associate decoded pictures with Decode() calls
+   * (e.g. to assign timestamps or frame numbers to pictures.)
+   *
+   * @param[in] video_decoder A <code>PP_Resource</code> identifying the video
+   * decoder.
+   * @param[in] user_id An identifier that can be used to associate calls to
+   * Decode() with decoded pictures returned by GetPicture().
+   * @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 upon
+   * completion.
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
+   */
+  int32_t Decode(
+      [in] PP_Resource video_decoder,
+      [in] uint32_t user_id,

[dmichael (off chromium), 2014/04/17 20:23:26]

Is the expectation that this id will be different for each call to Decode? The
name "user_id" makes it sound more static than that. Should it be "buffer_id" or
something, instead? Or would it maybe suffice to eliminate this parameter and
use |buffer| for this purpose?

[bbudge, 2014/04/18 17:03:17]

It was 'picture_id' and from your comment I think that's a better name. I think
it's needed since |buffer| might not be unique.

[dmichael (off chromium), 2014/04/21 17:25:33]

But will you ever have more than 1 Decode call in flight with the same buffer? I
thought you wouldn't. I thought it was probably "unique enough"

I'm just worried this will be confusing; that plugin authors might not know what
they should pass here. If I understand right, they're supposed to make up their
own unique ID? Is it legal for them to pass 0 all the time, if they somehow
don't actually need to associate Decode calls with GetPicture results?

[bbudge, 2014/04/21 18:14:58]

On further reflection, I think a better name than user_id or picture_id is
'decode_id'.

This parameter is optional. I've changed the docs to make this clear.

As far as the plugin is concerned, it only has a single Decode pending at any
time. Internally, however, there can be several Decodes in flight in the steady
state, most of them causing a new picture to be generated. The plugin could call
Decode with a given 'buffer', receive completion, and send off another Decode
from the same 'buffer' before getting the picture from the first one. It would
be unclear which Decode caused the picture. That's why this is needed.

+      [in] uint32_t size,
+      [in] mem_t buffer,
+      [in] PP_CompletionCallback callback);
+
+  /**
+   * Gets the next picture from the decoder. The picture is valid after the
+   * decoder signals completion by returning PP_OK or running the callback. The
+   * plugin can call GetPictureBuffer() again after completion.
+   * When the plugin is finished using the picture, it should return it to the
+   * system by calling RecyclePictureBuffer().
+   *
+   * @param[in] video_decoder A <code>PP_Resource</code> identifying the video
+   * decoder.
+   * @param[out] picture A <code>PP_MediaCodec_Picture</code> to hold the
+   * decoded picture.
+   * @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 GetPicture(
+      [in] PP_Resource video_decoder,
+      [out] PP_MediaCodec_Picture picture,

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

What is the order of resolved pictures? Does it somehow correspond to the order
of Decode() calls?

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

According to Ami, pictures are always returned in presentation order. I don't
know enough about how video is encoded to say if that implies that decode order
is the same as presentation order. I'll make sure this is the case and add a
comment.

+      [in] PP_CompletionCallback callback);
+
+  /**
+   * Recycles a picture that the plugin has received from the decoder.
+   * The plugin should call this as soon as it has finished using the texture so
+   * the decoder can decode more pictures.
+   *
+   * @param[in] video_decoder A <code>PP_Resource</code> identifying the video
+   * decoder.
+   * @param[in] picture A <code>PP_MediaCodec_Picture</code> to return to
+   * the decoder.
+   */
+  void RecyclePicture(
+      [in] PP_Resource video_decoder,
+      [in] PP_MediaCodec_Picture picture);
+
+  /**
+   * Flushes the decoder. The plugin should call this when it reaches the end of
+   * its video stream in order to stop cleanly. The decoder will run all pending
+   * calls to completion. The plugin should make no calls to the decoder other
+   * than RecyclePicture() until the decoder signals completion by running the
+   * callback.
+   *
+   * @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. The plugin should call Reset to
+   * skip to another position in the video stream. Pending calls to Decode() and
+   * GetPicture()) are aborted, causing their callbacks to run with
+   * PP_ERROR_ABORTED. The plugin should not make any further calls to the
+   * decoder until the decoder signals completion by running the callback.
+   *
+   * @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);
+};