Energy Field

Typedefs

typedef struct _IPLEnergyField_t *IPLEnergyField

An energy field.

Energy fields represent a histogram of sound energy arriving at a point, as a function of incident direction, frequency band, and arrival time.

Time is subdivided into “bins” of the histogram, with each bin corresponding to 10ms. For each bin, incident energy is stored separately for each frequency band. For a given frequency band and time bin, we store an Ambisonic representation of the variation of incident energy as a function of direction.

Energy field data is stored as a 3D array of size #channels * #bands * #bins, in row-major order.

Functions

IPLerror iplEnergyFieldCreate(IPLContext context, IPLEnergyFieldSettings *settings, IPLEnergyField *energyField)

Creates an energy field.

Parameters:

  • context – The context used to initialize Steam Audio.

  • settings – The settings to use when creating the energy field.

  • energyField – [out] The created energy field.

Returns:

Status code indicating whether or not the operation succeeded.

IPLEnergyField iplEnergyFieldRetain(IPLEnergyField energyField)

Retains an additional reference to an energy field.

Parameters:

energyField – The energy field to retain a reference to.

Returns:

The additional reference to the energy field.

void iplEnergyFieldRelease(IPLEnergyField *energyField)

Releases a reference to an energy field.

Parameters:

energyField – The energy field to release a reference to.

IPLint32 iplEnergyFieldGetNumChannels(IPLEnergyField energyField)

Returns the number of channels in the energy field.

Parameters:

energyField – The energy field.

Returns:

The number of channels in the energy field.

IPLint32 iplEnergyFieldGetNumBins(IPLEnergyField energyField)

Returns the number of bins in the energy field.

Parameters:

energyField – The energy field.

Returns:

The number of bins in the energy field.

IPLfloat32 *iplEnergyFieldGetData(IPLEnergyField energyField)

Returns a pointer to the data stored in the energy field.

Parameters:

energyField – The energy field.

Returns:

Pointer to #channels * #bands * #bins IPLfloat32 values stored in the energy field, in row-major order.

IPLfloat32 *iplEnergyFieldGetChannel(IPLEnergyField energyField, IPLint32 channelIndex)

Returns a pointer to the data stored in the energy field for the given channel.

Parameters:

  • energyField – The energy field.

  • channelIndex – Index of the channel.

Returns:

Pointer to #bands * #bins IPLfloat32 values stored in the energy field for the given channel, in row-major order.

IPLfloat32 *iplEnergyFieldGetBand(IPLEnergyField energyField, IPLint32 channelIndex, IPLint32 bandIndex)

Returns a pointer to the data stored in the energy field for the given channel and band.

Parameters:

  • energyField – The energy field.

  • channelIndex – Index of the channel.

  • bandIndex – Index of the band.

Returns:

Pointer to #bins IPLfloat32 values stored in the energy field for the given channel and band, in row-major order.

void iplEnergyFieldReset(IPLEnergyField energyField)

Resets all values stored in an energy field to zero.

Parameters:

energyField – The energy field.

void iplEnergyFieldCopy(IPLEnergyField src, IPLEnergyField dst)

Copies data from one energy field into another.

If the source and destination energy fields have different numbers of channels, only the smaller of the two numbers of channels will be copied.

If the source and destination energy fields have different numbers of bins, only the smaller of the two numbers of bins will be copied.

Parameters:

  • src – The source energy field.

  • dst – The destination energy field.

void iplEnergyFieldSwap(IPLEnergyField a, IPLEnergyField b)

Swaps the data contained in one energy field with the data contained in another energy field.

The two energy fields may contain different numbers of channels or bins.

Parameters:

  • a – The first energy field.

  • b – The second energy field.

void iplEnergyFieldAdd(IPLEnergyField in1, IPLEnergyField in2, IPLEnergyField out)

Adds the values stored in two energy fields, and stores the result in a third energy field.

If the energy fields have different numbers of channels, only the smallest of the three numbers of channels will be added.

If the energy fields have different numbers of bins, only the smallest of the three numbers of bins will be added.

This function can be used for in-place addition, i.e. out may be equal to in1 or in2.

Parameters:

  • in1 – The first input energy field.

  • in2 – The second input energy field.

  • out – The output energy field.

void iplEnergyFieldScale(IPLEnergyField in, IPLfloat32 scalar, IPLEnergyField out)

Scales the values stored in an energy field by a scalar, and stores the result in a second energy field.

If the energy fields have different numbers of channels, only the smallest of the two numbers of channels will be scaled.

If the energy fields have different numbers of bins, only the smallest of the two numbers of bins will be scaled.

This function can be used for in-place scaling, i.e. out may be equal to in.

Parameters:

  • in – The input energy field.

  • scalar – The scalar value.

  • out – The output energy field.

void iplEnergyFieldScaleAccum(IPLEnergyField in, IPLfloat32 scalar, IPLEnergyField out)

Scales the values stored in an energy field by a scalar, and adds the result to a second energy field.

If the energy fields have different numbers of channels, only the smallest of the two numbers of channels will be added.

If the energy fields have different numbers of bins, only the smallest of the two numbers of bins will be added.

This function can be used for in-place operation, i.e. out may be equal to in.

Parameters:

  • in – The input energy field.

  • scalar – The scalar value.

  • out – The output energy field.

Structures

struct IPLEnergyFieldSettings

Settings used to create an energy field.

Public Members

IPLfloat32 duration

Total duration (in seconds) of the energy field.

This determines the number of bins in each channel and band.

IPLint32 order

The Ambisonic order.

This determines the number of channels.