src/third_party/webrtc/modules/video_coding/codecs/interface/video_codec_interface.h

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