3D Panning

This page explains the steps involved in 3D panning. Note that only the panner strategy applies to PannedSource.

1. Convert the source's position from world coordinates to Azimuth, Elevation, and distance

This is done by converting the position, at, and up vectors to a transformation matrix. The result is a position in listener coordinates. Then application of the pythagorean theorem and basic trigonometry gets to spherical coordinates.

2. Compute the Gain from the Distance Model

Let d be the distance to the source, d_ref the reference distance, d_max the max distance, r the roll-off factor. Then the gain of the source is computed as a linear scalar using one of the following formulas:

ModelFormula
SYZ_DISTANCE_MODEL_NONE1.0
SYZ_DISTANCE_MODEL_LINEAR1 - r * (clamp(d, d_ref, d_max) - d_ref) / (d_max - d_ref);
SYZ_DISTANCE_MODEL_EXPONENTIAL when d_ref == 0.00.0
SYZ_DISTANCE_MODEL_EXPONENTIAL when d_ref > 0.0(max(d_ref, d) / d_ref) ** -r
SYZ_DISTANCE_MODEL_INVERSE when d_ref = 0.00.0
SYZ_DISTANCE_MODEL_INVERSE when d_ref > 0.0d_ref / (d_ref + r * max(d, d_ref) - d_ref)

Qualitatively, d_ref is the "size" of the source, d_max is where the source is silent, r is how fast the source becomes quieter. Mapping these to real world scenarios is difficult, and in general the best approach is to experiment for your use case.

3. Apply the closeness boost and clamp

The closeness boost, specified through SYZ_P_CLOSENESS_BOOST and SYZ_P_CLOSENESS_BOOST_DISTANCE is used to emphasize sources that have crossed a threshold of interest, i.e. because the player is now close enough to interact. SYZ_P_CLOSENESS_BOOST specifies a gain in DB (negative DB is allowed) which is added to the source's gain when the source is closer than SYZ_P_CLOSENESS_BOOST_DISTANCE.

After the closeness boost is applied, gain is clamped to the range 0.0 to 1.0.

4. Apply the Panning Strategy

The panning strategy specifies how sources are to be panned. SYnthizer supports the following panning strategies:

StrategyChannelsDescription
SYZ_PANNER_STRATEGY_HRTF2An HRTF implementation, intended for use via headphones.
SYZ_PANNER_STRATEGY_STEREO2A simple stereo panning strategy assuming speakers are at -90 and 90.