1/*
2 *  Copyright (c) 2014 The WebRTC project authors. All Rights Reserved.
3 *
4 *  Use of this source code is governed by a BSD-style license
5 *  that can be found in the LICENSE file in the root of the source
6 *  tree. An additional intellectual property rights grant can be found
7 *  in the file PATENTS.  All contributing project authors may
8 *  be found in the AUTHORS file in the root of the source tree.
9 */
10
11#ifndef WEBRTC_VIDEO_ENCODER_H_
12#define WEBRTC_VIDEO_ENCODER_H_
13
14#include <string>
15#include <vector>
16
17#include "webrtc/common_types.h"
18#include "webrtc/typedefs.h"
19#include "webrtc/video_frame.h"
20
21namespace webrtc {
22
23class RTPFragmentationHeader;
24// TODO(pbos): Expose these through a public (root) header or change these APIs.
25struct CodecSpecificInfo;
26struct VideoCodec;
27
28class EncodedImageCallback {
29 public:
30  virtual ~EncodedImageCallback() {}
31
32  // Callback function which is called when an image has been encoded.
33  virtual int32_t Encoded(const EncodedImage& encoded_image,
34                          const CodecSpecificInfo* codec_specific_info,
35                          const RTPFragmentationHeader* fragmentation) = 0;
36};
37
38class VideoEncoder {
39 public:
40  enum EncoderType {
41    kH264,
42    kVp8,
43    kVp9,
44    kUnsupportedCodec,
45  };
46
47  static VideoEncoder* Create(EncoderType codec_type);
48
49  static VideoCodecVP8 GetDefaultVp8Settings();
50  static VideoCodecVP9 GetDefaultVp9Settings();
51  static VideoCodecH264 GetDefaultH264Settings();
52
53  virtual ~VideoEncoder() {}
54
55  // Initialize the encoder with the information from the codecSettings
56  //
57  // Input:
58  //          - codec_settings    : Codec settings
59  //          - number_of_cores   : Number of cores available for the encoder
60  //          - max_payload_size  : The maximum size each payload is allowed
61  //                                to have. Usually MTU - overhead.
62  //
63  // Return value                  : Set bit rate if OK
64  //                                 <0 - Errors:
65  //                                  WEBRTC_VIDEO_CODEC_ERR_PARAMETER
66  //                                  WEBRTC_VIDEO_CODEC_ERR_SIZE
67  //                                  WEBRTC_VIDEO_CODEC_LEVEL_EXCEEDED
68  //                                  WEBRTC_VIDEO_CODEC_MEMORY
69  //                                  WEBRTC_VIDEO_CODEC_ERROR
70  virtual int32_t InitEncode(const VideoCodec* codec_settings,
71                             int32_t number_of_cores,
72                             size_t max_payload_size) = 0;
73
74  // Register an encode complete callback object.
75  //
76  // Input:
77  //          - callback         : Callback object which handles encoded images.
78  //
79  // Return value                : WEBRTC_VIDEO_CODEC_OK if OK, < 0 otherwise.
80  virtual int32_t RegisterEncodeCompleteCallback(
81      EncodedImageCallback* callback) = 0;
82
83  // Free encoder memory.
84  // Return value                : WEBRTC_VIDEO_CODEC_OK if OK, < 0 otherwise.
85  virtual int32_t Release() = 0;
86
87  // Encode an I420 image (as a part of a video stream). The encoded image
88  // will be returned to the user through the encode complete callback.
89  //
90  // Input:
91  //          - frame             : Image to be encoded
92  //          - frame_types       : Frame type to be generated by the encoder.
93  //
94  // Return value                 : WEBRTC_VIDEO_CODEC_OK if OK
95  //                                <0 - Errors:
96  //                                  WEBRTC_VIDEO_CODEC_ERR_PARAMETER
97  //                                  WEBRTC_VIDEO_CODEC_MEMORY
98  //                                  WEBRTC_VIDEO_CODEC_ERROR
99  //                                  WEBRTC_VIDEO_CODEC_TIMEOUT
100  virtual int32_t Encode(const VideoFrame& frame,
101                         const CodecSpecificInfo* codec_specific_info,
102                         const std::vector<FrameType>* frame_types) = 0;
103
104  // Inform the encoder of the new packet loss rate and the round-trip time of
105  // the network.
106  //
107  // Input:
108  //          - packet_loss : Fraction lost
109  //                          (loss rate in percent = 100 * packetLoss / 255)
110  //          - rtt         : Round-trip time in milliseconds
111  // Return value           : WEBRTC_VIDEO_CODEC_OK if OK
112  //                          <0 - Errors: WEBRTC_VIDEO_CODEC_ERROR
113  virtual int32_t SetChannelParameters(uint32_t packet_loss, int64_t rtt) = 0;
114
115  // Inform the encoder about the new target bit rate.
116  //
117  // Input:
118  //          - bitrate         : New target bit rate
119  //          - framerate       : The target frame rate
120  //
121  // Return value                : WEBRTC_VIDEO_CODEC_OK if OK, < 0 otherwise.
122  virtual int32_t SetRates(uint32_t bitrate, uint32_t framerate) = 0;
123
124  virtual int32_t SetPeriodicKeyFrames(bool enable) { return -1; }
125  virtual void OnDroppedFrame() {}
126  virtual int GetTargetFramerate() { return -1; }
127  virtual bool SupportsNativeHandle() const { return false; }
128  virtual const char* ImplementationName() const { return "unknown"; }
129};
130
131// Class used to wrap external VideoEncoders to provide a fallback option on
132// software encoding when a hardware encoder fails to encode a stream due to
133// hardware restrictions, such as max resolution.
134class VideoEncoderSoftwareFallbackWrapper : public VideoEncoder {
135 public:
136  VideoEncoderSoftwareFallbackWrapper(VideoCodecType codec_type,
137                                      webrtc::VideoEncoder* encoder);
138
139  int32_t InitEncode(const VideoCodec* codec_settings,
140                     int32_t number_of_cores,
141                     size_t max_payload_size) override;
142
143  int32_t RegisterEncodeCompleteCallback(
144      EncodedImageCallback* callback) override;
145
146  int32_t Release() override;
147  int32_t Encode(const VideoFrame& frame,
148                 const CodecSpecificInfo* codec_specific_info,
149                 const std::vector<FrameType>* frame_types) override;
150  int32_t SetChannelParameters(uint32_t packet_loss, int64_t rtt) override;
151
152  int32_t SetRates(uint32_t bitrate, uint32_t framerate) override;
153  void OnDroppedFrame() override;
154  int GetTargetFramerate() override;
155  bool SupportsNativeHandle() const override;
156  const char* ImplementationName() const override;
157
158 private:
159  bool InitFallbackEncoder();
160
161  // Settings used in the last InitEncode call and used if a dynamic fallback to
162  // software is required.
163  VideoCodec codec_settings_;
164  int32_t number_of_cores_;
165  size_t max_payload_size_;
166
167  // The last bitrate/framerate set, and a flag for noting they are set.
168  bool rates_set_;
169  uint32_t bitrate_;
170  uint32_t framerate_;
171
172  // The last channel parameters set, and a flag for noting they are set.
173  bool channel_parameters_set_;
174  uint32_t packet_loss_;
175  int64_t rtt_;
176
177  const EncoderType encoder_type_;
178  webrtc::VideoEncoder* const encoder_;
179
180  rtc::scoped_ptr<webrtc::VideoEncoder> fallback_encoder_;
181  std::string fallback_implementation_name_;
182  EncodedImageCallback* callback_;
183};
184}  // namespace webrtc
185#endif  // WEBRTC_VIDEO_ENCODER_H_
186