From 03b4b5f9a565d34d1437ca20f753ddadeeec74f6 Mon Sep 17 00:00:00 2001 From: cosmonaut Date: Wed, 2 Aug 2023 21:49:07 -0700 Subject: [PATCH] add some more Voice documentation --- src/Audio/StreamingVoice.cs | 8 +++ src/Audio/Voice.cs | 120 ++++++++++++++++++++++++++++++++---- 2 files changed, 116 insertions(+), 12 deletions(-) diff --git a/src/Audio/StreamingVoice.cs b/src/Audio/StreamingVoice.cs index 9a1b98f..0b39a96 100644 --- a/src/Audio/StreamingVoice.cs +++ b/src/Audio/StreamingVoice.cs @@ -27,6 +27,10 @@ namespace MoonWorks.Audio return new StreamingVoice(device, format); } + /// + /// Loads and prepares an AudioDataStreamable for streaming playback. + /// This automatically calls Load on the given AudioDataStreamable. + /// public void Load(AudioDataStreamable data) { lock (StateLock) @@ -44,6 +48,10 @@ namespace MoonWorks.Audio } } + /// + /// Unloads AudioDataStreamable from this voice. + /// This automatically calls Unload on the given AudioDataStreamable. + /// public void Unload() { lock (StateLock) diff --git a/src/Audio/Voice.cs b/src/Audio/Voice.cs index cbf7243..c5870a4 100644 --- a/src/Audio/Voice.cs +++ b/src/Audio/Voice.cs @@ -20,6 +20,9 @@ namespace MoonWorks.Audio public bool Is3D { get; protected set; } private float dopplerFactor; + /// + /// The strength of the doppler effect on this voice. + /// public float DopplerFactor { get => dopplerFactor; @@ -34,6 +37,9 @@ namespace MoonWorks.Audio } private float volume = 1; + /// + /// The overall volume level for the voice. + /// public float Volume { get => volume; @@ -49,6 +55,9 @@ namespace MoonWorks.Audio } private float pitch = 0; + /// + /// The pitch of the voice. + /// public float Pitch { get => pitch; @@ -73,6 +82,9 @@ namespace MoonWorks.Audio OneOverQ = 1f }; + /// + /// The frequency cutoff on the voice filter. + /// public float FilterFrequency { get => filterParameters.Frequency; @@ -92,6 +104,10 @@ namespace MoonWorks.Audio } } + /// + /// Reciprocal of Q factor. + /// Controls how quickly frequencies beyond the filter frequency are dampened. + /// public float FilterOneOverQ { get => filterParameters.OneOverQ; @@ -112,6 +128,9 @@ namespace MoonWorks.Audio } private FilterType filterType; + /// + /// The frequency filter that is applied to the voice. + /// public FilterType FilterType { get => filterType; @@ -157,6 +176,9 @@ namespace MoonWorks.Audio } protected float pan = 0; + /// + /// Left-right panning. -1 is hard left pan, 1 is hard right pan. + /// public float Pan { get => pan; @@ -192,6 +214,10 @@ namespace MoonWorks.Audio } private float reverb; + /// + /// The wet-dry mix of the reverb effect. + /// Has no effect if SetReverbEffectChain has not been called. + /// public unsafe float Reverb { get => reverb; @@ -241,91 +267,154 @@ namespace MoonWorks.Audio SetPanMatrixCoefficients(); } + /// + /// Sets the pitch of the voice. Valid input range is -1f to 1f. + /// public void SetPitch(float targetValue) { Pitch = targetValue; Device.ClearTweens(this, AudioTweenProperty.Pitch); } + /// + /// Sets the pitch of the voice over a time duration in seconds. + /// + /// An easing function. See MoonWorks.Math.Easing.Function.Float public void SetPitch(float targetValue, float duration, EasingFunction easingFunction) { Device.CreateTween(this, AudioTweenProperty.Pitch, easingFunction, Pitch, targetValue, duration, 0); } + /// + /// Sets the pitch of the voice over a time duration in seconds after a delay in seconds. + /// + /// An easing function. See MoonWorks.Math.Easing.Function.Float public void SetPitch(float targetValue, float delayTime, float duration, EasingFunction easingFunction) { Device.CreateTween(this, AudioTweenProperty.Pitch, easingFunction, Pitch, targetValue, duration, delayTime); } + /// + /// Sets the volume of the voice. Minimum value is 0f. + /// public void SetVolume(float targetValue) { Volume = targetValue; Device.ClearTweens(this, AudioTweenProperty.Volume); } + /// + /// Sets the volume of the voice over a time duration in seconds. + /// + /// An easing function. See MoonWorks.Math.Easing.Function.Float public void SetVolume(float targetValue, float duration, EasingFunction easingFunction) { Device.CreateTween(this, AudioTweenProperty.Volume, easingFunction, Volume, targetValue, duration, 0); } + /// + /// Sets the volume of the voice over a time duration in seconds after a delay in seconds. + /// + /// An easing function. See MoonWorks.Math.Easing.Function.Float public void SetVolume(float targetValue, float delayTime, float duration, EasingFunction easingFunction) { Device.CreateTween(this, AudioTweenProperty.Volume, easingFunction, Volume, targetValue, duration, delayTime); } + /// + /// Sets the frequency cutoff on the voice filter. Valid range is 0.01f to 1f. + /// public void SetFilterFrequency(float targetValue) { FilterFrequency = targetValue; Device.ClearTweens(this, AudioTweenProperty.FilterFrequency); } + /// + /// Sets the frequency cutoff on the voice filter over a time duration in seconds. + /// + /// An easing function. See MoonWorks.Math.Easing.Function.Float public void SetFilterFrequency(float targetValue, float duration, EasingFunction easingFunction) { Device.CreateTween(this, AudioTweenProperty.FilterFrequency, easingFunction, FilterFrequency, targetValue, duration, 0); } + /// + /// Sets the frequency cutoff on the voice filter over a time duration in seconds after a delay in seconds. + /// + /// An easing function. See MoonWorks.Math.Easing.Function.Float public void SetFilterFrequency(float targetValue, float delayTime, float duration, EasingFunction easingFunction) { Device.CreateTween(this, AudioTweenProperty.FilterFrequency, easingFunction, FilterFrequency, targetValue, duration, delayTime); } + /// + /// Sets reciprocal of Q factor on the frequency filter. + /// Controls how quickly frequencies beyond the filter frequency are dampened. + /// public void SetFilterOneOverQ(float targetValue) { FilterOneOverQ = targetValue; } + /// + /// Sets a left-right panning value. -1f is hard left pan, 1f is hard right pan. + /// public virtual void SetPan(float targetValue) { Pan = targetValue; Device.ClearTweens(this, AudioTweenProperty.Pan); } + /// + /// Sets a left-right panning value over a time duration in seconds. + /// + /// An easing function. See MoonWorks.Math.Easing.Function.Float public virtual void SetPan(float targetValue, float duration, EasingFunction easingFunction) { Device.CreateTween(this, AudioTweenProperty.Pan, easingFunction, Pan, targetValue, duration, 0); } + /// + /// Sets a left-right panning value over a time duration in seconds after a delay in seconds. + /// + /// An easing function. See MoonWorks.Math.Easing.Function.Float public virtual void SetPan(float targetValue, float delayTime, float duration, EasingFunction easingFunction) { Device.CreateTween(this, AudioTweenProperty.Pan, easingFunction, Pan, targetValue, duration, delayTime); } + /// + /// Sets the wet-dry mix value of the reverb effect. Minimum value is 0f. + /// public virtual void SetReverb(float targetValue) { Reverb = targetValue; Device.ClearTweens(this, AudioTweenProperty.Reverb); } + /// + /// Sets the wet-dry mix value of the reverb effect over a time duration in seconds. + /// + /// An easing function. See MoonWorks.Math.Easing.Function.Float public virtual void SetReverb(float targetValue, float duration, EasingFunction easingFunction) { Device.CreateTween(this, AudioTweenProperty.Reverb, easingFunction, Volume, targetValue, duration, 0); } + /// + /// Sets the wet-dry mix value of the reverb effect over a time duration in seconds after a delay in seconds. + /// + /// An easing function. See MoonWorks.Math.Easing.Function.Float public virtual void SetReverb(float targetValue, float delayTime, float duration, EasingFunction easingFunction) { Device.CreateTween(this, AudioTweenProperty.Reverb, easingFunction, Volume, targetValue, duration, delayTime); } + /// + /// Sets the output voice for this voice. + /// + /// Where the output should be sent. public unsafe void SetOutputVoice(SubmixVoice send) { OutputVoice = send; @@ -351,6 +440,9 @@ namespace MoonWorks.Audio } } + /// + /// Applies a reverb effect chain to this voice. + /// public unsafe void SetReverbEffectChain(ReverbEffect reverbEffect) { var sendDesc = stackalloc FAudio.FAudioSendDescriptor[2]; @@ -371,6 +463,9 @@ namespace MoonWorks.Audio ReverbEffect = reverbEffect; } + /// + /// Removes the reverb effect chain from this voice. + /// public void RemoveReverbEffectChain() { if (ReverbEffect != null) @@ -381,6 +476,19 @@ namespace MoonWorks.Audio } } + /// + /// Resets all voice parameters to defaults. + /// + 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;