ppapi/api/ppb_video_encoder.idl

   1 /* Copyright 2015 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_VideoEncoder</code> interface.
   8  */
   9
  10 [generate_thunk]
  11
  12 label Chrome {
  13   [channel=dev] M42 = 0.1,
  14   M44 = 0.2
  15 };
  16
  17 /**
  18  * Video encoder interface.
  19  *
  20  * Typical usage:
  21  * - Call Create() to create a new video encoder resource.
  22  * - Call GetSupportedFormats() to determine which codecs and profiles are
  23  *   available.
  24  * - Call Initialize() to initialize the encoder for a supported profile.
  25  * - Call GetVideoFrame() to get a blank frame and fill it in, or get a video
  26  *   frame from another resource, e.g. <code>PPB_MediaStreamVideoTrack</code>.
  27  * - Call Encode() to push the video frame to the encoder. If an external frame
  28  *   is pushed, wait for completion to recycle the frame.
  29  * - Call GetBitstreamBuffer() continuously (waiting for each previous call to
  30  *   complete) to pull encoded pictures from the encoder.
  31  * - Call RecycleBitstreamBuffer() after consuming the data in the bitstream
  32  *   buffer.
  33  * - To destroy the encoder, the plugin should release all of its references to
  34  *   it. Any pending callbacks will abort before the encoder is destroyed.
  35  *
  36  * Available video codecs vary by platform.
  37  * All: vp8 (software).
  38  * ChromeOS, depending on your device: h264 (hardware), vp8 (hardware)
  39  */
  40 interface PPB_VideoEncoder {
  41   /**
  42    * Creates a new video encoder resource.
  43    *
  44    * @param[in] instance A <code>PP_Instance</code> identifying the instance
  45    * with the video encoder.
  46    *
  47    * @return A <code>PP_Resource</code> corresponding to a video encoder if
  48    * successful or 0 otherwise.
  49    */
  50   PP_Resource Create([in] PP_Instance instance);
  51
  52   /**
  53    * Determines if the given resource is a video encoder.
  54    *
  55    * @param[in] resource A <code>PP_Resource</code> identifying a resource.
  56    *
  57    * @return <code>PP_TRUE</code> if the resource is a
  58    * <code>PPB_VideoEncoder</code>, <code>PP_FALSE</code> if the resource is
  59    * invalid or some other type.
  60    */
  61   PP_Bool IsVideoEncoder([in] PP_Resource resource);
  62
  63   /**
  64    * Gets an array of supported video encoder profiles.
  65    * These can be used to choose a profile before calling Initialize().
  66    *
  67    * @param[in] video_encoder A <code>PP_Resource</code> identifying the video
  68    * encoder.
  69    * @param[in] output A <code>PP_ArrayOutput</code> to receive the supported
  70    * <code>PP_VideoProfileDescription_0_1</code> structs.
  71    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
  72    * completion.
  73    *
  74    * @return If >= 0, the number of supported profiles returned, otherwise an
  75    * error code from <code>pp_errors.h</code>.
  76    */
  77   int32_t GetSupportedProfiles([in] PP_Resource video_encoder,
  78                                [in] PP_ArrayOutput output,
  79                                [in] PP_CompletionCallback callback);
  80
  81   /**
  82    * Gets an array of supported video encoder profiles.
  83    * These can be used to choose a profile before calling Initialize().
  84    *
  85    * @param[in] video_encoder A <code>PP_Resource</code> identifying the video
  86    * encoder.
  87    * @param[in] output A <code>PP_ArrayOutput</code> to receive the supported
  88    * <code>PP_VideoProfileDescription</code> structs.
  89    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
  90    * completion.
  91    *
  92    * @return If >= 0, the number of supported profiles returned, otherwise an
  93    * error code from <code>pp_errors.h</code>.
  94    */
  95   [version = 0.2]
  96   int32_t GetSupportedProfiles([in] PP_Resource video_encoder,
  97                                [in] PP_ArrayOutput output,
  98                                [in] PP_CompletionCallback callback);
  99
 100   /**
 101    * Initializes a video encoder resource. The plugin should call Initialize()
 102    * successfully before calling any of the functions below.
 103    *
 104    * @param[in] video_encoder A <code>PP_Resource</code> identifying the video
 105    * encoder.
 106    * @param[in] input_format The <code>PP_VideoFrame_Format</code> of the
 107    * frames which will be encoded.
 108    * @param[in] input_visible_size A <code>PP_Size</code> specifying the
 109    * dimensions of the visible part of the input frames.
 110    * @param[in] output_profile A <code>PP_VideoProfile</code> specifying the
 111    * codec profile of the encoded output stream.
 112    * @param[in] acceleration A <code>PP_HardwareAcceleration</code> specifying
 113    * whether to use a hardware accelerated or a software implementation.
 114    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 115    * completion.
 116    *
 117    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
 118    * Returns PP_ERROR_NOTSUPPORTED if video encoding is not available, or the
 119    * requested codec profile is not supported.
 120    */
 121   int32_t Initialize([in] PP_Resource video_encoder,
 122                      [in] PP_VideoFrame_Format input_format,
 123                      [in] PP_Size input_visible_size,
 124                      [in] PP_VideoProfile output_profile,
 125                      [in] uint32_t initial_bitrate,
 126                      [in] PP_HardwareAcceleration acceleration,
 127                      [in] PP_CompletionCallback callback);
 128
 129   /**
 130    * Gets the number of input video frames that the encoder may hold while
 131    * encoding. If the plugin is providing the video frames, it should have at
 132    * least this many available.
 133    *
 134    * @param[in] video_encoder A <code>PP_Resource</code> identifying the video
 135    * encoder.
 136    * @return An int32_t containing the number of frames required, or an error
 137    * code from <code>pp_errors.h</code>.
 138    * Returns PP_ERROR_FAILED if Initialize() has not successfully completed.
 139    */
 140   int32_t GetFramesRequired([in] PP_Resource video_encoder);
 141
 142   /**
 143    * Gets the coded size of the video frames required by the encoder. Coded
 144    * size is the logical size of the input frames, in pixels.  The encoder may
 145    * have hardware alignment requirements that make this different from
 146    * |input_visible_size|, as requested in the call to Initialize().
 147    *
 148    * @param[in] video_encoder A <code>PP_Resource</code> identifying the video
 149    * encoder.
 150    * @param[in] coded_size A <code>PP_Size</code> to hold the coded size.
 151    * @return An int32_t containing a result code from <code>pp_errors.h</code>.
 152    * Returns PP_ERROR_FAILED if Initialize() has not successfully completed.
 153    */
 154   int32_t GetFrameCodedSize([in] PP_Resource video_encoder,
 155                             [out] PP_Size coded_size);
 156
 157   /**
 158    * Gets a blank video frame which can be filled with video data and passed
 159    * to the encoder.
 160    *
 161    * @param[in] video_encoder A <code>PP_Resource</code> identifying the video
 162    * encoder.
 163    * @param[out] video_frame A blank <code>PPB_VideoFrame</code> resource.
 164    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 165    * completion.
 166    *
 167    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
 168    * Returns PP_ERROR_FAILED if Initialize() has not successfully completed.
 169    */
 170   int32_t GetVideoFrame([in] PP_Resource video_encoder,
 171                         [out] PP_Resource video_frame,
 172                         [in] PP_CompletionCallback callback);
 173
 174   /**
 175    * Encodes a video frame.
 176    *
 177    * @param[in] video_encoder A <code>PP_Resource</code> identifying the video
 178    * encoder.
 179    * @param[in] video_frame The <code>PPB_VideoFrame</code> to be encoded.
 180    * @param[in] force_keyframe A <code>PP_Bool> specifying whether the encoder
 181    * should emit a key frame for this video frame.
 182    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 183    * completion. Plugins that pass <code>PPB_VideoFrame</code> resources owned
 184    * by other resources should wait for completion before reusing them.
 185    *
 186    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
 187    * Returns PP_ERROR_FAILED if Initialize() has not successfully completed.
 188    */
 189   int32_t Encode([in] PP_Resource video_encoder,
 190                  [in] PP_Resource video_frame,
 191                  [in] PP_Bool force_keyframe,
 192                  [in] PP_CompletionCallback callback);
 193
 194   /**
 195    * Gets the next encoded bitstream buffer from the encoder.
 196    *
 197    * @param[in] video_encoder A <code>PP_Resource</code> identifying the video
 198    * encoder.
 199    * @param[out] bitstream_buffer A <code>PP_BitstreamBuffer</code> containing
 200    * encoded video data.
 201    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 202    * completion. The plugin can call GetBitstreamBuffer from the callback in
 203    * order to continuously "pull" bitstream buffers from the encoder.
 204    *
 205    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
 206    * Returns PP_ERROR_FAILED if Initialize() has not successfully completed.
 207    * Returns PP_ERROR_INPROGRESS if a prior call to GetBitstreamBuffer() has
 208    * not completed.
 209    */
 210   int32_t GetBitstreamBuffer([in] PP_Resource video_encoder,
 211                              [out] PP_BitstreamBuffer bitstream_buffer,
 212                              [in] PP_CompletionCallback callback);
 213
 214   /**
 215    * Recycles a bitstream buffer back to the encoder.
 216    *
 217    * @param[in] video_encoder A <code>PP_Resource</code> identifying the video
 218    * encoder.
 219    * @param[in] bitstream_buffer A <code>PP_BitstreamBuffer</code> that is no
 220    * longer needed by the plugin.
 221    */
 222   void RecycleBitstreamBuffer([in] PP_Resource video_encoder,
 223                               [in] PP_BitstreamBuffer bitstream_buffer);
 224
 225   /**
 226    * Requests a change to encoding parameters. This is only a request,
 227    * fulfilled on a best-effort basis.
 228    *
 229    * @param[in] video_encoder A <code>PP_Resource</code> identifying the video
 230    * encoder.
 231    * @param[in] bitrate The requested new bitrate, in bits per second.
 232    * @param[in] framerate The requested new framerate, in frames per second.
 233    */
 234   void RequestEncodingParametersChange([in] PP_Resource video_encoder,
 235                                        [in] uint32_t bitrate,
 236                                        [in] uint32_t framerate);
 237
 238   /**
 239    * Closes the video encoder, and cancels any pending encodes. Any pending
 240    * callbacks will still run, reporting <code>PP_ERROR_ABORTED</code> . It is
 241    * not valid to call any encoder functions after a call to this method.
 242    * <strong>Note:</strong> Destroying the video encoder closes it implicitly,
 243    * so you are not required to call Close().
 244    *
 245    * @param[in] video_encoder A <code>PP_Resource</code> identifying the video
 246    * encoder.
 247    */
 248   void Close([in] PP_Resource video_encoder);
 249 };