Difference between revisions of "Source:setFilter"

(Created page)
 
(Note about effects.)
 
(6 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{newin|[[0.11.0]]|110|type=function}}
+
{{newin|[[11.0]]|110|type=function}}
 
Sets a low-pass, high-pass, or band-pass filter to apply when playing the Source.
 
Sets a low-pass, high-pass, or band-pass filter to apply when playing the Source.
  
Line 11: Line 11:
 
{{subparam|FilterType|type|The type of filter to use.}}
 
{{subparam|FilterType|type|The type of filter to use.}}
 
{{subparam|number|volume|The overall volume of the audio. Must be between 0 and 1.}}
 
{{subparam|number|volume|The overall volume of the audio. Must be between 0 and 1.}}
{{subparam|number|highgain|Volume of high-frequency audio. Only applies to low-pass and band-pass filters. Must be between 0 and 1.}}
+
{{subparam|number|highgain|Volume of high-frequency audio. Only applies to <code>lowpass</code> and <code>bandpass</code> filters. Must be between 0 and 1.}}
{{subparam|number|lowgain|Volume of low-frequency audio. Only applies to high-pass and band-pass filters. Must be between 0 and 1.}}
+
{{subparam|number|lowgain|Volume of low-frequency audio. Only applies to <code>highpass</code> and <code>bandpass</code> filters. Must be between 0 and 1.}}
 
 
 
=== Returns ===
 
=== Returns ===
 
{{param|boolean|success|Whether the filter was successfully applied to the Source.}}
 
{{param|boolean|success|Whether the filter was successfully applied to the Source.}}
Line 27: Line 26:
 
=== Returns ===
 
=== Returns ===
 
Nothing.
 
Nothing.
 +
 +
== Examples ==
 +
=== Play music at half volume with a low-pass filter applied ===
 +
<source lang="lua">
 +
function love.load()
 +
local source = love.audio.newSource("music.ogg", "stream")
 +
source:setFilter{
 +
type    = "lowpass",
 +
volume  = .5,
 +
highgain = .4,
 +
}
 +
source:play()
 +
end
 +
</source>
 +
 +
== Notes ==
 +
Audio filter functionality is not supported on iOS.
 +
 +
While the cutoff frequency cannot be set directly, changing high/lowgain has the effect of altering the cutoff. See it explained in [https://github.com/kcat/openal-soft/issues/164 this thread].
 +
 +
The filter does not affect any [[Source:setEffect|effects]] for the Source.
 +
 
== See Also ==
 
== See Also ==
 
* [[parent::Source]]
 
* [[parent::Source]]
 
* [[Source:getFilter]]
 
* [[Source:getFilter]]
 
* [[Source:setEffect]]
 
* [[Source:setEffect]]
 +
 +
== Other Languages ==
 +
{{i18n|Source:setFilter}}
 +
 
[[Category:Functions]]
 
[[Category:Functions]]
 
{{#set:Description=Sets a low-pass, high-pass, or band-pass filter to apply when playing the Source.}}
 
{{#set:Description=Sets a low-pass, high-pass, or band-pass filter to apply when playing the Source.}}
== Other Languages ==
 
{{i18n|Source:setFilter}}
 

Latest revision as of 10:43, 17 August 2022

Available since LÖVE 11.0
This function is not supported in earlier versions.

Sets a low-pass, high-pass, or band-pass filter to apply when playing the Source.

Function

Synopsis

success = Source:setFilter( settings )

Arguments

table settings
The filter settings to use for this Source, with the following fields:
FilterType type
The type of filter to use.
number volume
The overall volume of the audio. Must be between 0 and 1.
number highgain
Volume of high-frequency audio. Only applies to lowpass and bandpass filters. Must be between 0 and 1.
number lowgain
Volume of low-frequency audio. Only applies to highpass and bandpass filters. Must be between 0 and 1.

Returns

boolean success
Whether the filter was successfully applied to the Source.

Function

Disables filtering on this Source.

Synopsis

Source:setFilter( )

Arguments

None.

Returns

Nothing.

Examples

Play music at half volume with a low-pass filter applied

function love.load()
	local source = love.audio.newSource("music.ogg", "stream")
	source:setFilter{
		type     = "lowpass",
		volume   = .5,
		highgain = .4,
	}
	source:play()
end

Notes

Audio filter functionality is not supported on iOS.

While the cutoff frequency cannot be set directly, changing high/lowgain has the effect of altering the cutoff. See it explained in this thread.

The filter does not affect any effects for the Source.

See Also

Other Languages