Classes
struct	Microphone
	Properties of a logical audio microphone. A microphone also has a pose, which can be stored as a component of a microphone entity via components::Pose. More...

struct	Source
	Properties of a logical audio source. A source also has a pose, which can be stored as a component of a source entity via components::Pose. More...

struct	SourcePlayInfo
	A source's playing information. Useful for keeping track of when to start/stop playing a source. More...

Enumerations
enum class	AttenuationFunction { LINEAR , UNDEFINED }
	Audio source attenuation functions. AttenuationFunction::Undefined is used to indicate that an attenuation function has not been defined yet. More...

enum class	AttenuationShape { SPHERE , UNDEFINED }
	Audio source attenuation shapes. AttenuationShape::Undefined is used to indicate that an attenuation shape has not been defined yet. More...

Functions
GZ_SIM_LOGICALAUDIOSENSORPLUGIN_SYSTEM_VISIBLE double	computeVolume (bool _playing, AttenuationFunction _attenuationFunc, AttenuationShape _attenuationShape, double _sourceEmissionVolume, double _innerRadius, double _falloffDistance, const gz::math::Pose3d &_sourcePose, const gz::math::Pose3d &_targetPose)
	Computes the volume level of an audio source at a certain location. More...

GZ_SIM_LOGICALAUDIOSENSORPLUGIN_SYSTEM_VISIBLE bool	detect (double _volumeLevel, double _volumeDetectionThreshold)
	Determines if an audio device can detect volume at a certain level. More...

GZ_SIM_LOGICALAUDIOSENSORPLUGIN_SYSTEM_VISIBLE void	setAttenuationFunction (AttenuationFunction &_attenuationFunc, std::string _str)
	Set the attenuation function that matches the defined string. The string is not case sensitive, and must match the spelling of the values in AttenuationFunction. If the spelling does not match, the attenuation function is set as AttenuationFunction::Undefined. More...

GZ_SIM_LOGICALAUDIOSENSORPLUGIN_SYSTEM_VISIBLE void	setAttenuationShape (AttenuationShape &_attenuationShape, std::string _str)
	Set the attenuation shape that matches the defined string. The string is not case sensitive, and must match the spelling of the values in AttenuationShape. If the spelling does not match, the attenuation shape is set as AttenuationShape::Undefined. More...

GZ_SIM_LOGICALAUDIOSENSORPLUGIN_SYSTEM_VISIBLE void	validateInnerRadiusAndFalloffDistance (double &_innerRadius, double &_falloffDistance)
	Validate the inner radius and falloff distance for an audio source. More...

GZ_SIM_LOGICALAUDIOSENSORPLUGIN_SYSTEM_VISIBLE void	validateVolumeLevel (double &_volumeLevel)
	Validate a source's emission volume level. More...

Enumeration Type Documentation

◆ AttenuationFunction

enum AttenuationFunction

strong

Audio source attenuation functions. AttenuationFunction::Undefined is used to indicate that an attenuation function has not been defined yet.

Enumerator
LINEAR
UNDEFINED

◆ AttenuationShape

enum AttenuationShape

strong

Audio source attenuation shapes. AttenuationShape::Undefined is used to indicate that an attenuation shape has not been defined yet.

Enumerator
SPHERE
UNDEFINED

Function Documentation

◆ computeVolume()

GZ_SIM_LOGICALAUDIOSENSORPLUGIN_SYSTEM_VISIBLE double gz::sim::logical_audio::computeVolume	(	bool	_playing,
		AttenuationFunction	_attenuationFunc,
		AttenuationShape	_attenuationShape,
		double	_sourceEmissionVolume,
		double	_innerRadius,
		double	_falloffDistance,
		const gz::math::Pose3d &	_sourcePose,
		const gz::math::Pose3d &	_targetPose
	)

Computes the volume level of an audio source at a certain location.

Note: Users should call logical_audio::ValidateInnerRadiusAndFalloffDistance and logical_audio::ValidateVolumeLevel before calling this method in order to prevent undefined behavior.

Parameters

[in]	_playing	Whether the audio source is playing or not.
[in]	_attenuationFunc	The source's attenuation function.
[in]	_attenuationShape	The source's attenuation shape.
[in]	_sourceEmissionVolume	The source's emission volume level.
[in]	_innerRadius	The source's inner radius, which should be >= 0.
[in]	_falloffDistance	The source's falloffDistance, which should be greater than _innerRadius.
[in]	_sourcePose	The source's pose.
[in]	_targetPose	The pose where the volume level should be calculated.

Returns: The volume level at this location. If the attenuation function or shape is undefined, -1.0 is returned. If the source is not playing, 0.0 is returned.

◆ detect()

GZ_SIM_LOGICALAUDIOSENSORPLUGIN_SYSTEM_VISIBLE bool gz::sim::logical_audio::detect	(	double	_volumeLevel,
		double	_volumeDetectionThreshold
	)

Determines if an audio device can detect volume at a certain level.

Parameters

[in]	_volumeLevel	The volume level that the microphone is attempting to detect. This should be a value between 0.0 (no volume) and 1.0 (maximum volume).
[in]	_volumeDetectionThreshold	The listening device's minimum audio detection volume. This should be a value between 0.0 and 1.0. A device with a low detection threshold can hear a wider range of audio than a device with a higher detection threshold.

Returns: true if the listening device can detect volume at _volumeLevel, false otherwise.

◆ setAttenuationFunction()

GZ_SIM_LOGICALAUDIOSENSORPLUGIN_SYSTEM_VISIBLE void gz::sim::logical_audio::setAttenuationFunction	(	AttenuationFunction &	_attenuationFunc,
		std::string	_str
	)

Set the attenuation function that matches the defined string. The string is not case sensitive, and must match the spelling of the values in AttenuationFunction. If the spelling does not match, the attenuation function is set as AttenuationFunction::Undefined.

Example: to set the attenuation function to AttenuationFunction::Linear, the following are examples of valid strings: "linear", "Linear", "LINEAR"

Parameters

[out]	_attenuationFunc	A reference to the variable that stores the calculated attenuation function.
[in]	_str	A string that should map to a value in AttenuationFunction.

◆ setAttenuationShape()

GZ_SIM_LOGICALAUDIOSENSORPLUGIN_SYSTEM_VISIBLE void gz::sim::logical_audio::setAttenuationShape	(	AttenuationShape &	_attenuationShape,
		std::string	_str
	)

Set the attenuation shape that matches the defined string. The string is not case sensitive, and must match the spelling of the values in AttenuationShape. If the spelling does not match, the attenuation shape is set as AttenuationShape::Undefined.

Example: to set the attenuation shape to AttenuationShape::Sphere, the following are examples of valid strings: "sphere", "Sphere", "SPHERE"

Parameters

[out]	_attenuationShape	A reference to the variable that stores the calculated attenuation shape.
[in]	_str	A string that should map to a value in AttenuationShape.

◆ validateInnerRadiusAndFalloffDistance()

GZ_SIM_LOGICALAUDIOSENSORPLUGIN_SYSTEM_VISIBLE void gz::sim::logical_audio::validateInnerRadiusAndFalloffDistance	(	double &	_innerRadius,
		double &	_falloffDistance
	)

Validate the inner radius and falloff distance for an audio source.

Parameters

[in,out]	_innerRadius	The inner radius to set for the source. This value must be > 0. If the value of this parameter is < 0, the source's inner radius will be set to 0.
[in,out]	_falloffDistance	The falloff distance to set for the source. This value must be greater than _innerRadius. If _falloffDistance < _innerRadius, _falloffDistance will be set to _innerRadius + 1 (assuming that _innerRadius is valid).

◆ validateVolumeLevel()

GZ_SIM_LOGICALAUDIOSENSORPLUGIN_SYSTEM_VISIBLE void gz::sim::logical_audio::validateVolumeLevel ( double & _volumeLevel )

Validate a source's emission volume level.

Parameters

[in,out] _volumeLevel The volume the source should play at. This parameter is checked (and possibly clipped) to ensure that it falls between 0.0 (0% volume) and 1.0 (100% volume).

Gazebo Sim

API Reference

Classes

Enumerations

Functions

Enumeration Type Documentation

◆ AttenuationFunction

◆ AttenuationShape

Function Documentation

◆ computeVolume()

◆ detect()

◆ setAttenuationFunction()

◆ setAttenuationShape()

◆ validateInnerRadiusAndFalloffDistance()

◆ validateVolumeLevel()