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.
5 #ifndef MEDIA_VIDEO_VIDEO_ENCODE_ACCELERATOR_H_
6 #define MEDIA_VIDEO_VIDEO_ENCODE_ACCELERATOR_H_
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"
19 class BitstreamBuffer;
22 // Video encoder interface.
23 class MEDIA_EXPORT VideoEncodeAccelerator {
25 virtual ~VideoEncodeAccelerator();
27 // Specification of an encoding profile supported by an encoder.
28 struct SupportedProfile {
29 VideoCodecProfile profile;
30 gfx::Size max_resolution;
37 // Enumeration of potential errors generated by the API.
39 // An operation was attempted during an incompatible encoder state.
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
47 kPlatformFailureError,
48 kErrorMax = kPlatformFailureError
51 // Interface for clients that use VideoEncodeAccelerator.
52 class MEDIA_EXPORT Client {
54 // Callback to notify client that encoder has been successfully initialized.
55 virtual void NotifyInitializeDone() = 0;
57 // Callback to tell the client what size of frames and buffers to provide
58 // for input and output. The VEA disclaims use or ownership of all
59 // previously provided buffers once this callback is made.
61 // |input_count| is the number of input VideoFrames required for encoding.
62 // The client should be prepared to feed at least this many frames into the
63 // encoder before being returned any input frames, since the encoder may
64 // need to hold onto some subset of inputs as reference pictures.
65 // |input_coded_size| is the logical size of the input frames (as reported
66 // by VideoFrame::coded_size()) to encode, in pixels. The encoder may have
67 // hardware alignment requirements that make this different from
68 // |input_visible_size|, as requested in Initialize(), in which case the
69 // input VideoFrame to Encode() should be padded appropriately.
70 // |output_buffer_size| is the required size of output buffers for this
72 virtual void RequireBitstreamBuffers(unsigned int input_count,
73 const gfx::Size& input_coded_size,
74 size_t output_buffer_size) = 0;
76 // Callback to deliver encoded bitstream buffers. Ownership of the buffer
77 // is transferred back to the VEA::Client once this callback is made.
79 // |bitstream_buffer_id| is the id of the buffer that is ready.
80 // |payload_size| is the byte size of the used portion of the buffer.
81 // |key_frame| is true if this delivered frame is a keyframe.
82 virtual void BitstreamBufferReady(int32 bitstream_buffer_id,
86 // Error notification callback.
87 virtual void NotifyError(Error error) = 0;
90 // Clients are not owned by VEA instances and should not be deleted through
95 // Video encoder functions.
97 // Initialize the video encoder with a specific configuration. Called once
98 // per encoder construction.
100 // |input_format| is the frame format of the input stream (as would be
101 // reported by VideoFrame::format() for frames passed to Encode()).
102 // |input_visible_size| is the resolution of the input stream (as would be
103 // reported by VideoFrame::visible_rect().size() for frames passed to
105 // |output_profile| is the codec profile of the encoded output stream.
106 // |initial_bitrate| is the initial bitrate of the encoded output stream,
107 // in bits per second.
108 // TODO(sheu): handle resolution changes. http://crbug.com/249944
109 virtual void Initialize(media::VideoFrame::Format input_format,
110 const gfx::Size& input_visible_size,
111 VideoCodecProfile output_profile,
112 uint32 initial_bitrate) = 0;
114 // Encodes the given frame.
116 // |frame| is the VideoFrame that is to be encoded.
117 // |force_keyframe| forces the encoding of a keyframe for this frame.
118 virtual void Encode(const scoped_refptr<VideoFrame>& frame,
119 bool force_keyframe) = 0;
121 // Send a bitstream buffer to the encoder to be used for storing future
122 // encoded output. Each call here with a given |buffer| will cause the buffer
123 // to be filled once, then returned with BitstreamBufferReady().
125 // |buffer| is the bitstream buffer to use for output.
126 virtual void UseOutputBitstreamBuffer(const BitstreamBuffer& buffer) = 0;
128 // Request a change to the encoding parameters. This is only a request,
129 // fulfilled on a best-effort basis.
131 // |bitrate| is the requested new bitrate, in bits per second.
132 // |framerate| is the requested new framerate, in frames per second.
133 virtual void RequestEncodingParametersChange(uint32 bitrate,
134 uint32 framerate) = 0;
136 // Destroys the encoder: all pending inputs and outputs are dropped
137 // immediately and the component is freed. This call may asynchronously free
138 // system resources, but its client-visible effects are synchronous. After
139 // this method returns no more callbacks will be made on the client. Deletes
140 // |this| unconditionally, so make sure to drop all pointers to it!
141 virtual void Destroy() = 0;
146 #endif // MEDIA_VIDEO_VIDEO_ENCODE_ACCELERATOR_H_