ima_adpcm.h

Tixys source code, include G.711, G.726, IMA-ADPCM etc.

/**
@file

@brief Implementation of the IMA ADPCM audio coding algorithm

For latest source code see http://www.tixy.clara.net/source/

Copyright (C) 2005 J.D.Medhurst (a.k.a. Tixy)

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
*/

#ifndef __IMA_ADPCM_H__
#define __IMA_ADPCM_H__

/**
@defgroup ima_adpcm Audio Codec - IMA ADPCM
@{
*/

/**
@brief A class which implements the IMA ADPCM audio coding algorithm.

Typically, IMA ADPCM data is stored as blocks of data with the #PredictedValue
and #StepIndex values held in a header to each block. When decoding, these values
should be writen to this class to initialise the decoding of a block. When encoding, 
these values should be writen out to a block's header prior to encoding the samples
in the block.

Note, when IMA ADPCM data is stored in Microsoft WAV files, the #PredictedValue
found in the block's header is used as the first sample for that block. The first ADPCM
value in the block's data then represents the second sample.
*/
class IMA_ADPCM
	{
public:
	/**
	Initialise the #PredictedValue and #StepIndex members to the
	optimum values for encoding an audio stream whoes first two PCM samples have the
	values given. Use of this method at the start of audio stream encoding gives
	improved accuracy over a naive initialisation which sets #PredictedValue
	and #StepIndex to predetermined constant values.

	@param sample1 The first PCM sample in the audio stream.
	@param sample2 The second PCM sample in the audio stream.
	*/
	IMPORT void EncodeInit(int16 sample1,int16 sample2);

	/**
	Encode a single linear PCM sample as an ADPCM value.

	@param pcm16 The PCM value to encode.

	@return The 4 least significan bits represent the encoded ADPCM value.
			Other bits are zero.

	@post #PredictedValue and #StepIndex are updated ready
		  for encoding the next sample.
	*/
	IMPORT uint Encode(int16 pcm16);

	/**
	Decode a single ADPCM value into a 16bit linear PCM value.

	@param adpcm The 4 least significan bits represent ADPCM value to encode. 
				 Other bits are ignored.

	@return The decoded 16 bit PCM value sign extended to an int.

	@post #PredictedValue and #StepIndex are updated ready
		  for decoding the next sample.
	*/
	IMPORT int Decode(uint adpcm);

	/**
	Encode a buffer of 16 bit uniform PCM values into ADPCM values.

	Two ADPCM values are stored in each byte. The value stored in bits 0-3
	corresponds to the sample preceding that stored in bits 4-7.
	Note, if the last encoded ADPCM value is stored in bits 0-3, then bits 4-7
	will be cleared to zero.

	@param dst		 Pointer to location to store ADPCM values.
	@param dstOffset Offset from \a dst, in number-of-bits, at which the decoded values
					 will be stored. I.e. the least significant bit of the first ADPCM
					 value will be stored in byte 
					 @code	 dst[dstOffset>>3]	 @endcode
					 at bit position
					 @code	 dstOffset&7		 @endcode
					 Where the bit 0 is the least significant bit in a byte
					 and bit 7 is the most significant bit.
					 The value of \a dstOffset must be a multiple of 4.
	@param src		 Pointer to the buffer of PCM values to be converted.
	@param srcSize	 The size, in bytes, of the buffer at \a src.
					 Must be a multiple of 2.

	@return 		 The number of bits which were stored at dst.
	*/
	IMPORT uint Encode(uint8* dst, int dstOffset, const int16* src, uint srcSize);

	/**
	Decode a buffer of ADPCM values into 16 bit uniform PCM values.

	Two ADPCM values are stored in each byte. The value stored in bits 0-3
	corresponds to the sample preceding that stored in bits 4-7.

	@param dst		 Pointer to location to store PCM values.
	@param src		 Pointer to the buffer of ADPCM values to be converted.
	@param srcOffset Offset from \a src, in number-of-bits, from which the ADPCM values
					 will be read. I.e. the least significant bit of the first ADPCM
					 value will be read from byte 
					 @code	 src[srcOffset>>3]	 @endcode
					 at bit position
					 @code	 srcOffset&7		 @endcode
					 Where the bit 0 is the least significant bit in a byte
					 and bit 7 is the most significant bit.
					 The value of \a srcOffset must be a multiple of 4.
	@param srcSize	 The number of bits to be read from the buffer at \a src.
					 Must be a multiple of the size of 4.

	@return 		 The number of bytes which were stored at dst.
	*/
	IMPORT uint Decode(int16* dst, const uint8* src, int srcOffset, uint srcSize);
public:
	/**
	The predicted value of the next sample.
	Typically, this value is read from the header, or written to the header, of a block
	of ADPCM values.
	*/
	int16 PredictedValue;

	/**
	The step index used for the next ADPCM value
	Typically, this value is read from the header, or written to the header, of a block
	of ADPCM values.
	*/
	uint8 StepIndex;
	};

/** @} */ // End of group

#endif