MoonsideGames
/
MoonWorks
1
0
Fork 1
Code Issues 4 Pull Requests Projects Releases 1 Activity

add some more Voice documentation

pull/50/head
cosmonaut 2023-08-02 21:49:07 -07:00
parent cb153cff3a
commit 03b4b5f9a5
2 changed files with 116 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
src/Audio/StreamingVoice.cs
View File

@ -27,6 +27,10 @@ namespace MoonWorks.Audio
return new StreamingVoice(device, format);
}
/// <summary>
/// Loads and prepares an AudioDataStreamable for streaming playback.
/// This automatically calls Load on the given AudioDataStreamable.
/// </summary>
public void Load(AudioDataStreamable data)
{
lock (StateLock)
@ -44,6 +48,10 @@ namespace MoonWorks.Audio
}
}
/// <summary>
/// Unloads AudioDataStreamable from this voice.
/// This automatically calls Unload on the given AudioDataStreamable.
/// </summary>
public void Unload()
{
lock (StateLock)

120
src/Audio/Voice.cs
View File

@ -20,6 +20,9 @@ namespace MoonWorks.Audio
public bool Is3D { get; protected set; }
private float dopplerFactor;
/// <summary>
/// The strength of the doppler effect on this voice.
/// </summary>
public float DopplerFactor
{
get => dopplerFactor;
@ -34,6 +37,9 @@ namespace MoonWorks.Audio
}
private float volume = 1;
/// <summary>
/// The overall volume level for the voice.
/// </summary>
public float Volume
{
get => volume;
@ -49,6 +55,9 @@ namespace MoonWorks.Audio
}
private float pitch = 0;
/// <summary>
/// The pitch of the voice.
/// </summary>
public float Pitch
{
get => pitch;
@ -73,6 +82,9 @@ namespace MoonWorks.Audio
OneOverQ = 1f
};
/// <summary>
/// The frequency cutoff on the voice filter.
/// </summary>
public float FilterFrequency
{
get => filterParameters.Frequency;
@ -92,6 +104,10 @@ namespace MoonWorks.Audio
}
}
/// <summary>
/// Reciprocal of Q factor.
/// Controls how quickly frequencies beyond the filter frequency are dampened.
/// </summary>
public float FilterOneOverQ
{
get => filterParameters.OneOverQ;
@ -112,6 +128,9 @@ namespace MoonWorks.Audio
}
private FilterType filterType;
/// <summary>
/// The frequency filter that is applied to the voice.
/// </summary>
public FilterType FilterType
{
get => filterType;
@ -157,6 +176,9 @@ namespace MoonWorks.Audio
}
protected float pan = 0;
/// <summary>
/// Left-right panning. -1 is hard left pan, 1 is hard right pan.
/// </summary>
public float Pan
{
get => pan;
@ -192,6 +214,10 @@ namespace MoonWorks.Audio
}
private float reverb;
/// <summary>
/// The wet-dry mix of the reverb effect.
/// Has no effect if SetReverbEffectChain has not been called.
/// </summary>
public unsafe float Reverb
{
get => reverb;
@ -241,91 +267,154 @@ namespace MoonWorks.Audio
SetPanMatrixCoefficients();
}
/// <summary>
/// Sets the pitch of the voice. Valid input range is -1f to 1f.
/// </summary>
public void SetPitch(float targetValue)
{
Pitch = targetValue;
Device.ClearTweens(this, AudioTweenProperty.Pitch);
}
/// <summary>
/// Sets the pitch of the voice over a time duration in seconds.
/// </summary>
/// <param name="easingFunction">An easing function. See MoonWorks.Math.Easing.Function.Float</param>
public void SetPitch(float targetValue, float duration, EasingFunction easingFunction)
{
Device.CreateTween(this, AudioTweenProperty.Pitch, easingFunction, Pitch, targetValue, duration, 0);
}
/// <summary>
/// Sets the pitch of the voice over a time duration in seconds after a delay in seconds.
/// </summary>
/// <param name="easingFunction">An easing function. See MoonWorks.Math.Easing.Function.Float</param>
public void SetPitch(float targetValue, float delayTime, float duration, EasingFunction easingFunction)
{
Device.CreateTween(this, AudioTweenProperty.Pitch, easingFunction, Pitch, targetValue, duration, delayTime);
}
/// <summary>
/// Sets the volume of the voice. Minimum value is 0f.
/// </summary>
public void SetVolume(float targetValue)
{
Volume = targetValue;
Device.ClearTweens(this, AudioTweenProperty.Volume);
}
/// <summary>
/// Sets the volume of the voice over a time duration in seconds.
/// </summary>
/// <param name="easingFunction">An easing function. See MoonWorks.Math.Easing.Function.Float</param>
public void SetVolume(float targetValue, float duration, EasingFunction easingFunction)
{
Device.CreateTween(this, AudioTweenProperty.Volume, easingFunction, Volume, targetValue, duration, 0);
}
/// <summary>
/// Sets the volume of the voice over a time duration in seconds after a delay in seconds.
/// </summary>
/// <param name="easingFunction">An easing function. See MoonWorks.Math.Easing.Function.Float</param>
public void SetVolume(float targetValue, float delayTime, float duration, EasingFunction easingFunction)
{
Device.CreateTween(this, AudioTweenProperty.Volume, easingFunction, Volume, targetValue, duration, delayTime);
}
/// <summary>
/// Sets the frequency cutoff on the voice filter. Valid range is 0.01f to 1f.
/// </summary>
public void SetFilterFrequency(float targetValue)
{
FilterFrequency = targetValue;
Device.ClearTweens(this, AudioTweenProperty.FilterFrequency);
}
/// <summary>
/// Sets the frequency cutoff on the voice filter over a time duration in seconds.
/// </summary>
/// <param name="easingFunction">An easing function. See MoonWorks.Math.Easing.Function.Float</param>
public void SetFilterFrequency(float targetValue, float duration, EasingFunction easingFunction)
{
Device.CreateTween(this, AudioTweenProperty.FilterFrequency, easingFunction, FilterFrequency, targetValue, duration, 0);
}
/// <summary>
/// Sets the frequency cutoff on the voice filter over a time duration in seconds after a delay in seconds.
/// </summary>
/// <param name="easingFunction">An easing function. See MoonWorks.Math.Easing.Function.Float</param>
public void SetFilterFrequency(float targetValue, float delayTime, float duration, EasingFunction easingFunction)
{
Device.CreateTween(this, AudioTweenProperty.FilterFrequency, easingFunction, FilterFrequency, targetValue, duration, delayTime);
}
/// <summary>
/// Sets reciprocal of Q factor on the frequency filter.
/// Controls how quickly frequencies beyond the filter frequency are dampened.
/// </summary>
public void SetFilterOneOverQ(float targetValue)
{
FilterOneOverQ = targetValue;
}
/// <summary>
/// Sets a left-right panning value. -1f is hard left pan, 1f is hard right pan.
/// </summary>
public virtual void SetPan(float targetValue)
{
Pan = targetValue;
Device.ClearTweens(this, AudioTweenProperty.Pan);
}
/// <summary>
/// Sets a left-right panning value over a time duration in seconds.
/// </summary>
/// <param name="easingFunction">An easing function. See MoonWorks.Math.Easing.Function.Float</param>
public virtual void SetPan(float targetValue, float duration, EasingFunction easingFunction)
{
Device.CreateTween(this, AudioTweenProperty.Pan, easingFunction, Pan, targetValue, duration, 0);
}
/// <summary>
/// Sets a left-right panning value over a time duration in seconds after a delay in seconds.
/// </summary>
/// <param name="easingFunction">An easing function. See MoonWorks.Math.Easing.Function.Float</param>
public virtual void SetPan(float targetValue, float delayTime, float duration, EasingFunction easingFunction)
{
Device.CreateTween(this, AudioTweenProperty.Pan, easingFunction, Pan, targetValue, duration, delayTime);
}
/// <summary>
/// Sets the wet-dry mix value of the reverb effect. Minimum value is 0f.
/// </summary>
public virtual void SetReverb(float targetValue)
{
Reverb = targetValue;
Device.ClearTweens(this, AudioTweenProperty.Reverb);
}
/// <summary>
/// Sets the wet-dry mix value of the reverb effect over a time duration in seconds.
/// </summary>
/// <param name="easingFunction">An easing function. See MoonWorks.Math.Easing.Function.Float</param>
public virtual void SetReverb(float targetValue, float duration, EasingFunction easingFunction)
{
Device.CreateTween(this, AudioTweenProperty.Reverb, easingFunction, Volume, targetValue, duration, 0);
}
/// <summary>
/// Sets the wet-dry mix value of the reverb effect over a time duration in seconds after a delay in seconds.
/// </summary>
/// <param name="easingFunction">An easing function. See MoonWorks.Math.Easing.Function.Float</param>
public virtual void SetReverb(float targetValue, float delayTime, float duration, EasingFunction easingFunction)
{
Device.CreateTween(this, AudioTweenProperty.Reverb, easingFunction, Volume, targetValue, duration, delayTime);
}
/// <summary>
/// Sets the output voice for this voice.
/// </summary>
/// <param name="send">Where the output should be sent.</param>
public unsafe void SetOutputVoice(SubmixVoice send)
{
OutputVoice = send;
@ -351,6 +440,9 @@ namespace MoonWorks.Audio
}
}
/// <summary>
/// Applies a reverb effect chain to this voice.
/// </summary>
public unsafe void SetReverbEffectChain(ReverbEffect reverbEffect)
{
var sendDesc = stackalloc FAudio.FAudioSendDescriptor[2];
@ -371,6 +463,9 @@ namespace MoonWorks.Audio
ReverbEffect = reverbEffect;
}
/// <summary>
/// Removes the reverb effect chain from this voice.
/// </summary>
public void RemoveReverbEffectChain()
{
if (ReverbEffect != null)
@ -381,6 +476,19 @@ namespace MoonWorks.Audio
}
}
/// <summary>
/// Resets all voice parameters to defaults.
/// </summary>
public virtual void Reset()
{
RemoveReverbEffectChain();
Volume = 1;
Pan = 0;
Pitch = 0;
FilterType = FilterType.None;
SetOutputVoice(Device.MasteringVoice);
}
// Taken from https://github.com/FNA-XNA/FNA/blob/master/src/Audio/SoundEffectInstance.cs
private unsafe void SetPanMatrixCoefficients()
{
@ -435,18 +543,6 @@ namespace MoonWorks.Audio
}
}
public virtual void Reset()
{
RemoveReverbEffectChain();
Volume = 1;
Pan = 0;
Pitch = 0;
FilterType = FilterType.None;
FilterFrequency = 1;
FilterOneOverQ = 1;
SetOutputVoice(Device.MasteringVoice);
}
protected void UpdatePitch()
{
float doppler;