ppapi/c/ppb_video_encoder.h

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