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