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:

[Ami GONE FROM CHROMIUM, 2014/04/22 00:27:40]

IIUC platform errors from the HW get delivered to an arbitrary callback (e.g.
Initialize()'s callback, or Decode()'s callback, or Flush()'s callback, etc),
based on whatever is currently outstanding from the plugin (if anything).  That
seems unfortunate, but maybe this is forced by pepper style?

[bbudge, 2014/04/23 18:35:22]

I can choose how to return the error, but yes, there's no way to have a separate
channel for these errors with this API, short of adding a new GetError function
with a callback. I think the best thing to do is to return the error code to all
outstanding callbacks when it's received on the plugin side.

[Ami GONE FROM CHROMIUM, 2014/04/23 21:05:46]

My worry is what happens if there are no outstanding callbacks.
(e.g. the error happens because the GPU process crashed after a Flush was done &
called-back, but before the next Decode or GetPicture call is made).  I guess
you'd eventually get the error when the next API call is made but sad for that
delay.

+ * - 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.
+ * - Call Flush() to signal end of stream to the decoder and perform shutdown
+ *   when it completes.
+ * - To reset the decoder (e.g. to implement Seek), call Reset() and wait for
+ *   the callback.
+ * - To destroy the decoder, the plugin should release all of its references to
+ *   it. To avoid receiving aborted callbacks, call Flush() and wait for

[Ami GONE FROM CHROMIUM, 2014/04/22 00:27:40]

It seems unfortunate to have to wait for the decode pipeline to drain to be able
to exit?

[bbudge, 2014/04/23 18:35:22]

I think we can avoid this in the resource destructor.

[Ami GONE FROM CHROMIUM, 2014/04/23 21:05:46]

Can it be hidden from the plugin?
IOW make it so that when the last reference is released it guarantees no more
callbacks?

+ *   completion first.
+ */
+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.
+   *
+   * @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_VideoProfile</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 graphics3d_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 should maintain the buffer and not call Decode() again
+   * until the decoder signals completion by returning PP_OK or by running
+   * |callback|.
+   * If the call to Decode() eventually results in a picture, the |decode_id|
+   * parameter is copied into the returned picture. The plugin can use this to
+   * associate decoded pictures with Decode() calls (e.g. to assign timestamps
+   * or frame numbers to pictures.) It's OK to pass 0 if this isn't needed.

[Ami GONE FROM CHROMIUM, 2014/04/22 00:27:40]

I would just say that this value is opaque to the API (since "0" isn't special).

[bbudge, 2014/04/23 18:35:22]

Done.

+   *
+   * @param[in] video_decoder A <code>PP_Resource</code> identifying the video
+   * decoder.
+   * @param[in] decode_id An optional value, chosen by the plugin, 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 decode_id,
+      [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 |callback|. The
+   * plugin can call GetPicture() again after the decoder signals completion.
+   * When the plugin is finished using the picture, it should return it to the
+   * system by calling RecyclePicture().
+   *
+   * @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,
+      [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 can 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 |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);
+};