ppapi/api/dev/ppb_video_decoder_dev.idl

   1 /* Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2  * Use of this source code is governed by a BSD-style license that can be
   3  * found in the LICENSE file.
   4  */
   5
   6 /**
   7  * This file defines the <code>PPB_VideoDecoder_Dev</code> interface.
   8  */
   9 label Chrome {
  10   M14 = 0.16
  11 };
  12
  13 /**
  14  * Video decoder interface.
  15  *
  16  * Typical usage:
  17  * - Use Create() to create & configure a new PPB_VideoDecoder_Dev resource.
  18  * - Call Decode() to decode some video data.
  19  * - Receive ProvidePictureBuffers callback
  20  *   - Supply the decoder with textures using AssignPictureBuffers.
  21  * - Receive PictureReady callbacks
  22  *   - Hand the textures back to the decoder using ReusePictureBuffer.
  23  * - To signal EOS to the decoder: call Flush() and wait for NotifyFlushDone
  24  *   callback.
  25  * - To reset the decoder (e.g. to implement Seek): call Reset() and wait for
  26  *   NotifyResetDone callback.
  27  * - To tear down the decoder call Destroy().
  28  *
  29  * See PPP_VideoDecoder_Dev for the notifications the decoder may send the
  30  * plugin.
  31  */
  32 interface PPB_VideoDecoder_Dev {
  33   /**
  34    * Creates & initializes a video decoder.
  35    *
  36    * Parameters:
  37    *   |instance| pointer to the plugin instance.
  38    *   |context| a PPB_Graphics3D resource in which decoding will happen.
  39    *   |profile| the video stream's format profile.
  40    *
  41    * The created decoder is returned as PP_Resource. 0 means failure.
  42    */
  43   PP_Resource Create(
  44       [in] PP_Instance instance,
  45       [in] PP_Resource context,
  46       [in] PP_VideoDecoder_Profile profile);
  47
  48   /**
  49    * Tests whether |resource| is a video decoder created through Create
  50    * function of this interface.
  51    *
  52    * Parameters:
  53    *   |resource| is handle to resource to test.
  54    *
  55    * Returns true if is a video decoder, false otherwise.
  56    */
  57   PP_Bool IsVideoDecoder(
  58       [in] PP_Resource resource);
  59
  60   /**
  61    * Dispatches bitstream buffer to the decoder.
  62    *
  63    * Parameters:
  64    *   |video_decoder| is the previously created handle to the decoder resource.
  65    *   |bitstream_buffer| is the bitstream buffer that contains at most one
  66    *   input frame.
  67    *   |callback| will be called when |bitstream_buffer| has been processed by
  68    *   the decoder.
  69    *
  70    * Returns an error code from pp_errors.h.
  71    */
  72   int32_t Decode(
  73       [in] PP_Resource video_decoder,
  74       [in] PP_VideoBitstreamBuffer_Dev bitstream_buffer,
  75       [in] PP_CompletionCallback callback);
  76
  77   /**
  78    * Provides the decoder with texture-backed picture buffers for video
  79    * decoding.
  80    *
  81    * This function should be called when the plugin has its
  82    * ProvidePictureBuffers method called.  The decoder will stall until it has
  83    * received all the buffers it's asked for.
  84    *
  85    * Parameters:
  86    *   |video_decoder| is the previously created handle to the decoder resource.
  87    *   |no_of_buffers| how many buffers are behind picture buffer pointer.
  88    *   |buffers| contains the reference to the picture buffer that was
  89    *   allocated.
  90    */
  91   void AssignPictureBuffers(
  92       [in] PP_Resource video_decoder,
  93       [in] uint32_t no_of_buffers,
  94       [in, size_as=no_of_buffers] PP_PictureBuffer_Dev[] buffers);
  95
  96   /**
  97    * Tells the decoder to reuse the given picture buffer. Typical use of this
  98    * function is to call from PictureReady callback to recycle picture buffer
  99    * back to the decoder after blitting the image so that decoder can use the
 100    * image for output again.
 101    *
 102    * Parameters:
 103    *   |video_decoder| is the previously created handle to the decoder resource.
 104    *   |picture_buffer_id| contains the id of the picture buffer that was
 105    *   processed.
 106    */
 107   void ReusePictureBuffer(
 108       [in] PP_Resource video_decoder,
 109       [in] int32_t picture_buffer_id);
 110
 111   /**
 112    * Flush input and output buffers in the decoder.  Any pending inputs are
 113    * decoded and pending outputs are delivered to the plugin.  Once done
 114    * flushing, the decoder will call |callback|.
 115    *
 116    * Parameters:
 117    *   |video_decoder| is the previously created handle to the decoder resource.
 118    *   |callback| is one-time callback that will be called once the flushing
 119    *   request has been completed.
 120    *
 121    * Returns an error code from pp_errors.h.
 122    */
 123   int32_t Flush(
 124       [in] PP_Resource video_decoder,
 125       [in] PP_CompletionCallback callback);
 126
 127   /**
 128    * Reset the decoder as quickly as possible.  Pending inputs and outputs are
 129    * dropped and the decoder is put back into a state ready to receive further
 130    * Decode() calls.  |callback| will be called when the reset is done.
 131    *
 132    * Parameters:
 133    *   |video_decoder| is the previously created handle to the decoder resource.
 134    *   |callback| is one-time callback that will be called once the reset
 135    *   request has been completed.
 136    *
 137    * Returns an error code from pp_errors.h.
 138    */
 139   int32_t Reset(
 140       [in] PP_Resource video_decoder,
 141       [in] PP_CompletionCallback callback);
 142
 143   /**
 144    * Tear down the decoder as quickly as possible.  Pending inputs and outputs
 145    * are dropped and the decoder frees all of its resources.  Although resources
 146    * may be freed asynchronously, after this method returns no more callbacks
 147    * will be made on the client.  Any resources held by the client at that point
 148    * may be freed.
 149    *
 150    * Parameters:
 151    *   |video_decoder| is the previously created handle to the decoder resource.
 152    */
 153   void Destroy(
 154       [in] PP_Resource video_decoder);
 155 };