OSDL::Audio::AudioChannel Class Reference

Corresponds to a mixing audio channel. More...

#include <OSDLAudioChannel.h>

Public Member Functions
	AudioChannel (ChannelNumber channelNumber)
	Creates a new audio channel instance.
virtual	~AudioChannel () throw ()
	Virtual destructor.
virtual ChannelNumber	getNumber () const
	Returns the number of this mixing channel.
virtual Volume	getVolume () const
	Returns the volume associated to this channel.
virtual void	setVolume (Volume newVolume)
	Sets the volume associated to this channel.
virtual void	setPanning (Ceylan::Maths::Percentage leftPercentage)
	Activates stereo panning and sets the specified distribution between left/right output channels for this input mixing channel.
virtual void	unsetPanning ()
	Deactivates stereo panning effect for this channel.
virtual void	setReverseStereo (bool reverse=true)
	Activates or deactivates reverse stereo: if activated, swaps left and right output for this channel.
virtual void	setDistanceAttenuation (ListenerDistance distance)
	Activates distance attenuation for this input mixing channel.
virtual void	unsetDistanceAttenuation ()
	Deactivates distance attenuation effect for this mixing channel.
virtual void	setPositionAttenuation (ListenerDistance distance, ListenerAngle angle)
	Activates attenuation based on distance and angle for this input mixing channel.
virtual void	unsetPositionAttenuation ()
	Deactivates position attenuation effect for this mixing channel.
virtual bool	isPlaying () const
	Returns true iff this channel is currently playing (not halted), including if it is playing but paused.
virtual bool	isPaused () const
	Returns true iff this channel is currently paused, including if it has been halted afterwards.
virtual FadingStatus	getFadingStatus () const
	Returns the fading status of this channel.
virtual void	pause ()
	Pauses this channel.
virtual void	resume ()
	Resumes the playing on this supposedly paused channel.
virtual void	waitEndOfPlayback () const
	Waits (synchronously, i.e.
virtual void	halt ()
	Halts the playing on this channel.
virtual void	expireIn (Ceylan::System::Millisecond expireDuration)
	Makes that channel stop after the specified duration is elapsed.
virtual void	fadeOutDuring (Ceylan::System::Millisecond fadeOutDuration)
	Makes that channel stop after the specified duration is elapsed.
virtual const std::string	toString (Ceylan::VerbosityLevels level=Ceylan::high) const
	Returns an user-friendly description of the state of this object.
Protected Member Functions
virtual void	onPlaybackFinished ()
	This method will be automatically called as soon as this channel stops playback.
Protected Attributes
ChannelNumber	_channelNumber
	The number of this channel in channel list.
Private Member Functions
	AudioChannel (const AudioChannel &source)
	Copy constructor made private to ensure that it will be never called.
AudioChannel &	operator= (const AudioChannel &source)
	Assignment operator made private to ensure that it will be never called.
Static Private Member Functions
static void	HandleFinishedPlaybackCallback (int channelNumber)
	Callback to catch the end of a channel playback.

Detailed Description

Corresponds to a mixing audio channel.

Audio channel instances are owned by the audio module.

On a given channel, up to one sample can be played at a time.

Note:: All play* methods of Sound and Music could be accessible from channel instances as well.

Definition at line 73 of file OSDLAudioChannel.h.

Constructor & Destructor Documentation

AudioChannel::AudioChannel ( ChannelNumber channelNumber ) [explicit]

Creates a new audio channel instance.

On creation, the channel volume is the maximum one.

Parameters:

channelNumber

the number of the channel.

Exceptions:

AudioChannelException

if the operation failed or is not supported.

Note:: Usually the user does not create his own channels, he retrieves them thanks to AudioModule::getMixingChannelAt.

Definition at line 84 of file OSDLAudioChannel.cc.

References HandleFinishedPlaybackCallback().

AudioChannel::~AudioChannel ( ) throw () [virtual]

Virtual destructor.

Definition at line 106 of file OSDLAudioChannel.cc.

OSDL::Audio::AudioChannel::AudioChannel ( const AudioChannel & source ) [explicit, private]

Copy constructor made private to ensure that it will be never called.

The compiler should complain whenever this undefined constructor is called, implicitly or not.

Member Function Documentation

void AudioChannel::expireIn ( Ceylan::System::Millisecond expireDuration ) [virtual]

Makes that channel stop after the specified duration is elapsed.

Parameters:

expireDuration

the duration, in milliseconds, until this channel is stopped.

Exceptions:

AudioChannelException

if the operation failed, including if not supported.

Definition at line 451 of file OSDLAudioChannel.cc.

References _channelNumber.

void AudioChannel::fadeOutDuring ( Ceylan::System::Millisecond fadeOutDuration ) [virtual]

Makes that channel stop after the specified duration is elapsed.

Parameters:

fadeOutDuration

the duration, in milliseconds, of the fade-out, which will start immediately.

Exceptions:

AudioChannelException

if the operation failed, including if not supported.

Definition at line 471 of file OSDLAudioChannel.cc.

References _channelNumber.

FadingStatus AudioChannel::getFadingStatus ( ) const [virtual]

Returns the fading status of this channel.

Note:: Does not tell whether it is playing anything, or paused, etc., it must be tested separately.

Definition at line 348 of file OSDLAudioChannel.cc.

References _channelNumber, OSDL::Audio::In, OSDL::Audio::None, and OSDL::Audio::Out.

ChannelNumber AudioChannel::getNumber ( ) const [virtual]

Returns the number of this mixing channel.

Definition at line 115 of file OSDLAudioChannel.cc.

References _channelNumber.

Volume AudioChannel::getVolume ( ) const [virtual]

Returns the volume associated to this channel.

Exceptions:

AudioChannelException

if the operation failed.

Definition at line 124 of file OSDLAudioChannel.cc.

References _channelNumber.

void AudioChannel::halt ( ) [virtual]

Halts the playing on this channel.

Note:: onPlaybackFinished will be automatically called.

Exceptions:

AudioChannelException

if the operation failed, including if not supported.

Definition at line 433 of file OSDLAudioChannel.cc.

References _channelNumber.

void AudioChannel::HandleFinishedPlaybackCallback ( int channelNumber ) [static, private]

Callback to catch the end of a channel playback.

This signature is mandatory.

Definition at line 519 of file OSDLAudioChannel.cc.

References OSDL::Audio::getExistingAudioModule(), OSDL::Audio::AudioModule::getMixingChannelAt(), and onPlaybackFinished().

Referenced by AudioChannel().

bool AudioChannel::isPaused ( ) const [virtual]

Returns true iff this channel is currently paused, including if it has been halted afterwards.

Definition at line 330 of file OSDLAudioChannel.cc.

References _channelNumber.

bool AudioChannel::isPlaying ( ) const [virtual]

Returns true iff this channel is currently playing (not halted), including if it is playing but paused.

Definition at line 312 of file OSDLAudioChannel.cc.

References _channelNumber.

Referenced by waitEndOfPlayback().

void AudioChannel::onPlaybackFinished ( ) [protected, virtual]

This method will be automatically called as soon as this channel stops playback.

This method is meant to be overriden, in order to be able to react when this event occurs (like a call-back).

Note:: Never call back-end functions (ex: SDL or SDL_mixer) from the callback.

This default implementation is do-nothing.

Exceptions:

AudioChannelException

if the operation failed.

Definition at line 492 of file OSDLAudioChannel.cc.

Referenced by HandleFinishedPlaybackCallback().

AudioChannel& OSDL::Audio::AudioChannel::operator= ( const AudioChannel & source ) [private]

Assignment operator made private to ensure that it will be never called.

The compiler should complain whenever this undefined operator is called, implicitly or not.

void AudioChannel::pause ( ) [virtual]

Pauses this channel.

You may still halt a paused channel.

Exceptions:

AudioChannelException

if the operation failed, including if not supported.

Definition at line 387 of file OSDLAudioChannel.cc.

References _channelNumber.

void AudioChannel::resume ( ) [virtual]

Resumes the playing on this supposedly paused channel.

Exceptions:

AudioChannelException

if the operation failed, including if not supported.

Definition at line 405 of file OSDLAudioChannel.cc.

References _channelNumber.

void AudioChannel::setDistanceAttenuation ( ListenerDistance distance ) [virtual]

Activates distance attenuation for this input mixing channel.

Parameters:

distance

corresponds to the distance between the audio sources (deemed all at the same location) and the listener. It ranges for 0 (closest possible) to 255 (far). A distance of 0 unregisters this effect (volume continuity is then ensured).

Exceptions:

AudioChannelException

if the operation failed, including if not supported.

See also:: ListenerDistance

Definition at line 225 of file OSDLAudioChannel.cc.

References _channelNumber.

void AudioChannel::setPanning ( Ceylan::Maths::Percentage leftPercentage ) [virtual]

Activates stereo panning and sets the specified distribution between left/right output channels for this input mixing channel.

Note:: This effect will only work on stereo audio output. On mono audio device, nothing will be done.

Parameters:

leftPercentage,between

0 and 100 (%). Right percentage will be equal to 100 - leftPercentage.

Exceptions:

AudioChannelException

if the operation failed, including if not supported.

Definition at line 160 of file OSDLAudioChannel.cc.

References _channelNumber.

void AudioChannel::setPositionAttenuation	(	ListenerDistance	distance,
		ListenerAngle	angle
	)			`[virtual]`

Activates attenuation based on distance and angle for this input mixing channel.

Parameters:

	distance	corresponds to the distance between the audio sources (deemed all at the same location) and the listener. It ranges for 0 (closest possible) to 255 (far).
	angle	corresponds to the angle between the audio sources (deemed all at the same location) and the listener. Larger angles will be reduced to the [0..360[ range using the 'modulo 360' (angle % 360 ) operator.

Exceptions:

AudioChannelException

if the operation failed, including if not supported.

See also:: ListenerDistance, ListenerAngle

Definition at line 268 of file OSDLAudioChannel.cc.

References _channelNumber.

void AudioChannel::setReverseStereo ( bool reverse = true ) [virtual]

Activates or deactivates reverse stereo: if activated, swaps left and right output for this channel.

Note:: This effect will only work on stereo audio output. On mono audio device, nothing will be done.

Parameters:

reverse

if true, left channel will be output into right one, and right channel into left one, for this input mixing channel only.

Exceptions:

AudioChannelException

if the operation failed, including if not supported.

Definition at line 204 of file OSDLAudioChannel.cc.

References _channelNumber.

void AudioChannel::setVolume ( Volume newVolume ) [virtual]

Sets the volume associated to this channel.

Parameters:

newVolume

the new volume to be set.

Exceptions:

AudioChannelException

if the operation failed, including if not supported.

Definition at line 142 of file OSDLAudioChannel.cc.

References _channelNumber.

const string AudioChannel::toString ( Ceylan::VerbosityLevels level = Ceylan::high ) const [virtual]

Returns an user-friendly description of the state of this object.

Parameters:

level

the requested verbosity level.

Note:: Text output format is determined from overall settings.

See also:: Ceylan::TextDisplayable

Definition at line 507 of file OSDLAudioChannel.cc.

References _channelNumber.

void AudioChannel::unsetDistanceAttenuation ( ) [virtual]

Deactivates distance attenuation effect for this mixing channel.

Exceptions:

AudioChannelException

if the operation failed, including if not supported.

Definition at line 246 of file OSDLAudioChannel.cc.

References _channelNumber.

void AudioChannel::unsetPanning ( ) [virtual]

Deactivates stereo panning effect for this channel.

Exceptions:

AudioChannelException

if the operation failed, including if not supported.

Definition at line 184 of file OSDLAudioChannel.cc.

References _channelNumber.

void AudioChannel::unsetPositionAttenuation ( ) [virtual]

Deactivates position attenuation effect for this mixing channel.

Exceptions:

AudioChannelException

if the operation failed, including if not supported.

Definition at line 290 of file OSDLAudioChannel.cc.

References _channelNumber.

void AudioChannel::waitEndOfPlayback ( ) const [virtual]

Waits (synchronously, i.e.

blocks) as long as this channel is playing.

Note:: CPU-friendly busy waiting is performed.

Exceptions:

AudioException

if the operation failed, including if not supported.

Definition at line 423 of file OSDLAudioChannel.cc.

References isPlaying().

Member Data Documentation

ChannelNumber OSDL::Audio::AudioChannel::_channelNumber [protected]

The number of this channel in channel list.

Definition at line 408 of file OSDLAudioChannel.h.

Referenced by expireIn(), fadeOutDuring(), getFadingStatus(), getNumber(), getVolume(), halt(), isPaused(), isPlaying(), pause(), resume(), setDistanceAttenuation(), setPanning(), setPositionAttenuation(), setReverseStereo(), setVolume(), toString(), unsetDistanceAttenuation(), unsetPanning(), and unsetPositionAttenuation().

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

OSDL::Audio::AudioChannel Class Reference

Public Member Functions

Protected Member Functions

Protected Attributes

Private Member Functions

Static Private Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation