CrystalSpace

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.

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:

Generated for Crystal Space 2.0 by doxygen 1.6.1