Probes

Typedefs

typedef struct _IPLProbeArray_t *IPLProbeArray

An array of sound probes.

Each probe has a position and a radius of influence.

typedef struct _IPLProbeBatch_t *IPLProbeBatch

A batch of sound probes, along with associated data.

The associated data may include reverb, reflections from a static source position, pathing, and more. This data is loaded and unloaded as a unit, either from disk or over the network.

Functions

IPLerror iplProbeArrayCreate(IPLContext context, IPLProbeArray *probeArray)

Creates an empty probe array.

Parameters

  • context – The context used to initialize Steam Audio.

  • probeArray – [out] The created probe array.

Returns

Status code indicating whether or not the operation succeeded.

IPLProbeArray iplProbeArrayRetain(IPLProbeArray probeArray)

Retains an additional reference to a probe array.

Parameters

probeArray – The probe array to retain a reference to.

Returns

The additional reference to the probe array.

void iplProbeArrayRelease(IPLProbeArray *probeArray)

Releases a reference to a probe array.

Parameters

probeArray – The probe array to release a reference to.

void iplProbeArrayGenerateProbes(IPLProbeArray probeArray, IPLScene scene, IPLProbeGenerationParams *params)

Generates probes and adds them to a probe array.

Parameters

  • scene – The scene in which to generate probes.

  • params – Parameters to use for generating probes.

  • probeArray – The array into which to add the generated probes.

IPLint32 iplProbeArrayGetNumProbes(IPLProbeArray probeArray)
Parameters

probeArray – The probe array.

Returns

The number of probes in a probe array.

IPLSphere iplProbeArrayGetProbe(IPLProbeArray probeArray, IPLint32 index)
Parameters

  • probeArray – The probe array.

  • index – Index of the probe within the array.

Returns

The probe at a given index in a probe array.

IPLerror iplProbeBatchCreate(IPLContext context, IPLProbeBatch *probeBatch)

Creates an empty probe batch.

Parameters

  • context – The context used to initialize Steam Audio.

  • probeBatch – [out] The created probe batch.

Returns

Status code indicating whether or not the operation succeeded.

IPLProbeBatch iplProbeBatchRetain(IPLProbeBatch probeBatch)

Retains an additional reference to a probe batch.

Parameters

probeBatch – The probe batch to retain a reference to.

Returns

The additional reference to the probe batch.

void iplProbeBatchRelease(IPLProbeBatch *probeBatch)

Releases a reference to a probe batch.

Parameters

probeBatch – The probe batch to release a reference to.

IPLerror iplProbeBatchLoad(IPLContext context, IPLSerializedObject serializedObject, IPLProbeBatch *probeBatch)

Loads a probe batch from a serialized object.

Typically, the serialized object will be created from a byte array loaded from disk or over the network.

Parameters

  • context – The context used to initialize Steam Audio.

  • serializedObject – The serialized object from which to load the probe batch.

  • probeBatch – [out] The created probe batch.

Returns

Status code indicating whether or not the operation succeeded.

void iplProbeBatchSave(IPLProbeBatch probeBatch, IPLSerializedObject serializedObject)

Saves a probe batch to a serialized object.

Typically, the serialized object will then be saved to disk.

Parameters

  • probeBatch – The probe batch to save.

  • serializedObject – The serialized object into which to save the probe batch.

IPLint32 iplProbeBatchGetNumProbes(IPLProbeBatch probeBatch)
Parameters

probeBatch – The probe batch.

Returns

The number of probes in a probe batch.

void iplProbeBatchAddProbe(IPLProbeBatch probeBatch, IPLSphere probe)

Adds a probe to a batch.

The new probe will be added as the last probe in the batch.

Parameters

  • probeBatch – The probe batch.

  • probe – The probe to add.

void iplProbeBatchAddProbeArray(IPLProbeBatch probeBatch, IPLProbeArray probeArray)

Adds every probe in an array to a batch.

The new probes will be added, in order, at the end of the batch.

Parameters

  • probeBatch – The probe batch.

  • probeArray – The probe array containing the probes to add.

void iplProbeBatchRemoveProbe(IPLProbeBatch probeBatch, IPLint32 index)

Removes a probe from a batch.

Parameters

  • probeBatch – The probe batch.

  • index – Index of the probe to remove.

void iplProbeBatchCommit(IPLProbeBatch probeBatch)

Commits all changes made to a probe batch since this function was last called (or since the probe batch was first created, if this function was never called).

This function must be called after adding, removing, or updating any probes in the batch, for the changes to take effect.

Parameters

probeBatch – The probe batch.

void iplProbeBatchRemoveData(IPLProbeBatch probeBatch, IPLBakedDataIdentifier *identifier)

Deletes a specific layer of data from a probe batch.

Parameters

  • probeBatch – The probe batch.

  • identifier – The identifier of the baked data layer to delete.

IPLsize iplProbeBatchGetDataSize(IPLProbeBatch probeBatch, IPLBakedDataIdentifier *identifier)
Parameters

  • probeBatch – The probe batch.

  • identifier – The identifier of the baked data layer.

Returns

The size (in bytes) of a specific baked data layer in a probe batch.

Structures

struct IPLProbeGenerationParams

Settings used to generate probes.

Public Members

IPLProbeGenerationType type

The algorithm to use for generating probes.

IPLfloat32 spacing

Spacing (in meters) between two neighboring probes.

Only for IPL_PROBEGENERATIONTYPE_UNIFORMFLOOR.

IPLfloat32 height

Height (in meters) above the floor at which probes will be generated.

Only for IPL_PROBEGENERATIONTYPE_UNIFORMFLOOR.

IPLMatrix4x4 transform

A transformation matrix that transforms an axis-aligned unit cube, with minimum and maximum vertices at (0, 0, 0) and (1, 1, 1), into a parallelopiped volume.

Probes will be generated within this volume.

struct IPLBakedDataIdentifier

Identifies a “layer” of data stored in a probe batch.

Each probe batch may store multiple layers of data, such as reverb, static source reflections, or pathing. Each layer can be accessed using an identifier.

Public Members

IPLBakedDataType type

The type of data stored.

IPLBakedDataVariation variation

The way in which source and listener positions depend on probe position.

IPLSphere endpointInfluence

The static source (for IPL_BAKEDDATAVARIATION_STATICSOURCE) or static listener (for IPL_BAKEDDATAVARIATION_STATICLISTENER) used to generate baked data.

Baked data is only stored for probes that lie within the radius of this sphere.

Enumerations

enum IPLProbeGenerationType

The different algorithms for generating probes.

Values:

enumerator IPL_PROBEGENERATIONTYPE_CENTROID

Generates a single probe at the center of the specified box.

enumerator IPL_PROBEGENERATIONTYPE_UNIFORMFLOOR

Generates probes that are uniformly-spaced, at a fixed height above solid geometry.

A probe will never be generated above another probe unless there is a solid object between them. The goal is to model floors or terrain, and generate probes that are a fixed height above the floor or terrain, and uniformly-spaced along the horizontal plane. This algorithm is not suitable for scenarios where the listener may fly into a region with no probes; if this happens, the listener will not be influenced by any of the baked data.

enum IPLBakedDataType

The types of baked data that can be stored in a probe batch.

Values:

enumerator IPL_BAKEDDATATYPE_REFLECTIONS

Reflections.

The source and listener positions used to compute the reflections data stored at each probe depends on the IPLBakedDataVariation selected.

enumerator IPL_BAKEDDATATYPE_PATHING

Pathing.

The probe batch stores data about the shortest paths between any pair of probes in the batch.

enum IPLBakedDataVariation

The different ways in which the source and listener positions used to generate baked data can vary as a function of probe position.

Values:

enumerator IPL_BAKEDDATAVARIATION_REVERB

At each probe, baked data is calculated with both the source and the listener at the probe position.

This is useful for modeling traditional reverbs, which depend only on the listener’s position (or only on the source’s position).

enumerator IPL_BAKEDDATAVARIATION_STATICSOURCE

At each probe, baked data is calculated with the source at some fixed position (specified separately), and the listener at the probe position.

This is used for modeling reflections from a static source to any point within the probe batch.

enumerator IPL_BAKEDDATAVARIATION_STATICLISTENER

At each probe, baked data is calculated with the source at the probe position, and the listener at some fixed position (specified separately).

This is used for modeling reflections from a moving source to a static listener.

enumerator IPL_BAKEDDATAVARIATION_DYNAMIC

Baked data is calculated for each pair of probes.

For example, this is used for calculating paths between every pair of probes in a batch.