ph_disp.cpp

实现3GPP的GSM中AMR语音的CODECS。

/* ------------------------------------------------------------------
 * Copyright (C) 2008 PacketVideo
 *
 * Licensed under the Apache License, Version 2.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.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
 * express or implied.
 * See the License for the specific language governing permissions
 * and limitations under the License.
 * -------------------------------------------------------------------
 */
/****************************************************************************************
Portions of this file are derived from the following 3GPP standard:

    3GPP TS 26.073
    ANSI-C code for the Adaptive Multi-Rate (AMR) speech codec
    Available from http://www.3gpp.org

(C) 2004, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TTA, TTC)
Permission to distribute, modify and use this file under the standard license
terms listed above has been obtained from the copyright holder.
****************************************************************************************/
/*
------------------------------------------------------------------------------



 Pathname: ./audio/gsm-amr/c/src/ph_disp.c
 Functions:
            ph_disp_reset
            ph_disp_lock
            ph_disp_release
            ph_disp

     Date: 04/05/2000

------------------------------------------------------------------------------
 REVISION HISTORY

 Description: Changed template used to PV coding template. First attempt at
          optimizing C code.

 Description: Updated file per comments gathered from Phase 2/3 review.

 Description: Clarified grouping in the equation to calculated L_temp from the
          product of state->prevCbGain and ONFACTPLUS1 in the ph_disp
          function.

 Description: Added setting of Overflow flag in inlined code.

 Description: Synchronized file with UMTS version 3.2.0. Updated coding
              coding template. Removed unnecessary include files.

 Description: Replaced basic_op.h with the header file of the math functions
              used in the file.

 Description: Removed the functions ph_disp_init and ph_disp_exit.
 The ph_disp related structure is no longer dynamically allocated.

 Description: Pass in pointer to overflow flag for EPOC compatibility.
              Change code for ph_disp() function to reflect this. Remove
              inclusion of ph_disp.tab. This table will now be referenced
              externally.

 Description: Optimized ph_disp() to reduce clock cycle usage. Updated
              copyright year and removed unused files in Include section.

 Description:  Replaced OSCL mem type functions and eliminated include
               files that now are chosen by OSCL definitions

 Description:  Replaced "int" and/or "char" with defined types.
               Added proper casting (Word32) to some left shifting operations

 Description: Changed round function name to pv_round to avoid conflict with
              round function in C standard library.

 Description:

------------------------------------------------------------------------------
 MODULE DESCRIPTION

 This file contains the function that performs adaptive phase dispersion of
 the excitation signal. The phase dispersion initialization, reset, and
 exit functions are included in this file, as well as, the phase dispersion
 lock and release functions.

------------------------------------------------------------------------------
*/

/*----------------------------------------------------------------------------
; INCLUDES
----------------------------------------------------------------------------*/
#include "ph_disp.h"
#include "typedef.h"
#include "basic_op.h"
#include "cnst.h"

/*----------------------------------------------------------------------------
; MACROS
; Define module specific macros here
----------------------------------------------------------------------------*/

/*----------------------------------------------------------------------------
; DEFINES
; Include all pre-processor statements here. Include conditional
; compile variables also.
----------------------------------------------------------------------------*/

/*----------------------------------------------------------------------------
; LOCAL FUNCTION DEFINITIONS
; Function Prototype declaration
----------------------------------------------------------------------------*/

/*----------------------------------------------------------------------------
; LOCAL VARIABLE DEFINITIONS
; Variable declaration - defined here and used outside this module
----------------------------------------------------------------------------*/


/*
------------------------------------------------------------------------------
 FUNCTION NAME: ph_disp_reset
------------------------------------------------------------------------------
 INPUT AND OUTPUT DEFINITIONS

 Inputs:
    state = pointer to a structure of type ph_dispState

 Outputs:
    Structure pointed to by state is initialized to zeros

 Returns:
    return_value = 0, if reset was successful; -1, otherwise (int)

 Global Variables Used:
    None

 Local Variables Needed:
    None

------------------------------------------------------------------------------
 FUNCTION DESCRIPTION

 This function resets the variables used by the phase dispersion function.

------------------------------------------------------------------------------
 REQUIREMENTS

 None

------------------------------------------------------------------------------
 REFERENCES

 ph_disp.c, UMTS GSM AMR speech codec, R99 - Version 3.2.0, March 2, 2001

------------------------------------------------------------------------------
 PSEUDO-CODE

int ph_disp_reset (ph_dispState *state)
{
  Word16 i;

   if (state == (ph_dispState *) NULL){
      fprint(stderr, "ph_disp_reset: invalid parameter\n");
      return -1;
   }
   for (i=0; i<PHDGAINMEMSIZE; i++)
   {
       state->gainMem[i] = 0;
   }
   state->prevState = 0;
   state->prevCbGain = 0;
   state->lockFull = 0;
   state->onset = 0;          // assume no onset in start

   return 0;
}

------------------------------------------------------------------------------
 RESOURCES USED [optional]

 When the code is written for a specific target processor the
 the resources used should be documented below.

 HEAP MEMORY USED: x bytes

 STACK MEMORY USED: x bytes

 CLOCK CYCLES: (cycle count equation for this function) + (variable
                used to represent cycle count for each subroutine
                called)
     where: (cycle count variable) = cycle count for [subroutine
                                     name]

------------------------------------------------------------------------------
 CAUTION [optional]
 [State any special notes, constraints or cautions for users of this function]

------------------------------------------------------------------------------
*/

Word16 ph_disp_reset(ph_dispState *state)
{
    register Word16 i;

    if (state == (ph_dispState *) NULL)
    {
        /*  fprint(stderr, "ph_disp_reset: invalid parameter\n");  */
        return(-1);
    }
    for (i = 0; i < PHDGAINMEMSIZE; i++)
    {
        state->gainMem[i] = 0;
    }
    state->prevState = 0;
    state->prevCbGain = 0;
    state->lockFull = 0;
    state->onset = 0;          /* assume no onset in start */

    return(0);
}

/****************************************************************************/

/*
------------------------------------------------------------------------------
 FUNCTION NAME: ph_disp_lock
------------------------------------------------------------------------------
 INPUT AND OUTPUT DEFINITIONS

 Inputs:
    state = pointer to a structure of type ph_dispState

 Outputs:
    lockFull field of the structure pointed to by state is set to 1

 Returns:
    None

 Global Variables Used:
    None

 Local Variables Needed:
    None

------------------------------------------------------------------------------
 FUNCTION DESCRIPTION

 This function sets the lockFull flag to indicate a lock condition.

------------------------------------------------------------------------------
 REQUIREMENTS

 None

------------------------------------------------------------------------------
 REFERENCES

 ph_disp.c, UMTS GSM AMR speech codec, R99 - Version 3.2.0, March 2, 2001

------------------------------------------------------------------------------
 PSEUDO-CODE

void ph_disp_lock (ph_dispState *state)
{
  state->lockFull = 1;
  return;
}

------------------------------------------------------------------------------
 RESOURCES USED [optional]

 When the code is written for a specific target processor the
 the resources used should be documented below.

 HEAP MEMORY USED: x bytes

 STACK MEMORY USED: x bytes

 CLOCK CYCLES: (cycle count equation for this function) + (variable
                used to represent cycle count for each subroutine
                called)
     where: (cycle count variable) = cycle count for [subroutine
                                     name]

------------------------------------------------------------------------------
 CAUTION [optional]
 [State any special notes, constraints or cautions for users of this function]

------------------------------------------------------------------------------
*/

void ph_disp_lock(ph_dispState *state)
{
    state->lockFull = 1;

    return;
}

/****************************************************************************/

/*
------------------------------------------------------------------------------
 FUNCTION NAME: ph_disp_release
------------------------------------------------------------------------------
 INPUT AND OUTPUT DEFINITIONS

 Inputs:
    state = pointer to a structure of type ph_dispState

 Outputs:
    lockFull field of the structure pointed to by state is set to 0

 Returns:
    None

 Global Variables Used:
    None

 Local Variables Needed:
    None

------------------------------------------------------------------------------
 FUNCTION DESCRIPTION

 This function clears the lockFull flag to indicate an unlocked state.

------------------------------------------------------------------------------
 REQUIREMENTS

 None

------------------------------------------------------------------------------
 REFERENCES

 ph_disp.c, UMTS GSM AMR speech codec, R99 - Version 3.2.0, March 2, 2001

------------------------------------------------------------------------------
 PSEUDO-CODE

void ph_disp_release (ph_dispState *state)
{
  state->lockFull = 0;
  return;
}

------------------------------------------------------------------------------
 RESOURCES USED [optional]

 When the code is written for a specific target processor the
 the resources used should be documented below.

 HEAP MEMORY USED: x bytes

 STACK MEMORY USED: x bytes

 CLOCK CYCLES: (cycle count equation for this function) + (variable
                used to represent cycle count for each subroutine
                called)
     where: (cycle count variable) = cycle count for [subroutine
                                     name]

------------------------------------------------------------------------------
 CAUTION [optional]
 [State any special notes, constraints or cautions for users of this function]

------------------------------------------------------------------------------
*/

void ph_disp_release(ph_dispState *state)
{
    state->lockFull = 0;

    return;
}

/****************************************************************************/

/*
------------------------------------------------------------------------------
 FUNCTION NAME: ph_disp
------------------------------------------------------------------------------
 INPUT AND OUTPUT DEFINITIONS

 Inputs:
    state = pointer to a structure of type ph_dispState
    mode = codec mode (enum Mode)
    x = LTP excitation signal buffer (Word16)
    cbGain = codebook gain (Word16)
    ltpGain = LTP gain (Word16)
    inno = innovation buffer (Word16)
    pitch_fac = pitch factor used to scale the LTP excitation (Word16)
    tmp_shift = shift factor applied to sum of scaled LTP excitation and
                innovation before rounding (Word16)
    pOverflow = pointer to overflow indicator (Flag)

 Outputs:
    structure pointed to by state contains the updated gainMem array,
      prevState, prevCbGain, and onset fields
    x buffer contains the new excitation signal
    inno buffer contains the new innovation signal
    pOverflow -> 1 if there is overflow

 Returns:
    None

 Global Variables Used:
    None

 Local Variables Needed:
    None

------------------------------------------------------------------------------
 FUNCTION DESCRIPTION

 This function performs adaptive phase dispersion, i.e., forming of total
 excitation for the synthesis part of the decoder.

------------------------------------------------------------------------------
 REQUIREMENTS

 None

------------------------------------------------------------------------------
 REFERENCES

 ph_disp.c, UMTS GSM AMR speech codec, R99 - Version 3.2.0, March 2, 2001

------------------------------------------------------------------------------
 PSEUDO-CODE

void ph_disp (
      ph_dispState *state, // i/o     : State struct
      enum Mode mode,      // i       : codec mode
      Word16 x[],          // i/o Q0  : in:  LTP excitation signal
                           //           out: total excitation signal
      Word16 cbGain,       // i   Q1  : Codebook gain
      Word16 ltpGain,      // i   Q14 : LTP gain
      Word16 inno[],       // i/o Q13 : Innovation vector (Q12 for 12.2)
      Word16 pitch_fac,    // i   Q14 : pitch factor used to scale the
                                        LTP excitation (Q13 for 12.2)
      Word16 tmp_shift     // i   Q0  : shift factor applied to sum of
                                        scaled LTP ex & innov. before
                                        rounding