NAME

audio_gain - Retrieve and/or update the audio gain for a specific audio object.

SYNOPSIS

aid_gain
audio_gain( aid, gain, time )

DESCRIPTION

Each audio object has a separate gain property clamped to the 0..1 range, set to 1.0 by default when an object is loaded or created. The optional gain argument will update this for a specific audio source. The optional time argument applies a fade from the old gain to the new one, the interpolation function used is implementation defined.

NOTES

1: Any value outside the particular range will be clamped.
2: AID 0 is reserved for changing the default gain for new sources.
3: For the cases where the engine is responsible for pushing the audio
4: The gain value returned is the target gain, with a pending transformation, this state may not have been reached yet. to the target device, even a gain of 0.0 will generate data due to some buffering restrictions with underlying API s.
5: There's a logarithmic distribution applied internally to better mimic the linear appearance used in other sound interfaces.

EXAMPLE

function audio_gain0()
      local asrc = load_asample("sample.wav");
      audio_gain(asrc, 0.0, 100);
      play_audio(asrc);
end

MISUSE

function audio_gain0()
      local asrc = load_asample("sample.wav");
      audio_gain(asrc, -1.0, -1);
      play_audio(asrc);
end