ppapi/cpp/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 #ifndef PPAPI_CPP_VIDEO_ENCODER_H_
   6 #define PPAPI_CPP_VIDEO_ENCODER_H_
   7
   8 #include "ppapi/c/pp_codecs.h"
   9 #include "ppapi/c/pp_size.h"
  10 #include "ppapi/cpp/completion_callback.h"
  11 #include "ppapi/cpp/resource.h"
  12 #include "ppapi/cpp/size.h"
  13 #include "ppapi/cpp/video_frame.h"
  14
  15 /// @file
  16 /// This file defines the API to create and use a VideoEncoder resource.
  17
  18 namespace pp {
  19
  20 class InstanceHandle;
  21
  22 /// Video encoder interface.
  23 ///
  24 /// Typical usage:
  25 /// - Call Create() to create a new video encoder resource.
  26 /// - Call GetSupportedFormats() to determine which codecs and profiles are
  27 ///   available.
  28 /// - Call Initialize() to initialize the encoder for a supported profile.
  29 /// - Call GetVideoFrame() to get a blank frame and fill it in, or get a video
  30 ///   frame from another resource, e.g. <code>PPB_MediaStreamVideoTrack</code>.
  31 /// - Call Encode() to push the video frame to the encoder. If an external frame
  32 ///   is pushed, wait for completion to recycle the frame.
  33 /// - Call GetBitstreamBuffer() continuously (waiting for each previous call to
  34 ///   complete) to pull encoded pictures from the encoder.
  35 /// - Call RecycleBitstreamBuffer() after consuming the data in the bitstream
  36 ///   buffer.
  37 /// - To destroy the encoder, the plugin should release all of its references to
  38 ///   it. Any pending callbacks will abort before the encoder is destroyed.
  39 ///
  40 /// Available video codecs vary by platform.
  41 /// All: theora, vorbis, vp8.
  42 /// Chrome and ChromeOS: h264.
  43 /// ChromeOS: mpeg4.
  44 class VideoEncoder : public Resource {
  45  public:
  46   /// Default constructor for creating an is_null() <code>VideoEncoder</code>
  47   /// object.
  48   VideoEncoder();
  49
  50   /// A constructor used to create a <code>VideoEncoder</code> and associate it
  51   /// with the provided <code>Instance</code>.
  52   /// @param[in] instance The instance with which this resource will be
  53   /// associated.
  54   explicit VideoEncoder(const InstanceHandle& instance);
  55
  56   /// The copy constructor for <code>VideoEncoder</code>.
  57   /// @param[in] other A reference to a <code>VideoEncoder</code>.
  58   VideoEncoder(const VideoEncoder& other);
  59
  60   /// Gets an array of supported video encoder profiles.
  61   /// These can be used to choose a profile before calling Initialize().
  62   ///
  63   /// @param[in] callback A <code>CompletionCallbackWithOutput</code> to be
  64   /// called upon completion with the PP_VideoProfileDescription structs.
  65   ///
  66   /// @return If >= 0, the number of supported profiles returned, otherwise an
  67   /// error code from <code>pp_errors.h</code>.
  68   int32_t GetSupportedProfiles(const CompletionCallbackWithOutput<
  69       std::vector<PP_VideoProfileDescription> >& cc);
  70
  71   /// Initializes a video encoder resource. This should be called after
  72   /// GetSupportedProfiles() and before any functions below.
  73   ///
  74   /// @param[in] input_format The <code>PP_VideoFrame_Format</code> of the
  75   /// frames which will be encoded.
  76   /// @param[in] input_visible_size A <code>Size</code> specifying the
  77   /// dimensions of the visible part of the input frames.
  78   /// @param[in] output_profile A <code>PP_VideoProfile</code> specifying the
  79   /// codec profile of the encoded output stream.
  80   /// @param[in] acceleration A <code>PP_HardwareAcceleration</code> specifying
  81   /// whether to use a hardware accelerated or a software implementation.
  82   /// @param[in] callback A <code>CompletionCallback</code> to be called upon
  83   /// completion.
  84   ///
  85   /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
  86   /// Returns PP_ERROR_NOTSUPPORTED if video encoding is not available, or the
  87   /// requested codec profile is not supported.
  88   /// Returns PP_ERROR_NOMEMORY if frame and bitstream buffers can't be created.
  89   int32_t Initialize(const PP_VideoFrame_Format& input_format,
  90                      const Size& input_visible_size,
  91                      const PP_VideoProfile& output_profile,
  92                      const uint32_t initial_bitrate,
  93                      PP_HardwareAcceleration acceleration,
  94                      const CompletionCallback& cc);
  95
  96   /// Gets the number of input video frames that the encoder may hold while
  97   /// encoding. If the plugin is providing the video frames, it should have at
  98   /// least this many available.
  99   ///
 100   /// @return An int32_t containing the number of frames required, or an error
 101   /// code from <code>pp_errors.h</code>.
 102   /// Returns PP_ERROR_FAILED if Initialize() has not successfully completed.
 103   int32_t GetFramesRequired();
 104
 105   /// Gets the coded size of the video frames required by the encoder. Coded
 106   /// size is the logical size of the input frames, in pixels.  The encoder may
 107   /// have hardware alignment requirements that make this different from
 108   /// |input_visible_size|, as requested in the call to Initialize().
 109   ///
 110   /// @param[in] coded_size A <code>Size</code> to hold the coded size.
 111   ///
 112   /// @return An int32_t containing a result code from <code>pp_errors.h</code>.
 113   /// Returns PP_ERROR_FAILED if Initialize() has not successfully completed.
 114   int32_t GetFrameCodedSize(Size* coded_size);
 115
 116   /// Gets a blank video frame which can be filled with video data and passed
 117   /// to the encoder.
 118   ///
 119   /// @param[in] callback A <code>CompletionCallbackWithOutput</code> to be
 120   /// called upon completion with the blank <code>VideoFrame</code> resource.
 121   ///
 122   /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
 123   int32_t GetVideoFrame(const CompletionCallbackWithOutput<VideoFrame>& cc);
 124
 125   /// Encodes a video frame.
 126   ///
 127   /// @param[in] video_frame The <code>VideoFrame</code> to be encoded.
 128   /// @param[in] force_keyframe A <code>PP_Bool> specifying whether the encoder
 129   /// should emit a key frame for this video frame.
 130   /// @param[in] callback A <code>CompletionCallback</code> to be called upon
 131   /// completion. Plugins that pass <code>VideoFrame</code> resources owned
 132   /// by other resources should wait for completion before reusing them.
 133   ///
 134   /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
 135   /// Returns PP_ERROR_FAILED if Initialize() has not successfully completed.
 136   int32_t Encode(const VideoFrame& video_frame,
 137                  bool force_keyframe,
 138                  const CompletionCallback& cc);
 139
 140   /// Gets the next encoded bitstream buffer from the encoder.
 141   ///
 142   /// @param[out] bitstream_buffer A <code>PP_BitstreamBuffer</code> containing
 143   /// encoded video data.
 144   /// @param[in] callback A <code>CompletionCallbackWithOutput</code> to be
 145   /// called upon completion with the next bitstream buffer. The plugin can call
 146   /// GetBitstreamBuffer from the callback in order to continuously "pull"
 147   /// bitstream buffers from the encoder.
 148   ///
 149   /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
 150   /// Returns PP_ERROR_FAILED if Initialize() has not successfully completed.
 151   /// Returns PP_ERROR_INPROGRESS if a prior call to GetBitstreamBuffer() has
 152   /// not completed.
 153   int32_t GetBitstreamBuffer(
 154       const CompletionCallbackWithOutput<PP_BitstreamBuffer>& cc);
 155
 156   /// Recycles a bitstream buffer back to the encoder.
 157   ///
 158   /// @param[in] bitstream_buffer A <code>PP_BitstreamBuffer</code> that is no
 159   /// longer needed by the plugin.
 160   void RecycleBitstreamBuffer(const PP_BitstreamBuffer& bitstream_buffer);
 161
 162   /// Requests a change to encoding parameters. This is only a request,
 163   /// fulfilled on a best-effort basis.
 164   ///
 165   /// @param[in] bitrate The requested new bitrate, in bits per second.
 166   /// @param[in] framerate The requested new framerate, in frames per second.
 167   void RequestEncodingParametersChange(uint32_t bitrate, uint32_t framerate);
 168
 169   /// Closes the video encoder, and cancels any pending encodes. Any pending
 170   /// callbacks will still run, reporting <code>PP_ERROR_ABORTED</code> . It is
 171   /// not valid to call any encoder functions after a call to this method.
 172   /// <strong>Note:</strong> Destroying the video encoder closes it implicitly,
 173   /// so you are not required to call Close().
 174   void Close();
 175 };
 176
 177 }  // namespace pp
 178
 179 #endif  // PPAPI_CPP_VIDEO_ENCODER_H_