/*
 *  Copyright (c) 2011 The WebRTC project authors. All Rights Reserved.
 *
 *  Use of this source code is governed by a BSD-style license
 *  that can be found in the LICENSE file in the root of the source
 *  tree. An additional intellectual property rights grant can be found
 *  in the file PATENTS.  All contributing project authors may
 *  be found in the AUTHORS file in the root of the source tree.
 */

#ifndef WEBRTC_MODULES_INTERFACE_VIDEO_CODING_H_
#define WEBRTC_MODULES_INTERFACE_VIDEO_CODING_H_

#include "modules/interface/module.h"
#include "modules/interface/module_common_types.h"
#include "modules/video_coding/main/interface/video_coding_defines.h"

namespace webrtc
{

class TickTimeBase;
class VideoEncoder;
class VideoDecoder;
struct CodecSpecificInfo;

class VideoCodingModule : public Module
{
public:
    enum SenderNackMode {
        kNackNone,
        kNackAll,
        kNackSelective
    };

    enum ReceiverRobustness {
        kNone,
        kHardNack,
        kSoftNack,
        kDualDecoder,
        kReferenceSelection
    };

    enum DecodeErrors {
        kNoDecodeErrors,
        kAllowDecodeErrors
    };

    static VideoCodingModule* Create(const WebRtc_Word32 id);

    static VideoCodingModule* Create(const WebRtc_Word32 id,
                                     TickTimeBase* clock);

    static void Destroy(VideoCodingModule* module);

    // Get number of supported codecs
    //
    // Return value     : Number of supported codecs
    static WebRtc_UWord8 NumberOfCodecs();

    // Get supported codec settings with using id
    //
    // Input:
    //      - listId         : Id or index of the codec to look up
    //      - codec          : Memory where the codec settings will be stored
    //
    // Return value     : VCM_OK,              on success
    //                    VCM_PARAMETER_ERROR  if codec not supported or id too high
    static WebRtc_Word32 Codec(const WebRtc_UWord8 listId, VideoCodec* codec);

    // Get supported codec settings using codec type
    //
    // Input:
    //      - codecType      : The codec type to get settings for
    //      - codec          : Memory where the codec settings will be stored
    //
    // Return value     : VCM_OK,              on success
    //                    VCM_PARAMETER_ERROR  if codec not supported
    static WebRtc_Word32 Codec(VideoCodecType codecType, VideoCodec* codec);

    /*
    *   Sender
    */

    // Any encoder-related state of VCM will be initialized to the
    // same state as when the VCM was created. This will not interrupt
    // or effect decoding functionality of VCM. VCM will lose all the
    // encoding-related settings by calling this function.
    // For instance, a send codec has to be registered again.
    //
    // Return value      : VCM_OK, on success.
    //                     < 0,         on error.
    virtual WebRtc_Word32 InitializeSender() = 0;

    // Resets the encoder state to the same state as when the encoder
    // was created.
    //
    // Return value      : VCM_OK, on success.
    //                     < 0,         on error.
    virtual WebRtc_Word32 ResetEncoder() = 0;

    // Registers a codec to be used for encoding. Calling this
    // API multiple times overwrites any previously registered codecs.
    //
    // Input:
    //      - sendCodec      : Settings for the codec to be registered.
    //      - numberOfCores  : The number of cores the codec is allowed
    //                         to use.
    //      - maxPayloadSize : The maximum size each payload is allowed
    //                                to have. Usually MTU - overhead.
    //
    // Return value      : VCM_OK, on success.
    //                     < 0,         on error.
    virtual WebRtc_Word32 RegisterSendCodec(const VideoCodec* sendCodec,
                                            WebRtc_UWord32 numberOfCores,
                                            WebRtc_UWord32 maxPayloadSize) = 0;

    // API to get the current send codec in use.
    //
    // Input:
    //      - currentSendCodec : Address where the sendCodec will be written.
    //
    // Return value      : VCM_OK, on success.
    //                     < 0,         on error.
    virtual WebRtc_Word32 SendCodec(VideoCodec* currentSendCodec) const = 0;

    // API to get the current send codec type
    //
    // Return value      : Codec type, on success.
    //                     kVideoCodecUnknown, on error or if no send codec is set
    virtual VideoCodecType SendCodec() const = 0;

    // Register an external encoder object. This can not be used together with
    // external decoder callbacks.
    //
    // Input:
    //      - externalEncoder : Encoder object to be used for encoding frames inserted
    //                          with the AddVideoFrame API.
    //      - payloadType     : The payload type bound which this encoder is bound to.
    //
    // Return value      : VCM_OK, on success.
    //                     < 0,         on error.
    virtual WebRtc_Word32 RegisterExternalEncoder(VideoEncoder* externalEncoder,
                                                  WebRtc_UWord8 payloadType,
                                                  bool internalSource = false) = 0;

    // API to get codec config parameters to be sent out-of-band to a receiver.
    //
    // Input:
    //      - buffer          : Memory where the codec config parameters should be written.
    //      - size            : Size of the memory available.
    //
    // Return value      : Number of bytes written, on success.
    //                     < 0,                     on error.
    virtual WebRtc_Word32 CodecConfigParameters(WebRtc_UWord8* buffer, WebRtc_Word32 size) = 0;

    // API to get currently configured encoder target bit rate.
    //
    // Return value      : The encoder target bit rate, on success.
    //                     < 0,                         on error.
    virtual WebRtc_UWord32 Bitrate() const = 0;

    // API to get currently configured encoder target frame rate.
    //
    // Return value      : The encoder target frame rate, on success.
    //                     < 0,                           on error.
    virtual WebRtc_UWord32 FrameRate() const = 0;

    // Sets the parameters describing the send channel. These parameters are inputs to the
    // Media Optimization inside the VCM and also specifies the target bit rate for the
    // encoder. Bit rate used by NACK should already be compensated for by the user.
    //
    // Input:
    //      - availableBandWidth    : Band width available for the VCM in kbit/s.
    //      - lossRate              : Fractions of lost packets the past second.
    //                                (loss rate in percent = 100 * packetLoss / 255)
    //      - rtt                   : Current round-trip time in ms.
    //
    // Return value      : VCM_OK, on success.
    //                     < 0,         on error.
    virtual WebRtc_Word32 SetChannelParameters(WebRtc_UWord32 availableBandWidth,
                                               WebRtc_UWord8 lossRate,
                                               WebRtc_UWord32 rtt) = 0;

    // Sets the parameters describing the receive channel. These parameters are inputs to the
    // Media Optimization inside the VCM.
    //
    // Input:
    //      - rtt                   : Current round-trip time in ms.
    //                                with the most amount available bandwidth in a conference
    //                                scenario
    //
    // Return value      : VCM_OK, on success.
    //                     < 0,         on error.
    virtual WebRtc_Word32 SetReceiveChannelParameters(WebRtc_UWord32 rtt) = 0;

    // Register a transport callback which will be called to deliver the encoded data and
    // side information.
    //
    // Input:
    //      - transport  : The callback object to register.
    //
    // Return value      : VCM_OK, on success.
    //                     < 0,         on error.
    virtual WebRtc_Word32 RegisterTransportCallback(VCMPacketizationCallback* transport) = 0;

    // Register video output information callback which will be called to deliver information
    // about the video stream produced by the encoder, for instance the average frame rate and
    // bit rate.
    //
    // Input:
    //      - outputInformation  : The callback object to register.
    //
    // Return value      : VCM_OK, on success.
    //                     < 0,         on error.
    virtual WebRtc_Word32 RegisterSendStatisticsCallback(
                                     VCMSendStatisticsCallback* sendStats) = 0;

    // Register a video quality settings callback which will be called when
    // frame rate/dimensions need to be updated for video quality optimization
    //
    // Input:
    //		- videoQMSettings  : The callback object to register.
    //
    // Return value      : VCM_OK, on success.
    //                     < 0,         on error
    virtual WebRtc_Word32 RegisterVideoQMCallback(VCMQMSettingsCallback* videoQMSettings) = 0;

    // Register a video protection callback which will be called to deliver
    // the requested FEC rate and NACK status (on/off).
    //
    // Input:
    //      - protection  : The callback object to register.
    //
    // Return value      : VCM_OK, on success.
    //                     < 0,         on error.
    virtual WebRtc_Word32 RegisterProtectionCallback(VCMProtectionCallback* protection) = 0;

    // Enable or disable a video protection method.
    //
    // Input:
    //      - videoProtection  : The method to enable or disable.
    //      - enable           : True if the method should be enabled, false if
    //                           it should be disabled.
    //
    // Return value      : VCM_OK, on success.
    //                     < 0,         on error.
    virtual WebRtc_Word32 SetVideoProtection(VCMVideoProtection videoProtection,
                                             bool enable) = 0;

    // Add one raw video frame to the encoder. This function does all the necessary
    // processing, then decides what frame type to encode, or if the frame should be
    // dropped. If the frame should be encoded it passes the frame to the encoder
    // before it returns.
    //
    // Input:
    //      - videoFrame        : Video frame to encode.
    //      - codecSpecificInfo : Extra codec information, e.g., pre-parsed in-band signaling.
    //
    // Return value      : VCM_OK, on success.
    //                     < 0,         on error.
    virtual WebRtc_Word32 AddVideoFrame(
        const VideoFrame& videoFrame,
        const VideoContentMetrics* contentMetrics = NULL,
        const CodecSpecificInfo* codecSpecificInfo = NULL) = 0;

    // Next frame encoded should be of the type frameType.
    //
    // Input:
    //      - frameType    : The frame type to encode next time a VideoFrame
    //                       is added to the module.
    //
    // Return value      : VCM_OK, on success.
    //                     < 0,         on error.
    virtual WebRtc_Word32 FrameTypeRequest(FrameType frameType,
                                           WebRtc_UWord8 simulcastIdx) = 0;

    // Frame Dropper enable. Can be used to disable the frame dropping when the encoder
    // over-uses its bit rate. This API is designed to be used when the encoded frames
    // are supposed to be stored to an AVI file, or when the I420 codec is used and the
    // target bit rate shouldn't affect the frame rate.
    //
    // Input:
    //      - enable            : True to enable the setting, false to disable it.
    //
    // Return value      : VCM_OK, on success.
    //                     < 0,         on error.
    virtual WebRtc_Word32 EnableFrameDropper(bool enable) = 0;

    // Sent frame counters
    virtual WebRtc_Word32 SentFrameCount(VCMFrameCount& frameCount) const = 0;

    /*
    *   Receiver
    */

    // The receiver state of the VCM will be initialized to the
    // same state as when the VCM was created. This will not interrupt
    // or effect the send side functionality of VCM. VCM will lose all the
    // decoding-related settings by calling this function. All frames
    // inside the jitter buffer are flushed and the delay is reset.
    // For instance, a receive codec has to be registered again.
    //
    // Return value      : VCM_OK, on success.
    //                     < 0,         on error.
    virtual WebRtc_Word32 InitializeReceiver() = 0;

    // Register possible receive codecs, can be called multiple times for different codecs.
    // The module will automatically switch between registered codecs depending on the
    // payload type of incoming frames. The actual decoder will be created when needed.
    //
    // Input:
    //      - receiveCodec      : Settings for the codec to be registered.
    //      - numberOfCores     : Number of CPU cores that the decoder is allowed to use.
    //      - requireKeyFrame   : Set this to true if you don't want any delta frames
    //                            to be decoded until the first key frame has been decoded.
    //
    // Return value      : VCM_OK, on success.
    //                     < 0,         on error.
    virtual WebRtc_Word32 RegisterReceiveCodec(const VideoCodec* receiveCodec,
                                               WebRtc_Word32 numberOfCores,
                                               bool requireKeyFrame = false) = 0;

    // Register an externally defined decoder/renderer object. Can be a decoder only or a
    // decoder coupled with a renderer. Note that RegisterReceiveCodec must be called to
    // be used for decoding incoming streams.
    //
    // Input:
    //      - externalDecoder        : The external decoder/renderer object.
    //      - payloadType            : The payload type which this decoder should be
    //                                 registered to.
    //      - internalRenderTiming   : True if the internal renderer (if any) of the decoder
    //                                 object can make sure to render at a given time in ms.
    //
    // Return value      : VCM_OK, on success.
    //                     < 0,         on error.
    virtual WebRtc_Word32 RegisterExternalDecoder(VideoDecoder* externalDecoder,
                                                  WebRtc_UWord8 payloadType,
                                                  bool internalRenderTiming) = 0;

    // Register a receive callback. Will be called whenever there is a new frame ready
    // for rendering.
    //
    // Input:
    //      - receiveCallback        : The callback object to be used by the module when a
    //                                 frame is ready for rendering.
    //                                 De-register with a NULL pointer.
    //
    // Return value      : VCM_OK, on success.
    //                     < 0,         on error.
    virtual WebRtc_Word32 RegisterReceiveCallback(VCMReceiveCallback* receiveCallback) = 0;

    // Register a receive statistics callback which will be called to deliver information
    // about the video stream received by the receiving side of the VCM, for instance the
    // average frame rate and bit rate.
    //
    // Input:
    //      - receiveStats  : The callback object to register.
    //
    // Return value      : VCM_OK, on success.
    //                     < 0,         on error.
    virtual WebRtc_Word32 RegisterReceiveStatisticsCallback(
                               VCMReceiveStatisticsCallback* receiveStats) = 0;

    // Register a frame type request callback. This callback will be called when the
    // module needs to request specific frame types from the send side.
    //
    // Input:
    //      - frameTypeCallback      : The callback object to be used by the module when
    //                                 requesting a specific type of frame from the send side.
    //                                 De-register with a NULL pointer.
    //
    // Return value      : VCM_OK, on success.
    //                     < 0,         on error.
    virtual WebRtc_Word32 RegisterFrameTypeCallback(
                                  VCMFrameTypeCallback* frameTypeCallback) = 0;

    // Register a frame storage callback. This callback will be called right before an
    // encoded frame is given to the decoder. Useful for recording the incoming video sequence.
    //
    // Input:
    //      - frameStorageCallback    : The callback object used by the module
    //                                  to store a received encoded frame.
    //
    // Return value     : VCM_OK, on success.
    //                    < 0,         on error.
    virtual WebRtc_Word32 RegisterFrameStorageCallback(
                             VCMFrameStorageCallback* frameStorageCallback) = 0;

    // Registers a callback which is called whenever the receive side of the VCM
    // encounters holes in the packet sequence and needs packets to be retransmitted.
    //
    // Input:
    //              - callback      : The callback to be registered in the VCM.
    //
    // Return value     : VCM_OK,     on success.
    //                    <0,              on error.
    virtual WebRtc_Word32 RegisterPacketRequestCallback(
                                        VCMPacketRequestCallback* callback) = 0;

    // Waits for the next frame in the jitter buffer to become complete
    // (waits no longer than maxWaitTimeMs), then passes it to the decoder for decoding.
    // Should be called as often as possible to get the most out of the decoder.
    //
    // Return value      : VCM_OK, on success.
    //                     < 0,         on error.
    virtual WebRtc_Word32 Decode(WebRtc_UWord16 maxWaitTimeMs = 200) = 0;

    // Waits for the next frame in the dual jitter buffer to become complete
    // (waits no longer than maxWaitTimeMs), then passes it to the dual decoder
    // for decoding. This will never trigger a render callback. Should be
    // called frequently, and as long as it returns 1 it should be called again
    // as soon as possible.
    //
    // Return value      : 1,           if a frame was decoded
    //                     0,           if no frame was decoded
    //                     < 0,         on error.
    virtual WebRtc_Word32 DecodeDualFrame(WebRtc_UWord16 maxWaitTimeMs = 200) = 0;

    // Decodes a frame and sets an appropriate render time in ms relative to the system time.
    // Should be used in conjunction with VCMFrameStorageCallback.
    //
    // Input:
    //      - frameFromStorage      : Encoded frame read from file or received through
    //                                the VCMFrameStorageCallback callback.
    //
    // Return value:        : VCM_OK, on success
    //                        < 0,         on error
    virtual WebRtc_Word32 DecodeFromStorage(const EncodedVideoData& frameFromStorage) = 0;

    // Reset the decoder state to the initial state.
    //
    // Return value      : VCM_OK, on success.
    //                     < 0,         on error.
    virtual WebRtc_Word32 ResetDecoder() = 0;

    // API to get the codec which is currently used for decoding by the module.
    //
    // Input:
    //      - currentReceiveCodec      : Settings for the codec to be registered.
    //
    // Return value      : VCM_OK, on success.
    //                     < 0,         on error.
    virtual WebRtc_Word32 ReceiveCodec(VideoCodec* currentReceiveCodec) const = 0;

    // API to get the codec type currently used for decoding by the module.
    //
    // Return value      : codecy type,            on success.
    //                     kVideoCodecUnknown, on error or if no receive codec is registered
    virtual VideoCodecType ReceiveCodec() const = 0;

    // Insert a parsed packet into the receiver side of the module. Will be placed in the
    // jitter buffer waiting for the frame to become complete. Returns as soon as the packet
    // has been placed in the jitter buffer.
    //
    // Input:
    //      - incomingPayload      : Payload of the packet.
    //      - payloadLength        : Length of the payload.
    //      - rtpInfo              : The parsed header.
    //
    // Return value      : VCM_OK, on success.
    //                     < 0,         on error.
    virtual WebRtc_Word32 IncomingPacket(const WebRtc_UWord8* incomingPayload,
                                       WebRtc_UWord32 payloadLength,
                                       const WebRtcRTPHeader& rtpInfo) = 0;

    // Minimum playout delay (Used for lip-sync). This is the minimum delay required
    // to sync with audio. Not included in  VideoCodingModule::Delay()
    // Defaults to 0 ms.
    //
    // Input:
    //      - minPlayoutDelayMs   : Additional delay in ms.
    //
    // Return value      : VCM_OK, on success.
    //                     < 0,         on error.
    virtual WebRtc_Word32 SetMinimumPlayoutDelay(WebRtc_UWord32 minPlayoutDelayMs) = 0;

    // Set the time required by the renderer to render a frame.
    //
    // Input:
    //      - timeMS        : The time in ms required by the renderer to render a frame.
    //
    // Return value      : VCM_OK, on success.
    //                     < 0,         on error.
    virtual WebRtc_Word32 SetRenderDelay(WebRtc_UWord32 timeMS) = 0;

    // The total delay desired by the VCM. Can be less than the minimum
    // delay set with SetMinimumPlayoutDelay.
    //
    // Return value      : Total delay in ms, on success.
    //                     < 0,               on error.
    virtual WebRtc_Word32 Delay() const = 0;

    // Get the received frame counters. Keeps track of the number of each frame type
    // received since the start of the call.
    //
    // Output:
    //      - frameCount      : Struct to be filled with the number of frames received.
    //
    // Return value           : VCM_OK,        on success.
    //                          <0,                 on error.
    virtual WebRtc_Word32 ReceivedFrameCount(VCMFrameCount& frameCount) const = 0;

    // Returns the number of packets discarded by the jitter buffer due to being
    // too late. This can include duplicated packets which arrived after the
    // frame was sent to the decoder. Therefore packets which were prematurely
    // NACKed will be counted.
    virtual WebRtc_UWord32 DiscardedPackets() const = 0;


    // Robustness APIs

    // Set the sender RTX/NACK mode.
    // Input:
    //      - mode       : the selected NACK mode.
    //
    // Return value      : VCM_OK, on success;
    //                     < 0, on error.
    virtual int SetSenderNackMode(SenderNackMode mode) = 0;

    // Set the sender reference picture selection (RPS) mode.
    // Input:
    //      - enable     : true or false, for enable and disable, respectively.
    //
    // Return value      : VCM_OK, on success;
    //                     < 0, on error.
    virtual int SetSenderReferenceSelection(bool enable) = 0;

    // Set the sender forward error correction (FEC) mode.
    // Input:
    //      - enable     : true or false, for enable and disable, respectively.
    //
    // Return value      : VCM_OK, on success;
    //                     < 0, on error.
    virtual int SetSenderFEC(bool enable) = 0;

    // Set the key frame period, or disable periodic key frames (I-frames).
    // Input:
    //      - periodMs   : period in ms; <= 0 to disable periodic key frames.
    //
    // Return value      : VCM_OK, on success;
    //                     < 0, on error.
    virtual int SetSenderKeyFramePeriod(int periodMs) = 0;

    // Set the receiver robustness mode. The mode decides how the receiver
    // responds to losses in the stream. The type of counter-measure (soft or
    // hard NACK, dual decoder, RPS, etc.) is selected through the
    // robustnessMode parameter. The errorMode parameter decides if it is
    // allowed to display frames corrupted by losses. Note that not all
    // combinations of the two parameters are feasible. An error will be
    // returned for invalid combinations.
    // Input:
    //      - robustnessMode : selected robustness mode.
    //      - errorMode      : selected error mode.
    //
    // Return value      : VCM_OK, on success;
    //                     < 0, on error.
    virtual int SetReceiverRobustnessMode(ReceiverRobustness robustnessMode,
                                          DecodeErrors errorMode) = 0;
};

} // namespace webrtc

#endif // WEBRTC_MODULES_INTERFACE_VIDEO_CODING_H_