Sara
c3f9669b10
git-subtree-dir: engine git-subtree-mainline:b74841629egit-subtree-split:a8e37fc010
53 lines
4.5 KiB
XML
53 lines
4.5 KiB
XML
<?xml version="1.0" encoding="UTF-8" ?>
|
|
<class name="AudioEffectDistortion" inherits="AudioEffect" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
|
|
<brief_description>
|
|
Adds a distortion audio effect to an audio bus.
|
|
Remaps audio samples using a nonlinear function to achieve a distorted sound.
|
|
</brief_description>
|
|
<description>
|
|
A "distortion" effect modifies the waveform via a nonlinear mathematical function (see available ones in [enum Mode]), based on the amplitude of the waveform's samples.
|
|
[b]Note:[/b] In a nonlinear function, an input sample at [i]x[/i] amplitude value, will either have its amplitude increased or decreased to a [i]y[/i] value, based on the function value at [i]x[/i], which is why even at the same [member drive], the output sound will vary depending on the input's volume. To change the volume while maintaining the output waveform, use [member post_gain].
|
|
In this effect, each type is a different nonlinear function. The different types available are: clip, atan, lofi (bitcrush), overdrive, and waveshape. Every distortion type available here is symmetric: negative amplitude values are affected the same way as positive ones.
|
|
Although distortion will always change frequency content, usually by introducing high harmonics, different distortion types offer a range of sound qualities; from "soft" and "warm", to "crunchy" and "abrasive".
|
|
For games, it can help simulate sound coming from some saturated device or speaker very efficiently. It can also help the audio stand out in a mix, by introducing higher frequencies and increasing the volume.
|
|
[b]Note:[/b] Although usually imperceptible, an enabled distortion effect still changes the sound even when [member drive] is set to 0. This is not a bug. If this behavior is undesirable, consider disabling the effect using [method AudioServer.set_bus_effect_enabled].
|
|
</description>
|
|
<tutorials>
|
|
<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
|
|
<link title="Audio effects">$DOCS_URL/tutorials/audio/audio_effects.html</link>
|
|
</tutorials>
|
|
<members>
|
|
<member name="drive" type="float" setter="set_drive" getter="get_drive" default="0.0">
|
|
Distortion intensity. Controls how much of the input audio is affected by the distortion curve by moving from a linear function to a nonlinear one. Value can range from 0 to 1.
|
|
</member>
|
|
<member name="keep_hf_hz" type="float" setter="set_keep_hf_hz" getter="get_keep_hf_hz" default="16000.0">
|
|
High-pass filter, in Hz. Frequencies higher than this value will not be affected by the distortion. Value can range from 1 to 20000.
|
|
</member>
|
|
<member name="mode" type="int" setter="set_mode" getter="get_mode" enum="AudioEffectDistortion.Mode" default="0">
|
|
Distortion type. Changes the nonlinear function used to distort the waveform. See [enum Mode].
|
|
</member>
|
|
<member name="post_gain" type="float" setter="set_post_gain" getter="get_post_gain" default="0.0">
|
|
Gain after the effect, in dB. Value can range from -80 to 24.
|
|
</member>
|
|
<member name="pre_gain" type="float" setter="set_pre_gain" getter="get_pre_gain" default="0.0">
|
|
Gain before the effect, in dB. Value can range from -60 to 60.
|
|
</member>
|
|
</members>
|
|
<constants>
|
|
<constant name="MODE_CLIP" value="0" enum="Mode">
|
|
Flattens the waveform at 0 dB in a sharp manner. [member drive] increases amplitude of samples exponentially. This mode functions as a hard clipper if [member drive] is set to 0, and is the only mode that clips audio signals at 0 dB.
|
|
</constant>
|
|
<constant name="MODE_ATAN" value="1" enum="Mode">
|
|
Flattens the waveform in a smooth manner, following an arctangent curve. The audio decreases in volume, before flattening peaks to [code]PI * 4.0[/code] (linear value), if it was normalized beforehand.
|
|
</constant>
|
|
<constant name="MODE_LOFI" value="2" enum="Mode">
|
|
Decreases audio bit depth to achieve a low-resolution audio signal, going from 16-bit to 2-bit. Can be used to emulate the sound of early digital audio devices.
|
|
</constant>
|
|
<constant name="MODE_OVERDRIVE" value="3" enum="Mode">
|
|
Emulates the warm distortion produced by a field effect transistor, which is commonly used in solid-state musical instrument amplifiers. [member drive] has no effect in this mode.
|
|
</constant>
|
|
<constant name="MODE_WAVESHAPE" value="4" enum="Mode">
|
|
Flattens the waveform in a smooth manner, until it reaches a sharp peak at [code]drive = 1[/code], following a generic absolute sigmoid function.
|
|
</constant>
|
|
</constants>
|
|
</class>
|