Saves the data for playback. More...

#include <SoftwareDevice.h>

Inheritance diagram for SoftwareDevice::SoftwareHandle:

Public Member Functions
bool	pause (bool keep)
	This method is for internal use only.

	SoftwareHandle (SoftwareDevice *device, std::shared_ptr< IReader > reader, std::shared_ptr< PitchReader > pitch, std::shared_ptr< ResampleReader > resampler, std::shared_ptr< ChannelMapperReader > mapper, bool keep)
	Creates a new software handle.

void	update ()
	Updates the handle's playback parameters.

void	setSpecs (Specs specs)
	Sets the audio output specification of the readers.

virtual bool	pause ()
	Pauses a played back sound.

virtual bool	resume ()
	Resumes a paused sound.

virtual bool	stop ()
	Stops a played back or paused sound.

virtual bool	getKeep ()
	Gets the behaviour of the device for a played back sound when the sound doesn't return any more samples.

virtual bool	setKeep (bool keep)
	Sets the behaviour of the device for a played back sound when the sound doesn't return any more samples.

virtual bool	seek (double position)
	Seeks in a played back sound.

virtual double	getPosition ()
	Retrieves the current playback position of a sound.

virtual Status	getStatus ()
	Returns the status of a played back sound.

virtual float	getVolume ()
	Retrieves the volume of a playing sound.

virtual bool	setVolume (float volume)
	Sets the volume of a playing sound.

virtual float	getPitch ()
	Retrieves the pitch of a playing sound.

virtual bool	setPitch (float pitch)
	Sets the pitch of a playing sound.

virtual int	getLoopCount ()
	Retrieves the loop count of a playing sound.

virtual bool	setLoopCount (int count)
	Sets the loop count of a playing sound.

virtual bool	setStopCallback (stopCallback callback=0, void *data=0)
	Sets the callback function that's called when the end of a playing sound is reached.

virtual Vector3	getLocation ()
	Retrieves the location of the source.

virtual bool	setLocation (const Vector3 &location)
	Sets the location of the source.

virtual Vector3	getVelocity ()
	Retrieves the velocity of the source.

virtual bool	setVelocity (const Vector3 &velocity)
	Sets the velocity of the source.

virtual Quaternion	getOrientation ()
	Retrieves the orientation of the source.

virtual bool	setOrientation (const Quaternion &orientation)
	Sets the orientation of the source.

virtual bool	isRelative ()
	Checks whether the source location, velocity and orientation are relative to the listener.

virtual bool	setRelative (bool relative)
	Sets whether the source location, velocity and orientation are relative to the listener.

virtual float	getVolumeMaximum ()
	Retrieves the maximum volume of a source.

virtual bool	setVolumeMaximum (float volume)
	Sets the maximum volume of a source.

virtual float	getVolumeMinimum ()
	Retrieves the minimum volume of a source.

virtual bool	setVolumeMinimum (float volume)
	Sets the minimum volume of a source.

virtual float	getDistanceMaximum ()
	Retrieves the maximum distance of a source.

virtual bool	setDistanceMaximum (float distance)
	Sets the maximum distance of a source.

virtual float	getDistanceReference ()
	Retrieves the reference distance of a source.

virtual bool	setDistanceReference (float distance)
	Sets the reference distance of a source.

virtual float	getAttenuation ()
	Retrieves the attenuation of a source.

virtual bool	setAttenuation (float factor)
	Sets the attenuation of a source.

virtual float	getConeAngleOuter ()
	Retrieves the outer opening angle of the cone of a source.

virtual bool	setConeAngleOuter (float angle)
	Sets the outer opening angle of the cone of a source.

virtual float	getConeAngleInner ()
	Retrieves the inner opening angle of the cone of a source.

virtual bool	setConeAngleInner (float angle)
	Sets the inner opening angle of the cone of a source.

virtual float	getConeVolumeOuter ()
	Retrieves the outer volume of the cone of a source.

virtual bool	setConeVolumeOuter (float volume)
	Sets the outer volume of the cone of a source.

Public Member Functions inherited from IHandle
virtual	~IHandle ()
	Destroys the handle.

virtual bool	pause ()=0
	Pauses a played back sound.

virtual bool	resume ()=0
	Resumes a paused sound.

virtual bool	stop ()=0
	Stops a played back or paused sound.

virtual bool	getKeep ()=0
	Gets the behaviour of the device for a played back sound when the sound doesn't return any more samples.

virtual bool	setKeep (bool keep)=0
	Sets the behaviour of the device for a played back sound when the sound doesn't return any more samples.

virtual bool	seek (double position)=0
	Seeks in a played back sound.

virtual double	getPosition ()=0
	Retrieves the current playback position of a sound.

virtual Status	getStatus ()=0
	Returns the status of a played back sound.

virtual float	getVolume ()=0
	Retrieves the volume of a playing sound.

virtual bool	setVolume (float volume)=0
	Sets the volume of a playing sound.

virtual float	getPitch ()=0
	Retrieves the pitch of a playing sound.

virtual bool	setPitch (float pitch)=0
	Sets the pitch of a playing sound.

virtual int	getLoopCount ()=0
	Retrieves the loop count of a playing sound.

virtual bool	setLoopCount (int count)=0
	Sets the loop count of a playing sound.

virtual bool	setStopCallback (stopCallback callback=0, void *data=0)=0
	Sets the callback function that's called when the end of a playing sound is reached.

Public Member Functions inherited from I3DHandle
virtual	~I3DHandle ()
	Destroys the handle.

virtual Vector3	getLocation ()=0
	Retrieves the location of the source.

virtual bool	setLocation (const Vector3 &location)=0
	Sets the location of the source.

virtual Vector3	getVelocity ()=0
	Retrieves the velocity of the source.

virtual bool	setVelocity (const Vector3 &velocity)=0
	Sets the velocity of the source.

virtual Quaternion	getOrientation ()=0
	Retrieves the orientation of the source.

virtual bool	setOrientation (const Quaternion &orientation)=0
	Sets the orientation of the source.

virtual bool	isRelative ()=0
	Checks whether the source location, velocity and orientation are relative to the listener.

virtual bool	setRelative (bool relative)=0
	Sets whether the source location, velocity and orientation are relative to the listener.

virtual float	getVolumeMaximum ()=0
	Retrieves the maximum volume of a source.

virtual bool	setVolumeMaximum (float volume)=0
	Sets the maximum volume of a source.

virtual float	getVolumeMinimum ()=0
	Retrieves the minimum volume of a source.

virtual bool	setVolumeMinimum (float volume)=0
	Sets the minimum volume of a source.

virtual float	getDistanceMaximum ()=0
	Retrieves the maximum distance of a source.

virtual bool	setDistanceMaximum (float distance)=0
	Sets the maximum distance of a source.

virtual float	getDistanceReference ()=0
	Retrieves the reference distance of a source.

virtual bool	setDistanceReference (float distance)=0
	Sets the reference distance of a source.

virtual float	getAttenuation ()=0
	Retrieves the attenuation of a source.

virtual bool	setAttenuation (float factor)=0
	Sets the attenuation of a source.

virtual float	getConeAngleOuter ()=0
	Retrieves the outer opening angle of the cone of a source.

virtual bool	setConeAngleOuter (float angle)=0
	Sets the outer opening angle of the cone of a source.

virtual float	getConeAngleInner ()=0
	Retrieves the inner opening angle of the cone of a source.

virtual bool	setConeAngleInner (float angle)=0
	Sets the inner opening angle of the cone of a source.

virtual float	getConeVolumeOuter ()=0
	Retrieves the outer volume of the cone of a source.

virtual bool	setConeVolumeOuter (float volume)=0
	Sets the outer volume of the cone of a source.

Public Attributes
std::shared_ptr< IReader >	m_reader
	The reader source.

std::shared_ptr< PitchReader >	m_pitch
	The pitch reader in between.

std::shared_ptr< ResampleReader >	m_resampler
	The resample reader in between.

std::shared_ptr< ChannelMapperReader >	m_mapper
	The channel mapper reader in between.

bool	m_first_reading
	Whether the source is being read for the first time.

bool	m_keep
	Whether to keep the source if end of it is reached.

float	m_user_pitch
	The user set pitch of the source.

float	m_user_volume
	The user set volume of the source.

float	m_user_pan
	The user set panning for non-3D sources.

float	m_volume
	The calculated final volume of the source.

float	m_old_volume
	The previous calculated final volume of the source.

int	m_loopcount
	The loop count of the source.

Vector3	m_location
	Location in 3D Space.

Vector3	m_velocity
	Velocity in 3D Space.

Quaternion	m_orientation
	Orientation in 3D Space.

bool	m_relative
	Whether the position to the listener is relative or absolute.

float	m_volume_max
	Maximum volume.

float	m_volume_min
	Minimum volume.

float	m_distance_max
	Maximum distance.

float	m_distance_reference
	Reference distance;.

float	m_attenuation
	Attenuation.

float	m_cone_angle_outer
	Cone outer angle.

float	m_cone_angle_inner
	Cone inner angle.

float	m_cone_volume_outer
	Cone outer volume.

int	m_flags
	Rendering flags.

stopCallback	m_stop
	The stop callback.

void *	m_stop_data
	Stop callback data.

Status	m_status
	Current status of the handle.

SoftwareDevice *	m_device
	Own device.

Detailed Description

Saves the data for playback.

Constructor & Destructor Documentation

◆ SoftwareHandle()

SoftwareDevice::SoftwareHandle::SoftwareHandle	(	SoftwareDevice *	device,
		std::shared_ptr< IReader >	reader,
		std::shared_ptr< PitchReader >	pitch,
		std::shared_ptr< ResampleReader >	resampler,
		std::shared_ptr< ChannelMapperReader >	mapper,
		bool	keep
	)

Creates a new software handle.

Parameters

device	The device this handle is from.
reader	The reader to play.
pitch	The pitch reader.
resampler	The resampling reader.
mapper	The channel mapping reader.
keep	Whether to keep the handle when the sound ends.

Member Function Documentation

◆ getAttenuation()

virtual float SoftwareDevice::SoftwareHandle::getAttenuation ( )

virtual

Retrieves the attenuation of a source.

Returns: The attenuation.

Implements I3DHandle.

◆ getConeAngleInner()

virtual float SoftwareDevice::SoftwareHandle::getConeAngleInner ( )

virtual

Retrieves the inner opening angle of the cone of a source.

The volume inside this cone is unaltered.

Returns: The inner angle of the cone.

Note: This angle is defined in degrees.

Implements I3DHandle.

◆ getConeAngleOuter()

virtual float SoftwareDevice::SoftwareHandle::getConeAngleOuter ( )

virtual

Retrieves the outer opening angle of the cone of a source.

Returns: The outer angle of the cone.

Note: This angle is defined in degrees.

Implements I3DHandle.

◆ getConeVolumeOuter()

virtual float SoftwareDevice::SoftwareHandle::getConeVolumeOuter ( )

virtual

Retrieves the outer volume of the cone of a source.

The volume between inner and outer angle is interpolated between inner volume and this value.

Returns: The outer volume of the cone.

Note: The general volume of the handle still applies on top of this.

Implements I3DHandle.

◆ getDistanceMaximum()

virtual float SoftwareDevice::SoftwareHandle::getDistanceMaximum ( )

virtual

Retrieves the maximum distance of a source.

If a source is further away from the reader than this distance, the volume will automatically be set to 0.

Returns: The maximum distance.

Implements I3DHandle.

◆ getDistanceReference()

virtual float SoftwareDevice::SoftwareHandle::getDistanceReference ( )

virtual

Retrieves the reference distance of a source.

Returns: The reference distance.

Implements I3DHandle.

◆ getKeep()

virtual bool SoftwareDevice::SoftwareHandle::getKeep ( )

virtual

Gets the behaviour of the device for a played back sound when the sound doesn't return any more samples.

Returns

true if the source will be paused when it's end is reached
false if the handle won't kept or is invalid.

Implements IHandle.

◆ getLocation()

virtual Vector3 SoftwareDevice::SoftwareHandle::getLocation ( )

virtual

Retrieves the location of the source.

Returns: The location.

Implements I3DHandle.

◆ getLoopCount()

virtual int SoftwareDevice::SoftwareHandle::getLoopCount ( )

virtual

Retrieves the loop count of a playing sound.

A negative value indicates infinity.

Returns: The remaining loop count.

Implements IHandle.

◆ getOrientation()

virtual Quaternion SoftwareDevice::SoftwareHandle::getOrientation ( )

virtual

Retrieves the orientation of the source.

Returns: The orientation as quaternion.

Implements I3DHandle.

◆ getPitch()

virtual float SoftwareDevice::SoftwareHandle::getPitch ( )

virtual

Retrieves the pitch of a playing sound.

Returns: The pitch.

Implements IHandle.

◆ getPosition()

virtual double SoftwareDevice::SoftwareHandle::getPosition ( )

virtual

Retrieves the current playback position of a sound.

Returns: The playback position in seconds, or 0.0 if the handle is invalid.

Implements IHandle.

◆ getStatus()

virtual Status SoftwareDevice::SoftwareHandle::getStatus ( )

virtual

Returns the status of a played back sound.

Returns

STATUS_INVALID if the sound has stopped or the handle is . invalid
STATUS_PLAYING if the sound is currently played back.
STATUS_PAUSED if the sound is currently paused.
STATUS_STOPPED if the sound finished playing and is still kept in the device.

See also: Status

Implements IHandle.

◆ getVelocity()

virtual Vector3 SoftwareDevice::SoftwareHandle::getVelocity ( )

virtual

Retrieves the velocity of the source.

Returns: The velocity.

Implements I3DHandle.

◆ getVolume()

virtual float SoftwareDevice::SoftwareHandle::getVolume ( )

virtual

Retrieves the volume of a playing sound.

Returns: The volume.

Implements IHandle.

◆ getVolumeMaximum()

virtual float SoftwareDevice::SoftwareHandle::getVolumeMaximum ( )

virtual

Retrieves the maximum volume of a source.

Returns: The maximum volume.

Implements I3DHandle.

◆ getVolumeMinimum()

virtual float SoftwareDevice::SoftwareHandle::getVolumeMinimum ( )

virtual

Retrieves the minimum volume of a source.

Returns: The minimum volume.

Implements I3DHandle.

◆ isRelative()

virtual bool SoftwareDevice::SoftwareHandle::isRelative ( )

virtual

Checks whether the source location, velocity and orientation are relative to the listener.

Returns: Whether the source is relative.

Implements I3DHandle.

◆ pause() [1/2]

virtual bool SoftwareDevice::SoftwareHandle::pause ( )

virtual

Pauses a played back sound.

Returns

true if the sound has been paused.
false if the sound isn't playing back or the handle is invalid.

Implements IHandle.

◆ pause() [2/2]

bool SoftwareDevice::SoftwareHandle::pause ( bool keep )

This method is for internal use only.

Parameters

keep	Whether the sound should be marked stopped or paused.

Returns: Whether the action succeeded.

◆ resume()

virtual bool SoftwareDevice::SoftwareHandle::resume ( )

virtual

Resumes a paused sound.

Returns

true if the sound has been resumed.
false if the sound isn't paused or the handle is invalid.

Implements IHandle.

◆ seek()

virtual bool SoftwareDevice::SoftwareHandle::seek ( double position )

virtual

Seeks in a played back sound.

Parameters

position The new position from where to play back, in seconds.

Returns

true if the handle is valid.
false if the handle is invalid.

Warning: Whether the seek works or not depends on the sound source.

Implements IHandle.

◆ setAttenuation()

virtual bool SoftwareDevice::SoftwareHandle::setAttenuation ( float factor )

virtual

Sets the attenuation of a source.

This value is used for distance calculation.

Parameters

factor The new attenuation.

Returns: Whether the action succeeded.

Implements I3DHandle.

◆ setConeAngleInner()

virtual bool SoftwareDevice::SoftwareHandle::setConeAngleInner ( float angle )

virtual

Sets the inner opening angle of the cone of a source.

The volume inside this cone is unaltered.

Parameters

angle The new inner angle of the cone.

Returns: Whether the action succeeded.

Note: This angle is defined in degrees.

Implements I3DHandle.

◆ setConeAngleOuter()

virtual bool SoftwareDevice::SoftwareHandle::setConeAngleOuter ( float angle )

virtual

Sets the outer opening angle of the cone of a source.

Parameters

angle The new outer angle of the cone.

Returns: Whether the action succeeded.

Note: This angle is defined in degrees.

Implements I3DHandle.

◆ setConeVolumeOuter()

virtual bool SoftwareDevice::SoftwareHandle::setConeVolumeOuter ( float volume )

virtual

Sets the outer volume of the cone of a source.

The volume between inner and outer angle is interpolated between inner volume and this value.

Parameters

volume The new outer volume of the cone.

Returns: Whether the action succeeded.

Note: The general volume of the handle still applies on top of this.

Implements I3DHandle.

◆ setDistanceMaximum()

virtual bool SoftwareDevice::SoftwareHandle::setDistanceMaximum ( float distance )

virtual

Sets the maximum distance of a source.

If a source is further away from the reader than this distance, the volume will automatically be set to 0.

Parameters

distance The new maximum distance.

Returns: Whether the action succeeded.

Implements I3DHandle.

◆ setDistanceReference()

virtual bool SoftwareDevice::SoftwareHandle::setDistanceReference ( float distance )

virtual

Sets the reference distance of a source.

Parameters

distance The new reference distance.

Returns: Whether the action succeeded.

Implements I3DHandle.

◆ setKeep()

virtual bool SoftwareDevice::SoftwareHandle::setKeep ( bool keep )

virtual

Sets the behaviour of the device for a played back sound when the sound doesn't return any more samples.

Parameters

keep	True when the source should be paused and not deleted.

Returns

true if the behaviour has been changed.
false if the handle is invalid.

Implements IHandle.

◆ setLocation()

virtual bool SoftwareDevice::SoftwareHandle::setLocation ( const Vector3 & location )

virtual

Sets the location of the source.

Parameters

location The new location.

Returns: Whether the action succeeded.

Note: The location is not updated with the velocity and remains constant until the next call of this method.

Implements I3DHandle.

◆ setLoopCount()

virtual bool SoftwareDevice::SoftwareHandle::setLoopCount ( int count )

virtual

Sets the loop count of a playing sound.

A negative value indicates infinity.

Parameters

count The new loop count.

Returns

true if the handle is valid.
false if the handle is invalid.

Implements IHandle.

◆ setOrientation()

virtual bool SoftwareDevice::SoftwareHandle::setOrientation ( const Quaternion & orientation )

virtual

Sets the orientation of the source.

Parameters

orientation The new orientation as quaternion.

Returns: Whether the action succeeded.

Note: The coordinate system used is right handed and the source by default is oriented looking in the negative z direction with the positive y axis as up direction.; This setting currently only affects sounds with non-default cone settings.

Implements I3DHandle.

◆ setPitch()

virtual bool SoftwareDevice::SoftwareHandle::setPitch ( float pitch )

virtual

Sets the pitch of a playing sound.

Parameters

pitch The pitch.

Returns

true if the handle is valid.
false if the handle is invalid.

Implements IHandle.

◆ setRelative()

virtual bool SoftwareDevice::SoftwareHandle::setRelative ( bool relative )

virtual

Sets whether the source location, velocity and orientation are relative to the listener.

Parameters

relative Whether the source is relative.

Returns: Whether the action succeeded.

Note: The default value is true as this setting is used to play sounds ordinarily without 3D.

Implements I3DHandle.

◆ setSpecs()

void SoftwareDevice::SoftwareHandle::setSpecs ( Specs specs )

Sets the audio output specification of the readers.

Parameters

specs The output specification.

◆ setStopCallback()

virtual bool SoftwareDevice::SoftwareHandle::setStopCallback	(	stopCallback	callback = `0`,
		void *	data = `0`
	)

virtual

Sets the callback function that's called when the end of a playing sound is reached.

Parameters

callback	The callback function.
data	The data that should be passed to the callback function.

Returns

true if the handle is valid.
false if the handle is invalid.

Implements IHandle.

◆ setVelocity()

virtual bool SoftwareDevice::SoftwareHandle::setVelocity ( const Vector3 & velocity )

virtual

Sets the velocity of the source.

Parameters

velocity The new velocity.

Returns: Whether the action succeeded.

Note: This velocity does not change the position of the listener over time, it is simply used for the calculation of the doppler effect.

Implements I3DHandle.

◆ setVolume()

virtual bool SoftwareDevice::SoftwareHandle::setVolume ( float volume )

virtual

Sets the volume of a playing sound.

Parameters

volume The volume.

Returns

true if the handle is valid.
false if the handle is invalid.

Implements IHandle.

◆ setVolumeMaximum()

virtual bool SoftwareDevice::SoftwareHandle::setVolumeMaximum ( float volume )

virtual

Sets the maximum volume of a source.

Parameters

volume The new maximum volume.

Returns: Whether the action succeeded.

Implements I3DHandle.

◆ setVolumeMinimum()

virtual bool SoftwareDevice::SoftwareHandle::setVolumeMinimum ( float volume )

virtual

Sets the minimum volume of a source.

Parameters

volume The new minimum volume.

Returns: Whether the action succeeded.

Implements I3DHandle.

◆ stop()

virtual bool SoftwareDevice::SoftwareHandle::stop ( )

virtual

Stops a played back or paused sound.

The handle is definitely invalid afterwards.

Returns

true if the sound has been stopped.
false if the handle is invalid.

Implements IHandle.

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

devices/SoftwareDevice.h

Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ SoftwareHandle()

Member Function Documentation

◆ getAttenuation()

◆ getConeAngleInner()

◆ getConeAngleOuter()

◆ getConeVolumeOuter()

◆ getDistanceMaximum()

◆ getDistanceReference()

◆ getKeep()

◆ getLocation()

◆ getLoopCount()

◆ getOrientation()

◆ getPitch()

◆ getPosition()

◆ getStatus()

◆ getVelocity()

◆ getVolume()

◆ getVolumeMaximum()

◆ getVolumeMinimum()

◆ isRelative()

◆ pause() [1/2]

◆ pause() [2/2]

◆ resume()

◆ seek()

◆ setAttenuation()

◆ setConeAngleInner()

◆ setConeAngleOuter()

◆ setConeVolumeOuter()

◆ setDistanceMaximum()

◆ setDistanceReference()

◆ setKeep()

◆ setLocation()

◆ setLoopCount()

◆ setOrientation()

◆ setPitch()

◆ setRelative()

◆ setSpecs()

◆ setStopCallback()

◆ setVelocity()

◆ setVolume()

◆ setVolumeMaximum()

◆ setVolumeMinimum()

◆ stop()