maulingmonkey / thindx-xaudio2

Rust bindings for XAudio2

🦀 thindx-xaudio2[-sys] 🦀

FFI and thin wrappers for XAudio2

crate	crates.io	docs.rs	Description
thindx-xaudio2			High level FFI for XAudio2
thindx-xaudio2-sys			Low level FFI for XAudio2

Warnings

⚠️ 0.0.0-yyyy-mm-dd does not obey semver.
⚠️ I'm not yet willing to stabilize these crates APIs.
⚠️ thindx-xaudio2 lacks testing and may not yet be sound.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

thindx-xaudio2's Issues

De-`*Ext` interface fns?

Overhaul doc versioning

Having the same symbol exported N times in docs.rs is lame.
Abuse wildcards, probably. And #[doc(no_inline)].

Don't require importing winresult to use thindx-xaudio2

thindx-xaudio2/crates/thindx-xaudio2/examples/a440.rs

Line 60 in 5f64853

fn on_voice_error(&self, _buffer_context: &Self::BufferContext, error: winresult::HResult) { panic!("{error:?}"); }

This effectively requires pulling in winresult just to impl this semi-mandatory trait.
Also consider making a callbackless version of this, or at least introduce:

• impl DefaultVoiceCallback for VoiceCallback
• impl DefaultEngineCallback for EngineCallback

Which would presumably panic on errors but otherwise do ≈nothing. The A440 sample really shouldn't be forced to impl callbacks.

Replace WAVEFORMATEX with trait nonsense for soundness.

Setup CI

submit_source_buffer doesn't ensure `samples.AudioData` is kept alive until dequed

thindx-xaudio2/crates/thindx-xaudio2/examples/a440.rs

Lines 46 to 47 in a671977

	// TODO: XXX: soundness: keep `samples` alive until processed.
	a440.submit_source_buffer(samples, None).expect("a440.submit_source_buffer(samples, None)");

Create wav-playing example

winapi requires external spatial provenance fixes?

Narrowing spatial provenance to IUnknown and then re-expanding it to CSomeComClass is problematic.

Unstable !semver policy

Publish crates

Publish repository

XAudio 2.8 support / testing

User context pointer improvements?

pContext -> mid struct
static/thread_local freers allowing non-alloc contexts?

Provenance tracking issues

core::ptr::from_raw_parts is not yet stable

• rust-lang/rust#81513

Which is a problem for here:

thindx-xaudio2/crates/thindx-xaudio2/src/xa28/ixaudio2sourcevoice_ext.rs

Lines 57 to 75 in 8b77f0e

	b.pContext = Box::into_raw(Box::new(SourceBuffer::<Context> {
	context,
	audio_len: audio_data.len(),
	audio_data: {
	// ⚠️ WARNING: easy to muck up provenance of ArcInner<[Sample]> here.
	let raw : *const [Sample] = Arc::into_raw(audio_data);
	let raw : *const Sample = unsafe { (*raw).as_ptr() };
	raw.cast()
	},
	audio_free: |data, len| {
	// 🐞 BUG: core::slice::from_raw_parts here incorrectly narrows provenance from ArcInner<[Sample]> to [Sample] here.
	// However, core::ptr::from_raw_parts is not yet stable: https://github.com/rust-lang/rust/issues/81513
	// Local tracking issue: https://github.com/MaulingMonkey/thindx-xaudio2/issues/18
	let audio_data : *const [Sample] = unsafe { core::slice::from_raw_parts(data as *const Sample, len) };
	let audio_data = unsafe { Arc::from_raw(audio_data) };
	drop(audio_data);
	},
	})).cast();

Validate type

thindx-xaudio2/crates/thindx-xaudio2-sys/src/sys28.rs

Line 271 in a671977

#[repr(transparent)] pub struct XAUDIO2_FILTER_TYPE(u32); // TODO: check type

Add callback guards

• It is invalid to call DestroyVoice from within a callback, so panic instead
• It is undefined behavior to panic=unwind over an FFI boundary, so catch and/or or seppuku the process instead

Create mp3-playing example

XAudio2 bit flips via voltage sag when using AVX256 instructions at the same as I destroy source voices?

Unsound if XAudio2 threads outlive main?
Had a once-off XAudio2 thread crash when tearing down my snake clone with a leaked IXAudio2 instance. Worth investigating.

Interop with `windows`?

Caveat: windows mixes 2_8 and 2_9 freely, which makes the ambiguous IID of IXAudio2 awkward.

https://github.com/riverar/win32metadata/blob/5ad71f45ef73a72864c16ef6a1924652aeb1a50d/generation/WinSDK/libMappings.rsp#L15-L24

Validate ABI types against C++ header parsing?

voice destruction

• DestroyVoice warns of perf issues / delays measured in milliseconds
• destroy_voice_async for automatic offloading to a worker thread per doc suggestions?
• features to make drop do so automatically?
• Also probably bad to allow them to outlive IXAudio2
• Make SourceVoice et all borrow IXAudio2?

create_source_voice* doesn't ensure `callback` outlives the voice

thindx-xaudio2/crates/thindx-xaudio2/examples/a440.rs

Lines 35 to 36 in a671977

	// TODO: XXX: soundness: ensure `callback` outlives `a440` via type system.
	let a440 = xaudio2.create_source_voice_typed_callback(&waveformatex, 0, xaudio2::DEFAULT_FREQ_RATIO, &callback, None /* defaults to master */, None).expect("a440");

Reference from main thindx crate

Pull a `windows` and add a level of indirection to pointer types to avoid spatial provenance issues?