home *** CD-ROM | disk | FTP | other *** search
/ ftp.muug.mb.ca / 2014.06.ftp.muug.mb.ca.tar / ftp.muug.mb.ca / pub / openh323.tar.gz / openh323.tar / openh323 / include / codecs.h < prev    next >
Text File  |  2003-07-16  |  38KB  |  1,062 lines
  1. /*
  2.  * codecs.h
  3.  *
  4.  * H.323 protocol handler
  5.  *
  6.  * Open H323 Library
  7.  *
  8.  * Copyright (c) 1998-2000 Equivalence Pty. Ltd.
  9.  *
  10.  * The contents of this file are subject to the Mozilla Public License
  11.  * Version 1.0 (the "License"); you may not use this file except in
  12.  * compliance with the License. You may obtain a copy of the License at
  13.  * http://www.mozilla.org/MPL/
  14.  *
  15.  * Software distributed under the License is distributed on an "AS IS"
  16.  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
  17.  * the License for the specific language governing rights and limitations
  18.  * under the License.
  19.  *
  20.  * The Original Code is Open H323 Library.
  21.  *
  22.  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
  23.  *
  24.  * Portions of this code were written with the assisance of funding from
  25.  * Vovida Networks, Inc. http://www.vovida.com.
  26.  *
  27.  * Contributor(s): ______________________________________.
  28.  *
  29.  * $Log: codecs.h,v $
  30.  * Revision 1.68  2003/07/16 10:43:12  csoutheren
  31.  * Added SwapChannel function to H323Codec to allow media hold channels
  32.  * to work better. Thanks to Federico Pinna
  33.  *
  34.  * Revision 1.67  2003/05/27 09:39:15  dereksmithies
  35.  * Add frames per sec variable to the videocodec class
  36.  *
  37.  * Revision 1.66  2002/12/16 09:11:15  robertj
  38.  * Added new video bit rate control, thanks Walter H. Whitlock
  39.  *
  40.  * Revision 1.65  2002/09/16 01:14:15  robertj
  41.  * Added #define so can select if #pragma interface/implementation is used on
  42.  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
  43.  *
  44.  * Revision 1.64  2002/08/05 10:03:47  robertj
  45.  * Cosmetic changes to normalise the usage of pragma interface/implementation.
  46.  *
  47.  * Revision 1.63  2002/01/23 06:13:52  robertj
  48.  * Added filter function hooks to codec raw data channel.
  49.  *
  50.  * Revision 1.62  2002/01/23 01:58:25  robertj
  51.  * Added function to determine if codecs raw data channel is native format.
  52.  *
  53.  * Revision 1.61  2002/01/22 16:17:19  rogerh
  54.  * Back out the DTMF Decoder class. There will soon be a better way
  55.  * to do this.
  56.  *
  57.  * Revision 1.60  2002/01/22 16:09:38  rogerh
  58.  * Back out the DTMF detection from H323FramedAudioCodec::Write().
  59.  * There will shortly be a better place for it.
  60.  *
  61.  * Revision 1.59  2002/01/22 15:21:47  rogerh
  62.  * Add DTMF decoding to PCM audio streams. This has been tested with
  63.  * NetMeeting sending Dial Pad codes, using the G.711 codec.
  64.  * At this time, DTMF codes (fron NetMeeting) are just displayed on the
  65.  * screen and are not passed up to the users application.
  66.  *
  67.  * Revision 1.58  2002/01/13 23:56:01  robertj
  68.  * Added mutex so can change raw data channel while reading/writing from codec.
  69.  *
  70.  * Revision 1.57  2001/12/04 05:13:09  robertj
  71.  * Added videa bandwidth limiting code for H.261, thanks Jose Luis Urien.
  72.  *
  73.  * Revision 1.56  2001/11/16 01:05:21  craigs
  74.  * Changed to allow access to uLaw/ALaw to/from linear functions
  75.  *
  76.  * Revision 1.55  2001/10/23 02:18:06  dereks
  77.  * Initial release of CU30 video codec.
  78.  *
  79.  * Revision 1.54  2001/09/25 03:14:47  dereks
  80.  * Add constant bitrate control for the h261 video codec.
  81.  * Thanks Tiziano Morganti for the code to set bit rate. Good work!
  82.  *
  83.  * Revision 1.53  2001/09/11 01:24:36  robertj
  84.  * Added conditional compilation to remove video and/or audio codecs.
  85.  *
  86.  * Revision 1.52  2001/08/28 09:27:38  robertj
  87.  * Updated documentation to reflect some relationships between functions.
  88.  *
  89.  * Revision 1.51  2001/03/29 23:44:35  robertj
  90.  * Added ability to get current silence detect state and threshold.
  91.  * Changed silence detection to use G.723.1 SID frames as indicator of
  92.  *   silence instead of using the average energy and adaptive threshold.
  93.  * Changed default signal on deadband time to be much shorter.
  94.  *
  95.  * Revision 1.50  2001/02/09 05:16:24  robertj
  96.  * Added #pragma interface for GNU C++.
  97.  *
  98.  * Revision 1.49  2001/01/25 07:27:14  robertj
  99.  * Major changes to add more flexible OpalMediaFormat class to normalise
  100.  *   all information about media types, especially codecs.
  101.  *
  102.  * Revision 1.48  2000/12/19 22:33:44  dereks
  103.  * Adjust so that the video channel is used for reading/writing raw video
  104.  * data, which better modularizes the video codec.
  105.  *
  106.  * Revision 1.47  2000/10/13 01:47:26  dereks
  107.  * Include command option for setting the number of transmitted video
  108.  * frames per second.   use --videotxfps n
  109.  *
  110.  * Revision 1.46  2000/09/08 06:41:37  craigs
  111.  * Added ability to set video device
  112.  * Added ability to select test input frames
  113.  *
  114.  * Revision 1.45  2000/08/31 08:15:32  robertj
  115.  * Added support for dynamic RTP payload types in H.245 OpenLogicalChannel negotiations.
  116.  *
  117.  * Revision 1.44  2000/08/21 04:45:06  dereks
  118.  * Fix dangling pointer that caused segfaults for windows&unix users.
  119.  * Improved the test image which is used when video grabber won't open.
  120.  * Added code to handle setting of video Tx Quality.
  121.  * Added code to set the number of background blocks sent with every frame.
  122.  *
  123.  * Revision 1.43  2000/05/16 02:04:16  craigs
  124.  * Added access functions for silence compression mode
  125.  *
  126.  * Revision 1.42  2000/05/02 04:32:24  robertj
  127.  * Fixed copyright notice comment.
  128.  *
  129.  * Revision 1.41  2000/04/14 20:11:16  robertj
  130.  * Removed redundent member variable from H323FramedAudioCodec.
  131.  *
  132.  * Revision 1.40  2000/03/30 23:10:50  robertj
  133.  * Fixed error in comments regarding GetFramerate() function.
  134.  *
  135.  * Revision 1.39  2000/03/21 03:06:47  robertj
  136.  * Changes to make RTP TX of exact numbers of frames in some codecs.
  137.  *
  138.  * Revision 1.38  2000/02/28 13:00:22  robertj
  139.  * Added some virtual keywords at the request of Yura Ershov
  140.  *
  141.  * Revision 1.37  2000/02/10 03:08:02  craigs
  142.  * Added ability to specify NTSC or PAL video format
  143.  *
  144.  * Revision 1.36  2000/02/04 05:00:08  craigs
  145.  * Changes for video transmission
  146.  *
  147.  * Revision 1.35  2000/01/13 04:03:45  robertj
  148.  * Added video transmission
  149.  *
  150.  * Revision 1.34  1999/12/31 00:05:36  robertj
  151.  * Added Microsoft ACM G.723.1 codec capability.
  152.  *
  153.  * Revision 1.33  1999/12/29 01:19:16  craigs
  154.  * Fixed problem with RTP payload type variable
  155.  *
  156.  * Revision 1.32  1999/12/23 23:02:34  robertj
  157.  * File reorganision for separating RTP from H.323 and creation of LID for VPB support.
  158.  *
  159.  * Revision 1.31  1999/11/29 09:01:46  craigs
  160.  * Added new code for new video code interface
  161.  *
  162.  * Revision 1.30  1999/11/29 04:50:11  robertj
  163.  * Added adaptive threshold calculation to silence detection.
  164.  *
  165.  * Revision 1.29  1999/11/20 00:53:46  robertj
  166.  * Fixed ability to have variable sized frames in single RTP packet under G.723.1
  167.  *
  168.  * Revision 1.28  1999/11/13 14:10:32  robertj
  169.  * Changes to make silence detection selectable.
  170.  *
  171.  * Revision 1.27  1999/11/11 23:28:52  robertj
  172.  * Added first cut silence detection algorithm.
  173.  *
  174.  * Revision 1.26  1999/11/04 00:43:42  robertj
  175.  * Added extra constructors for nonStandard codecs.
  176.  *
  177.  * Revision 1.25  1999/10/14 12:03:08  robertj
  178.  * Fixed comment.
  179.  *
  180.  * Revision 1.24  1999/10/08 09:59:01  robertj
  181.  * Rewrite of capability for sending multiple audio frames
  182.  *
  183.  * Revision 1.23  1999/10/08 04:58:37  robertj
  184.  * Added capability for sending multiple audio frames in single RTP packet
  185.  *
  186.  * Revision 1.22  1999/09/23 07:25:12  robertj
  187.  * Added open audio and video function to connection and started multi-frame codec send functionality.
  188.  *
  189.  * Revision 1.21  1999/09/21 14:51:33  robertj
  190.  * Fixed NonStandardCapabilityInfo class virtual destructor (and name).
  191.  *
  192.  * Revision 1.20  1999/09/21 14:04:41  robertj
  193.  * Added non-standard codec capability classes
  194.  *
  195.  * Revision 1.19  1999/09/21 08:12:49  craigs
  196.  * Added support for video codecs and H261
  197.  *
  198.  * Revision 1.18  1999/09/18 13:27:24  craigs
  199.  * Added ability disable jitter buffer for codecs
  200.  * Added ability to access entire RTP frame from codec Write
  201.  *
  202.  * Revision 1.17  1999/09/08 04:05:48  robertj
  203.  * Added support for video capabilities & codec, still needs the actual codec itself!
  204.  *
  205.  * Revision 1.16  1999/08/31 12:34:18  robertj
  206.  * Added gatekeeper support.
  207.  *
  208.  * Revision 1.15  1999/08/25 03:08:23  robertj
  209.  * Added UserInput capability.
  210.  * Allowed the attachment of a channel on a codec to optionally delete the channel object,
  211.  *
  212.  * Revision 1.14  1999/07/22 14:32:48  robertj
  213.  * Fixed erroneous comments
  214.  *
  215.  * Revision 1.13  1999/07/16 16:05:48  robertj
  216.  * Added "human readable" codec type name display.
  217.  *
  218.  * Revision 1.12  1999/07/15 14:45:35  robertj
  219.  * Added propagation of codec open error to shut down logical channel.
  220.  * Fixed control channel start up bug introduced with tunnelling.
  221.  *
  222.  * Revision 1.11  1999/07/13 09:53:24  robertj
  223.  * Fixed some problems with jitter buffer and added more debugging.
  224.  *
  225.  * Revision 1.10  1999/07/09 06:09:49  robertj
  226.  * Major implementation. An ENORMOUS amount of stuff added everywhere.
  227.  *
  228.  * Revision 1.9  1999/06/24 13:32:45  robertj
  229.  * Fixed ability to change sound device on codec and fixed NM3 G.711 compatibility
  230.  *
  231.  * Revision 1.8  1999/06/22 13:49:40  robertj
  232.  * Added GSM support and further RTP protocol enhancements.
  233.  *
  234.  * Revision 1.7  1999/06/14 15:08:40  robertj
  235.  * Added GSM codec class frame work (still no actual codec).
  236.  *
  237.  * Revision 1.6  1999/06/14 06:39:08  robertj
  238.  * Fixed problem with getting transmit flag to channel from PDU negotiator
  239.  *
  240.  * Revision 1.5  1999/06/14 05:15:55  robertj
  241.  * Changes for using RTP sessions correctly in H323 Logical Channel context
  242.  *
  243.  * Revision 1.4  1999/06/13 12:41:14  robertj
  244.  * Implement logical channel transmitter.
  245.  * Fixed H245 connect on receiving call.
  246.  *
  247.  * Revision 1.3  1999/06/09 05:26:19  robertj
  248.  * Major restructuring of classes.
  249.  *
  250.  * Revision 1.2  1999/06/06 06:06:36  robertj
  251.  * Changes for new ASN compiler and v2 protocol ASN files.
  252.  *
  253.  * Revision 1.1  1999/01/16 01:31:01  robertj
  254.  * Initial revision
  255.  *
  256.  */
  257.  
  258. #ifndef __CODECS_H
  259. #define __CODECS_H
  260.  
  261. #ifdef P_USE_PRAGMA
  262. #pragma interface
  263. #endif
  264.  
  265.  
  266. #include <mediafmt.h>
  267. #include <rtp.h>
  268. #include <channels.h>
  269.  
  270. /* The following classes have forward references to avoid including the VERY
  271.    large header files for H225 and H245. If an application requires access
  272.    to the protocol classes they can include them, but for simple usage their
  273.    inclusion can be avoided.
  274.  */
  275. class H245_MiscellaneousCommand_type;
  276. class H245_MiscellaneousIndication_type;
  277. class H323Connection;
  278.  
  279.  
  280.  
  281. ///////////////////////////////////////////////////////////////////////////////
  282.  
  283. /**This class embodies the implementation of a specific codec instance
  284.    used to transfer data via the logical channels opened and managed by the
  285.    H323 control channel.
  286.  
  287.    An application may create a descendent off this class and override
  288.    functions as required for descibing a codec.
  289.  */
  290. class H323Codec : public PObject
  291. {
  292.   PCLASSINFO(H323Codec, PObject);
  293.  
  294.   public:
  295.     enum Direction {
  296.       Encoder,
  297.       Decoder
  298.     };
  299.  
  300.     H323Codec(
  301.       const char * mediaFormat, /// Media format for codec
  302.       Direction direction       /// Direction in which this instance runs
  303.     );
  304.  
  305.  
  306.     /**Open the codec.
  307.        This will open the codec for encoding or decoding, it is called after
  308.        the logical channel have been established and the background threads to
  309.        drive them have been started. This is primarily used to delay allocation
  310.        of resources until the last millisecond.
  311.  
  312.        A descendent class may be created by the application and it may cast
  313.        the connection parameter to the application defined descendent of 
  314.        H323Connection to obtain information needed to open the codec.
  315.  
  316.        The default behaviour does nothing.
  317.       */
  318.     virtual BOOL Open(
  319.       H323Connection & connection /// Connection between the endpoints
  320.     );
  321.  
  322.     /**Close the codec.
  323.       */
  324.     virtual void Close() = 0;
  325.  
  326.     /**Encode the data from the appropriate device.
  327.        This will encode data for transmission. The exact size and description
  328.        of the data placed in the buffer is codec dependent but should be less
  329.        than OpalMediaFormat::GetFrameSize() in length.
  330.  
  331.        The length parameter is filled with the actual length of the encoded
  332.        data, often this will be the same as OpalMediaFormat::GetFrameSize().
  333.  
  334.        This function is called every GetFrameRate() timestamp units, so MUST
  335.        take less than (or equal to) that amount of time to complete. It
  336.        should always return the amount of data that corresponds to the
  337.        GetFrameRate() timestamp units as well.
  338.  
  339.        A returned length of zero indicates that time has passed but there is
  340.        no data encoded. This is typically used for silence detection in an
  341.        audio codec.
  342.      */
  343.     virtual BOOL Read(
  344.       BYTE * buffer,            /// Buffer of encoded data
  345.       unsigned & length,        /// Actual length of encoded data buffer
  346.       RTP_DataFrame & rtpFrame  /// RTP data frame
  347.     ) = 0;
  348.  
  349.     /**Decode the data and output it to appropriate device.
  350.        This will decode a single frame of received data. The exact size and
  351.        description of the data required in the buffer is codec dependent but
  352.        should be at least than OpalMediaFormat::GetFrameSize() in length.
  353.  
  354.        It is expected this function anunciates the data. That is, for example
  355.        with audio data, the sound is output on a speaker.
  356.  
  357.        This function is called every GetFrameRate() timestamp units, so MUST
  358.        take less than that amount of time to complete!
  359.      */
  360.     virtual BOOL Write(
  361.       const BYTE * buffer,          /// Buffer of encoded data
  362.       unsigned length,              /// Length of encoded data buffer
  363.       const RTP_DataFrame & frame,  /// Entire RTP frame
  364.       unsigned & written            /// Number of bytes used from data buffer
  365.     ) = 0;
  366.  
  367.     /**Get the frame rate in RTP timestamp units.
  368.       */
  369.     virtual unsigned GetFrameRate() const;
  370.  
  371.     /**Limit bit flow for the logical channel.
  372.        The default behaviour does nothing.
  373.      */
  374.     virtual void OnFlowControl(
  375.       long bitRateRestriction   /// Bit rate limitation
  376.     );
  377.  
  378.     /**Process a miscellaneous command on the logical channel.
  379.        The default behaviour does nothing.
  380.      */
  381.     virtual void OnMiscellaneousCommand(
  382.       const H245_MiscellaneousCommand_type & type  /// Command to process
  383.     );
  384.  
  385.     /**Process a miscellaneous indication on the logical channel.
  386.        The default behaviour does nothing.
  387.      */
  388.     virtual void OnMiscellaneousIndication(
  389.       const H245_MiscellaneousIndication_type & type  /// Indication to process
  390.     );
  391.  
  392.     Direction GetDirection()   const { return direction; }
  393.  
  394.     const OpalMediaFormat & GetMediaFormat() const { return mediaFormat; }
  395.  
  396.     /**Attach the raw data channel for use by codec.
  397.        Note the channel provided will be deleted on destruction of the codec.
  398.        
  399.        The channel connects the codec (audio or video) with hardware to read/write data.
  400.        Thus, the video codec provides a pointer to the data, which the renderer/grabber
  401.        then accesses to display/grab the image from/to.
  402.       */
  403.     virtual BOOL AttachChannel(
  404.       PChannel * channel,     /// Channel to read/write raw codec data
  405.       BOOL autoDelete = TRUE  /// Channel is to be automatically deleted
  406.     );
  407.  
  408.     /**Attach a new channel and returns the previous one, without neither
  409.        deleting it nor closing it. This method is used to, for example,
  410.        when swapping to or from a hold media channel
  411.      */
  412.     virtual PChannel * SwapChannel(
  413.       PChannel * newChannel,  /// Channel to read/write raw codec data
  414.       BOOL autoDelete = TRUE  /// Channel is to be automatically deleted
  415.     );
  416.  
  417.     /**Close the raw data channel, described in H323Codec::AttachChannel
  418.       */
  419.     virtual BOOL CloseRawDataChannel();
  420.  
  421.     /**Return a pointer to the raw data channel, which can then be used to
  422.        access the recording/playing device. (or testing if channel is attached).
  423.     */
  424.     PChannel *GetRawDataChannel()
  425.       {    return rawDataChannel; }
  426.  
  427.     /**Return flag indicating raw channel is native.
  428.        For audio codecs, FALSE typically means that the format is PCM-16.
  429.        For video codecs, FALSE typically means that the format is YUV411P.
  430.  
  431.        The default behaviour returns FALSE.
  432.       */
  433.     virtual BOOL IsRawDataChannelNative() const;
  434.  
  435.     /**Read from the raw data channel.
  436.       */
  437.     BOOL ReadRaw(
  438.       void * data,
  439.       PINDEX size,
  440.       PINDEX & length
  441.     );
  442.  
  443.     /**Write from the raw data channel.
  444.       */
  445.     BOOL WriteRaw(
  446.       void * data,
  447.       PINDEX length
  448.     );
  449.  
  450.     /**Attach the logical channel, for use by the codec.
  451.        The channel provided is not deleted on destruction, it is just used.
  452.  
  453.        The logical channel provides a means for the codec to send control messages.
  454.        E.G. the receive video codec wants to receive a frame update.
  455.     */
  456.     BOOL AttachLogicalChannel(H323Channel *channel);
  457.  
  458.     class FilterInfo : public PObject {
  459.         PCLASSINFO(FilterInfo, PObject);
  460.       public:
  461.         FilterInfo(H323Codec & c, void * b, PINDEX s, PINDEX l)
  462.           : codec(c), buffer(b), bufferSize(s), bufferLength(l) { }
  463.  
  464.         H323Codec & codec;
  465.         void      * buffer;
  466.         PINDEX      bufferSize;
  467.         PINDEX      bufferLength;
  468.     };
  469.  
  470.     /**Add a filter to the codec.
  471.        The call back function is executed just after reading from, or just
  472.        before writing to, the raw data channel. The callback is passed the
  473.        H323Codec::FilterInfo structure containing the data that is being
  474.        read or written.
  475.  
  476.        To use define:
  477.          PDECLARE_NOTIFIER(H323Codec::FilterInfo, YourClass, YourFunction);
  478.        and
  479.          void YourClass::YourFunction(H323Codec::FilterInfo & info, INT)
  480.          {
  481.            // DO something with data
  482.          }
  483.        and to connect to a codec:
  484.          BOOL YourClass::OnStartLogicalChannel(H323Channel & channel)
  485.          {
  486.            H323Codec * codec = channel.GetCodec();
  487.            codec->AddFilter(PCREATE_NOTIFIER(YourFunction));
  488.          }
  489.        for example. Other places can be used to set the filter.
  490.       */
  491.     void AddFilter(
  492.       const PNotifier & notifier
  493.     );
  494.  
  495.   protected:
  496.     Direction direction;
  497.     OpalMediaFormat mediaFormat;
  498.     
  499.     H323Channel * logicalChannel; // sends messages from receive codec to tx codec.
  500.  
  501.     PChannel * rawDataChannel;  // connection to the hardware for reading/writing data.
  502.     BOOL       deleteChannel;
  503.     PMutex     rawChannelMutex;
  504.  
  505.     PINDEX     lastSequenceNumber;  // Detects lost RTP packets in the video codec.
  506.  
  507.     PLIST(FilterList, PNotifier);
  508.     FilterList filters;
  509. };
  510.  
  511.  
  512. /**This class defines a codec class that will use the standard platform PCM
  513.    output device.
  514.  
  515.    An application may create a descendent off this class and override
  516.    functions as required for descibing a specific codec.
  517.  */
  518. class H323AudioCodec : public H323Codec
  519. {
  520.   PCLASSINFO(H323AudioCodec, H323Codec);
  521.  
  522.   public:
  523.     /** Create a new audio codec.
  524.         This opens the standard PCM audio output device, for input and output
  525.         and allows descendent codec classes to do audio I/O after
  526.         decoding/encoding.
  527.       */
  528.     H323AudioCodec(
  529.       const char * mediaFormat, /// Media format for codec
  530.       Direction direction       /// Direction in which this instance runs
  531.     );
  532.  
  533.     ~H323AudioCodec();
  534.  
  535.     /**Open the codec.
  536.        This will open the codec for encoding or decoding. This is primarily
  537.        used to delay allocation of resources until the last minute.
  538.  
  539.        The default behaviour calls the H323EndPoint::OpenAudioChannel()
  540.        function and assigns the result of that function to the raw data
  541.        channel in the H323Codec class.
  542.       */
  543.     virtual BOOL Open(
  544.       H323Connection & connection /// Connection between the endpoints
  545.     );
  546.  
  547.     /**Close down the codec.
  548.        This will close the codec breaking any block on the Read() or Write()
  549.        functions.
  550.  
  551.        The default behaviour will close the rawDataChannel if it is not NULL
  552.        and thene delete it if delteChannel is TRUE.
  553.       */
  554.     virtual void Close();
  555.  
  556.     /**Get the frame rate in RTP timestamp units.
  557.       */
  558.     virtual unsigned GetFrameRate() const;
  559.  
  560.     enum SilenceDetectionMode {
  561.       NoSilenceDetection,
  562.       FixedSilenceDetection,
  563.       AdaptiveSilenceDetection
  564.     };
  565.  
  566.     /**Enable/Disable silence detection.
  567.        The deadband periods are in audio samples of 8kHz.
  568.       */
  569.     void SetSilenceDetectionMode(
  570.       SilenceDetectionMode mode,   /// New silence detection mode
  571.       unsigned threshold = 0,      /// Threshold value if FixedSilenceDetection
  572.       unsigned signalDeadband = 80,    /// 10 milliseconds of signal needed
  573.       unsigned silenceDeadband = 3200, /// 400 milliseconds of silence needed
  574.       unsigned adaptivePeriod = 4800   /// 600 millisecond window for adaptive threshold
  575.     );
  576.  
  577.     /**Get silence detection mode
  578.  
  579.        The inTalkBurst value is TRUE if packet transmission is enabled and
  580.        FALSE if it is being suppressed due to silence.
  581.  
  582.        The currentThreshold value is the value from 0 to 32767 which is used
  583.        as the threshold value for 16 bit PCM data.
  584.       */
  585.     SilenceDetectionMode GetSilenceDetectionMode(
  586.       BOOL * isInTalkBurst = NULL,        // Current silence detct state.
  587.       unsigned * currentThreshold = NULL  // Current signal/silence threshold
  588.     ) const;
  589.     
  590.     /**Check frame for a talk burst.
  591.        This does the deadband calculations on the average signal levels
  592.        returned by the GetAverageSignalLevel() function and based on the
  593.        levelThreshold, signalDeadbandFrames and silenceDeadbandFrames
  594.        member variables.
  595.       */
  596.     virtual BOOL DetectSilence();
  597.  
  598.     /**Get the average signal level in the audio stream.
  599.        This is called from within DetectSilence() to calculate the average
  600.        signal level since the last call to DetectSilence().
  601.  
  602.        The default behaviour returns UINT_MAX which disables the silence
  603.        detection algorithm.
  604.       */
  605.     virtual unsigned GetAverageSignalLevel();
  606.  
  607.   protected:
  608.     unsigned samplesPerFrame;
  609.  
  610.     SilenceDetectionMode silenceDetectMode;
  611.  
  612.     unsigned signalDeadbandFrames;  // Frames of signal before talk burst starts
  613.     unsigned silenceDeadbandFrames; // Frames of silence before talk burst ends
  614.     unsigned adaptiveThresholdFrames; // Frames to min/max over for adaptive threshold
  615.  
  616.     BOOL     inTalkBurst;           // Currently sending RTP data
  617.     unsigned framesReceived;        // Signal/Silence frames received so far.
  618.     unsigned levelThreshold;        // Threshold level for silence/signal
  619.     unsigned signalMinimum;         // Minimum of frames above threshold
  620.     unsigned silenceMaximum;        // Maximum of frames below threshold
  621.     unsigned signalFramesReceived;  // Frames of signal received
  622.     unsigned silenceFramesReceived; // Frames of silence received
  623. };
  624.  
  625.  
  626. /**This class defines a codec class that will use the standard platform PCM
  627.    output device, and the encoding/decoding has fixed blocks. That is each
  628.    input block of n samples is encoded to exactly the same sized compressed
  629.    data, eg G.711, GSM etc.
  630.  
  631.    An application may create a descendent off this class and override
  632.    functions as required for descibing a specific codec.
  633.  */
  634. class H323FramedAudioCodec : public H323AudioCodec
  635. {
  636.   PCLASSINFO(H323FramedAudioCodec, H323AudioCodec);
  637.  
  638.   public:
  639.     /** Create a new audio codec.
  640.         This opens the standard PCM audio output device, for input and output
  641.         and allows descendent codec classes to do audio I/O after
  642.         decoding/encoding.
  643.       */
  644.     H323FramedAudioCodec(
  645.       const char * mediaFormat, /// Media format for codec
  646.       Direction direction       /// Direction in which this instance runs
  647.     );
  648.  
  649.     /**Encode the data from the appropriate device.
  650.        This will encode data for transmission. The exact size and description
  651.        of the data placed in the buffer is codec dependent but should be less
  652.        than OpalMediaFormat::GetFrameSize() in length.
  653.  
  654.        The length parameter is filled with the actual length of the encoded
  655.        data, often this will be the same as OpalMediaFormat::GetFrameSize().
  656.  
  657.        This function is called every GetFrameRate() timestamp units, so MUST
  658.        take less than (or equal to) that amount of time to complete. It
  659.        should always return the amount of data that corresponds to the
  660.        GetFrameRate() timestamp units as well.
  661.  
  662.        A returned length of zero indicates that time has passed but there is
  663.        no data encoded. This is typically used for silence detection in an
  664.        audio codec.
  665.      */
  666.     virtual BOOL Read(
  667.       BYTE * buffer,            /// Buffer of encoded data
  668.       unsigned & length,        /// Actual length of encoded data buffer
  669.       RTP_DataFrame & rtpFrame  /// RTP data frame
  670.     );
  671.  
  672.     /**Decode the data and output it to appropriate device.
  673.        This will decode a single frame of received data. The exact size and
  674.        description of the data required in the buffer is codec dependent but
  675.        should be less than H323Capability::GetRxFramesInPacket() *
  676.        OpalMediaFormat::GetFrameSize()  in length.
  677.  
  678.        It is expected this function anunciates the data. That is, for example
  679.        with audio data, the sound is output on a speaker.
  680.  
  681.        This function is called every GetFrameRate() timestamp units, so MUST
  682.        take less than that amount of time to complete!
  683.      */
  684.     virtual BOOL Write(
  685.       const BYTE * buffer,            /// Buffer of encoded data
  686.       unsigned length,                /// Length of encoded data buffer
  687.       const RTP_DataFrame & rtpFrame, /// RTP data frame
  688.       unsigned & written              /// Number of bytes used from data buffer
  689.     );
  690.  
  691.  
  692.     /**Get the average signal level in the audio stream.
  693.        This is called from within DetectSilence() to calculate the average
  694.        signal level since the last call to DetectSilence().
  695.       */
  696.     virtual unsigned GetAverageSignalLevel();
  697.  
  698.  
  699.     /**Encode a sample block into the buffer specified.
  700.        The samples have been read and are waiting in the readBuffer member
  701.        variable. it is expected this function will encode exactly
  702.        bytesPerFrame bytes.
  703.      */
  704.     virtual BOOL EncodeFrame(
  705.       BYTE * buffer,    /// Buffer into which encoded bytes are placed
  706.       unsigned & length /// Actual length of encoded data buffer
  707.     ) = 0;
  708.  
  709.     /**Decode a sample block from the buffer specified.
  710.        The samples must be placed into the writeBuffer member variable. It is
  711.        expected that exactly samplesPerFrame samples is decoded.
  712.      */
  713.     virtual BOOL DecodeFrame(
  714.       const BYTE * buffer,  /// Buffer from which encoded data is found
  715.       unsigned length,      /// Length of encoded data buffer
  716.       unsigned & written    /// Number of bytes used from data buffer
  717.     ) = 0;
  718.  
  719.  
  720.   protected:
  721.     PShortArray sampleBuffer;
  722.     unsigned    bytesPerFrame;
  723. };
  724.  
  725.  
  726. /**This class defines a codec class that will use the standard platform PCM
  727.    output device, and the encoding/decoding is streamed. That is each input
  728.    16 bit PCM sample is encoded to 8 bits or less of encoded data and no
  729.    blocking of PCM data is required, eg G.711, G.721 etc.
  730.  
  731.    An application may create a descendent off this class and override
  732.    functions as required for descibing a specific codec.
  733.  */
  734. class H323StreamedAudioCodec : public H323FramedAudioCodec
  735. {
  736.   PCLASSINFO(H323StreamedAudioCodec, H323FramedAudioCodec);
  737.  
  738.   public:
  739.     /** Create a new audio codec.
  740.         This opens the standard PCM audio output device, for input and output
  741.         and allows descendent codec classes to do audio I/O after
  742.         decoding/encoding.
  743.       */
  744.     H323StreamedAudioCodec(
  745.       const char * mediaFormat, /// Media format for codec
  746.       Direction direction,      /// Direction in which this instance runs
  747.       unsigned samplesPerFrame, /// Number of samples in a frame
  748.       unsigned bits             /// Bits per sample
  749.     );
  750.  
  751.     /**Encode a sample block into the buffer specified.
  752.        The samples have been read and are waiting in the readBuffer member
  753.        variable. it is expected this function will encode exactly
  754.        encodedBlockSize bytes.
  755.      */
  756.     virtual BOOL EncodeFrame(
  757.       BYTE * buffer,    /// Buffer into which encoded bytes are placed
  758.       unsigned & length /// Actual length of encoded data buffer
  759.     );
  760.  
  761.     /**Decode a sample block from the buffer specified.
  762.        The samples must be placed into the writeBuffer member variable. It is
  763.        expected that no more than frameSamples is decoded. The return value
  764.        is the number of samples decoded. Zero indicates an error.
  765.      */
  766.     virtual BOOL DecodeFrame(
  767.       const BYTE * buffer,  /// Buffer from which encoded data is found
  768.       unsigned length,      /// Length of encoded data buffer
  769.       unsigned & written    /// Number of bytes used from data buffer
  770.     );
  771.  
  772.     /**Encode a single sample value.
  773.      */
  774.     virtual int Encode(short sample) const = 0;
  775.  
  776.     /**Decode a single sample value.
  777.      */
  778.     virtual short Decode(int sample) const = 0;
  779.  
  780.   protected:
  781.     unsigned bitsPerSample;
  782. };
  783.  
  784.  
  785. #ifndef NO_H323_VIDEO
  786.  
  787. /**This class defines a codec class that will use the standard platform image
  788.    output device.
  789.  
  790.    An application may create a descendent off this class and override
  791.    functions as required for descibing a specific codec.
  792.  */
  793. class H323VideoCodec : public H323Codec
  794. {
  795.   PCLASSINFO(H323VideoCodec, H323Codec);
  796.  
  797.   public:
  798.     /** Create a new video codec.
  799.         This opens the standard image output device, for input and output
  800.         and allows descendent codec classes to do video I/O after
  801.         decoding/encoding.
  802.       */
  803.     H323VideoCodec(
  804.       const char * mediaFormat, /// Media format for codec
  805.       Direction direction      /// Direction in which this instance runs
  806.     );
  807.  
  808.     ~H323VideoCodec();
  809.  
  810.     /**Open the codec.
  811.        This will open the codec for encoding or decoding. This is primarily
  812.        used to delay allocation of resources until the last minute.
  813.  
  814.        The default behaviour calls the H323EndPoint::OpenVideoDevice()
  815.        function and assigns the result of that function to the raw data
  816.        channel in the H323Codec class.
  817.       */
  818.     virtual BOOL Open(
  819.       H323Connection & connection /// Connection between the endpoints
  820.     );
  821.  
  822.     /**Close down the codec.
  823.        This will close the codec breaking any block on the Read() or Write()
  824.        functions.
  825.  
  826.        The default behaviour will close the rawDataChannel if it is not NULL
  827.        and thene delete it if delteChannel is TRUE.
  828.       */
  829.     virtual void Close();
  830.  
  831.  
  832.     /**Process a miscellaneous command on the logical channel.
  833.        The default behaviour does nothing.
  834.      */
  835.     virtual void OnMiscellaneousCommand(
  836.       const H245_MiscellaneousCommand_type & type  /// Command to process
  837.     );
  838.  
  839.     /**Process a miscellaneous indication on the logical channel.
  840.        The default behaviour does nothing.
  841.      */
  842.     virtual void OnMiscellaneousIndication(
  843.       const H245_MiscellaneousIndication_type & type  /// Indication to process
  844.     );
  845.  
  846.     //    /**Attach the raw data device for use by codec.
  847.     //   Note the device provided will be deleted on destruction of the codec.
  848.     //   */
  849.     // virtual BOOL AttachDevice(
  850.     //  H323VideoDevice * device, /// Device to read/write data
  851.     //  BOOL autoDelete = TRUE    /// Device is to be automatically deleted
  852.     // );
  853.  
  854.     /**Process a FreezePicture command from remote endpoint.
  855.        The default behaviour does nothing.
  856.      */
  857.     virtual void OnFreezePicture();
  858.  
  859.     /**Process a FastUpdatePicture command from remote endpoint.
  860.        The default behaviour does nothing.
  861.      */
  862.     virtual void OnFastUpdatePicture();
  863.  
  864.     /**Process a FastUpdateGOB command from remote endpoint.
  865.        The default behaviour does nothing.
  866.      */
  867.     virtual void OnFastUpdateGOB(unsigned firstGOB, unsigned numberOfGOBs);
  868.  
  869.     /**Process a FastUpdateMB command from remote endpoint.
  870.        The default behaviour does nothing.
  871.      */
  872.     virtual void OnFastUpdateMB(int firstGOB, int firstMB, unsigned numberOfMBs);
  873.  
  874.     /**Process a OnVideoIndicateReadyToActivate indication from remote endpoint.
  875.        The default behaviour does nothing.
  876.      */
  877.     virtual void OnVideoIndicateReadyToActivate();
  878.  
  879.     /**Process a OnVideoTemporalSpatialTradeOff indication from remote endpoint.
  880.        The default behaviour does nothing.
  881.      */
  882.     virtual void OnVideoTemporalSpatialTradeOff();
  883.  
  884.     /**Process a OnVideoNotDecodedMBs indication from remote endpoint.
  885.        The default behaviour does nothing.
  886.      */
  887.     virtual void OnVideoNotDecodedMBs(unsigned firstMB, unsigned numberOfMBs, unsigned temporalReference);
  888.  
  889.     /**Process a request for a new frame, 
  890.        as part of the picture has been lost.
  891.     */
  892.     virtual void OnLostPartialPicture();
  893.  
  894.     /**Process a request for a new frame, 
  895.        as the entire picture has been lost.
  896.     */
  897.     virtual void OnLostPicture();
  898.  
  899.     /** Get width of video
  900.      */ 
  901.     int GetWidth() const { return frameWidth; }
  902.  
  903.     /** Get height of video
  904.      */ 
  905.     int GetHeight() const { return frameHeight; }
  906.  
  907.     /**Quality of the transmitted video. 1 is good, 31 is poor.
  908.      */
  909.     virtual void SetTxQualityLevel(int qlevel) {videoQuality = qlevel; }
  910.  
  911.     /**Minimum quality limit for the transmitted video.
  912.      * Default is 1.  Encode quality will not be set below this value.
  913.      */
  914.     virtual void SetTxMinQuality(int qlevel) {videoQMin = qlevel; }
  915.  
  916.     /**Maximum quality limit for the transmitted video.
  917.      * Default is 24.  Encode quality will not be set above this value.
  918.      */
  919.     virtual void SetTxMaxQuality(int qlevel) {videoQMax = qlevel; }
  920.  
  921.     /**number of blocks (that haven't changed) transmitted with each 
  922.        frame. These blocks fill in the background */
  923.     virtual void SetBackgroundFill(int idle) {fillLevel= idle; }
  924.  
  925.     enum BitRateModeBits {
  926.       None                = 0x00,
  927.       DynamicVideoQuality = 0x01,
  928.       AdaptivePacketDelay = 0x02
  929.     };
  930.  
  931.     /**Get the current value for video control mode
  932.      */
  933.     unsigned GetVideoMode(void) {return videoBitRateControlModes;}
  934.  
  935.     /**Set the current value for video control mode
  936.      * return the resulting value video control mode
  937.      */
  938.     unsigned SetVideoMode(unsigned mode) {return videoBitRateControlModes = mode;}
  939.     
  940.     /**Set maximum bitrate when transmitting video.  A value of 0 disables bit rate
  941.        control.  The average bitrate will be less depending on channel dead time,
  942.        i.e. time that the channel could be transmitting bits but is not.
  943.      */
  944.     virtual BOOL SetMaxBitRate(
  945.       unsigned bitRate // New bit rate
  946.     );
  947.  
  948.     /**Set target time in milliseconds between video frames going through
  949.        the channel.  This sets the video frame rate through the channel,
  950.        which is <= grabber frame rate.  Encoder quality will be adjusted
  951.        dynamically by the codec to find a frame size that allows sending
  952.        at this rate.  Default = 167 ms = 6 frames per second.  A value of 0
  953.        means the channel will attempt to run at the video grabber frame rate
  954.        Sometimes the channel cannot transmit as fast as the video grabber.
  955.     */
  956.     virtual BOOL SetTargetFrameTimeMs(
  957.       unsigned ms // new time between frames
  958.     );
  959.  
  960.     /**
  961.        Send a miscellaneous command to the remote transmitting video codec.
  962.        This message is sent via the H245 Logical Channel.
  963.     */
  964.     void SendMiscCommand(unsigned command);
  965.  
  966.   protected:
  967.  
  968.     int frameWidth;
  969.     int frameHeight;
  970.     int fillLevel;
  971.  
  972.     // used in h261codec.cxx
  973.     unsigned videoBitRateControlModes;
  974.     // variables used for video bit rate control
  975.     int bitRateHighLimit; // maximum instantaneous bit rate allowed
  976.     unsigned oldLength;
  977.     PTimeInterval oldTime;
  978.     PTimeInterval newTime;
  979.     // variables used for dynamic video quality control
  980.     int targetFrameTimeMs; //targetFrameTimeMs = 1000 / videoSendFPS
  981.     int frameBytes; // accumulate count of bytes per frame
  982.     int sumFrameTimeMs, sumAdjFrameTimeMs, sumFrameBytes; // accumulate running average
  983.     int videoQMax, videoQMin; // dynamic video quality min/max limits
  984.     int videoQuality; // current video encode quality setting, 1..31
  985.     PTimeInterval frameStartTime;
  986.     PTimeInterval grabInterval;
  987.     
  988.     int frameNum, packetNum, oldPacketNum;
  989.     int framesPerSec;
  990.  
  991.     PMutex  videoHandlerActive;    
  992. };
  993.  
  994. #endif // NO_H323_VIDEO
  995.  
  996.  
  997. ///////////////////////////////////////////////////////////////////////////////
  998. // The simplest codec is the G.711 PCM codec.
  999.  
  1000. /**This class is a G711 ALaw codec.
  1001.  */
  1002. class H323_ALawCodec : public H323StreamedAudioCodec
  1003. {
  1004.   PCLASSINFO(H323_ALawCodec, H323StreamedAudioCodec)
  1005.  
  1006.   public:
  1007.   /**@name Construction */
  1008.   //@{
  1009.     /**Create a new G.711 codec for ALaw.
  1010.      */
  1011.     H323_ALawCodec(
  1012.       Direction direction,  /// Direction in which this instance runs
  1013.       BOOL at56kbps,        /// Encoding bit rate.
  1014.       unsigned frameSize    /// Size of frame in bytes
  1015.     );
  1016.   //@}
  1017.  
  1018.     virtual int   Encode(short sample) const { return EncodeSample(sample); }
  1019.     virtual short Decode(int   sample) const { return DecodeSample(sample); }
  1020.  
  1021.     static int   EncodeSample(short sample);
  1022.     static short DecodeSample(int   sample);
  1023.  
  1024.   protected:
  1025.     BOOL sevenBit;
  1026. };
  1027.  
  1028.  
  1029. /**This class is a G711 uLaw codec.
  1030.  */
  1031. class H323_muLawCodec : public H323StreamedAudioCodec
  1032. {
  1033.   PCLASSINFO(H323_muLawCodec, H323StreamedAudioCodec)
  1034.  
  1035.   public:
  1036.   /**@name Construction */
  1037.   //@{
  1038.     /**Create a new G.711 codec for muLaw.
  1039.      */
  1040.     H323_muLawCodec(
  1041.       Direction direction,  /// Direction in which this instance runs
  1042.       BOOL at56kbps,        /// Encoding bit rate.
  1043.       unsigned frameSize    /// Size of frame in bytes
  1044.     );
  1045.   //@}
  1046.  
  1047.     virtual int   Encode(short sample) const { return EncodeSample(sample); }
  1048.     virtual short Decode(int   sample) const { return DecodeSample(sample); }
  1049.  
  1050.     static int   EncodeSample(short sample);
  1051.     static short DecodeSample(int   sample);
  1052.  
  1053.   protected:
  1054.     BOOL sevenBit;
  1055. };
  1056.  
  1057.  
  1058. #endif // __CODECS_H
  1059.  
  1060.  
  1061. /////////////////////////////////////////////////////////////////////////////
  1062.