AudioEngine

Remarks

Two threads, and no lock between them. The game thread starts and stops sounds and moves them about; the device's thread renders. They meet at three kinds of shared state and each kind has its own mechanism, all of them lock-free:

A voice's life — free, playing, paused, stopping, finished — is one Int32 moved with a compare-and-swap. A stop that races a natural end resolves to whichever got there first, and the loser does nothing. Scalar parameters — gain, pitch, pan, a bus's volume — are written straight in. The CLR writes a Single atomically, so the worst case is a change taking effect one block later than it was made. Whole structs — a source's spatial settings, the listener — go through Published<T>, a sequence lock. Neither side ever waits, and a reader that catches a write in progress keeps the value it already had for one block.

There is no command queue, and that is the point: a queue would allocate in the frame loop for every moving emitter in the scene.

Update must be called once a frame. It is where a finished voice goes back to the pool, where a stream is handed back to the pump, and where the counters the audio thread wrote become statistics and log lines. An engine that is never updated plays its first sixty-four sounds and then goes quiet.

Fields and properties (21)

• public IAudioDevice Device

  Where the samples go.

• public AudioMixer Mixer

  The bus tree and the voice pool.

• public AudioStreamPump Streams

  The thread keeping streaming voices fed.

• public AudioBus Master

  The bus everything reaches.

• public MixerSnapshots? Snapshots

  The named mix states from the last LoadMixer, or .

• public LimiterEffect? Limiter

  The limiter on the master, if MasterLimiter asked for one.

• public AudioFormat Format

  What the device is rendering.

• public AudioListener Listener

  Where the ears are, as last set. The first of them, if there are several.

• public AudioListenerSet Listeners

  Everywhere the game is listening from.

• public AudioOcclusion Occlusion

  The occlusion pass: what answers whether there is a wall in the way, how often it is asked, and how quickly the answer takes effect.

• public AudioReverbZones ReverbZones

  The reverb zones in the level, and what the listener is currently standing in.

• public bool UseHrtf

  Whether spatial sounds are panned through a head model rather than between speakers.

• public int ListenerCount

  How many pairs of ears there are. One, unless somebody asked for split-screen.

• public AudioStatistics Statistics

  What the subsystem was doing as of the last Update.

• public MixerParameters? Parameters

  The engine-wide parameters, if any have been loaded.

• public MixControl Control

  Every knob in the mix, reachable by name — the runtime half of live update.

• public int PendingLayers

  How many layers are waiting on their delay.

• public long DroppedLayers

  How many layers were never played because the pending table was full.

• public long RenderedFrames

  How many frames the device has rendered since the engine was built.

• public int AudibleVoices

  How many voices may be heard at once, or zero if every voice is real.

• public int VoiceCapacity

  How many voices can sound at once.

Methods (46)

• public AudioEngine(IAudioDevice device, in AudioEngineOptions options, ILogger? logger = null)

  An engine on a device.

• public static AudioEngine Create(IAudioBackend backend, in AudioEngineOptions options, ILogger? logger = null)

  Opens a device on a backend, and falls back to silence if it will not open.

• public static AudioEngine Create(IAudioBackend backend, ILogger? logger = null)

  An engine on a backend, with the default options.

• public IReadOnlyList<string> LoadMixer(MixerAsset asset)

  Builds a mixer asset's buses, effects, sends and sidechains onto this engine.

• public AudioEvent LoadEvent(AudioEventAsset asset, out IReadOnlyList<string> problems, IAudioEventLibrary? library = null)

  Resolves an event asset against this engine, ready to be played.

• public void SetListener(in AudioListener value)

  Moves the listener.

• public void SetListeners(in AudioListenerSet value)

  Moves every listener at once.

• public AudioBus CreateBus(string name, AudioBus? parent = null)

  Adds a bus.

• public AudioBus? FindBus(string name)

  Finds a bus.

• public VoiceHandle Play(AudioClip clip)

  Plays a clip at full volume on the master bus.

• public VoiceHandle Play(AudioClip clip, in PlaybackSettings settings)

  Plays a clip.

• public VoiceHandle Play(IAudioSampleProvider source, in PlaybackSettings settings)

  Plays whatever a caller can produce samples from.

• public VoiceHandle PlayStream(IAudioStreamDecoder decoder, in PlaybackSettings settings)

  Plays a track without loading all of it, decoding as it goes.

• public void Stop(VoiceHandle handle)

  Stops a sound, over one block so it does not click.

• public void StopAll()

  Stops everything.

• public void Pause(VoiceHandle handle)

  Holds a sound where it is.

• public void Resume(VoiceHandle handle)

  Lets a paused sound carry on.

• public void SetGain(VoiceHandle handle, float gain)

  Changes a sound's volume.

• public float GainOf(VoiceHandle handle)

  What a sound's gain currently is.

• public void SetPitch(VoiceHandle handle, float pitch)

  Changes a sound's playback rate.

• public float PitchOf(VoiceHandle handle)

  What a sound's playback rate currently is.

• public void SetPan(VoiceHandle handle, float pan)

  Moves a non-spatial sound between the speakers.

• public void SetSpatial(VoiceHandle handle, in SpatialSettings settings)

  Moves a sound in the world.

• public VoiceState StateOf(VoiceHandle handle)

  What a sound is doing.

• public MixerParameters LoadParameters(IReadOnlyList<AudioBusParameterDefinition> definitions, out IReadOnlyList<string> problems)

  Resolves engine-wide parameters against this engine's mixer.

• public bool AttachParameters(VoiceHandle handle, AudioParameterSheet sheet)

  Gives a sound a set of parameters, at their defaults.

• public AudioParameterSheet? ParametersOf(VoiceHandle handle)

  The parameters a sound is running, if any.

• public bool SetParameter(VoiceHandle handle, int parameter, float value)

  Points one of a sound's parameters at a value.

• public bool SetParameter(VoiceHandle handle, string name, float value)

  Points one of a sound's parameters at a value, by name.

• public float ParameterOf(VoiceHandle handle, int parameter)

  Where one of a sound's parameters currently is.

• public float AudibilityOf(VoiceHandle handle)

  How easy a sound is to hear, counting its gain and how far away it is.

• public float OcclusionOf(VoiceHandle handle)

  How occluded a sound currently is: 0 clear, 1 blocked.

• public bool SetSend(VoiceHandle handle, int bus, float level)

  Points a sound's own send at a bus, at a level.

• public float SendLevelOf(VoiceHandle handle)

  How much of a sound is going to its own send.

• public int SendBusOf(VoiceHandle handle)

  Which bus a sound's own send reaches, or −1.

• public float LowPassOf(VoiceHandle handle)

  The authored low-pass cutoff on a sound, in hertz, or zero for none.

• public bool IsPlaying(VoiceHandle handle)

  Whether a sound is still going.

• public void FadeTo(VoiceHandle handle, float gain, TimeSpan duration, AudioFadeCurve curve = Decibel)

  Takes a sound's gain somewhere else over time.

• public void FadeOutAndStop(VoiceHandle handle, TimeSpan duration, AudioFadeCurve curve = Decibel)

  Fades a sound out and stops it when it gets there.

• public bool IsFading(VoiceHandle handle)

  Whether a fade is running on a sound.

• public void Update()

  Collects finished voices, steps the fades, and gathers the frame's numbers.

• public void Update(float deltaSeconds)

  Collects finished voices, steps the fades, and gathers the frame's numbers.

• public void Start()

  Starts the device.

• public void Suspend()

  Stops the device without losing what is playing.

• public IReadOnlyList<string> Validate()

  Checks the engine's own invariants and says what is wrong.

• public void Dispose()

  Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Used by (46, showing 40)

• GameSoundsThirdPersonShooter
• PeerVoiceChat
• VideoGameVideoPlayback
• AudioEffectTestsVixen.Audio.Tests
• AudioEventVixen.Audio
• AudioEventAssetTestsVixen.Audio.Tests
• AudioEventBuilderVixen.Audio
• AudioEventSystemTestsVixen.Audio.Tests
• AudioEventTestsVixen.Audio.Tests
• AudioMixerTestsVixen.Audio.Tests
• AudioOverlayVixen.Audio
• AudioRoutingTestsVixen.Audio.Tests
• AudioScattererVixen.Audio
• AudioSystemVixen.Audio
• AudioSystemTestsVixen.Audio.Tests
• AudioTestDataVixen.Audio.Tests
• BuiltinParameterTestsVixen.Audio.Tests
• CaptureTestsVixen.Audio.Tests
• ConvolutionTestsVixen.Audio.Tests
• DynamicsTestsVixen.Audio.Tests
• FadeTestsVixen.Audio.Tests
• HrtfTestsVixen.Audio.Tests
• LayeredEventTestsVixen.Audio.Tests
• LiveSampleProviderTestsVixen.Audio.Tests
• MixControlVixen.Audio
• MixControlServerTestsVixen.Audio.Tests
• MixControlTestsVixen.Audio.Tests
• MixerAssetTestsVixen.Audio.Tests
• MixerParameterTestsVixen.Audio.Tests
• MultipleListenerTestsVixen.Audio.Tests
• MusicBuilderVixen.Audio
• MusicPlayerVixen.Audio
• MusicPlayerTestsVixen.Audio.Tests
• OcclusionTestsVixen.Audio.Tests
• OpenALBackendTestsVixen.Audio.Backend.OpenAL.Tests
• PerVoiceSendTestsVixen.Audio.Tests
• ResamplerTestsVixen.Audio.Tests
• ReverbZoneSystemTestsVixen.Audio.Tests
• ReverbZoneTestsVixen.Audio.Tests
• ScattererTestsVixen.Audio.Tests