Ship::AudioPlayer Class Reference

Abstract base class for platform-specific audio output backends. More...

#include <AudioPlayer.h>

Inheritance diagram for Ship::AudioPlayer:

Public Member Functions
	AudioPlayer (AudioSettings settings)
	Constructs an AudioPlayer with the given configuration.
	~AudioPlayer ()
bool	Init ()
	Calls DoInit() and sets the initialised flag on success.
virtual int32_t	Buffered ()=0
	Returns the number of audio frames currently queued in the device buffer.
void	Play (const uint8_t *buf, size_t len)
	Submits a frame of PCM audio to the output device.
bool	IsInitialized ()
	Returns true if Init() has been called and succeeded.
int32_t	GetSampleRate () const
	Returns the configured output sample rate in Hz.
int32_t	GetSampleLength () const
	Returns the configured number of samples per audio frame.
int32_t	GetDesiredBuffered () const
	Returns the target number of frames to keep buffered.
AudioChannelsSetting	GetAudioChannels () const
	Returns the current channel-output mode.
void	SetSampleRate (int32_t rate)
	Sets the output sample rate.
void	SetSampleLength (int32_t length)
	Sets the number of samples per audio frame.
void	SetDesiredBuffered (int32_t size)
	Sets the target number of buffered frames.
bool	SetAudioChannels (AudioChannelsSetting channels)
	Changes the channel mode and reinitialises the audio device.
int32_t	GetNumOutputChannels () const
	Returns the number of output channels implied by the current channel setting.

Protected Member Functions
virtual bool	DoInit ()=0
	Opens and configures the platform audio device.
virtual void	DoClose ()=0
	Closes the platform audio device and releases its resources.
virtual void	DoPlay (const uint8_t *buf, size_t len)=0
	Writes interleaved PCM samples to the platform audio device.

Detailed Description

Abstract base class for platform-specific audio output backends.

AudioPlayer owns the audio device lifecycle (DoInit / DoClose) and the optional SoundMatrixDecoder that converts stereo input to 5.1 surround. Concrete subclasses implement DoInit(), DoClose(), and DoPlay() for each supported platform (SDL2, CoreAudio, WASAPI, or a null no-op).

Obtain the active instance from Context::GetAudio() → Audio::GetAudioPlayer().

Constructor & Destructor Documentation

AudioPlayer()

Ship::AudioPlayer::AudioPlayer ( AudioSettings  settings )

inline

Constructs an AudioPlayer with the given configuration.

Parameters

settings

Sample rate, buffer size, desired buffered frames, and channel mode.

~AudioPlayer()

Ship::AudioPlayer::~AudioPlayer

(

)

Member Function Documentation

Buffered()

virtual int32_t Ship::AudioPlayer::Buffered ( )

pure virtual

Returns the number of audio frames currently queued in the device buffer.

The audio system uses this to pace audio production: if Buffered() exceeds DesiredBuffered the game can skip producing audio for that tick.

Implemented in Ship::CoreAudioAudioPlayer, Ship::NullAudioPlayer, Ship::SDLAudioPlayer, and Ship::WasapiAudioPlayer.

DoClose()

virtual void Ship::AudioPlayer::DoClose ( )

protectedpure virtual

Closes the platform audio device and releases its resources.

Called by SetAudioChannels() before reinitialisation and by the destructor.

Implemented in Ship::CoreAudioAudioPlayer, Ship::NullAudioPlayer, Ship::SDLAudioPlayer, and Ship::WasapiAudioPlayer.

DoInit()

virtual bool Ship::AudioPlayer::DoInit ( )

protectedpure virtual

Opens and configures the platform audio device.

Called by Init() and by SetAudioChannels() when reinitialising.

Returns

true on success.

Implemented in Ship::CoreAudioAudioPlayer, Ship::NullAudioPlayer, Ship::SDLAudioPlayer, and Ship::WasapiAudioPlayer.

DoPlay()

virtual void Ship::AudioPlayer::DoPlay ( const uint8_t *  buf, size_t  len  )

protectedpure virtual

Writes interleaved PCM samples to the platform audio device.

Receives audio already in the correct output format (stereo or 6-channel).

Parameters

buf	Sample data.
len	Length of buf in bytes.

Implemented in Ship::CoreAudioAudioPlayer, Ship::NullAudioPlayer, Ship::SDLAudioPlayer, and Ship::WasapiAudioPlayer.

GetAudioChannels()

AudioChannelsSetting Ship::AudioPlayer::GetAudioChannels

(

)

const

Returns the current channel-output mode.

GetDesiredBuffered()

int32_t Ship::AudioPlayer::GetDesiredBuffered

(

)

const

Returns the target number of frames to keep buffered.

GetNumOutputChannels()

int32_t Ship::AudioPlayer::GetNumOutputChannels

(

)

const

Returns the number of output channels implied by the current channel setting.

Returns

2 for stereo, 6 for any 5.1 mode.

GetSampleLength()

int32_t Ship::AudioPlayer::GetSampleLength

(

)

const

Returns the configured number of samples per audio frame.

GetSampleRate()

int32_t Ship::AudioPlayer::GetSampleRate

(

)

const

Returns the configured output sample rate in Hz.

Init()

bool Ship::AudioPlayer::Init

(

)

Calls DoInit() and sets the initialised flag on success.

Returns

true if the audio device was initialised successfully.

IsInitialized()

bool Ship::AudioPlayer::IsInitialized

(

)

Returns true if Init() has been called and succeeded.

Play()

void Ship::AudioPlayer::Play	(	const uint8_t *	buf,
		size_t	len
	)

Submits a frame of PCM audio to the output device.

If 5.1 surround output is configured and the channel setting requires matrix decoding, the stereo buf is first decoded to 6-channel surround before being passed to DoPlay().

Parameters

buf	Interleaved samples: Stereo: (L, R, L, R, …) 5.1: (FL, FR, C, LFE, SL, SR, …)
len	Length of buf in bytes.

SetAudioChannels()

bool Ship::AudioPlayer::SetAudioChannels

(

AudioChannelsSetting

channels

)

Changes the channel mode and reinitialises the audio device.

Closes the current device, updates the channel setting, and calls DoInit() again. If reinitialisation fails the previous channel mode is restored.

Parameters

channels

New channel mode.

Returns

true if the device was successfully reinitialised.

SetDesiredBuffered()

void Ship::AudioPlayer::SetDesiredBuffered

(

int32_t

size

)

Sets the target number of buffered frames.

Parameters

size	New buffered-frame target.

SetSampleLength()

void Ship::AudioPlayer::SetSampleLength

(

int32_t

length

)

Sets the number of samples per audio frame.

Parameters

length

New frame size in samples.

SetSampleRate()

void Ship::AudioPlayer::SetSampleRate

(

int32_t

rate

)

Sets the output sample rate.

Parameters

rate	New sample rate in Hz.

---

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

• include/ship/audio/AudioPlayer.h