asw::sound Namespace Reference

Classes
struct	Attenuation
	Distance settings for positional sounds, in world units (pixels). More...
struct	HandleAccess
struct	PlayOptions
	Options for playing a sound. More...
class	SoundHandle
	A handle to a playing sound, used to change it while it plays. More...

Enumerations
enum class	Bus : uint8_t {   Sfx , Music , Ambient , Ui ,   Voice , Count }
	Mix buses. Each sound plays on one bus, and each bus has its own volume and can be ducked. More...
enum class	Rolloff : uint8_t { Linear , Inverse , InverseSquare }
	How volume falls off with distance for positional sounds. More...
enum class	SpatialMode : uint8_t { Stereo , Surround }
	How positional sounds are placed on the speakers. More...

Functions
bool	_init ()
	Initialize the sound module. Called automatically by asw::core::init().
void	_update ()
	Update fades, ducking and positional sounds. Called automatically by asw::core::update().
void	_shutdown ()
	Shut down the sound module. Called automatically by asw::core::shutdown().
MIX_Mixer *	get_mixer ()
	Get the SDL mixer device.
uint32_t	_get_session ()
	Get the number of times the sound module has been shut down.
SoundHandle	play (const asw::Sample &sample, float volume=1.0F, float pan=0.0F, bool loop=false)
	Play a sample.
SoundHandle	play (const asw::Sample &sample, const PlayOptions &options)
	Play a sample with options.
SoundHandle	play_positional (const asw::Sample &sample, const Vec2< float > &position, const PlayOptions &options={})
	Play a sample at a point in the world. It is panned, faded and pitch shifted relative to the listener, and keeps updating while it plays.
SoundHandle	play_at (const asw::Sample &sample, float x, float volume=1.0F)
	Play a sample panned by where it happens on screen. Sounds pan towards the side they are on and fade out once they are off screen, going silent a full screen width past the edge.
SoundHandle	play_at (const asw::Sample &sample, float x, const PlayOptions &options)
	Play a sample panned by where it happens on screen, with options. Works like play_at above, so pitch, variation, bus and priority can be set too. The pan is worked out once when the sound starts.
void	set_listener (const Vec2< float > &position, const Vec2< float > &velocity={ 0.0F, 0.0F })
	Set where the listener is, usually the player or camera centre.
Vec2< float >	get_listener ()
	Get the listener position.
void	set_spatial_mode (SpatialMode mode)
	Choose how positional sounds are placed on the speakers.
void	set_doppler (float factor, float speed_of_sound=3000.0F)
	Set how strong doppler pitch shift is.
void	set_bus_volume (Bus bus, float volume)
	Set a bus volume.
float	get_bus_volume (Bus bus)
	Get a bus volume.
void	duck (Bus bus, float gain, float hold_s, float fade_s=0.2F)
	Turn a bus down for a while, for example music under dialogue or everything under a big explosion. Overlapping ducks keep the deepest level and the longest hold.
void	play_music (const asw::Music &sample, float volume=1.0F, float fade_in_s=0.0F)
	Play a music sample.
void	stop_music (float fade_out_s=0.0F)
	Stop the currently playing music.
void	pause_music ()
	Pause the currently playing music.
void	resume_music ()
	Resume paused music.
bool	is_music_playing ()
	Check if music is currently playing.
bool	is_music_paused ()
	Check if music is paused.
void	set_master_volume (float volume)
	Set the master volume multiplier (affects all audio).
void	set_sfx_volume (float volume)
	Set the SFX volume multiplier. Same as the Sfx bus volume.
void	set_music_volume (float volume)
	Set the music volume multiplier. Same as the Music bus volume.
float	get_master_volume ()
	Get the current master volume multiplier.
float	get_sfx_volume ()
	Get the current SFX volume multiplier.
float	get_music_volume ()
	Get the current music volume multiplier.

Enumeration Type Documentation

Bus

enum class asw::sound::Bus : uint8_t

strong

Mix buses. Each sound plays on one bus, and each bus has its own volume and can be ducked.

Enumerator
Sfx
Music
Ambient
Ui
Voice
Count

Definition at line 22 of file sound.h.

Rolloff

enum class asw::sound::Rolloff : uint8_t

strong

How volume falls off with distance for positional sounds.

Enumerator
Linear	Straight line from full volume at min_distance to silent at max_distance.
Inverse	Natural sounding, loud close up and a long quiet tail.
InverseSquare	Like Inverse but drops faster.

Definition at line 33 of file sound.h.

SpatialMode

enum class asw::sound::SpatialMode : uint8_t

strong

How positional sounds are placed on the speakers.

Enumerator
Stereo	Left/right panning. Best for headphones and side on games.
Surround	SDL_mixer 3D positioning, also uses rear and side speakers. The world is treated as top down: up the screen is in front, down is behind.

Definition at line 44 of file sound.h.

Function Documentation

_get_session()

uint32_t asw::sound::_get_session

(

)

Get the number of times the sound module has been shut down.

Shutting down frees all loaded audio, so audio loaded before a shutdown must not be destroyed again, even after the next init.

Returns

The shutdown count.

Definition at line 460 of file sound.cpp.

_init()

bool asw::sound::_init

(

)

Initialize the sound module. Called automatically by asw::core::init().

Returns

True if initialization was successful, false otherwise.

Definition at line 465 of file sound.cpp.

_shutdown()

void asw::sound::_shutdown

(

)

Shut down the sound module. Called automatically by asw::core::shutdown().

Definition at line 444 of file sound.cpp.

_update()

void asw::sound::_update

(

)

Update fades, ducking and positional sounds. Called automatically by asw::core::update().

Definition at line 511 of file sound.cpp.

duck()

void asw::sound::duck	(	Bus	bus,
		float	gain,
		float	hold_s,
		float	fade_s = 0.2F )

Turn a bus down for a while, for example music under dialogue or everything under a big explosion. Overlapping ducks keep the deepest level and the longest hold.

Parameters

bus	The bus to turn down.
gain	Level while ducked (0.0 - 1.0).
hold_s	Seconds to stay ducked.
fade_s	Seconds to fade down and back up.

Definition at line 701 of file sound.cpp.

get_bus_volume()

float asw::sound::get_bus_volume

(

Bus

bus

)

Get a bus volume.

Parameters

bus

The bus.

Returns

The volume multiplier (0.0 - 1.0).

Definition at line 693 of file sound.cpp.

get_listener()

asw::Vec2< float > asw::sound::get_listener

(

)

Get the listener position.

Returns

The world position.

Definition at line 669 of file sound.cpp.

get_master_volume()

float asw::sound::get_master_volume

(

)

Get the current master volume multiplier.

Returns

The master volume (0.0 - 1.0).

Definition at line 772 of file sound.cpp.

get_mixer()

MIX_Mixer * asw::sound::get_mixer

(

)

Get the SDL mixer device.

Returns

Pointer to the MIX_Mixer, or nullptr if not initialized.

Definition at line 439 of file sound.cpp.

get_music_volume()

float asw::sound::get_music_volume

(

)

Get the current music volume multiplier.

Returns

The music volume (0.0 - 1.0).

Definition at line 782 of file sound.cpp.

get_sfx_volume()

float asw::sound::get_sfx_volume

(

)

Get the current SFX volume multiplier.

Returns

The SFX volume (0.0 - 1.0).

Definition at line 777 of file sound.cpp.

is_music_paused()

bool asw::sound::is_music_paused

(

)

Check if music is paused.

Returns

True if music is paused.

Definition at line 750 of file sound.cpp.

is_music_playing()

bool asw::sound::is_music_playing

(

)

Check if music is currently playing.

Returns

True if music is playing.

Definition at line 745 of file sound.cpp.

pause_music()

void asw::sound::pause_music

(

)

Pause the currently playing music.

Definition at line 735 of file sound.cpp.

play() [1/2]

asw::sound::SoundHandle asw::sound::play	(	const asw::Sample &	sample,
		const PlayOptions &	options )

Play a sample with options.

Parameters

sample	Sample to play
options	How to play it.

Returns

A handle to the sound, stale if it could not be played.

Definition at line 604 of file sound.cpp.

play() [2/2]

asw::sound::SoundHandle asw::sound::play	(	const asw::Sample &	sample,
		float	volume = 1.0F,
		float	pan = 0.0F,
		bool	loop = false )

Play a sample.

Parameters

sample	Sample to play
volume	Playback volume (0.0 - 1.0).
pan	Panning (-1.0 - 1.0), where -1.0 is full left, 0.0 is center, and 1.0 is full right.
loop	Whether to loop the sample (false = no loop, true = infinite loop).

Returns

A handle to the sound, stale if it could not be played.

Definition at line 609 of file sound.cpp.

play_at() [1/2]

asw::sound::SoundHandle asw::sound::play_at	(	const asw::Sample &	sample,
		float	x,
		const PlayOptions &	options )

Play a sample panned by where it happens on screen, with options. Works like play_at above, so pitch, variation, bus and priority can be set too. The pan is worked out once when the sound starts.

Parameters

sample	Sample to play
x	Horizontal position in logical screen coordinates.
options	How to play it. volume is before distance fading, pan is replaced by the screen position.

Returns

A handle to the sound, stale if it could not be played.

Definition at line 638 of file sound.cpp.

play_at() [2/2]

asw::sound::SoundHandle asw::sound::play_at	(	const asw::Sample &	sample,
		float	x,
		float	volume = 1.0F )

Play a sample panned by where it happens on screen. Sounds pan towards the side they are on and fade out once they are off screen, going silent a full screen width past the edge.

Parameters

sample	Sample to play
x	Horizontal position in logical screen coordinates.
volume	Playback volume (0.0 - 1.0) before distance fading.

Returns

A handle to the sound, stale if it could not be played.

Definition at line 631 of file sound.cpp.

play_music()

void asw::sound::play_music	(	const asw::Music &	sample,
		float	volume = 1.0F,
		float	fade_in_s = 0.0F )

Play a music sample.

Parameters

sample	Sample to play
volume	Playback volume (0.0 - 1.0).
fade_in_s	Fade-in duration in seconds.

Definition at line 713 of file sound.cpp.

play_positional()

asw::sound::SoundHandle asw::sound::play_positional	(	const asw::Sample &	sample,
		const Vec2< float > &	position,
		const PlayOptions &	options = {} )

Play a sample at a point in the world. It is panned, faded and pitch shifted relative to the listener, and keeps updating while it plays.

Parameters

sample	Sample to play
position	The world position.
options	How to play it.

Returns

A handle to the sound, stale if it could not be played. One shot sounds out of hearing range are not played.

Definition at line 619 of file sound.cpp.

resume_music()

void asw::sound::resume_music

(

)

Resume paused music.

Definition at line 740 of file sound.cpp.

set_bus_volume()

void asw::sound::set_bus_volume	(	Bus	bus,
		float	volume )

Set a bus volume.

Parameters

bus	The bus.
volume	Volume multiplier (0.0 - 1.0).

Definition at line 685 of file sound.cpp.

set_doppler()

void asw::sound::set_doppler	(	float	factor,
		float	speed_of_sound = 3000.0F )

Set how strong doppler pitch shift is.

Parameters

factor	0 turns doppler off, 1 is realistic. Defaults to 1.
speed_of_sound	World units per second. Lower makes the effect stronger. Defaults to 3000.

Definition at line 679 of file sound.cpp.

set_listener()

void asw::sound::set_listener	(	const Vec2< float > &	position,
		const Vec2< float > &	velocity = { 0.0F, 0.0F } )

Set where the listener is, usually the player or camera centre.

Parameters

position	The world position.
velocity	Velocity in world units per second, for doppler.

Definition at line 663 of file sound.cpp.

set_master_volume()

void asw::sound::set_master_volume

(

float

volume

)

Set the master volume multiplier (affects all audio).

Parameters

volume

Volume multiplier (0.0 - 1.0).

Definition at line 755 of file sound.cpp.

set_music_volume()

void asw::sound::set_music_volume

(

float

volume

)

Set the music volume multiplier. Same as the Music bus volume.

Parameters

volume

Volume multiplier (0.0 - 1.0).

Definition at line 766 of file sound.cpp.

set_sfx_volume()

void asw::sound::set_sfx_volume

(

float

volume

)

Set the SFX volume multiplier. Same as the Sfx bus volume.

Parameters

volume

Volume multiplier (0.0 - 1.0).

Definition at line 761 of file sound.cpp.

set_spatial_mode()

void asw::sound::set_spatial_mode

(

SpatialMode

mode

)

Choose how positional sounds are placed on the speakers.

Parameters

mode	The mode. Defaults to Stereo.

Definition at line 674 of file sound.cpp.

stop_music()

void asw::sound::stop_music

(

float

fade_out_s = 0.0F

)

Stop the currently playing music.

Definition at line 727 of file sound.cpp.