parrocchetto/firmware.X/include/G726A.h

/**************************************************************************
*  
*             ITU-T SOFTWARE TOOLS' GENERAL PUBLIC LICENSE                  
*
*  This "General Public License" is published in the Annex 1 of the
*  ITU-T Recommendation on "SOFTWARE TOOLS FOR HOMOGENITY OF RESULTS
*  IN THE STANDARDIZATION PROCESS OF SPEECH AND AUDIO CODERS",
*  approved in Geneva, 2000.
*
*  TERMS AND CONDITIONS
*
*  1. This License Agreement applies to any module or other work
*  related to the ITU-T Software Tool Library, and developed by the
*  User's Group on Software Tools. The "Module", below, refers to any
*  such module or work, and a "work based on the Module" means either
*  the Module or any work containing the Module or a portion of it,
*  either verbatim or with modifications.  Each licensee is addressed
*  as "you".
*
*  2. You may copy and distribute verbatim copies of the Module's
*  source code as you receive it, in any medium, provided that you:
*  -  conspicuously and appropriately publish on each copy an appropriate
*     copyright notice and disclaimer of warranty;
*  -  keep intact all the notices that refer to this General Public
*     License and to the absence of any warranty; and
*  -  give any other recipients of the Module a copy of this General
*     Public License along with the Module.
*  You may charge a fee for the physical act of transferring a copy.
*
*  3. You may modify your copy or copies of the Module or any portion
*  of it, and copy and distribute such modifications under the terms
*  of Paragraph 1 above, provided that you also do the following:
*
*      o  cause the modified files to carry prominent notices stating
*      that you changed the files and the date of any change; and
*
*      o  cause the whole of any work that you distribute or publish,
*      that in whole or in part contains the Module or any part
*      thereof, either with or without modifications, to be licensed
*      at no charge to all third parties under the terms of this
*      General Public License (except that you may choose to grant
*      warranty protection to some or all third parties, at your
*      option).
*
*      o  If the modified module normally reads commands interactively
*      when run, you must cause it, when started running for such
*      interactive use in the simplest and most usual way, to print or
*      display an announcement including an appropriate copyright
*      notice and a notice that there is no warranty (or else, saying
*      that you provide a warranty) and that users may redistribute
*      the module under these conditions, and telling the user how to
*      view a copy of this General Public License.
*
*  You may charge a fee for the physical act of transferring a copy,
*  and you may at your option offer warranty protection in exchange
*  for a fee.
*
*  Mere aggregation of another independent work with the Module (or
*  its derivative) on a volume of a storage or distribution medium
*  does not bring the other work under the scope of these terms.
*
*  4.  You may copy and distribute the Module (or a portion or
*  derivative of it, under Paragraph 2) in object code or executable
*  form under the terms of Paragraphs 1 and 2 above provided that you
*  also do one of the following:
*
*      o  accompany it with the complete corresponding machine-
*      readable source code, which must be distributed under the terms
*      of Paragraphs 1 and 2 above; or,
*
*      o  accompany it with a written offer, valid for at least three
*      years, to give any third party free (except for a nominal
*      charge for the cost of distribution) a complete machine-
*      readable copy of the corresponding source code, to be
*      distributed under the terms of Paragraphs 1 and 2 above; or,
*
*      o  accompany it with the information you received as to where
*      the corresponding source code may be obtained.  (This
*      alternative is allowed only for noncommercial distribution and
*      only if you received the module in object code or executable
*      form alone.) 
*
*  Source code for a work means the preferred form of the work for
*  making modifications to it.  For an executable file, complete
*  source code means all the source code for all modules it contains;
*  but, as a special exception, it need not include source code for
*  modules which are standard libraries that accompany the operating
*  system on which the executable file runs, or for standard header
*  files or definitions files that accompany that operating system.
*
*  5.  You may not copy, modify, sublicense, distribute or transfer
*  the Module except as expressly provided under this General Public
*  License. Any attempt otherwise to copy, modify, sublicense,
*  distribute or transfer the Module is void, and will automatically
*  terminate your rights to use the Module under this License. 
*  However, parties who have received copies, or rights to use copies,
*  from you under this General Public License will not have their
*  licenses terminated so long as such parties remain in full
*  compliance.
*
*  6.  By copying, distributing or modifying the Module (or any work
*  based on the Module) you indicate your acceptance of this license
*  to do so, and all its terms and conditions.
*
*  7.  Each time you redistribute the Module (or any work based on the
*  Module), the recipient automatically receives a license from the
*  original licensor to copy, distribute or modify the Module subject
*  to these terms and conditions.  You may not impose any further
*  restrictions on the recipients' exercise of the rights granted
*  herein.
*
*  8.  The ITU-T may publish revised and/or new versions of this
*  General Public License from time to time.  Such new versions will
*  be similar in spirit to the present version, but may differ in
*  detail to address new problems or concerns.
*
*  Each version is given a distinguishing version number. If the
*  Module specifies a version number of the license which applies to
*  it and "any later version", you have the option of following the
*  terms and conditions either of that version or of any later version
*  published by the ITU-T. If the Module does not specify a version
*  number of the license, you may choose any version ever published by
*  the ITU-T.
*
*  9.  If you wish to incorporate parts of the Module into other free
*  modules whose distribution conditions are different, write to the
*  author to ask for permission.  For software which is copyrighted by
*  the ITU-T, write to the ITU-T Secretariat; exceptions may be made
*  for this. This decision will be guided by the two goals of
*  preserving the free status of all derivatives of this free software
*  and of promoting the sharing and reuse of software generally.
*
*
*  NO WARRANTY
*
*  10. BECAUSE THE MODULE IS LICENSED FREE OF CHARGE, THERE IS NO
*  WARRANTY FOR THE MODULE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. 
*  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS
*  AND/OR OTHER PARTIES PROVIDE THE MODULE "AS IS" WITHOUT WARRANTY OF
*  ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED
*  TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
*  PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND
*  PERFORMANCE OF THE MODULE IS WITH YOU.  SHOULD THE MODULE PROVE
*  DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR
*  OR CORRECTION.
*
*  11. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
*  WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
*  MODIFY AND/OR REDISTRIBUTE THE MODULE AS PERMITTED ABOVE, BE LIABLE
*  TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
*  CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
*  THE MODULE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
*  RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR
*  A FAILURE OF THE MODULE TO OPERATE WITH ANY OTHER MODULES), EVEN IF
*  SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
*  SUCH DAMAGES.
*
*  END OF TERMS AND CONDITIONS
***************************************************************************/
#ifndef _G726_H_
#define _G726_H_

/********************************
 * This defines the size of the
 * G.726A encoder state structure
 * in bytes.
 ********************************/
#define G726A_ENCODER_SIZE		76

/*********************************
 * This defines the size of the 
 * G.726A decoder state structure
 * in bytes.
 *********************************/
#define G726A_DECODER_SIZE		76

//***************************************************************
/* G726A_BIT_RATES

  Summary:
    Identifies the supported G.726A encoder and decoder
    bit rates.

  Description:
    This enumeration identifies the supported G.726A encoder
    and decoder bit rates. The bit rates for the encoder and
    decoder are specified at the time of encoder and decoder
    intialization.
*/

typedef enum
{
    // G.726A Encoder/Decoder work at 16kbps.
    // 2 LSBs of encoded byte are significant
    // Compression ratio 7:1
    G726A_16KBPS=2,     
    // G.726A Encoder/Decoder work at 24kbps.
    // 3 LSBs of encoded byte are significant
    // Compression ratio 4.6:1
    G726A_24KBPS=3,     
    // G.726A Encoder/Decoder work at 32kbps.
    // 4 LSBs of encoded byte are significant
    // Compression ratio 3.5:1
    G726A_32KBPS=4,     
    // G.726A Encoder/Decoder work at 40kbps.
    // 5 LSBs of encoded byte are significant
    // Compression ratio 2.8:1
    G726A_40KBPS=5      

}G726A_BIT_RATES;
//******************************************************************

/********************************
 * This defines the size of G.726A
 * encoder input frame size in samples
 * and is user definable. Minimum
 * size is 1.
 *********************************/
#define G726A_FRAME_SIZE	256

//-----------------------------------------------------------------------------
//FUNCTION PROTOTYPES
//-----------------------------------------------------------------------------

/*******************************************************************************
  Function:
    void G726AEncoderInit(unsigned char * encoder,G726A_BIT_RATES rate, 
                            int frameSize);

  Summary:
    This routine allows intializes a G.726A encoder to operate at the specified
    output bit rate and input frame size. 

  Description:
    This routine intializes a G.726A encoder to operate at the specified
    output bit rate and input frame size. Multiple encoders can instantiated, 
    each encoder operating at its own bit rate and it own input frame size. 
  
  Precondition:
    The encoder state memory for each decoder should have been allocated. 

  Parameters:
    encoder      - Encoder state memory.
    
    rate         - Specifies the bit rate at which the encoder will operate.

    frameSize    - Specifies the encoder input frame size in samples.
    
  Returns:
    None.

  Example:
    <code>
    
     // This code snippet shows how to initialize two G.726A
     // encoders, one to operate at 16kbps and  and the 
     // other to work at 24kbps. Note the state
     // memory sizes for both encoders is the same. The
     // input frame size for each encoder can be different.

    unsigned char encoder16kbps[G726A_ENCODER_SIZE];
    unsigned char encoder24kbps[G726A_ENCODER_SIZE];

    G726AEncoderInit(encoder16kbps, G726A_16KBPS, G726A_FRAME_SIZE);
    G726AEncoderInit(encoder24kbps, G726A_24KBPS, G726A_FRAME_SIZE);

    </code>

  Remarks:
    None.
  *****************************************************************************/
void G726AEncoderInit(unsigned char * encoder,G726A_BIT_RATES rate, int frameSize);

/*******************************************************************************
  Function:
    void G726ADecoderInit(unsigned char * decoder,G726A_BIT_RATES rate, 
                            int frameSize);

  Summary:
    This routine intializes a G.726A decoder to operate at the specified output
    bit rate and input frame size. 

  Description:
    This routine intializes a G.726A decoder to operate at the specified
    output bit rate and input frame size. Multiple decoders can instantiated, 
    each decoder operating at its own bit rate and it own input frame size. 
  
  Precondition:
    The decoder state memory for each decoder should have been allocated. 

  Parameters:
    decoder      - Decoder state memory.
    
    rate         - Specifies the bit rate at which the decoder will operate.

    frameSize    - Specifies the decoder input frame size in samples.
    
  Returns:
    None.

  Example:
    <code>
    
     // This code snippet shows how to initialize two G.726A
     // decoders, one to operate at 16kbps and  and the 
     // other to work at 24kbps. Note the state
     // memory sizes for both decoders is the same. The
     // input frame size for each decoder can be different.

    unsigned char decoder16kbps[G726A_DECODER_SIZE];
    unsigned char decoder24kbps[G726A_DECODER_SIZE];

    G726ADecoderInit(decoder16kbps, G726A_16KBPS, G726A_FRAME_SIZE);
    G726ADecoderInit(decoder24kbps, G726A_24KBPS, G726A_FRAME_SIZE);

    </code>

  Remarks:
    None.
  *****************************************************************************/
void G726ADecoderInit(unsigned char * decoder,G726A_BIT_RATES rate, int frameSize);

/*******************************************************************************
  Function:
    void G726AEncode(unsigned char * encoder, int * inputFrame, 
                    unsigned char * outputFrame);
 
  Summary:
    This routine encodes one input frame. 

  Description:
    This routine encodes one input frame. The size of the frame and the bit rate
    to be used should have been defined during encoder initialization. Irrespective
    of the bit rate used, each output sample requires one byte. Therefore, the 
    output array should be an unsigned char array of the same size as the input array.
    Note that the input to the encode function should be a 14 bit signed integer as
    specified by the ITU-T G.726A specification.
  
  Precondition:
    The encoder state memory should have been intialized.

  Parameters:
    encoder      - Encoder state memory.
    
    inputFrame   - Input array containing samples to be encoded. The samples
                   should be 14 bit signed integer values. The size of the 
                   array should match the encoder frame size specified during 
                   encoder initialization.

    outputFrame  - Output array where the encoded samples will be stored. Each
                   byte of output array will store one encoded sample. Depending
                   on the selected encoder bit rate, only certain number of LSBs
                   in the output sample byte will be significant. Refer to the
                   G726A_BIT_RATES type for details. 
    
  Returns:
    None.

  Example:
    <code>
    
    // This code snippet demonstartes how to use the
    // G.726A encoder. The encoder is first initialized
    // and then the encode function is used to encode
    // the input. Note the input and output array size
    // and types. The input should be right  shifted by
    // 2 bits for 16 bit values. This will make the input 
    // 14 bit as required by the encoder.


    unsigned char encoder16kbps[G726A_ENCODER_SIZE];
    int input[G726A_FRAME_SIZE];
    unsigned char output[G726A_FRAME_SIZE];
    int i;

    G726AEncoderInit(encoder16kbps, G726A_16KBPS, G726A_FRAME_SIZE);

    for(i = 0; i < G726A_FRAME_SIZE; i ++)
    {
        // Not necessary if its known that input
        // is 14 bits or less.

        input[i] = input[i] >> 2;
    }

    G726AEncode(encoder16kbps, input, output);

    </code>

  Remarks:
    None.
  *****************************************************************************/
void G726AEncode(unsigned char * encoder, int * inputFrame, unsigned char * outputFrame);

/*******************************************************************************
  Function:
    void G726ADecode(unsigned char * decoder, unsigned char * inputFrame, 
        int * outputFrame);
 
  Summary:
    This routine decodes one input frame. 

  Description:
    This routine decodes one input frame. The size of the frame and the bit rate
    to be used should have been defined during decoder initialization. The 
    input array should be an unsigned char array of the same size as the output array.
    Note that the output of the decode function will be a 14 bit signed integer as
    specified by the ITU-T G.726A specification.  
  
  Precondition:
    The decoder state memory should have been intialized.

  Parameters:
    decoder      - Decoder state memory.
    
    inputFrame   - Input array containing samples to be decoded. The samples
                   should have been encoded using the same bit rate as decoder
                   bit rate. The encoded samples should be arranged such that
                   one element of the array holds one encoded sample. 

    outputFrame  - Output array where the decoded samples will be stored. The 
                   decoded value is a 14 bit signed integer value.  
    
  Returns:
    None.

  Example:
    <code>
    
    // This code snippet demonstrates how to use the
    // G.726A decoder. The decoder is first initialized
    // and then the decode function is used to decode
    // the input. Note the input and output array
    // size and types. The output array can be left
    // shifted by 2 bits to scale up the 14 bit output
    // value to 16 bit.

    unsigned char decoder16kbps[G726A_DECODER_SIZE];
    int output[G726A_FRAME_SIZE];
    unsigned char input[G726A_FRAME_SIZE];

    G726ADecoderInit(decoder16kbps, G726A_16KBPS, G726A_FRAME_SIZE);
    G726ADecode(decoder16kbps, input, output);

    for(i = 0; i < G726A_FRAME_SIZE; i ++)
    {
        // Not necessary if the input to encoder
        // which generated the encoded samples
        // where not right shifted.

        output[i] = output[i] << 2;
    }

    </code>

  Remarks:
    None.
  *****************************************************************************/
void G726ADecode(unsigned char * decoder, unsigned char * inputFrame, int * outputFrame);


#endif                  /* _G726_H_ */
/* .......................... End of G726a.H ........................... */