Simulation

Typedefs

typedef struct _IPLSource_t *IPLSource

A sound source, for the purposes of simulation.

This object is used to specify various parameters for direct and indirect sound propagation simulation, and to retrieve the simulation results.

typedef struct _IPLSimulator_t *IPLSimulator

Manages direct and indirect sound propagation simulation for multiple sources.

Your application will typically create one simulator object and use it to run simulations with different source and listener parameters between consecutive simulation runs. The simulator can also be reused across scene changes.

Functions

IPLfloat32 iplDistanceAttenuationCalculate(IPLContext context, IPLVector3 source, IPLVector3 listener, IPLDistanceAttenuationModel *model)

Calculates the distance attenuation between a source and a listener.

Parameters

  • context – The context used to initialize Steam Audio.

  • source – The position of the source.

  • listener – The position of the listener.

  • model – The distance attenuation model to use.

Returns

The distance attenuation to apply, between 0 and 1.

void iplAirAbsorptionCalculate(IPLContext context, IPLVector3 source, IPLVector3 listener, IPLAirAbsorptionModel *model, IPLfloat32 *airAbsorption)

Calculates the air absorption coefficients between a source and a listener.

Parameters

  • context – The context used to initialize Steam Audio.

  • source – The position of the source.

  • listener – The position of the listener.

  • model – The air absorption model to use.

  • airAbsorption – [out] The 3-band air absorption coefficients, each between 0 and 1.

IPLfloat32 iplDirectivityCalculate(IPLContext context, IPLCoordinateSpace3 source, IPLVector3 listener, IPLDirectivity *model)

Calculates the attenuation of a source due to its directivity pattern and orientation relative to a listener.

Parameters

  • context – The context used to initialize Steam Audio.

  • source – The position and orientation of the source.

  • listener – The position of the listener.

  • model – The directivity pattern to use.

Returns

The directivity value to apply, between 0 and 1.

IPLerror iplSourceCreate(IPLSimulator simulator, IPLSourceSettings *settings, IPLSource *source)

Creates a simulation source.

Parameters

  • simulator – The simulator with which this source will be used.

  • settings – The settings to use for creating the source.

  • source – [out] The created source.

Returns

Status code indicating whether or not the operation succeeded.

IPLSource iplSourceRetain(IPLSource source)

Retains an additional reference to a source.

Parameters

source – The source to retain a reference to.

Returns

The additional reference to the source.

void iplSourceRelease(IPLSource *source)

Releases a reference to a source.

Parameters

source – The source to release a reference to.

void iplSourceAdd(IPLSource source, IPLSimulator simulator)

Adds a source to the set of sources processed by a simulator in subsequent simulations.

Parameters

  • simulator – The simulator being used.

  • source – The source to add.

void iplSourceRemove(IPLSource source, IPLSimulator simulator)

Removes a source from the set of sources processed by a simulator in subsequent simulations.

Parameters

  • simulator – The simulator being used.

  • source – The source to remove.

void iplSourceSetInputs(IPLSource source, IPLSimulationFlags flags, IPLSimulationInputs *inputs)

Specifies simulation parameters for a source.

Parameters

  • source – The source to specify parameters for.

  • flags – The types of simulation for which to specify inputs. If, for example, direct and reflections simulations are being run on separate threads, you can call this function on the direct simulation thread with IPL_SIMULATIONFLAGS_DIRECT, and on the reflections simulation thread with IPL_SIMULATIONFLAGS_REFLECTIONS, without requiring any synchronization between the calls.

  • inputs – The input parameters to set.

void iplSourceGetOutputs(IPLSource source, IPLSimulationFlags flags, IPLSimulationOutputs *outputs)

Retrieves simulation results for a source.

Parameters

  • source – The source to retrieve results for.

  • flags – The types of simulation for which to retrieve results.

  • outputs – [out] The simulation results.

IPLerror iplSimulatorCreate(IPLContext context, IPLSimulationSettings *settings, IPLSimulator *simulator)

Creates a simulator.

Parameters

  • context – The context used to initialize Steam Audio.

  • settings – The settings to use when creating the simulator.

  • simulator – [out] The created simulator.

Returns

Status code indicating whether or not the operation succeeded.

IPLSimulator iplSimulatorRetain(IPLSimulator simulator)

Retains an additional reference to a simulator.

Parameters

simulator – The simulator to retain a reference to.

Returns

The additional reference to the simulator.

void iplSimulatorRelease(IPLSimulator *simulator)

Releases a reference to a simulator.

Parameters

simulator – The simulator to release a reference to.

void iplSimulatorSetScene(IPLSimulator simulator, IPLScene scene)

Specifies the scene within which all subsequent simulations should be run.

Call iplSimulatorCommit after calling this function for the changes to take effect.

This function cannot be called while any simulation is running.

Parameters

  • simulator – The simulator being used.

  • scene – The scene to use for simulations.

void iplSimulatorAddProbeBatch(IPLSimulator simulator, IPLProbeBatch probeBatch)

Adds a probe batch for use in subsequent simulations.

Sources that require baked data can then use the data contained in the specified probe batch.

Call iplSimulatorCommit after calling this function for the changes to take effect.

This function cannot be called while any simulation is running.

Parameters

  • probeBatch – The probe batch to add.

  • simulator – The simulator being used.

void iplSimulatorRemoveProbeBatch(IPLSimulator simulator, IPLProbeBatch probeBatch)

Removed a probe batch from use in subsequent simulations.

Sources that require baked data will then stop using the data contained in the specified probe batch.

Call iplSimulatorCommit after calling this function for the changes to take effect.

This function cannot be called while any simulation is running.

Parameters

  • probeBatch – The probe batch to remove.

  • simulator – The simulator being used.

void iplSimulatorSetSharedInputs(IPLSimulator simulator, IPLSimulationFlags flags, IPLSimulationSharedInputs *sharedInputs)

Specifies simulation parameters that are not associated with any particular source.

Parameters

  • simulator – The simulator being used.

  • flags – The types of simulation for which to specify shared inputs. If, for example, direct and reflections simulations are being run on separate threads, you can call this function on the direct simulation thread with IPL_SIMULATIONFLAGS_DIRECT, and on the reflections simulation thread with IPL_SIMULATIONFLAGS_REFLECTIONS, without requiring any synchronization between the calls.

  • sharedInputs – The shared input parameters to set.

void iplSimulatorCommit(IPLSimulator simulator)

Commits changes to the scene or probe batches used for simulation.

Call this function after calling iplSimulatorSetScene, iplSimulatorAddProbeBatch, or iplSimulatorRemoveProbeBatch for the changes to take effect.

This function cannot be called while any simulation is running.

Parameters

simulator – The simulator being used.

void iplSimulatorRunDirect(IPLSimulator simulator)

Runs a direct simulation for all sources added to the simulator.

This may include distance attenuation, air absorption, directivity, occlusion, and transmission.

This function should not be called from the audio processing thread if occlusion and/or transmission are enabled.

Parameters

simulator – The simulator being used.

void iplSimulatorRunReflections(IPLSimulator simulator)

Runs a reflections simulation for all sources added to the simulator.

This function can be CPU intensive, and should be called from a separate thread in order to not block either the audio processing thread or the game’s main update thread.

Parameters

simulator – The simulator being used.

void iplSimulatorRunPathing(IPLSimulator simulator)

Runs a pathing simulation for all sources added to the simulator.

This function can be CPU intensive, and should be called from a separate thread in order to not block either the audio processing thread or the game’s main update thread.

Parameters

simulator – The simulator being used.

Structures

struct IPLDistanceAttenuationModel

A distance attenuation model that can be used for modeling attenuation of sound over distance.

Can be used with both direct and indirect sound propagation.

Public Members

IPLDistanceAttenuationModelType type

The type of distance attenuation model to use.

IPLfloat32 minDistance

When type is IPL_DISTANCEATTENUATIONTYPE_INVERSEDISTANCE, no distance attenuation is applied to any sound whose distance from the listener is less than this value.

IPLDistanceAttenuationCallback callback

When type is IPL_DISTANCEATTENUATIONTYPE_CALLBACK, this function will be called whenever Steam Audio needs to evaluate distance attenuation.

void *userData

Pointer to arbitrary data that will be provided to the callback function whenever it is called.

May be NULL.

IPLbool dirty

Set to IPL_TRUE to indicate that the distance attenuation model defined by the callback function has changed since the last time simulation was run.

For example, the callback may be evaluating a curve defined in a GUI. If the user is editing the curve in real-time, set this to IPL_TRUE whenever the curve changes, so Steam Audio can update simulation results to match.

struct IPLAirAbsorptionModel

An air absorption model that can be used for modeling frequency-dependent attenuation of sound over distance.

Public Members

IPLAirAbsorptionModelType type

The type of air absorption model to use.

IPLfloat32 coefficients[3]

The exponential falloff coefficients to use when type is IPL_AIRABSORPTIONTYPE_EXPONENTIAL.

IPLAirAbsorptionCallback callback

When type is IPL_AIRABSORPTIONTYPE_CALLBACK, this function will be called whenever Steam Audio needs to evaluate air absorption.

void *userData

Pointer to arbitrary data that will be provided to the callback function whenever it is called.

May be NULL.

IPLbool dirty

Set to IPL_TRUE to indicate that the air absorption model defined by the callback function has changed since the last time simulation was run.

For example, the callback may be evaluating a set of curves defined in a GUI. If the user is editing the curves in real-time, set this to IPL_TRUE whenever the curves change, so Steam Audio can update simulation results to match.

struct IPLDirectivity

A directivity pattern that can be used to model changes in sound intensity as a function of the source’s orientation.

Can be used with both direct and indirect sound propagation.

The default directivity model is a weighted dipole. This is a linear blend between an omnidirectional source (which emits sound with equal intensity in all directions), and a dipole oriented along the z-axis in the source’s coordinate system (which focuses sound along the +z and -z axes). A callback function can be specified to implement any other arbitrary directivity pattern.

Public Members

IPLfloat32 dipoleWeight

How much of the dipole to blend into the directivity pattern.

0 = pure omnidirectional, 1 = pure dipole. 0.5f results in a cardioid directivity pattern.

IPLfloat32 dipolePower

How “sharp” the dipole is.

Higher values result in sound being focused within a narrower range of directions.

IPLDirectivityCallback callback

If non NULL, this function will be called whenever Steam Audio needs to evaluate a directivity pattern.

void *userData

Pointer to arbitrary data that will be provided to the callback function whenever it is called.

May be NULL.

struct IPLSimulationSettings

Settings used to create a simulator.

Public Members

IPLSimulationFlags flags

The types of simulation that this simulator will be used for.

IPLSceneType sceneType

The type of scene that will be used for simulations via iplSimulatorSetScene.

The scene type cannot change during the lifetime of a simulator object.

IPLReflectionEffectType reflectionType

The type of reflections effect that will be used to render the results of reflections simulation.

The reflections effect type cannot change during the lifetime of a simulator object.

IPLint32 maxNumOcclusionSamples

The maximum number of point samples to consider when calculating occlusion using the volumetric occlusion algorithm.

Different sources can use different numbers of samples, and the number of samples can change between simulation runs, but this is the maximum value. Increasing this value results in smoother occlusion transitions, at the cost of increased CPU usage.

IPLint32 maxNumRays

The maximum number of rays to trace from the listener when simulating reflections.

You can use different numbers of rays between simulation runs, but this is the maximum value. Increasing this value results in more accurate reflections, at the cost of increased CPU usage.

IPLint32 numDiffuseSamples

The number of directions to sample when generating diffusely reflected rays.

Increasing this value may increase the accuracy of diffuse reflections.

IPLfloat32 maxDuration

The maximum length (in seconds) of impulse responses generated by reflection simulations.

You can change this value betweeen simulation runs, but this is the maximum value. Increasing this value results in longer, more accurate reverb tails, at the cost of increased CPU and memory usage.

IPLint32 maxOrder

The maximum Ambisonic order of impulse responses generated by reflection simulations.

You can change this value between simulation runs, but this is the maximum value. Increasing this value results in more accurate directional variations in the impulse responses, at the cost of increased CPU and memory usage.

IPLint32 maxNumSources

The maximum number of sources for which reflection simulations will be run at any given time.

IPLint32 numThreads

The number of threads used for real-time reflection simulations.

IPLint32 rayBatchSize

If using custom ray tracer callbacks, this the number of rays that will be passed to the callbacks every time rays need to be traced.

IPLint32 numVisSamples

The number of point samples to consider when calculating probe-to-probe visibility for pathing simulations.

Baked paths may end up being occluded by dynamic objects, in which case you can configure the simulator to look for alternate paths in real time. This process will involve checking visibility between probes.

IPLint32 samplingRate

The sampling rate (in Hz) used for audio processing.

IPLint32 frameSize

The size (in samples) of the audio buffers used for audio processing.

IPLOpenCLDevice openCLDevice

The OpenCL device being used.

Only necessary if \sceneType is IPL_SCENETYPE_RADEONRAYS, or reflectionType is IPL_REFLECTIONEFFECTTYPE_TAN.

IPLRadeonRaysDevice radeonRaysDevice

The Radeon Rays device being used.

Only necessary if \sceneType is IPL_SCENETYPE_RADEONRAYS.

IPLTrueAudioNextDevice tanDevice

The TrueAudio Next device being used.

Only necessary if reflectionType is IPL_REFLECTIONEFFECTTYPE_TAN.

struct IPLSourceSettings

Settings used to create a source.

Public Members

IPLSimulationFlags flags

The types of simulation that may be run for this source.

struct IPLSimulationInputs

Simulation parameters for a source.

Public Members

IPLSimulationFlags flags

The types of simulation to run for this source.

IPLDirectSimulationFlags directFlags

The types of direct simulation to run for this source.

IPLCoordinateSpace3 source

The position and orientation of this source.

IPLDistanceAttenuationModel distanceAttenuationModel

The distance attenuation model to use for this source.

IPLAirAbsorptionModel airAbsorptionModel

The air absorption model to use for this source.

IPLDirectivity directivity

The directivity pattern to use for this source.

IPLOcclusionType occlusionType

The occlusion algorithm to use for this source.

IPLfloat32 occlusionRadius

If using volumetric occlusion, the source is modeled as a sphere with this radius.

IPLint32 numOcclusionSamples

If using volumetric occlusion, this is the number of point samples to consider when tracing rays.

This value can change between simulation runs.

IPLfloat32 reverbScale[3]

If using parametric or hybrid reverb for rendering reflections, the reverb decay times for each frequency band are scaled by these values.

Set to {1.0f, 1.0f, 1.0f} to use the simulated values without modification.

IPLfloat32 hybridReverbTransitionTime

If using hybrid reverb for rendering reflections, this is the length (in seconds) of impulse response to use for convolution reverb.

The rest of the impulse response will be used for parametric reverb estimation only. Increasing this value results in more accurate reflections, at the cost of increased CPU usage.

IPLfloat32 hybridReverbOverlapPercent

If using hybrid reverb for rendering reflections, this is the amount of overlap between the convolution and parametric parts.

To ensure smooth transitions from the early convolution part to the late parametric part, the two are cross-faded towards the end of the convolution part. For example, if hybridReverbTransitionTime is 1.0f, and hybridReverbOverlapPercent is 0.25f, then the first 0.75 seconds are pure convolution, the next 0.25 seconds are a blend between convolution and parametric, and the portion of the tail beyond 1.0 second is pure parametric.

IPLbool baked

If IPL_TRUE, this source will used baked data for reflections simulation.

IPLBakedDataIdentifier bakedDataIdentifier

The identifier used to specify which layer of baked data to use for simulating reflections for this source.

IPLProbeBatch pathingProbes

The probe batch within which to find paths from this source to the listener.

IPLfloat32 visRadius

When testing for mutual visibility between a pair of probes, each probe is treated as a sphere of this radius (in meters), and point samples are generated within this sphere.

IPLfloat32 visThreshold

When tracing rays to test for mutual visibility between a pair of probes, the fraction of rays that are unoccluded must be greater than this threshold for the pair of probes to be considered mutually visible.

IPLfloat32 visRange

If the distance between two probes is greater than this value, the probes are not considered mutually visible.

Increasing this value can result in simpler paths, at the cost of increased CPU usage.

IPLint32 pathingOrder

If simulating pathing, this is the Ambisonic order used for representing path directionality.

Higher values result in more precise spatialization of paths, at the cost of increased CPU usage.

IPLbool enableValidation

If IPL_TRUE, baked paths are tested for visibility.

This is useful if your scene has dynamic objects that might occlude baked paths.

IPLbool findAlternatePaths

If IPL_TRUE, and enableValidation is IPL_TRUE, then if a baked path is occluded by dynamic geometry, path finding is re-run in real-time to find alternate paths that take into account the dynamic geometry.

IPLint32 numTransmissionRays

If simulating transmission, this is the maximum number of surfaces, starting from the closest surface to the listener, whose transmission coefficients will be considered when calculating the total amount of sound transmitted.

Increasing this value will result in more accurate results when multiple surfaces lie between the source and the listener, at the cost of increased CPU usage.

struct IPLSimulationSharedInputs

Simulation parameters that are not specific to any source.

Public Members

IPLCoordinateSpace3 listener

The position and orientation of the listener.

IPLint32 numRays

The number of rays to trace from the listener.

Increasing this value results in more accurate reflections, at the cost of increased CPU usage.

IPLint32 numBounces

The number of times each ray traced from the listener is reflected when it encounters a solid object.

Increasing this value results in longer, more accurate reverb tails, at the cost of increased CPU usage during simulation.

IPLfloat32 duration

The duration (in seconds) of the impulse responses generated when simulating reflections.

Increasing this value results in longer, more accurate reverb tails, at the cost of increased CPU usage during audio processing.

IPLint32 order

The Ambisonic order of the impulse responses generated when simulating reflections.

Increasing this value results in more accurate directional variation of reflected sound, at the cost of increased CPU usage during audio processing.

IPLfloat32 irradianceMinDistance

When calculating how much sound energy reaches a surface directly from a source, any source that is closer than irradianceMinDistance to the surface is assumed to be at a distance of irradianceMinDistance, for the purposes of energy calculations.

IPLPathingVisualizationCallback pathingVisCallback

Callback for visualizing valid path segments during call to iplSimulatorRunPathing.

void *pathingUserData

Pointer to arbitrary user-specified data provided when calling the function that will call this callback.

struct IPLSimulationOutputs

Simulation results for a source.

Public Members

IPLDirectEffectParams direct

Direct path simulation results.

IPLReflectionEffectParams reflections

Reflection simulation results.

IPLPathEffectParams pathing

Pathing simulation results.

Enumerations

enum IPLSimulationFlags

Flags indicating which types of simulation should be enabled for a given IPLSource.

Values:

enumerator IPL_SIMULATIONFLAGS_DIRECT

Enable direct simulation.

This includes distance attenuation, air absorption, directivity, occlusion, and transmission.

enumerator IPL_SIMULATIONFLAGS_REFLECTIONS

Enable reflections simulation.

This includes both real-time and baked simulation.

enumerator IPL_SIMULATIONFLAGS_PATHING

Enable pathing simulation.

enum IPLDirectSimulationFlags

Flags indicating which types of direct simulation should be enabled for a given IPLSource.

Values:

enumerator IPL_DIRECTSIMULATIONFLAGS_DISTANCEATTENUATION

Enable distance attenuation calculations.

enumerator IPL_DIRECTSIMULATIONFLAGS_AIRABSORPTION

Enable air absorption calculations.

enumerator IPL_DIRECTSIMULATIONFLAGS_DIRECTIVITY

Enable directivity calculations.

enumerator IPL_DIRECTSIMULATIONFLAGS_OCCLUSION

Enable occlusion simulation.

enumerator IPL_DIRECTSIMULATIONFLAGS_TRANSMISSION

Enable transmission simulation.

Requires occlusion to also be enabled.

enum IPLDistanceAttenuationModelType

The types of distance attenuation that can be used.

Values:

enumerator IPL_DISTANCEATTENUATIONTYPE_DEFAULT

The default distance attenuation model.

This is an inverse distance falloff, with all sounds within 1 meter of the listener rendered without distance attenuation.

enumerator IPL_DISTANCEATTENUATIONTYPE_INVERSEDISTANCE

An inverse distance falloff.

You can configure the minimum distance, within which distance attenuation is not applied.

enumerator IPL_DISTANCEATTENUATIONTYPE_CALLBACK

An arbitrary distance falloff function, defined by a callback function.

enum IPLAirAbsorptionModelType

The types of air absorption that can be used.

Values:

enumerator IPL_AIRABSORPTIONTYPE_DEFAULT

The default air absorption model.

This is an exponential falloff, with decay rates derived from physical properties of air.

enumerator IPL_AIRABSORPTIONTYPE_EXPONENTIAL

An exponential falloff.

You can configure the decay rates for each frequency band.

enumerator IPL_AIRABSORPTIONTYPE_CALLBACK

An arbitrary air absorption model, defined by a callback function.

enum IPLOcclusionType

The different algorithms for simulating occlusion.

Values:

enumerator IPL_OCCLUSIONTYPE_RAYCAST

Raycast occlusion.

A single ray is traced from the listener to the source. If the ray hits a solid object before it reaches the source, the source is considered occluded.

enumerator IPL_OCCLUSIONTYPE_VOLUMETRIC

A volumetric occlusion algorithm that can model partial occlusion.

The source is modeled as a sphere with a configurable radius. Multiple points are sampled within the volume of this sphere. Rays are then traced from each sample point to both the source and the listener. A sample point is considered occluded if either of these two rays is occluded. The occlusion value for the source is calculated as the fraction of sample points that are unoccluded. This algorithm allows for smoother transitions in and out of occlusion.

Callbacks

typedef float (*IPLDistanceAttenuationCallback)(IPLfloat32 distance, void *userData)

Callback for calculating how much attenuation should be applied to a sound based on its distance from the listener.

Parameters

  • distance – The distance (in meters) between the source and the listener.

  • userData – Pointer to the arbitrary data specified in the IPLDistanceAttenuationModel.

Returns

The distance attenuation to apply, between 0 and 1. 0 = the sound is not audible, 1 = the sound is as loud as it would be if it were emitted from the listener’s position.

typedef float (*IPLAirAbsorptionCallback)(IPLfloat32 distance, IPLint32 band, void *userData)

Callback for calculating how much air absorption should be applied to a sound based on its distance from the listener.

Parameters

  • distance – The distance (in meters) between the source and the listener.

  • band – Index of the frequency band for which to calculate air absorption. 0 = low frequencies, 1 = middle frequencies, 2 = high frequencies.

  • userData – Pointer to the arbitrary data specified in the IPLAirAbsorptionModel.

Returns

The air absorption to apply, between 0 and 1. 0 = sound in the frequency band band is not audible, 1 = sound in the frequency band band is not attenuated.

typedef float (*IPLDirectivityCallback)(IPLVector3 direction, void *userData)

Callback for calculating how much to attenuate a sound based on its directivity pattern and orientation in world space.

Parameters

  • direction – Unit vector (in world space) pointing forwards from the source. This is the direction that the source is “pointing towards”.

  • userData – Pointer to the arbitrary data specified in the IPLDirectivity.

Returns

The directivity value to apply, between 0 and 1. 0 = the sound is not audible, 1 = the sound is as loud as it would be if it had a uniform (omnidirectional) directivity pattern.

typedef void (*IPLPathingVisualizationCallback)(IPLVector3 from, IPLVector3 to, IPLbool occluded, void *userData)

Callback for visualizing valid path segments during call to iplSimulatorRunPathing.

You can use this to provide the user with visual feedback, like drawing each segment of a path.

Parameters

  • from – Position of starting probe.

  • to – Position of ending probe.

  • occluded – Occlusion status of ray segment between from to to.

  • userData – Pointer to arbitrary user-specified data provided when calling the function that will call this callback.