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