AudioGroupFilter ( group,type[,frequency#][,q#] )
Parameters
|
group - mixing group: 0: SFX (default for LoadSound/Load3DSound) 1: Music (default for non-MIDI PlayMusic) 2: UI 3: Ambience type - filter type; frequency and q are checked but unused when off: 0: off 1: low-pass 2: high-pass 3: band-pass 4: notch 5: one-pole low-pass 6: one-pole high-pass frequency# (optional) - cutoff/centre frequency in Hz; 1000 (default) q# (optional) - filter resonance; 0.7071068 (default) |
Description
|
Sets the filter applied to a whole mixing group. Groups are 0=SFX, 1=Music, 2=UI and 3=Ambience. LoadSound/Load3DSound default to SFX; non-MIDI PlayMusic defaults to Music. Group processing includes dry sound and shared wet returns. Types 1-4 accept 20..8000 Hz and Q 0.667..10. Types 5-6 accept 20..20000 Hz and ignore Q. Off ignores frequency/Q after checking they are finite. There is one filter per source and one per group. Frequency changes ramp over about 20 ms; a type change briefly fades the signal. The group filter processes its combined dry and wet sound. Filter SFX/ambience for underwater audio while leaving music/UI clear. Call InitAudioEffects before the first WAV/Ogg playback. Configuration commands return 1 on success or 0 on failure; use AudioLastError for the reason. Finite numeric values and valid handles are required in Debug and Release. Queries preserve errors unless the query itself fails. Audio effects process decoded WAV and mono/stereo Ogg at an internal 48 kHz. MIDI uses a separate backend. Sound defaults are copied to independent playing channels. Runtime pause freezes sources, tails and transition time; pausing one channel leaves shared tails running. Event waits service transitions and release completed source resources without ChannelPlaying polling. Lightweight completed handles are retained until program shutdown. The interactive Audio Playground sample demonstrates the whole effects family together. Requires Extended mode. See also: SoundFilter, ChannelFilter, AudioGroupEQ, AudioGroupClearEffects. |
Example
; AudioGroupFilter Example ; ------------------------ ; Requires Extended mode. ; Effects must be initialized before the first WAV/Ogg playback If Not InitAudioEffects() Then RuntimeError AudioLastError$() Graphics 640,480,0,2 SetBuffer BackBuffer() ; A looping machine hum to hear the effect on sound=LoadSound("../../../samples/audio/media/machine.wav") If sound=0 Then RuntimeError "The audio sample media is missing." LoopSound sound SoundVolume sound,0.25 ; Meters make the audio state visible on screen RequireAudio AudioMasterMeter(True) RequireAudio AudioGroupMeter(0,True) ; One shared filter per group - classic underwater trick for SFX filter_type=1 frequency#=600 channel=PlaySound(sound) If channel=0 Then RuntimeError "Unable to play the example sound." While Not KeyDown(1) ; Space toggles the low-pass on and off, [ / ] sweep the frequency If KeyHit(57) If filter_type=1 Then filter_type=0 Else filter_type=1 EndIf If KeyDown(26) And frequency>120 Then frequency=frequency-20 If KeyDown(27) And frequency<8000 Then frequency=frequency+20 RequireAudio AudioGroupFilter(0,filter_type,frequency) Cls Text 0,0,"Space: filter on/off [ / ] : frequency Esc: exit" Text 0,20,"AudioGroupFilter 0,"+filter_type+","+frequency Text 0,40,"The group filter processes the combined dry and wet group sound" Text 0,80,"Group 0 peak: "+AudioGroupPeak(0)+" RMS: "+AudioGroupRMS(0) Text 0,100,"Master peak: "+AudioMasterPeak()+" RMS: "+AudioMasterRMS() Flip Wend ; Let shared effect tails fade before the program ends For group=0 To 3 RequireAudio AudioGroupClearEffects(group) Next StopChannel channel FreeSound sound End ; Stop with the recorded reason if an audio-effects call fails Function RequireAudio(success) If Not success Then RuntimeError AudioLastError$() End Function
Index