transcoders.h

Go to the documentation of this file.

/*
 * transcoders.h
 *
 * Abstractions for converting media from one format to another.
 *
 * Open Phone Abstraction Library (OPAL)
 * Formally known as the Open H323 project.
 *
 * Copyright (c) 2001 Equivalence Pty. Ltd.
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.0 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 * the License for the specific language governing rights and limitations
 * under the License.
 *
 * The Original Code is Open Phone Abstraction Library.
 *
 * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
 *
 * Contributor(s): ______________________________________.
 *
 * $Log: transcoders.h,v $
 * Revision 2.29  2007/10/08 01:45:16  rjongbloed
 * Fixed bad virtual function causing uninitialised variable whcih prevented video from working.
 * Some more clean ups.
 *
 * Revision 2.28  2007/09/19 10:43:00  csoutheren
 * Exposed G.7231 capability class
 * Added macros to create empty transcoders and capabilities
 *
 * Revision 2.27  2007/09/10 03:15:04  rjongbloed
 * Fixed issues in creating and subsequently using correctly unique
 *   payload types in OpalMediaFormat instances and transcoders.
 *
 * Revision 2.26  2007/06/22 05:47:19  rjongbloed
 * Fixed setting of output RTP payload types on plug in video codecs.
 *
 * Revision 2.25  2007/03/29 05:22:32  csoutheren
 * Add extra logging
 *
 * Revision 2.24  2006/11/29 06:28:57  csoutheren
 * Add ability call codec control functions on all transcoders
 *
 * Revision 2.23  2006/04/09 12:12:54  rjongbloed
 * Changed the media format option merging to include the transcoder formats.
 *
 * Revision 2.22  2006/02/02 07:02:57  csoutheren
 * Added RTP payload map to transcoders and connections to allow remote SIP endpoints
 * to change the payload type used for outgoing RTP.
 *
 * Revision 2.21  2005/12/30 14:33:12  dsandras
 * Added support for Packet Loss Concealment frames for framed codecs supporting it similarly to what was done for OpenH323.
 *
 * Revision 2.20  2005/11/30 13:35:26  csoutheren
 * Changed tags for Doxygen
 *
 * Revision 2.19  2005/09/06 12:44:49  rjongbloed
 * Many fixes to finalise the video processing: merging remote media
 *
 * Revision 2.18  2005/09/04 06:23:38  rjongbloed
 * Added OpalMediaCommand mechanism (via PNotifier) for media streams
 *   and media transcoders to send commands back to remote.
 *
 * Revision 2.17  2005/09/02 14:31:40  csoutheren
 * Use inline function to work around compiler foo in gcc
 *
 * Revision 2.16  2005/08/31 13:19:25  rjongbloed
 * Added mechanism for controlling media (especially codecs) including
 *   changing the OpalMediaFormat option list (eg bit rate) and a completely
 *   new OpalMediaCommand abstraction for things like video fast update.
 *
 * Revision 2.15  2005/08/28 07:59:17  rjongbloed
 * Converted OpalTranscoder to use factory, requiring sme changes in making sure
 *   OpalMediaFormat instances are initialised before use.
 *
 * Revision 2.14  2005/03/19 04:08:10  csoutheren
 * Fixed warnings with gcc snapshot 4.1-20050313
 * Updated to configure 2.59
 *
 * Revision 2.13  2005/02/17 03:25:05  csoutheren
 * Added support for audio codecs that consume and produce variable size
 * frames, such as G.723.1
 *
 * Revision 2.12  2004/07/11 12:34:48  rjongbloed
 * Added function to get a list of all possible media formats that may be used given
 *   a list of media and taking into account all of the registered transcoders.
 *
 * Revision 2.11  2004/03/22 11:32:41  rjongbloed
 * Added new codec type for 16 bit Linear PCM as must distinguish between the internal
 *   format used by such things as the sound card and the RTP payload format which
 *   is always big endian.
 *
 * Revision 2.10  2004/03/11 06:54:27  csoutheren
 * Added ability to disable SIP or H.323 stacks
 *
 * Revision 2.9  2004/02/17 08:47:38  csoutheren
 * Changed codec loading macros to work with Linux
 *
 * Revision 2.8  2004/01/18 15:35:20  rjongbloed
 * More work on video support
 *
 * Revision 2.7  2003/06/02 02:59:43  rjongbloed
 * Changed transcoder search so uses destination list as preference order.
 *
 * Revision 2.6  2003/03/24 04:32:11  robertj
 * Fixed macro for transcoder with parameter (not used yet!)
 * Fixed so OPAL_NO_PARAM can be defined in other modules.
 *
 * Revision 2.5  2003/03/17 10:26:59  robertj
 * Added video support.
 *
 * Revision 2.4  2002/09/16 02:52:35  robertj
 * Added #define so can select if #pragma interface/implementation is used on
 *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
 *
 * Revision 2.3  2002/02/13 02:30:21  robertj
 * Added ability for media patch (and transcoders) to handle multiple RTP frames.
 *
 * Revision 2.2  2002/01/22 05:07:02  robertj
 * Added ability to get input and output media format names from transcoder.
 *
 * Revision 2.1  2001/08/01 05:52:08  robertj
 * Made OpalMediaFormatList class global to help with documentation.
 * Added functions to aid in determining if a transcoder can be used to get
 *   to another media format.
 * Fixed problem with streamed transcoder used in G.711.
 *
 * Revision 2.0  2001/07/27 15:48:24  robertj
 * Conversion of OpenH323 to Open Phone Abstraction Library (OPAL)
 *
 */

#ifndef __OPAL_TRANSCODERS_H
#define __OPAL_TRANSCODERS_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#include <opal/buildopts.h>

#include <opal/mediafmt.h>
#include <opal/mediacmd.h>

#include <rtp/rtp.h>

class RTP_DataFrame;
class OpalTranscoder;



class OpalMediaFormatPair : public PObject
{
    PCLASSINFO(OpalMediaFormatPair, PObject);
  public:
    OpalMediaFormatPair(
      const OpalMediaFormat & inputMediaFormat,  
      const OpalMediaFormat & outputMediaFormat  
    );

    void PrintOn(
      ostream & strm    
    ) const;

    virtual Comparison Compare(
      const PObject & obj   
    ) const;

    const OpalMediaFormat & GetInputFormat() const { return inputMediaFormat; }

    const OpalMediaFormat & GetOutputFormat() const { return outputMediaFormat; }

  protected:
    OpalMediaFormat inputMediaFormat;
    OpalMediaFormat outputMediaFormat;
};


typedef std::pair<PString, PString>                                      OpalTranscoderKey;
typedef PFactory<OpalTranscoder, OpalTranscoderKey>                      OpalTranscoderFactory;
typedef PFactory<OpalTranscoder, OpalTranscoderKey>::KeyList_T           OpalTranscoderList;
typedef PFactory<OpalTranscoder, OpalTranscoderKey>::KeyList_T::iterator OpalTranscoderIterator;

#define OPAL_REGISTER_TRANSCODER(cls, input, output) \
  OpalTranscoderFactory::Worker<cls> OpalTranscoder_##cls(OpalTranscoderKey(input, output))


class OpalTranscoder : public OpalMediaFormatPair
{
    PCLASSINFO(OpalTranscoder, OpalMediaFormatPair);
  public:
    OpalTranscoder(
      const OpalMediaFormat & inputMediaFormat,  
      const OpalMediaFormat & outputMediaFormat  
    );

    virtual BOOL UpdateOutputMediaFormat(
      const OpalMediaFormat & mediaFormat  
    );

    virtual BOOL ExecuteCommand(
      const OpalMediaCommand & command    
    );

    virtual PINDEX GetOptimalDataFrameSize(
      BOOL input      
    ) const = 0;

    virtual BOOL ConvertFrames(
      const RTP_DataFrame & input,  
      RTP_DataFrameList & output    
    );

    virtual BOOL Convert(
      const RTP_DataFrame & input,  
      RTP_DataFrame & output        
    ) = 0;

    static OpalTranscoder * Create(
      const OpalMediaFormat & srcFormat,  
      const OpalMediaFormat & dstFormat,  
      const BYTE * instance = NULL,       
      unsigned instanceLen = 0            
    );

    static BOOL SelectFormats(
      unsigned sessionID,               
      const OpalMediaFormatList & srcFormats, 
      const OpalMediaFormatList & dstFormats, 
      OpalMediaFormat & srcFormat,      
      OpalMediaFormat & dstFormat       
    );

    static BOOL FindIntermediateFormat(
      OpalMediaFormat & srcFormat,          
      OpalMediaFormat & dstFormat,          
      OpalMediaFormat & intermediateFormat  
    );

    static OpalMediaFormatList GetDestinationFormats(
      const OpalMediaFormat & srcFormat    
    );

    static OpalMediaFormatList GetSourceFormats(
      const OpalMediaFormat & dstFormat    
    );

    static OpalMediaFormatList GetPossibleFormats(
      const OpalMediaFormatList & formats    
    );

    PINDEX GetMaxOutputSize() const { return maxOutputSize; }

    void SetMaxOutputSize(
      PINDEX size
    ) { maxOutputSize = size; }

    void SetCommandNotifier(
      const PNotifier & notifier    
    ) { commandNotifier = notifier; }

    const PNotifier & GetCommandNotifier() const { return commandNotifier; }

    virtual void SetInstanceID(
      const BYTE * instance,              
      unsigned instanceLen                
    );

    void SetRTPPayloadMap(const RTP_DataFrame::PayloadMapType & v)
    { payloadTypeMap = v; }

    void AddRTPPayloadMapping(RTP_DataFrame::PayloadTypes from, RTP_DataFrame::PayloadTypes to)
    { payloadTypeMap.insert(RTP_DataFrame::PayloadMapType::value_type(from, to)); }

    RTP_DataFrame::PayloadTypes GetPayloadType(
      BOOL input      
    ) const;

  protected:
    PINDEX    maxOutputSize;
    bool      outputMediaFormatUpdated;
    PNotifier commandNotifier;
    PMutex    updateMutex;

    RTP_DataFrame::PayloadMapType payloadTypeMap;

    BOOL outputIsRTP, inputIsRTP;
};


class OpalFramedTranscoder : public OpalTranscoder
{
    PCLASSINFO(OpalFramedTranscoder, OpalTranscoder);
  public:
    OpalFramedTranscoder(
      const OpalMediaFormat & inputMediaFormat,  
      const OpalMediaFormat & outputMediaFormat, 
      PINDEX inputBytesPerFrame,  
      PINDEX outputBytesPerFrame  
    );

    virtual PINDEX GetOptimalDataFrameSize(
      BOOL input      
    ) const;

    virtual BOOL Convert(
      const RTP_DataFrame & input,  
      RTP_DataFrame & output        
    );

    virtual BOOL ConvertFrame(
      const BYTE * input,   
      BYTE * output         
    );
    virtual BOOL ConvertFrame(
      const BYTE * input,   
      PINDEX & consumed,    
      BYTE * output,        
      PINDEX & created      
    );
    virtual BOOL ConvertSilentFrame(
      BYTE * output         
    );

  protected:
    PINDEX     inputBytesPerFrame;
    PINDEX     outputBytesPerFrame;
    //PBYTEArray partialFrame;
    //PINDEX     partialBytes;
};


class OpalStreamedTranscoder : public OpalTranscoder
{
    PCLASSINFO(OpalStreamedTranscoder, OpalTranscoder);
  public:
    OpalStreamedTranscoder(
      const OpalMediaFormat & inputMediaFormat,  
      const OpalMediaFormat & outputMediaFormat, 
      unsigned inputBits,           
      unsigned outputBits,          
      PINDEX   optimalSamples       
    );

    virtual PINDEX GetOptimalDataFrameSize(
      BOOL input      
    ) const;

    virtual BOOL Convert(
      const RTP_DataFrame & input,  
      RTP_DataFrame & output        
    );

    virtual int ConvertOne(int sample) const = 0;

  protected:
    unsigned inputBitsPerSample;
    unsigned outputBitsPerSample;
    PINDEX   optimalSamples;
};



class Opal_Linear16Mono_PCM : public OpalStreamedTranscoder {
  public:
    Opal_Linear16Mono_PCM();
    virtual int ConvertOne(int sample) const;
};



class Opal_PCM_Linear16Mono : public OpalStreamedTranscoder {
  public:
    Opal_PCM_Linear16Mono();
    virtual int ConvertOne(int sample) const;
};



#define OPAL_REGISTER_L16_MONO() \
  OPAL_REGISTER_TRANSCODER(Opal_Linear16Mono_PCM, OpalL16_MONO_8KHZ, OpalPCM16); \
  OPAL_REGISTER_TRANSCODER(Opal_PCM_Linear16Mono, OpalPCM16,         OpalL16_MONO_8KHZ)


class OpalEmptyFramedAudioTranscoder : public OpalFramedTranscoder
{
  PCLASSINFO(OpalEmptyFramedAudioTranscoder, OpalFramedTranscoder);
  public:
    OpalEmptyFramedAudioTranscoder(const char * inFormat, const char * outFormat)
      : OpalFramedTranscoder(inFormat, outFormat, 100, 100)
    {  }

    BOOL ConvertFrame(const BYTE *, PINDEX &, BYTE *, PINDEX &)
    { return FALSE; }
};

#define OPAL_DECLARE_EMPTY_TRANSCODER(fmt) \
class Opal_Empty_##fmt##_Encoder : public OpalEmptyFramedAudioTranscoder \
{ \
  public: \
    Opal_Empty_##fmt##_Encoder() \
      : OpalEmptyFramedAudioTranscoder(OpalPCM16, fmt) \
    { } \
}; \
class Opal_Empty_##fmt##_Decoder : public OpalEmptyFramedAudioTranscoder \
{ \
  public: \
    Opal_Empty_##fmt##_Decoder() \
      : OpalEmptyFramedAudioTranscoder(fmt, OpalPCM16) \
    { } \
}; \

#define OPAL_DEFINE_EMPTY_TRANSCODER(fmt) \
OPAL_REGISTER_TRANSCODER(Opal_Empty_##fmt##_Encoder, OpalPCM16, fmt); \
OPAL_REGISTER_TRANSCODER(Opal_Empty_##fmt##_Decoder, fmt,       OpalPCM16); \

#endif // __OPAL_TRANSCODERS_H


// End of File ///////////////////////////////////////////////////////////////

---