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 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. ~Client()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 155 namespace base { 156 157 template <class T> 158 struct DefaultDeleter; 159 160 // Specialize DefaultDeleter so that scoped_ptr<VideoEncodeAccelerator> always 161 // uses "Destroy()" instead of trying to use the destructor. 162 template <> 163 struct 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