CUGL 2.0
Cornell University Game Library
Public Member Functions | Static Public Member Functions | Protected Attributes | List of all members
cugl::audio::FLACDecoder Class Reference

#include <CUFLACDecoder.h>

Inheritance diagram for cugl::audio::FLACDecoder:
cugl::audio::AudioDecoder

Public Member Functions

 FLACDecoder ()
 
 ~FLACDecoder ()
 
bool init (const char *file) override
 
bool init (const std::string &file) override
 
void dispose () override
 
Sint32 pagein (float *buffer) override
 
void setPage (Uint64 page) override
 
FLAC__StreamDecoderReadStatus doRead (FLAC__byte buffer[], size_t *bytes)
 
FLAC__StreamDecoderSeekStatus doSeek (FLAC__uint64 offset)
 
FLAC__StreamDecoderTellStatus doTell (FLAC__uint64 *offset)
 
FLAC__StreamDecoderLengthStatus doSize (FLAC__uint64 *length)
 
FLAC__StreamDecoderWriteStatus doWrite (const FLAC__Frame *frame, const FLAC__int32 *const buffer[])
 
FLAC__bool isEOF ()
 
void doMeta (const FLAC__StreamMetadata *metadata)
 
void doError (FLAC__StreamDecoderErrorStatus status)
 
- Public Member Functions inherited from cugl::audio::AudioDecoder
 AudioDecoder ()
 
 ~AudioDecoder ()
 
double getDuration () const
 
Uint32 getSampleRate () const
 
Uint64 getLength () const
 
Uint32 getChannels () const
 
std::string getFile () const
 
Uint32 getPageSize () const
 
bool ready ()
 
Uint64 getPage () const
 
Uint64 getPageCount () const
 
void rewind ()
 
Sint32 decode (float *buffer)
 

Static Public Member Functions

static std::shared_ptr< AudioDecoderalloc (const char *file)
 
static std::shared_ptr< AudioDecoderalloc (const std::string &file)
 

Protected Attributes

SDL_RWops * _source
 
FLAC__StreamDecoder * _decoder
 
Sint32 * _buffer
 
Uint64 _buffsize
 
Uint64 _bufflast
 
Uint32 _sampsize
 
- Protected Attributes inherited from cugl::audio::AudioDecoder
Uint8 _channels
 
Uint32 _rate
 
Uint64 _frames
 
std::string _file
 
Uint32 _pagesize
 
Uint64 _currpage
 
Uint64 _lastpage
 

Detailed Description

This class represents an FLAC decoder.

This class only supports native file encodings. It does not support FLAC data encoded in an Ogg file container. In addition, the FLAC data must have a complete stream info header containing the size and channel data.

FLAC supports up to 8 channels (7.1 stereo), though SDL is limited to 6 channels (5.1 stereo). Flac channel interleavings are compatible with SDL, so they are preserved.

FLAC files are not guaranteed to have uniform page sizes. This decoder tries to balance memory requirements with efficiency in paging frame data.

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

◆ FLACDecoder()

cugl::audio::FLACDecoder::FLACDecoder ( )

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.

◆ ~FLACDecoder()

cugl::audio::FLACDecoder::~FLACDecoder ( )

Deletes this decoder, disposing of all resources.

Member Function Documentation

◆ alloc() [1/2]

static std::shared_ptr<AudioDecoder> cugl::audio::FLACDecoder::alloc ( const char *  file)
inlinestatic

Creates a newly allocated decoder for the given FLAC file.

This method will fail and return nullptr if the file does not have a properly formed stream info header.

Parameters
filethe source file for the decoder
Returns
a newly allocated decoder for the given FLAC file.

◆ alloc() [2/2]

static std::shared_ptr<AudioDecoder> cugl::audio::FLACDecoder::alloc ( const std::string &  file)
static

Creates a newly allocated decoder for the given FLAC file.

This method will fail and return nullptr if the file does not have a properly formed stream info header.

Parameters
filethe source file for the decoder
Returns
a newly allocated decoder for the given FLAC file.

◆ dispose()

void cugl::audio::FLACDecoder::dispose ( )
overridevirtual

Deletes the decoder resources and resets all attributes.

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

Implements cugl::audio::AudioDecoder.

◆ doError()

void cugl::audio::FLACDecoder::doError ( FLAC__StreamDecoderErrorStatus  status)

Records an error in the underlying decoder

This method does not abort decoding. Instead, it records the error with SDL_SetError for later retrieval.

Parameters
statusThe error status.
Returns
the callback status (error or continue)

◆ doMeta()

void cugl::audio::FLACDecoder::doMeta ( const FLAC__StreamMetadata *  metadata)

Performs a write of the file metadata

This method is called when the decoder is initialized to query the stream info data. This is how the decoder gathers the important decoding information like sample rate and channel layout.

Parameters
metadataThe file metadata.
Returns
the callback status (error or continue)

◆ doRead()

FLAC__StreamDecoderReadStatus cugl::audio::FLACDecoder::doRead ( FLAC__byte  buffer[],
size_t *  bytes 
)

Performs a read of the underlying file stream for the FLAC decoder

This method abstracts the file access to allow us to read the asset on non-standard platforms (e.g. Android). If method reads less than the requested number of bytes, the actual value is stored in the provided parameter pointer.

Parameters
bufferThe buffer to start the data read
bytesThe number of bytes to read
Returns
the callback status (error or continue)

◆ doSeek()

FLAC__StreamDecoderSeekStatus cugl::audio::FLACDecoder::doSeek ( FLAC__uint64  offset)

Performs a seek of the underlying file stream for the FLAC decoder

This method abstracts the file access to allow us to read the asset on non-standard platforms (e.g. Android). The offset provided is from the file beginning (e.g. SEEK_SET).

Parameters
offsetThe number of bytes from the beginning of the file
Returns
the callback status (error or continue)

◆ doSize()

FLAC__StreamDecoderLengthStatus cugl::audio::FLACDecoder::doSize ( FLAC__uint64 *  length)

Performs a length computation of the underlying file for the FLAC decoder

This method abstracts the file access to allow us to read the asset on non-standard platforms (e.g. Android). The value computed is the length in bytes. The value read is stored in the provided parameter pointer.

Parameters
lengthThe pointer to store the file length
Returns
the callback status (error or continue)

◆ doTell()

FLAC__StreamDecoderTellStatus cugl::audio::FLACDecoder::doTell ( FLAC__uint64 *  offset)

Performs a tell of the underlying file stream for the FLAC decoder

This method abstracts the file access to allow us to read the asset on non-standard platforms (e.g. Android). The value computed is the file offset relative to the beginning of the file. The value read is stored in the provided parameter pointer.

Parameters
offsetThe pointer to store the offset from the beginning
Returns
the callback status (error or continue)

◆ doWrite()

FLAC__StreamDecoderWriteStatus cugl::audio::FLACDecoder::doWrite ( const FLAC__Frame *  frame,
const FLAC__int32 *const  buffer[] 
)

Performs a write of decoded sample data

This method is the primary write method for decoded sample data. The data is converted to a float format and stored in the backing buffer for later access.

Parameters
frameThe frame header for the current data block
bufferThe decoded samples for this block
Returns
the callback status (error or continue)

◆ init() [1/2]

bool cugl::audio::FLACDecoder::init ( const char *  file)
inlineoverridevirtual

Initializes a new decoder for the given FLAC file.

This method will fail if the file does not have a properly formed stream info header.

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

Reimplemented from cugl::audio::AudioDecoder.

◆ init() [2/2]

bool cugl::audio::FLACDecoder::init ( const std::string &  file)
overridevirtual

Initializes a new decoder for the given FLAC file.

This method will fail if the file does not have a properly formed stream info header.

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

Implements cugl::audio::AudioDecoder.

◆ isEOF()

FLAC__bool cugl::audio::FLACDecoder::isEOF ( )

Performs an eof computation of the underlying file for the FLAC decoder

This method abstracts the file access to allow us to read the asset on non-standard platforms (e.g. Android).

Returns
true if the stream is at the end of the file

◆ pagein()

Sint32 cugl::audio::FLACDecoder::pagein ( float *  buffer)
overridevirtual

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).

Implements cugl::audio::AudioDecoder.

◆ setPage()

void cugl::audio::FLACDecoder::setPage ( Uint64  page)
overridevirtual

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

Implements cugl::audio::AudioDecoder.

Member Data Documentation

◆ _buffer

Sint32* cugl::audio::FLACDecoder::_buffer
protected

The intermediate buffer for uniformizing FLAC data

◆ _bufflast

Uint64 cugl::audio::FLACDecoder::_bufflast
protected

The last element read from the intermediate buffer

◆ _buffsize

Uint64 cugl::audio::FLACDecoder::_buffsize
protected

The size of the intermediate buffer

◆ _decoder

FLAC__StreamDecoder* cugl::audio::FLACDecoder::_decoder
protected

The FLAC decoder struct

◆ _sampsize

Uint32 cugl::audio::FLACDecoder::_sampsize
protected

The number of bits used to encode the sample data

◆ _source

SDL_RWops* cugl::audio::FLACDecoder::_source
protected

The file for loading in information


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