media/video/video_encode_accelerator.h

   1 // Copyright 2013 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 MEDIA_VIDEO_VIDEO_ENCODE_ACCELERATOR_H_
   6 #define MEDIA_VIDEO_VIDEO_ENCODE_ACCELERATOR_H_
   7
   8 #include <vector>
   9
  10 #include "base/basictypes.h"
  11 #include "base/memory/ref_counted.h"
  12 #include "media/base/bitstream_buffer.h"
  13 #include "media/base/media_export.h"
  14 #include "media/base/video_decoder_config.h"
  15 #include "media/base/video_frame.h"
  16
  17 namespace media {
  18
  19 class BitstreamBuffer;
  20 class VideoFrame;
  21
  22 // Video encoder interface.
  23 class MEDIA_EXPORT VideoEncodeAccelerator {
  24  public:
  25   // Specification of an encoding profile supported by an encoder.
  26   struct MEDIA_EXPORT SupportedProfile {
  27     SupportedProfile();
  28     ~SupportedProfile();
  29     VideoCodecProfile profile;
  30     gfx::Size max_resolution;
  31     uint32 max_framerate_numerator;
  32     uint32 max_framerate_denominator;
  33   };
  34   using SupportedProfiles = std::vector<SupportedProfile>;
  35
  36   // Enumeration of potential errors generated by the API.
  37   enum Error {
  38     // An operation was attempted during an incompatible encoder state.
  39     kIllegalStateError,
  40     // Invalid argument was passed to an API method.
  41     kInvalidArgumentError,
  42     // A failure occurred at the GPU process or one of its dependencies.
  43     // Examples of such failures include GPU hardware failures, GPU driver
  44     // failures, GPU library failures, GPU process programming errors, and so
  45     // on.
  46     kPlatformFailureError,
  47     kErrorMax = kPlatformFailureError
  48   };
  49
  50   // Interface for clients that use VideoEncodeAccelerator. These callbacks will
  51   // not be made unless Initialize() has returned successfully.
  52   class MEDIA_EXPORT Client {
  53    public:
  54     // Callback to tell the client what size of frames and buffers to provide
  55     // for input and output.  The VEA disclaims use or ownership of all
  56     // previously provided buffers once this callback is made.
  57     // Parameters:
  58     //  |input_count| is the number of input VideoFrames required for encoding.
  59     //  The client should be prepared to feed at least this many frames into the
  60     //  encoder before being returned any input frames, since the encoder may
  61     //  need to hold onto some subset of inputs as reference pictures.
  62     //  |input_coded_size| is the logical size of the input frames (as reported
  63     //  by VideoFrame::coded_size()) to encode, in pixels.  The encoder may have
  64     //  hardware alignment requirements that make this different from
  65     //  |input_visible_size|, as requested in Initialize(), in which case the
  66     //  input VideoFrame to Encode() should be padded appropriately.
  67     //  |output_buffer_size| is the required size of output buffers for this
  68     //  encoder in bytes.
  69     virtual void RequireBitstreamBuffers(unsigned int input_count,
  70                                          const gfx::Size& input_coded_size,
  71                                          size_t output_buffer_size) = 0;
  72
  73     // Callback to deliver encoded bitstream buffers.  Ownership of the buffer
  74     // is transferred back to the VEA::Client once this callback is made.
  75     // Parameters:
  76     //  |bitstream_buffer_id| is the id of the buffer that is ready.
  77     //  |payload_size| is the byte size of the used portion of the buffer.
  78     //  |key_frame| is true if this delivered frame is a keyframe.
  79     virtual void BitstreamBufferReady(int32 bitstream_buffer_id,
  80                                       size_t payload_size,
  81                                       bool key_frame) = 0;
  82
  83     // Error notification callback. Note that errors in Initialize() will not be
  84     // reported here, but will instead be indicated by a false return value
  85     // there.
  86     virtual void NotifyError(Error error) = 0;
  87
  88    protected:
  89     // Clients are not owned by VEA instances and should not be deleted through
  90     // these pointers.
  91     virtual ~Client() {}
  92   };
  93
  94   // Video encoder functions.
  95
  96   // Returns a list of the supported codec profiles of the video encoder. This
  97   // can be called before Initialize().
  98   virtual SupportedProfiles GetSupportedProfiles() = 0;
  99
 100   // Initializes the video encoder with specific configuration.  Called once per
 101   // encoder construction.  This call is synchronous and returns true iff
 102   // initialization is successful.
 103   // Parameters:
 104   //  |input_format| is the frame format of the input stream (as would be
 105   //  reported by VideoFrame::format() for frames passed to Encode()).
 106   //  |input_visible_size| is the resolution of the input stream (as would be
 107   //  reported by VideoFrame::visible_rect().size() for frames passed to
 108   //  Encode()).
 109   //  |output_profile| is the codec profile of the encoded output stream.
 110   //  |initial_bitrate| is the initial bitrate of the encoded output stream,
 111   //  in bits per second.
 112   //  |client| is the client of this video encoder.  The provided pointer must
 113   //  be valid until Destroy() is called.
 114   // TODO(sheu): handle resolution changes.  http://crbug.com/249944
 115   virtual bool Initialize(VideoPixelFormat input_format,
 116                           const gfx::Size& input_visible_size,
 117                           VideoCodecProfile output_profile,
 118                           uint32 initial_bitrate,
 119                           Client* client) = 0;
 120
 121   // Encodes the given frame.
 122   // Parameters:
 123   //  |frame| is the VideoFrame that is to be encoded.
 124   //  |force_keyframe| forces the encoding of a keyframe for this frame.
 125   virtual void Encode(const scoped_refptr<VideoFrame>& frame,
 126                       bool force_keyframe) = 0;
 127
 128   // Send a bitstream buffer to the encoder to be used for storing future
 129   // encoded output.  Each call here with a given |buffer| will cause the buffer
 130   // to be filled once, then returned with BitstreamBufferReady().
 131   // Parameters:
 132   //  |buffer| is the bitstream buffer to use for output.
 133   virtual void UseOutputBitstreamBuffer(const BitstreamBuffer& buffer) = 0;
 134
 135   // Request a change to the encoding parameters.  This is only a request,
 136   // fulfilled on a best-effort basis.
 137   // Parameters:
 138   //  |bitrate| is the requested new bitrate, in bits per second.
 139   //  |framerate| is the requested new framerate, in frames per second.
 140   virtual void RequestEncodingParametersChange(uint32 bitrate,
 141                                                uint32 framerate) = 0;
 142
 143   // Destroys the encoder: all pending inputs and outputs are dropped
 144   // immediately and the component is freed.  This call may asynchronously free
 145   // system resources, but its client-visible effects are synchronous.  After
 146   // this method returns no more callbacks will be made on the client.  Deletes
 147   // |this| unconditionally, so make sure to drop all pointers to it!
 148   virtual void Destroy() = 0;
 149
 150  protected:
 151   // Do not delete directly; use Destroy() or own it with a scoped_ptr, which
 152   // will Destroy() it properly by default.
 153   virtual ~VideoEncodeAccelerator();
 154 };
 155
 156 }  // namespace media
 157
 158 namespace base {
 159
 160 template <class T>
 161 struct DefaultDeleter;
 162
 163 // Specialize DefaultDeleter so that scoped_ptr<VideoEncodeAccelerator> always
 164 // uses "Destroy()" instead of trying to use the destructor.
 165 template <>
 166 struct MEDIA_EXPORT DefaultDeleter<media::VideoEncodeAccelerator> {
 167  public:
 168   void operator()(void* video_encode_accelerator) const;
 169 };
 170
 171 }  // namespace base
 172
 173 #endif  // MEDIA_VIDEO_VIDEO_ENCODE_ACCELERATOR_H_