ugst-utl.c

ITU-T G.191中包含的G.722语音压缩编解码程序

/*                                                            v3.0  06.Mar.96
=============================================================================
 
                          U    U   GGG    SSSS  TTTTT
                          U    U  G       S       T
                          U    U  G  GG   SSSS    T
                          U    U  G   G       S   T
                           UUU     GG     SSS     T
 
                   ========================================
                    ITU-T - USER'S GROUP ON SOFTWARE TOOLS
                   ========================================
 
 
       =============================================================
       COPYRIGHT NOTE: This source code, and all of its derivations,
       is subject to the "ITU-T General Public License". Please have
       it  read  in    the  distribution  disk,   or  in  the  ITU-T
       Recommendation G.191 on "SOFTWARE TOOLS FOR SPEECH AND  AUDIO
       CODING STANDARDS".
       =============================================================
 
 
MODULE:         UGST-UTL.C, UGST UTILITY FUNCTIONS
 
ORIGINAL BY:    <[e-mail]> (editor),
                <[e-mail]>
 
PROTOTYPE:     in ugst-utl.h
 
FUNCTIONS:
 
    fl2sh_16bit: .... conversion of an array from float to 16 bit (*)
    fl2sh_15bit: .... conversion of an array from float to 15 bit (*)
    fl2sh_14bit: .... conversion of an array from float to 14 bit (*)
    fl2sh_13bit: .... conversion of an array from float to 13 bit (*)
    fl2sh_12bit: .... conversion of an array from float to 12 bit (*)
    fl2sh: .......... generic function for conversion from float to short
 
    scale: .......... gain/loss insertion algorithm.
 
    sh2fl_16bit: .... conversion of an array from 16 bit to float (*)
    sh2fl_15bit: .... conversion of an array from 15 bit to float (*)
    sh2fl_14bit: .... conversion of an array from 14 bit to float (*)
    sh2fl_13bit: .... conversion of an array from 13 bit to float (*)
    sh2fl_12bit: .... conversion of an array from 12 bit to float (*)
    sh2fl: .......... generic function for conversion from short to float
 
    serialize_left_justified ....... serialization for left-justified data
    serialize_right_justified ...... serialization for right-justified data
    parallelize_left_justified ..... parallelization for left-justified data
    parallelize_right_justified .... parallelization for right-justified data

    There are two families of serialize...() and parallelize_...()
    functions. Ones dates from the STL92 release, and the other was
    generated for the STL96 release. The difference between them is
    that in the STL96, frame boundaries, when marked, follow the
    description in Annex B of ITU-T Rec. G.192, while for the STL92,
    frame boundaries were be marked with a sync word only. In Annex B
    of G.192, frame boundaries are marked by a sync word followed by a
    two-complent 16-bit word with the number of softbits in the
    frame. By default, the G.192-compliant functions are used in the
    STL96. The STL92 version will be used if the symbol STL92 is
    defined during compilation.
 
    --------------------------------------------------------------------
    NB: all marked with (*) are implemented as macros (#defines), rather
        than true functions! For their definition, please see ugst-utl.h
    --------------------------------------------------------------------
 
HISTORY:
 
  28.Feb.92 v1.0 Release of 1st assembled file of UGST utilities.
  10.Apr.92 v1.1 Added ser/par routines
                 <[e-mail]>
  18.May.92 v1.2 Correction of `sh2fl' normalization factor calculation;
                 `fl2sh' modified to use floats in the normalizaed range;
                 removed built-in initialization of the `serialize_*'.
                 <[e-mail]>
  27.Nov.92 v1.3 "fl2sh()" for negative values corrected <[e-mail]>
                 "sh2fl()" fixed for resolution!=16 <[e-mail]>
		 created sh2fl_alt()" as an alternate to sh2fl() of the
		 STL92 manual <[e-mail]>
  06.Jun.95 v2.0 Fixed erroneous definition of softbits '1' and '0' in the
                 serial<->parallel conversion routines, to make
                 them inline with the EID module, the hardware 8kbit/s codec 
                 host lab EID and G.192. New definitions are '0'=0x7F and 
                 '1'=0x81. <[e-mail]>
  06.Mar.96 v3.0 Created new parallelize_...() and serialize_...() functions 
                 which comply to the bitstream definition given in Annex B 
                 of G.192. <[e-mail]>
=============================================================================
*/


/*
 * .................... INCLUDES ....................
 */
#include <string.h> /* For memset() */
#include "ugst-utl.h" /* Module Function prototypes */
 
 
/*
 * .................... FUNCTIONS ....................
 */
 
/*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
        long scale (float *buffer,long smpno,double factor)
        ~~~~~~~~~~
 
        Description:
        ~~~~~~~~~~~~
 
        Gain/loss insertion algorithm that scales the input buffer data
        by a given factor. If the factor is greater than 1.0, it means a
        gain; if less than 1.0, a loss. The basic algorithm is simply:
                              y(k)= x(k) * factor
 
        Please note that:
        > the scaled data is put into the same location of the
          original data, in order to save memory space;
        > input data buffer is an array of floats;
        > scaling precision is single (rather than double).
 
        Variables:
        ~~~~~~~~~~
        Name:        I/0: Type:   Use:
        buffer       I/O  float*  Data vector to be scaled.
        smpno         I   long    Number of samples in "buffer"
        factor        I   float   scaling factor
 
        Internal variables are declared as "register" to improve
        processing velocity.
 
        Return value:
        ~~~~~~~~~~~~~
        Returns the number of scaled samples, as a long.
 
        Functions used:      NONE
        ~~~~~~~~~~~~~~~
 
        Prototype:    in ugst-utl.h
        ~~~~~~~~~~
 
        Author:
        ~~~~~~~
        Simao Ferraz de Campos Neto
        DDS/Pr11                      Tel: [phone]
        CPqD/Telebras                 Fax: [phone]
        13085 Campinas SP Brazil      E-mail: <[e-mail]>
 
        Log of changes:
        ~~~~~~~~~~~~~~~
        Dates        Version        Description
        11.Oct.91      1.0        First release in C.
 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*/
long            scale(buffer, smpno, factor)
  float          *buffer;
  double          factor;
  long            smpno;
{
  register long   j;
  register float  f;
 
  /* scales all of the samples */
  for (f = (float) factor, j = 0; j < smpno; j++)
    buffer[j] *= f;
 
  /* and return the number of scaled samples */
  return (j);
}                  /* ......... end of scale() ......... */
 
 
/*
  --------------------------------------------------------------------------
 
        long fl2sh (long  n, float *x, short *iy,
        ~~~~~~~~~~  double half_lsb, unsigned mask);
 
        Description:
        ~~~~~~~~~~~~
 
        Common quantisation routine. The conversion routine expect the
        floating point data to be in the range between -1 .. +1,
        values outside this range are limited to -1 or +32767.0.
        Quantization is done by taking into account only the
        most significant bits. So the quantized (or converted) data are
        located left justified within the 16-bit word, and the results
        are in the range:
                  -32768,( 1),+32767, if quantized to 16 bit
                  -32768,( 2),+32766, if quantized to 15 bit
                  -32768,( 4),+32763, if quantized to 14 bit
                  -32768,( 8),+32760, if quantized to 13 bit
                  -32768,(16),+32752, if quantized to 12 bit
 
        In some cases one needs truncated data. For example, at the
        input of A-Law encoding, truncation to 12 bit is neccessary, not
        rounding. On the other hand within recursive filters rounding is
        essential. So, for both cases functions have been designed.
 
        Concerning the location of the fixed-point data within one 16
        bit word, it's most practical to have the decimal point
        immediateley after the sign bit (between bit 15 and 14, if the
        bits are ordered from 0 ... 15). Since this is well defined, a
        software, which processes the quantized data  needs no knowledge
        about the resolution of the data. It's not important,  whether
        tha data come out from A- or u-Law decoding routines or from
        12-bit (13,14,16-bit) A/D converters.
 
 
        Parameters:
        ~~~~~~~~~~~
        n .......... is the number of samples in x[];
        x .......... is input float array's pointer;
        iy ......... is output short array's pointer;
        half_lsb ... is the float representation of 0.5 lsb for the
                     desired resolution (quantization);
        mask ....... unsigned masking of the lower (right) bits.
 
        Returns value:
        ~~~~~~~~~~~~~~
        Returns the number of overflows that happened.
 
        Prototype:  in ugst-utl.h
        ~~~~~~~~~~
 
        Original author:
        ~~~~~~~~~~~~~~~~
              Rudolf Hofmann
              Advanced Development Digital Signal Processing
              PHILIPS KOMMUNIKATIONS INDUSTRIE AG
              Kommunikationssysteme
              Thurn-und-Taxis-Strasse 14
              D-8500 Nuernberg 10 (Germany)
 
              Phone : [phone]
              FAX   : [phone]
              EMail : [e-mail]
 
        History:
        ~~~~~~~~
        10.Dec.91 v1.0 Release of 1st version with callable routines for
                       conversion from float to short. <[e-mail]>
        25.Feb.92 v1.1 Change of specific functions to macros (#defines)
                       <[e-mail]>
        28.Feb.92 v1.2 Change of call from short to unsigned for parameter
                       mask, needed in Unix <[e-mail]>
        18.May.92 v1.3 Change to make it operate with input data in the
                       normalized range (-1.0 .. +1.0), instead of floats
                       in the integer range (-32768.0 .. 32767.0).
        27.Nov.92 v1.4 fl2sh() corrected for negative values 
                       <[e-mail]>
 
  --------------------------------------------------------------------------
*/
 
long            fl2sh(n, x, iy, half_lsb, mask)
  long            n;
  float          *x;
  short          *iy;
  double          half_lsb;
  short           mask;
{
  register long   iOvrFlw, k;
  register double y;

  /* Reset overflow counter */
  iOvrFlw = 0;

  /* Loop over all input samples: assume result left justified in array */

  /* ------------------------------------------------------------------------ */
  /* Perform 2's complement truncation if "no rounding" is selected           */
  /* ------------------------------------------------------------------------ */
  if (half_lsb == 0.0)
  {
    for (k = 0; k < n; k++)
    {
      /* Convert input data from normalized to 16-bit range (still float) */
      y = x[k] * 32768;

      /* Amplitude clip */
      if (y > 32767.0)		/* limitation to positive maximum */
      {
	y = 32767.0;
	iOvrFlw += 1;
      }
      else if (y < -32768.0)	/* limitation to negative maximum */
      {
	y = -32768.0;
	iOvrFlw += 1;
      }

      iy[k] = (short) (y);
      iy[k] &= mask;
    }
  }

  /* ---------------------------------------------------------------------- */
  /* Perform Magnitude Rounding                                             */
  /* ---------------------------------------------------------------------- */
  else
  {
    for (k = 0; k < n; k++)
    {
      /* Convert input data from normalized to 16-bit range (still float) */
      y = x[k] * 32768;
      if (y >= 0.0)
	y = y + half_lsb;
      else
	y = y - half_lsb;

      /* Amplitude clip */
      if (y > 32767.0)
      {
	/* limitation to positive maximum */
	y = 32767.0;
	iOvrFlw += 1;
      }
      else if (y < -32768.0)
      {
	/* limitation to negative maximum */
	y = -32768.0;
	iOvrFlw += 1;
      }

      if (y >= 0.0)
      {
	/* conversion to short (16 bit) */
	iy[k] = (short) (y);
	iy[k] &= mask;
      }
      else
      {
	/* if (y < 0.0) */
	iy[k] = (short) (-y);	/* iy will be 0x8000 even if y = -32768.0   */
	iy[k] &= mask;
	iy[k] = -iy[k];
      }
    }
  }

  /* Return number of overflows */
  return iOvrFlw;
}                   /* ......... end of fl2sh() ......... */
 
/*
  --------------------------------------------------------------------------
 
        void sh2fl_alt (long  n, short *ix, float *y, short mask)
        ~~~~~~~~~~~~~~
 
        Description:
        ~~~~~~~~~~~~
 
	Alternate common conversion routine. This conversion routine
	expects the fixed-point data to be in the range -32768..32767.
	Conversion to float is done by taking into account only the
	most significant bits, indicated by 'mask'.  Conversion to
	float results *NECESSARILY* in normalised values in the range
	-1.0 <= y[*] < +1.0. This is an alternate version of the
	sh2fl() as in the STL92 Manual.