1 /* 2 * Copyright (c) 2012 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_MODULES_VIDEO_CODING_CODECS_INTERFACE_VIDEO_CODEC_INTERFACE_H 12 #define WEBRTC_MODULES_VIDEO_CODING_CODECS_INTERFACE_VIDEO_CODEC_INTERFACE_H 13 14 #include <vector> 15 16 #include "webrtc/common_types.h" 17 #include "webrtc/common_video/interface/i420_video_frame.h" 18 #include "webrtc/common_video/interface/video_image.h" 19 #include "webrtc/modules/interface/module_common_types.h" 20 #include "webrtc/modules/video_coding/codecs/interface/video_error_codes.h" 21 22 #include "webrtc/typedefs.h" 23 24 namespace webrtc 25 { 26 27 class RTPFragmentationHeader; // forward declaration 28 29 // Note: if any pointers are added to this struct, it must be fitted 30 // with a copy-constructor. See below. 31 struct CodecSpecificInfoVP8 32 { 33 bool hasReceivedSLI; 34 uint8_t pictureIdSLI; 35 bool hasReceivedRPSI; 36 uint64_t pictureIdRPSI; 37 int16_t pictureId; // negative value to skip pictureId 38 bool nonReference; 39 uint8_t simulcastIdx; 40 uint8_t temporalIdx; 41 bool layerSync; 42 int tl0PicIdx; // Negative value to skip tl0PicIdx 43 int8_t keyIdx; // negative value to skip keyIdx 44 }; 45 46 struct CodecSpecificInfoGeneric { 47 uint8_t simulcast_idx; 48 }; 49 50 union CodecSpecificInfoUnion 51 { 52 CodecSpecificInfoGeneric generic; 53 CodecSpecificInfoVP8 VP8; 54 }; 55 56 // Note: if any pointers are added to this struct or its sub-structs, it 57 // must be fitted with a copy-constructor. This is because it is copied 58 // in the copy-constructor of VCMEncodedFrame. 59 struct CodecSpecificInfo 60 { 61 VideoCodecType codecType; 62 CodecSpecificInfoUnion codecSpecific; 63 }; 64 65 class EncodedImageCallback 66 { 67 public: 68 virtual ~EncodedImageCallback() {}; 69 70 // Callback function which is called when an image has been encoded. 71 // 72 // Input: 73 // - encodedImage : The encoded image 74 // 75 // Return value : > 0, signals to the caller that one or more future frames 76 // should be dropped to keep bit rate or frame rate. 77 // = 0, if OK. 78 // < 0, on error. 79 virtual int32_t 80 Encoded(EncodedImage& encodedImage, 81 const CodecSpecificInfo* codecSpecificInfo = NULL, 82 const RTPFragmentationHeader* fragmentation = NULL) = 0; 83 }; 84 85 class VideoEncoder 86 { 87 public: 88 virtual ~VideoEncoder() {}; 89 90 // Initialize the encoder with the information from the VideoCodec. 91 // 92 // Input: 93 // - codecSettings : Codec settings 94 // - numberOfCores : Number of cores available for the encoder 95 // - maxPayloadSize : The maximum size each payload is allowed 96 // to have. Usually MTU - overhead. 97 // 98 // Return value : WEBRTC_VIDEO_CODEC_OK if OK, < 0 otherwise. 99 virtual int32_t InitEncode(const VideoCodec* codecSettings, int32_t numberOfCores, uint32_t maxPayloadSize) = 0; 100 101 // Encode an I420 image (as a part of a video stream). The encoded image 102 // will be returned to the user through the encode complete callback. 103 // 104 // Input: 105 // - inputImage : Image to be encoded 106 // - codecSpecificInfo : Pointer to codec specific data 107 // - frame_types : The frame type to encode 108 // 109 // Return value : WEBRTC_VIDEO_CODEC_OK if OK, < 0 110 // otherwise. 111 virtual int32_t Encode( 112 const I420VideoFrame& inputImage, 113 const CodecSpecificInfo* codecSpecificInfo, 114 const std::vector<VideoFrameType>* frame_types) = 0; 115 116 // Register an encode complete callback object. 117 // 118 // Input: 119 // - callback : Callback object which handles encoded images. 120 // 121 // Return value : WEBRTC_VIDEO_CODEC_OK if OK, < 0 otherwise. 122 virtual int32_t RegisterEncodeCompleteCallback(EncodedImageCallback* callback) = 0; 123 124 // Free encoder memory. 125 // 126 // Return value : WEBRTC_VIDEO_CODEC_OK if OK, < 0 otherwise. 127 virtual int32_t Release() = 0; 128 129 // Inform the encoder about the packet loss and round trip time on the 130 // network used to decide the best pattern and signaling. 131 // 132 // - packetLoss : Fraction lost (loss rate in percent = 133 // 100 * packetLoss / 255) 134 // - rtt : Round-trip time in milliseconds 135 // 136 // Return value : WEBRTC_VIDEO_CODEC_OK if OK, < 0 otherwise. 137 virtual int32_t SetChannelParameters(uint32_t packetLoss, int rtt) = 0; 138 139 // Inform the encoder about the new target bit rate. 140 // 141 // - newBitRate : New target bit rate 142 // - frameRate : The target frame rate 143 // 144 // Return value : WEBRTC_VIDEO_CODEC_OK if OK, < 0 otherwise. 145 virtual int32_t SetRates(uint32_t newBitRate, uint32_t frameRate) = 0; 146 147 // Use this function to enable or disable periodic key frames. Can be useful for codecs 148 // which have other ways of stopping error propagation. 149 // 150 // - enable : Enable or disable periodic key frames 151 // 152 // Return value : WEBRTC_VIDEO_CODEC_OK if OK, < 0 otherwise. 153 virtual int32_t SetPeriodicKeyFrames(bool enable) { return WEBRTC_VIDEO_CODEC_ERROR; } 154 155 // Codec configuration data to send out-of-band, i.e. in SIP call setup 156 // 157 // - buffer : Buffer pointer to where the configuration data 158 // should be stored 159 // - size : The size of the buffer in bytes 160 // 161 // Return value : WEBRTC_VIDEO_CODEC_OK if OK, < 0 otherwise. 162 virtual int32_t CodecConfigParameters(uint8_t* /*buffer*/, int32_t /*size*/) { return WEBRTC_VIDEO_CODEC_ERROR; } 163 }; 164 165 class DecodedImageCallback 166 { 167 public: 168 virtual ~DecodedImageCallback() {}; 169 170 // Callback function which is called when an image has been decoded. 171 // 172 // Input: 173 // - decodedImage : The decoded image. 174 // 175 // Return value : 0 if OK, < 0 otherwise. 176 virtual int32_t Decoded(I420VideoFrame& decodedImage) = 0; 177 178 virtual int32_t ReceivedDecodedReferenceFrame(const uint64_t pictureId) {return -1;} 179 180 virtual int32_t ReceivedDecodedFrame(const uint64_t pictureId) {return -1;} 181 }; 182 183 class VideoDecoder 184 { 185 public: 186 virtual ~VideoDecoder() {}; 187 188 // Initialize the decoder with the information from the VideoCodec. 189 // 190 // Input: 191 // - inst : Codec settings 192 // - numberOfCores : Number of cores available for the decoder 193 // 194 // Return value : WEBRTC_VIDEO_CODEC_OK if OK, < 0 otherwise. 195 virtual int32_t InitDecode(const VideoCodec* codecSettings, int32_t numberOfCores) = 0; 196 197 // Decode encoded image (as a part of a video stream). The decoded image 198 // will be returned to the user through the decode complete callback. 199 // 200 // Input: 201 // - inputImage : Encoded image to be decoded 202 // - missingFrames : True if one or more frames have been lost 203 // since the previous decode call. 204 // - fragmentation : Specifies where the encoded frame can be 205 // split into separate fragments. The meaning 206 // of fragment is codec specific, but often 207 // means that each fragment is decodable by 208 // itself. 209 // - codecSpecificInfo : Pointer to codec specific data 210 // - renderTimeMs : System time to render in milliseconds. Only 211 // used by decoders with internal rendering. 212 // 213 // Return value : WEBRTC_VIDEO_CODEC_OK if OK, < 0 otherwise. 214 virtual int32_t 215 Decode(const EncodedImage& inputImage, 216 bool missingFrames, 217 const RTPFragmentationHeader* fragmentation, 218 const CodecSpecificInfo* codecSpecificInfo = NULL, 219 int64_t renderTimeMs = -1) = 0; 220 221 // Register an decode complete callback object. 222 // 223 // Input: 224 // - callback : Callback object which handles decoded images. 225 // 226 // Return value : WEBRTC_VIDEO_CODEC_OK if OK, < 0 otherwise. 227 virtual int32_t RegisterDecodeCompleteCallback(DecodedImageCallback* callback) = 0; 228 229 // Free decoder memory. 230 // 231 // Return value : WEBRTC_VIDEO_CODEC_OK if OK, < 0 otherwise. 232 virtual int32_t Release() = 0; 233 234 // Reset decoder state and prepare for a new call. 235 // 236 // Return value : WEBRTC_VIDEO_CODEC_OK if OK, < 0 otherwise. 237 virtual int32_t Reset() = 0; 238 239 // Codec configuration data sent out-of-band, i.e. in SIP call setup 240 // 241 // Input/Output: 242 // - buffer : Buffer pointer to the configuration data 243 // - size : The size of the configuration data in 244 // bytes 245 // 246 // Return value : WEBRTC_VIDEO_CODEC_OK if OK, < 0 otherwise. 247 virtual int32_t SetCodecConfigParameters(const uint8_t* /*buffer*/, int32_t /*size*/) { return WEBRTC_VIDEO_CODEC_ERROR; } 248 249 // Create a copy of the codec and its internal state. 250 // 251 // Return value : A copy of the instance if OK, NULL otherwise. 252 virtual VideoDecoder* Copy() { return NULL; } 253 }; 254 255 } // namespace webrtc 256 257 #endif // WEBRTC_MODULES_VIDEO_CODING_CODECS_INTERFACE_VIDEO_CODEC_INTERFACE_H 258
