CUGL 2.1
Cornell University Game Library
Public Member Functions | Protected Attributes | List of all members
cugl::audio::AudioDecoder Class Referenceabstract

#include <CUAudioDecoder.h>

Inheritance diagram for cugl::audio::AudioDecoder:
cugl::audio::FLACDecoder cugl::audio::MP3Decoder cugl::audio::OGGDecoder cugl::audio::WAVDecoder

Public Member Functions

 AudioDecoder ()
 
 ~AudioDecoder ()
 
virtual bool init (const char *file)
 
virtual bool init (const std::string &file)=0
 
virtual void dispose ()=0
 
double getDuration () const
 
Uint32 getSampleRate () const
 
Uint64 getLength () const
 
Uint32 getChannels () const
 
std::string getFile () const
 
Uint32 getPageSize () const
 
bool ready ()
 
virtual Sint32 pagein (float *buffer)=0
 
Uint64 getPage () const
 
virtual void setPage (Uint64 page)=0
 
Uint64 getPageCount () const
 
void rewind ()
 
Sint32 decode (float *buffer)
 

Protected Attributes

Uint8 _channels
 
Uint32 _rate
 
Uint64 _frames
 
std::string _file
 
Uint32 _pagesize
 
Uint64 _currpage
 
Uint64 _lastpage
 

Detailed Description

This class abstracts an audio codec for decoding.

By providing a single interface for all audio codecs, we make it easy to to support multiple file types. Currently we support four file types: WAV (including ADPCM encodings), MP3, Ogg (Vorbis), and Flac. As a general rule, we prefer WAV for sound effects and Ogg for music.

A decoder breaks up the sound into pages for streaming access. While some codecs refer to pages as "frames', we reserve that term for groups of samples at a single moment in time, as is the case for the rest of the API.

A decoder is NOT thread safe. If a decoder is used by an audio thread, then it should not be accessed directly in the main thread, and vice versa.

Constructor & Destructor Documentation

◆ AudioDecoder()

cugl::audio::AudioDecoder::AudioDecoder ( )

Creates an initialized audio decoder

NEVER USE A CONSTRUCTOR WITH NEW. If you want to allocate an asset on the heap, use one of the static constructors instead.

◆ ~AudioDecoder()

cugl::audio::AudioDecoder::~AudioDecoder ( )
inline

Deletes this decoder, disposing of all resources.

Member Function Documentation

◆ decode()

Sint32 cugl::audio::AudioDecoder::decode ( float *  buffer)

Decodes the entire audio file, storing its value in buffer.

The buffer should be able to hold channels * frames many elements. The data is interpretted as floats and channels are all interleaved. If the method returns -1, then an error occurred during reading.

Parameters
bufferThe buffer to store the audio data
Returns
the number of frames actually read (-1 on error).

◆ dispose()

virtual void cugl::audio::AudioDecoder::dispose ( )
pure virtual

Deletes the decoder resources and resets all attributes.

This will close the associated file. You must reinitialize the decoder to use it.

Implemented in cugl::audio::WAVDecoder, cugl::audio::FLACDecoder, cugl::audio::OGGDecoder, and cugl::audio::MP3Decoder.

◆ getChannels()

Uint32 cugl::audio::AudioDecoder::getChannels ( ) const
inline

Returns the number of channels used by this sound source

A value of 1 means mono, while 2 means stereo. Depending on the file format, other channels are possible. For example, 6 channels means support for 5.1 surround sound.

We support up to 32 possible channels.

Returns
the number of channels used by this sound asset

◆ getDuration()

double cugl::audio::AudioDecoder::getDuration ( ) const
inline

Returns the length of this sound source in seconds.

The accuracy of this method depends on the specific implementation.

Returns
the length of this sound source in seconds.

◆ getFile()

std::string cugl::audio::AudioDecoder::getFile ( ) const
inline

Returns the file for this audio source

This value is the empty string if there was no source file.

Returns
the file for this audio source

◆ getLength()

Uint64 cugl::audio::AudioDecoder::getLength ( ) const
inline

Returns the frame length of this sound source.

The frame length is the duration times the sample rate.

Returns
the frame length of this sound source.

◆ getPage()

Uint64 cugl::audio::AudioDecoder::getPage ( ) const
inline

Returns the current page of this decoder

This value is the next page to be read in with the pagein() command.

Returns
the current page of this decoder

◆ getPageCount()

Uint64 cugl::audio::AudioDecoder::getPageCount ( ) const
inline

Returns the total number of pages in this decoder

This value is the maximum value for the setPage command.

Returns
total number of pages in this decoder

◆ getPageSize()

Uint32 cugl::audio::AudioDecoder::getPageSize ( ) const
inline

Returns the number of frames in a single page of data

When multiplied by the number of channels, this gives the number of samples read per page

Returns
the number of frames in a single page of data

◆ getSampleRate()

Uint32 cugl::audio::AudioDecoder::getSampleRate ( ) const
inline

Returns the sample rate of this sound source.

Returns
the sample rate of this sound source.

◆ init() [1/2]

virtual bool cugl::audio::AudioDecoder::init ( const char *  file)
inlinevirtual

Initializes a new decoder for the given file.

This initializer is an abstract method in the base class. The file is either streamed or completely read into memory according to the specific implementation.

Parameters
filethe source file for the decoder
Returns
true if the decoder was initialized successfully

Reimplemented in cugl::audio::WAVDecoder, cugl::audio::FLACDecoder, cugl::audio::OGGDecoder, and cugl::audio::MP3Decoder.

◆ init() [2/2]

virtual bool cugl::audio::AudioDecoder::init ( const std::string &  file)
pure virtual

Initializes a new decoder for the given file.

This initializer is an abstract method in the base class. The file is either streamed or completely read into memory according to the specific implementation.

Parameters
filethe source file for the decoder
Returns
true if the decoder was initialized successfully

Implemented in cugl::audio::WAVDecoder, cugl::audio::FLACDecoder, cugl::audio::OGGDecoder, and cugl::audio::MP3Decoder.

◆ pagein()

virtual Sint32 cugl::audio::AudioDecoder::pagein ( float *  buffer)
pure virtual

Reads a page of data into the provided buffer.

The buffer should be able to hold channels * page size many elements. The data is interpretted as floats and channels are all interleaved. If a full page is read, this method should return the page size. If it reads less, it will return the number of frames read. It will return -1 on a processing error.

Parameters
bufferThe buffer to store the audio data
Returns
the number of frames actually read (-1 on error).

Implemented in cugl::audio::WAVDecoder, cugl::audio::FLACDecoder, cugl::audio::OGGDecoder, and cugl::audio::MP3Decoder.

◆ ready()

bool cugl::audio::AudioDecoder::ready ( )
inline

Returns true if there are still data to be read by the decoder

This value will return false if the decoder is at the end of the file

Returns
true if there are still data to be read by the decoder

◆ rewind()

void cugl::audio::AudioDecoder::rewind ( )
inline

Rewinds this decoder back the beginning of the stream

◆ setPage()

virtual void cugl::audio::AudioDecoder::setPage ( Uint64  page)
pure virtual

Sets the current page of this decoder

This value is the next page to be read in with the pagein() command. If the page is greater than the total number of pages, it will be set just beyond the last page.

Parameters
pageThe new page of this decoder

Implemented in cugl::audio::WAVDecoder, cugl::audio::OGGDecoder, cugl::audio::FLACDecoder, and cugl::audio::MP3Decoder.

Member Data Documentation

◆ _channels

Uint8 cugl::audio::AudioDecoder::_channels
protected

The number of channels in this sound source (max 32)

◆ _currpage

Uint64 cugl::audio::AudioDecoder::_currpage
protected

The current page in the stream

◆ _file

std::string cugl::audio::AudioDecoder::_file
protected

The source for this buffer (may be empty)

◆ _frames

Uint64 cugl::audio::AudioDecoder::_frames
protected

The number of frames in this sounds source

◆ _lastpage

Uint64 cugl::audio::AudioDecoder::_lastpage
protected

The previous page in the stream

◆ _pagesize

Uint32 cugl::audio::AudioDecoder::_pagesize
protected

The size of a decoder chunk

◆ _rate

Uint32 cugl::audio::AudioDecoder::_rate
protected

The sampling rate (frequency) of this sound source


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