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 virtual ~VideoEncodeAccelerator(); 26 27 // Specification of an encoding profile supported by an encoder. 28 struct SupportedProfile { 29 VideoCodecProfile profile; 30 gfx::Size max_resolution; 31 struct { 32 uint32 numerator; 33 uint32 denominator; 34 } max_framerate; 35 }; 36 37 // Enumeration of potential errors generated by the API. 38 enum Error { 39 // An operation was attempted during an incompatible encoder state. 40 kIllegalStateError, 41 // Invalid argument was passed to an API method. 42 kInvalidArgumentError, 43 // A failure occurred at the GPU process or one of its dependencies. 44 // Examples of such failures include GPU hardware failures, GPU driver 45 // failures, GPU library failures, GPU process programming errors, and so 46 // on. 47 kPlatformFailureError, 48 }; 49 50 // Interface for clients that use VideoEncodeAccelerator. 51 class MEDIA_EXPORT Client { 52 public: 53 // Callback to notify client that encoder has been successfully initialized. 54 virtual void NotifyInitializeDone() = 0; 55 56 // Callback to tell the client what size of frames and buffers to provide 57 // for input and output. The VEA disclaims use or ownership of all 58 // previously provided buffers once this callback is made. 59 // Parameters: 60 // |input_count| is the number of input VideoFrames required for encoding. 61 // The client should be prepared to feed at least this many frames into the 62 // encoder before being returned any input frames, since the encoder may 63 // need to hold onto some subset of inputs as reference pictures. 64 // |input_coded_size| is the logical size of the input frames (as reported 65 // by VideoFrame::coded_size()) to encode, in pixels. The encoder may have 66 // hardware alignment requirements that make this different from 67 // |input_visible_size|, as requested in Initialize(), in which case the 68 // input VideoFrame to Encode() should be padded appropriately. 69 // |output_buffer_size| is the required size of output buffers for this 70 // encoder in bytes. 71 virtual void RequireBitstreamBuffers(unsigned int input_count, 72 const gfx::Size& input_coded_size, 73 size_t output_buffer_size) = 0; 74 75 // Callback to deliver encoded bitstream buffers. Ownership of the buffer 76 // is transferred back to the VEA::Client once this callback is made. 77 // Parameters: 78 // |bitstream_buffer_id| is the id of the buffer that is ready. 79 // |payload_size| is the byte size of the used portion of the buffer. 80 // |key_frame| is true if this delivered frame is a keyframe. 81 virtual void BitstreamBufferReady(int32 bitstream_buffer_id, 82 size_t payload_size, 83 bool key_frame) = 0; 84 85 // Error notification callback. 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. ~Client()91 virtual ~Client() {} 92 }; 93 94 // Video encoder functions. 95 96 // Initialize the video encoder with a specific configuration. Called once 97 // per encoder construction. 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 // TODO(sheu): handle resolution changes. http://crbug.com/249944 108 virtual void Initialize(media::VideoFrame::Format input_format, 109 const gfx::Size& input_visible_size, 110 VideoCodecProfile output_profile, 111 uint32 initial_bitrate) = 0; 112 113 // Encodes the given frame. 114 // Parameters: 115 // |frame| is the VideoFrame that is to be encoded. 116 // |force_keyframe| forces the encoding of a keyframe for this frame. 117 virtual void Encode(const scoped_refptr<VideoFrame>& frame, 118 bool force_keyframe) = 0; 119 120 // Send a bitstream buffer to the encoder to be used for storing future 121 // encoded output. Each call here with a given |buffer| will cause the buffer 122 // to be filled once, then returned with BitstreamBufferReady(). 123 // Parameters: 124 // |buffer| is the bitstream buffer to use for output. 125 virtual void UseOutputBitstreamBuffer(const BitstreamBuffer& buffer) = 0; 126 127 // Request a change to the encoding parameters. This is only a request, 128 // fulfilled on a best-effort basis. 129 // Parameters: 130 // |bitrate| is the requested new bitrate, in bits per second. 131 // |framerate| is the requested new framerate, in frames per second. 132 virtual void RequestEncodingParametersChange(uint32 bitrate, 133 uint32 framerate) = 0; 134 135 // Destroys the encoder: all pending inputs and outputs are dropped 136 // immediately and the component is freed. This call may asynchronously free 137 // system resources, but its client-visible effects are synchronous. After 138 // this method returns no more callbacks will be made on the client. Deletes 139 // |this| unconditionally, so make sure to drop all pointers to it! 140 virtual void Destroy() = 0; 141 }; 142 143 } // namespace media 144 145 #endif // MEDIA_VIDEO_VIDEO_ENCODE_ACCELERATOR_H_ 146