dbapgains

Distance-Based Amplitude Panning gain vector generator.

dbapgains implements the same algorithm as dbap, including the optional soft-limited spread control, but instead of applying the spatialization to an input audio signal, it outputs only the vector of per-loudspeaker gains.

Syntax

ModernClassic

    var:k[] = dbapgains(mode:i, src:k[], lpos:i[][], sprd:k, rloff:i [, wgts:i[]])
    var:k[] = dbapgains(mode:i, src:k[], lpos:i, sprd:k, rloff:i, ldim:i [, wgts:i])

    kvar[] dbapgains imode, ksrc[], ilpos[][], ksprd, irloff [, iwgts[]]
    kvar[] dbapgains imode, ksrc[], ilpos, ksprd, irloff, ildim [, iwgts:i]

Initialization

mode -- Coordinate interpretation mode. Specifies how loudspeaker coordinates are interpreted: 0 = cartesian coordinates (x, y, z); 1 = polar coordinates in degrees (rho, phi, theta or phi, theta); 2 = polar coordinates in radians (rho, phi, theta or phi, theta).

lpos:i[][]/lpos:i -- Loudspeaker position definition. Defines the loudspeaker layout. It can be either: a 2D i-rate array of size n x 2 or n 3 (where n is the number of loudspeakers), or a function table containing the same data sequentially. Depending on coordinate mode arg, each loudspeaker can be defines in two- (x, y or phi, theta) or three-dimension (x, y, z or rho, phi, theta).

rloff -- rolloff coefficient controlling amplitude decay as a function of distance. Higher values produce a steeper attenuation with distance, increasing localization sharpness, while lower values result in a more diffuse spatial distribution.

ldim -- Dimension of loudspeaker position (2 or 3). This argument is only required when a function table is used to define the loudspeaker positions, indicating whether the data represents a 2D or 3D layout.

wgts:i[][]/wgets:i -- (optional) per-loudspeaker weighting factors. If provided, the array or GEN function must contain one value per loudspeaker. Each weight w_i scales the corresponding gain.

Performance

sprd:k -- spread factor (>= 0) controlling spatial focus. The gain for each loudspeaker is computed as

g_i = (k * w_i * b_i) / (d_i^a) * exp(-beta d_i)

where

beta = spread / (mean_distance + 1e-6)

The exponential term introduces a soft decay:

gain *= exp(-beta * distance)

Increasing sprd results in tighter spatial focus. When sprd = 0, the algorithm reduces to the classical DBAP formulation.

Examples

Here is an example of the dbap opcode. It uses the file dbapgains.csd.

Example of the dbapgains opcode.
<CsoundSynthesizer>
<CsOptions>
-n
</CsOptions>
<CsInstruments>

sr = 44100
ksmps = 1
nchnls = 8
0dbfs  = 1

/*
In instrument #1, the dbapgains opcode is tested by computing the gain
vector for eight loudspeakers arranged in a circular configuration.
A static source is positioned sequentially at azimuth angles matching
each loudspeaker (0°, 45°, ..., 315°). The gain vector is recalculated
at each step, and the resulting values are printed periodically to
verify that the maximum gain corresponds to the loudspeaker located
at the source position.
*/

instr 1
    ndx_count:k = init(0)

    dbap_gains:k[] = init(8) // init 8 channels gains vector

    // set loudspeaker positions
    lpos:i[][] = init(8, 2)
    lpos = [0, 0, 45, 0, 90, 0, 135, 0, 180, 0, 225, 0, 270, 0, 315, 0] // loudspeker positions

    // define source angle
    azi:i[] = [0, 45, 90, 135, 180, 225, 270, 315]
    source:k[] = [azi[ndx_count], 0.0]

    // solve gain vector
    smooth_decay:k = expseg(0.001, p3 / 2, 5, p3 / 2, 0.0001) // variable smooth_decay
    dbap_gains = dbapgains:k[](1, source, lpos, smooth_decay, 24.0)

    trig:k = metro(5)
    printarray(dbap_gains, trig, "", "GAINS VECTOR = ")

    ndx_count += 1
    ndx_count = ndx_count % 8

endin
</CsInstruments>
<CsScore>

i 1 0 3

</CsScore>
</CsoundSynthesizer>

Credits

Author: Pasquale Mainolfi
Italy
New in Csound version 7.0 February 2026.