Public API Reference

CS::SndSys::PCMSampleConverter Class Reference

A PCMSampleConverter object converts PCM data from one format to another. More...

#include <csplugincommon/sndsys/convert.h>

List of all members.

Public Member Functions
int	ConvertBuffer (const void *source, size_t source_len, void *dest, int dest_channels, int dest_bitspersample, int dest_frequency)
	Convert a buffer of PCM data from the currently set source format to the desired dest format.
int	GetRequiredOutputBufferMultiple (int dest_channels, int dest_bitspersample, int dest_frequency)
	Return a multiplier that relates input buffer samples/size to output buffer samples/size.
	PCMSampleConverter (int source_channels, int source_bitspersample, int source_frequency, bool swap16=false)
	Create a PCMSampleConverter with initial source properties provided.
void	SetSourceProperties (int source_channels, int source_bitspersample, int source_frequency)
	Adjust the source properties for data being presented in the next call to ConvertBuffer.
Protected Attributes
int	last_sample [CS_SOUND_ELEMENT_MAX_CHANNELS]
int	position_offset
int	src_bytes
int	src_channels
int	src_frequency
bool	swap_16

---

Detailed Description

A PCMSampleConverter object converts PCM data from one format to another.

The converter can convert between different number of channels, bits per sample and sampling frequency.

UNCOMPRESSED PCM SAMPLES ONLY!

8 and 16 bit samples are supported.

When converting between streams with different numbers of channels, mono source streams will have audio data copied to the second channel. If the destination is a stereo (2 channel) output, this will duplicate the mono/left stream onto the right stream. Additional channels will be left in silence. Converting a mono sample to a 5.1 sample will result in identical samples in streams 0 and 1 and silence in all other streams.

Frequency conversion is performed using linear interpolation between adjacent samples. If a direct-ratio conversion is performed (for example, if a 44100 khz stream is converted into a 11025 stream) then only direct data points will be considered and the rest will be thrown out.

Frequency conversion can be used to alter the playback speed of stream. If the output format should be 22050 khz and you specify 11025 khz, the sound will play twice as fast (no, this isn't a typo - the slower output data is read at a faster rate, causing the data to be traversed faster). Internally, speed can be stepped in 1/CS_SOUND INTERNAL_FREQUENCY_DIVISOR increments from the source frequency. This means if you specify more accurate than this increment, truncation to the next lowest value will occur. If you have a source at 44100 khz and specify an output at 44101 khz, the rate will most likely be reduced to 44100 khz - so no frequency conversion will take place.

Beware of very high frequency conversion rates! If your source audio is of poor sampling rate (11025 khz), increasing the speed of playback will make it sound worse! At some point it will degenerate into indistinguishable noise. If you intend to speed up playback it's best to start with a higher sampling rate (44100 khz).

Definition at line 101 of file convert.h.

---

Constructor & Destructor Documentation

CS::SndSys::PCMSampleConverter::PCMSampleConverter	(	int	source_channels,
		int	source_bitspersample,
		int	source_frequency,
		bool	swap16 = false
	)

Create a PCMSampleConverter with initial source properties provided.

---

Member Function Documentation

int CS::SndSys::PCMSampleConverter::ConvertBuffer	(	const void *	source,
		size_t	source_len,
		void *	dest,
		int	dest_channels,
		int	dest_bitspersample,
		int	dest_frequency
	)

Convert a buffer of PCM data from the currently set source format to the desired dest format.

Parameters:

	source
	source_len
	dest
	dest_channels
	dest_bitspersample
	dest_frequency

int CS::SndSys::PCMSampleConverter::GetRequiredOutputBufferMultiple	(	int	dest_channels,
		int	dest_bitspersample,
		int	dest_frequency
	)

Return a multiplier that relates input buffer samples/size to output buffer samples/size.

Note that in many cases one extra source sample should be presumed to be present. To be safe, use ((source_samples+1)*source_sample_size*GetRequiredOutputBufferMultiple()) for the size. The value returned will be constant for a given source format and destination format.

Parameters:

	dest_channels
	dest_bitspersample
	dest_frequency

void CS::SndSys::PCMSampleConverter::SetSourceProperties	(	int	source_channels,
		int	source_bitspersample,
		int	source_frequency
	)

Adjust the source properties for data being presented in the next call to ConvertBuffer.

This is primarily intended for variable-rate audio formats such as some Ogg and MP3 files.

Remarks:

At this time this function does not properly consider the transition between formats at the proper location and instead presumes the transition is at the last "step" from the previous buffer.

Parameters:

	source_channels
	source_bitspersample
	source_frequency

---

The documentation for this class was generated from the following file:

• csplugincommon/sndsys/convert.h

---