Source: encoderinterface.h


Annotated List
Files
Globals
Hierarchy
Index
// ##########################################################################
// ####                                                                  ####
// ####                      RTP Audio Server Project                    ####
// ####                    ============================                  ####
// ####                                                                  ####
// #### Encoder Interface                                                ####
// ####                                                                  ####
// #### Version 1.00  --  February 04, 2001                              ####
// ####                                                                  ####
// #### Copyright (C) 1999  Thomas Dreibholz                             ####
// ####               2000  Universität Bonn, Abt. IV                    ####
// ####               2001  EMail: Dreibholz@bigfoot.com                 ####
// ####                     WWW:   http://www.bigfoot.com/~dreibholz     ####
// ####                                                                  ####
// ##########################################################################


#ifndef ENCODERINTERFACE_H
#define ENCODERINTERFACE_H


#include "system.h"
#include "range.h"
#ifdef USE_TRANSPORTINFO
#include "transportinfo.h"
#else
#include "abstractqosdescription.h"
#endif


namespace Coral {


/**
  * This structure contains packet information for getNextPacket() call.
  *
  * @short   EncoderPacket
  * @author  Thomas Dreibholz (Dreibholz@bigfoot.com)
  * @version 1.0
  */
struct EncoderPacket
{
   /**
     * Buffer to write packet payload into.
     */
   void* Buffer;

   /**
     * Maximum length of payload to be written into Buffer.
     */
   cardinal MaxLength;

   /**
     * The packet's layer number, to be set within getNextPacket().
     */
   cardinal Layer;

   /**
     * The packet's payload type, to be set within getNextPacket().
     */
   card8 PayloadType;

   /**
     * The packet's marker, to be set within getNextPacket().
     */
   bool Marker;

   /**
     * The packet's error code. If greater than ME_UnrecoverableError,
     * the packet may sent even in case of exceeded traffic shaper buffer!
     */
   card8 ErrorCode;
};



/**
  * This class is the interface for an encoder.
  *
  * @short   Encoder Interface
  * @author  Thomas Dreibholz (Dreibholz@bigfoot.com)
  * @version 1.0
  */
class EncoderInterface
{
   // ====== Destructor =====================================================
   public:
   /**
     * Virtual destructor.
     */
   virtual ~EncoderInterface();


   // ====== Encoder type ===================================================
   /**
     * Get the encoder's type ID.
     *
     * @return Encoder's type ID.
     */
   virtual const card16 getTypeID() const = 0;
   
   /**
     * Get the encoder's name.
     *
     * @return Encoder's name
     */
   virtual const char* getTypeName() const = 0;


   // ====== Initialization/Clean-up ========================================
   /**
     * Activate the encoder.
     * Usage example: Start an encoder thread.
     */
   virtual void activate() = 0;
   
   /**
     * Deactivate the encoder.
     * Usage example: Stop an encoder thread.
     */
   virtual void deactivate() = 0;
   
   /**
     * Reset the encoder.
     * Usage example: Reset an encoder thread.
     */
   virtual void reset() = 0;


   // ====== Encode frame ===================================================
#ifndef USE_TRANSPORTINFO
   /**
     * Check, when prepareNextFrame() call reaches a new interval().
     *
     * @param time Reference to store time to next interval in microseconds.
     * @param Reference to store true, if new resource/utilization list has been reached since last call; false otherwise.
     * @return true, if new interval has been reached since last call; false otherwise.
     */
   virtual bool checkInterval(card64& time, bool& newRUList) = 0;
#endif


   /**
     * Prepare next frame.
     * Usage example: Read the next frame from file, transform it into
     * packages for transport.
     *
     * @param headerSize Size of underlying protocol's header (e.g. RTP packet)
     * @param maxPacketSize Maximum size of packet.
     * @param flags Encoder-specific flags (e.g. compression or encryption).
     * @return true, if there was a next frame; false, if not.
     */
   virtual bool prepareNextFrame(const cardinal headerSize,
                                 const cardinal maxPacketSize,
                                 const cardinal flags = 0) = 0;

   /**
     * Get next packet from current frame. The maximum payload length of the
     * packet (the size of packet->Buffer) is in packet->MaxLength.
     *
     * @param packet EncoderPacket structure.
     * @param buffer Buffer of the packet to write the data into.
     * @param maxLength Maximum length of the packet
     * @return Real length of the data written into the buffer or 0, if there is no more data of the current frame.
     */
   virtual cardinal getNextPacket(EncoderPacket* packet) = 0;


   // ====== Settings =======================================================
#ifdef USE_TRANSPORTINFO

   /**
     * Get TransportInfo for encoding.
     *
     * @param transportInfo Pointer to TransportInfo.
     * @param headerSize Size of underlying protocol's header (e.g. RTP packet)
     * @param maxPacketSize Maximum size of packet.
     * @param calculateLevels true to calculate all level constants; false otherwise.
     *
     * Note: maxPacketSize gives the total size of the packet. The size
     * usable by the encoder is maxPacketSize - headerSize!
     */
   virtual void getTransportInfo(TransportInfo& transportInfo,
                                 const cardinal headerSize,
                                 const cardinal maxPacketSize,
                                 const bool     calculateLevels = true) const = 0;

   /**
     * Set TransportInfo for encoding.
     *
     * @param transportInfo Pointer to TransportInfo.
     * @param headerSize Size of underlying protocol's header (e.g. RTP packet)
     * @param maxPacketSize Maximum size of packet.
     * @param calculateLevels true to calculate all level constants; false otherwise.
     *
     * Note 1: setTransportInfo() may adapt the settings in transportInfo
     * to fit the encoding's requirements. The corrected settings are returned
     * in transportInfo!
     *
     * Note 2: maxPacketSize gives the total size of the packet. The size
     * usable by the encoder is maxPacketSize - headerSize!
     */
   virtual void setTransportInfo(TransportInfo& transportInfo,
                                 const cardinal headerSize,
                                 const cardinal maxPacketSize,
                                 const bool     calculateLevels = true) = 0;

   /**
     * Adapt the quality of the transmission.
     * Usage example: Reduce audio quality, if too many packets are lost.
     *
     * @param fractionLost Fraction of the packets lost.
     * @param layer Layer number.
     */
   virtual void adaptQuality(const double   fractionLost,
                             const cardinal layer) = 0;

#else

   /**
     * Get QoS description. Important note: This result is a global pointer,
     * it becomes invalid when encoder is deleted!
     *
     * @param pktHeaderSize Packet header size.
     * @param pktMaxSize Maximum packet size.
     * @param offset RTP position offset.
     * @return QoS Description.
     */
   virtual AbstractQoSDescription* getQoSDescription(
                                      const cardinal pktHeaderSize,
                                      const cardinal pktMaxSize,
                                      const card64   offset) = 0;

   /**
     * Update encoder quality to changes made in QoS description returned
     * by getQoSDescription().
     *
     * @see EncoderInterface#getQoSDescription
     */
   virtual void updateQuality(const AbstractQoSDescription* aqd) = 0;

#endif
};


}


#endif

Generated by: viper@odin on Sun Feb 4 18:54:51 2001, using kdoc 2.0a22.