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 / cu30codec.h < prev    next >
C/C++ Source or Header  |  2002-10-09  |  15KB  |  442 lines
  1. /*
  2.  * cu30codec.h
  3.  *
  4.  * H.323 protocol handler
  5.  *
  6.  * Open H323 Library
  7.  *
  8.  * Copyright (c) 1999-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.  * Contributor(s): ______________________________________.
  25.  *                 Derek J Smithies (derek@indranet.co.nz)
  26.  *
  27.  * $Log: cu30codec.h,v $
  28.  * Revision 1.6  2002/10/09 18:18:35  rogerh
  29.  * Apply a patch from Damien Sandras
  30.  *
  31.  * Revision 1.5  2002/09/16 01:14:15  robertj
  32.  * Added #define so can select if #pragma interface/implementation is used on
  33.  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
  34.  *
  35.  * Revision 1.4  2002/09/03 06:19:36  robertj
  36.  * Normalised the multi-include header prevention ifdef/define symbol.
  37.  *
  38.  * Revision 1.3  2002/08/05 10:03:47  robertj
  39.  * Cosmetic changes to normalise the usage of pragma interface/implementation.
  40.  *
  41.  * Revision 1.2  2002/01/16 02:53:52  dereks
  42.  * Add methods to cope with H.245 RequestModeChange in h.261 video codec.
  43.  *
  44.  * Revision 1.1  2001/10/23 02:18:06  dereks
  45.  * Initial release of CU30 video codec.
  46.  *
  47.  *
  48.  */
  49.  
  50. #ifndef __OPAL_CU30CODEC_H
  51. #define __OPAL_CU30CODEC_H
  52.  
  53. #ifdef P_USE_PRAGMA
  54. #pragma interface
  55. #endif
  56.  
  57.  
  58. #include "h323caps.h"
  59.  
  60.  
  61. ///////////////////////////////////////////////////////////////////////////////
  62.  
  63.  
  64. /**This class describes the CU30 video codec capability.
  65.  */
  66. class H323_Cu30Capability : public H323NonStandardVideoCapability
  67. {
  68.   PCLASSINFO(H323_Cu30Capability, H323NonStandardVideoCapability);
  69.  
  70.   public:
  71.   /**@name Construction */
  72.   //@{
  73.     /**Create a new CU30 capability.
  74.      */
  75.     H323_Cu30Capability(
  76.       H323EndPoint & endpoint,   // Endpoint to get NonStandardInfo from.
  77.       PString      statsDir,     // Directory to read statistics for codec from/to.
  78.       INT          _width,       // width and height for the transmitter.
  79.       INT          _height,      //
  80.       INT          _statsFrames  // Number of frames to collect stats for.
  81.            ); 
  82.   //@}
  83.  
  84.   /**@name Overrides from class PObject */
  85.   //@{
  86.     /**Create a copy of the object.
  87.       */
  88.     virtual PObject * Clone() const;
  89.   //@}
  90.  
  91.   /**@name Operations */
  92.   //@{
  93.     /**Create the codec instance, allocating resources as required.
  94.      */
  95.     virtual H323Codec * CreateCodec(
  96.       H323Codec::Direction direction  /// Direction in which this instance runs      
  97.     ) const;
  98.   //@}
  99.  
  100.   /**@name Identification functions */
  101.   //@{
  102.     /**Get the name of the media data format this class represents.
  103.      */
  104.     virtual PString GetFormatName() const;
  105.   //@}
  106.  
  107.     PString statisticsDir;  //Required by cu30 codec at initialization.
  108.                             //directory containing stats. Good stats==good compression.
  109.  
  110.     INT      newWidth;     // width and height for the transmitter.
  111.     INT      newHeight;    //
  112.     INT      statsFrames;  // Number of frames to collect stats over.
  113. };
  114.  
  115. ///////////////////////////////////////////////////////////////////////////////
  116. /**This class is a CU30 codec.
  117.  */
  118. class H323_Cu30Codec :  public  H323VideoCodec, public PDynaLink
  119. {
  120.   PCLASSINFO(H323_Cu30Codec, H323VideoCodec)
  121.  
  122.   public:
  123.   /**@name Construction */
  124.   //@{
  125.     /**Create a new CU30 video codec.
  126.      */
  127.     H323_Cu30Codec(
  128.       Direction direction,        /// Direction in which this instance runs
  129.       PString   statsDir,
  130.       INT       _width,           /// width and height for the transmitter.
  131.       INT       _height,
  132.       INT       _statsFrames      /// Number of frames to collect stats over.
  133.     );
  134.     ~H323_Cu30Codec();
  135.   //@}
  136.  
  137.  
  138.   /**@name openh323 interface routines. */
  139.   //@{
  140.    /**Encode the data from the appropriate device.
  141.        This will encode a frame of data for transmission. The exact size and
  142.        description of the data placed in the buffer is codec dependent but
  143.        should be less than H323Capability::GetTxFramesInPacket() *
  144.        OpalMediaFormat::GetFrameSize()  in length.
  145.  
  146.        The length parameter is filled with the actual length of the encoded
  147.        data, often this will be the same as the size parameter.
  148.  
  149.        This function is called every GetFrameRate() timestamp units, so MUST
  150.        take less than (or equal to) that amount of time to complete!
  151.  
  152.        Note that a returned length of zero indicates that time has passed but
  153.        there is no data encoded. This is typically used for silence detection
  154.        in an audio codec.
  155.  
  156.        This function grabs, displays, and compresses a video frame into
  157.        into CU30 packets.
  158.        Get another frame if all packets of previous frame have been sent.
  159.        Get next packet on list and send that one.
  160.        Render the current frame if all of its packets have been sent.
  161.      */
  162.     virtual BOOL Read(
  163.       BYTE * buffer,            /// Buffer of encoded data
  164.       unsigned & length,        /// Actual length of encoded data buffer
  165.       RTP_DataFrame & rtpFrame  /// RTP data frame
  166.     );
  167.  
  168.    /**Decode the data and output it to appropriate device.
  169.        This will decode a single frame of received data. The exact size and
  170.        description of the data required in the buffer is codec dependent but
  171.        should be less than H323Capability::GetRxFramesInPacket() *
  172.        OpalMediaFormat::GetFrameSize()  in length.
  173.  
  174.        It is expected this function anunciates the data. That is, for example
  175.        with audio data, the sound is output on a speaker.
  176.  
  177.        This function is called every GetFrameRate() timestamp units, so MUST
  178.        take less than that amount of time to complete!
  179.      */
  180.     virtual BOOL Write(
  181.       const BYTE * buffer,        /// Buffer of encoded data
  182.       unsigned length,            /// Length of encoded data buffer
  183.       const RTP_DataFrame & rtp,  /// RTP data frame
  184.       unsigned & written          /// Number of bytes used from data buffer
  185.     );
  186.  
  187.     /**
  188.        Used to acquire statistics on this frame. Used in later h323 connections for
  189.        minimising the bits required to transmit cu30 video.
  190.     */
  191.     BOOL RecordStatistics(unsigned char *src);
  192.  
  193.   protected:
  194.     /** Resize the internal variables to cope with a new frame size.
  195.      */
  196.     BOOL Resize(int width, int height);
  197.  
  198.     /** call RenderFrame() routine.
  199.      */
  200.     BOOL Redraw();
  201.  
  202.     /** Display the current frame that the encoder/decoder has in memory.        
  203.         Takes the address of the current frame (set in last call to
  204.          encode/decode) and then call rawDataChannel->Write().
  205.         The current frame is in YUV420P format, and consists of 
  206.             width*height*1.5 bytes.
  207.         If there is no raw data channel, return true (success).
  208.     */
  209.     BOOL RenderFrame();
  210.  
  211.     /**Process a request for a new frame, 
  212.        as part of the picture has been lost.
  213.  
  214.        This request is handled by causing the transmitting video
  215.        codec to send out an intra frame. Subsequent frames will
  216.        be inter, inter, inter,,,,, and then an intra frame.
  217.     */
  218.     virtual void OnLostPartialPicture();
  219.  
  220.     /**In the context of the Cu30 codec, this message means
  221.        "Not all the statistics fields got through."
  222.        "Please resend the statistics".
  223.     */
  224.     virtual void OnLostPicture();
  225.  
  226.  private:
  227.     /*There is a problem with the CU30codec. It needs to be able to 
  228.        carry out two tasks. 1)Grab data from the camera.
  229.        2)Render data from an array.
  230.        Thus, we either: two PVideoChannels, or one PVideoChannel to both
  231.        grab and render.
  232.        We use one PVideoChannel, which is not consistant with elsewhere,
  233.        but enables us to (later) have a grab and display process irrespective
  234.        of there being a H323 connection.
  235.     */
  236.  
  237.     /**
  238.        Close the encoder & decoder objects in the run time library.
  239.        Delete the allocated memory for the frame buffer.
  240.      */
  241.     void Close();
  242.  
  243.   //@}
  244.  
  245.   /**@name cu30 interface routines. */
  246.   //@{
  247.     /**
  248.        Function pointer initialised when the plug in codec is read
  249.      */
  250.     int (*OpenEncoderWith)(void *, int,int,char *); 
  251.  
  252.     /**
  253.        Function pointer initialised when the plug in codec is read
  254.      */
  255.     int (*OpenEncoder)(void *, int,int);
  256.     
  257.     /**
  258.        Function pointer initialised when the plug in codec is read
  259.      */
  260.     int (*CloseEncoder)(void *);      
  261.     
  262.     /**
  263.        Function pointer initialised when the plug in codec is read
  264.      */
  265.     int (*OpenDecoder)(void *, int,int);
  266.     
  267.     /**
  268.        Function pointer initialised when the plug in codec is read
  269.      */
  270.     int (*CloseDecoder)(void *);      
  271.  
  272.     /**
  273.        Function pointer initialised when the plug in codec is read
  274.      */
  275.     int (*OpenStats)(void *, int,int);
  276.     
  277.     /**
  278.        Function pointer initialised when the plug in codec is read
  279.      */
  280.     int (*CloseStats)(void *);      
  281.     
  282.     /**
  283.        Function pointer initialised when the plug in codec is read
  284.      */
  285.     int (*DoEncode)(void *, unsigned char *,unsigned char **);  
  286.  
  287.     /**
  288.        Function pointer initialised when the plug in codec is read
  289.      */
  290.     int (*DoDecode)(void *, const unsigned char*, int, unsigned char **);
  291.  
  292.     /**
  293.        Function pointer initialised when the plug in codec is read
  294.      */
  295.     int (*DoStats)(void *, const unsigned char*);
  296.  
  297.     /**
  298.        Function pointer initialised when the plug in codec is read
  299.      */
  300.     int (*SetQuality)(void *, int); 
  301.  
  302.     /**
  303.        Function pointer initialised when the plug in codec is read
  304.      */
  305.     int (*SetCodecSize)(void *, int,int);
  306.  
  307.     /**
  308.        copy statistics for a particular field from the library.
  309.     */
  310.     int (*CopyStatsFromLib)(void *, unsigned char *dest, unsigned &length, char *field);
  311.  
  312.     /**
  313.        copy statistics for a particular field to the library.
  314.     */
  315.     int (*CopyStatsToLib)(void *, unsigned char *src, unsigned length, char *field);
  316.     
  317.     /**When packets have been lost in the network, we need to wait for an intraframe.
  318.        Intraframes do not depend on the previous frames. Use the test "IsIntraFrame" to
  319.        determine if it is an intra frame.
  320.     */
  321.     int (*IsIntraFrame)(void *, const unsigned char *);
  322.  
  323.     /**
  324.        If statistics have been kept on this session, save them to a directory. 
  325.        Statistics are saved in four text files, called "y", "u", "v", and "mc"
  326.     */
  327.     int (*SendStatsToFiles)(void *, char *dir);
  328.  
  329.  
  330.     /**
  331.        Given a message from the remote computer, generate an intra frame.
  332.        This occurs because the remote computer has not received all video packets.
  333.     */
  334.     int (*ForceIntraFrame)(void *);
  335.  
  336.     /**
  337.        Tell the codec to create some internal data. This data is specific to this
  338.        thread, and must not be viewed by other threads.
  339.     */
  340.     int (*MakeInternalData)(void **);
  341.  
  342.     /**
  343.        Tell the codec to free the internal data. This data was created in the
  344.        call to "MakeInternalData".
  345.     */
  346.     int (*FreeInternalData)(void *);
  347.  
  348.     /**
  349.        Query the Cu30 library, and ask if the all the statistics files have
  350.        been loaded successfully. 
  351.  
  352.        Returns 1 if everything is ready for the decoder to run.
  353.     */
  354.     int (*StatsLoadedOK)(void *);
  355.  
  356.       /**
  357.        Allocate the necessary space for yuv420pImage/encodedImage, depending
  358.        on frame size and direction. Checks for non existance of images first.
  359.        The encoder needs just the source image. The decoder needs just the 
  360.        soure encoded image. 
  361.  
  362.       For each Cu30 decoder created, the Cu30 decoder creates one output image.
  363.     */
  364.     BOOL AllocateInternalImages(void);
  365.  
  366.   //@}
  367.  
  368.     /**
  369.        Encoder creates a memory block to hold the raw image from the grabber.
  370.        The decoder just knows where this data is in the runtime codec.
  371.     */
  372.     unsigned char *yuv420pImage;     /// the rawimage, in yuv420p format.
  373.  
  374.     /**
  375.        The encoder just knows where this data is in the runtime codec.
  376.        The decoder uses this block of memory to assemble incoming packets 
  377.        to form the the entire encoded image.
  378.      */
  379.     unsigned char *encodedImage;     /// Current image we are woring on.
  380.  
  381.     /**
  382.        Size of the encoded image. 
  383.      */
  384.     int           encodedImageSize;  ///Size (in bytes) of current image.
  385.  
  386.     /**
  387.        position in encoded image that in(out)going packets are writtten(read) to(from)
  388.      */
  389.     int           encodedImageIndex; ///position of next packet in encodedImage.
  390.     
  391.     /** 
  392.         packetCount is used to determine if (a)need to send the statistics fields
  393.         and (b)which field to send.
  394.     */
  395.     PINDEX packetCount;
  396.  
  397.     /**Codec active determines if the codec has send (or received) one packet.
  398.    
  399.        There are two instances of this codec. one for rx, one for tx.
  400.        Each codec does not need to have an encoder and decoder.
  401.        Using this variable, we prevent duplication of encoder, and the decoder.
  402.     */
  403.     BOOL   codecActive;
  404.  
  405.     /** the Statistics dir describes where the stats files are. These files
  406.         provide a means for improving the compression achieved.
  407.         The encoder remembers the old stats dir, so once set, can just use
  408.         the OpenEncoder function, and not OpenEncoderWith().
  409.     */
  410.     PString statisticsDir; 
  411.  
  412.     /** For the decoder, sometimes miss incoming video packets. In this case, cannot 
  413.     keep going and hope. Consequently, we wait, until we get a frame that does not
  414.     depend on the previous frame. Thus, we wait for an IntraFrame.
  415.     */
  416.     BOOL waitForIntraFrame;
  417.  
  418.     /**
  419.        During the current video connection, record the statistics for N frames.
  420.        These statistics are saved, and used in subsequent video connections. By taking 
  421.        statistics, we can optimise the compression ratio next time a connection occurs.
  422.     */
  423.     INT  statsFrames;
  424.  
  425.     /**
  426.        Advises transmitting video codec that the statistics frames need to be resent.
  427.        This boolean is set true in response to a On_lostPicture H245 Message.
  428.     */
  429.     BOOL resendStats;
  430.  
  431.     /**
  432.        Pointer to the internal data used by the codec library.
  433.      */
  434.     void  *internData;
  435. };
  436.  
  437.  
  438. #endif // __OPAL_CU30CODEC_H
  439.  
  440.  
  441. /////////////////////////////////////////////////////////////////////////////
  442.