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