tympan_apo/lib.rs
1//! `tympan-apo` — Rust framework for Windows Audio Processing Objects.
2//!
3//! See `docs/overview.md` and `docs/architecture.md` for the design
4//! that drives this crate.
5//!
6//! The crate is organised into four conceptual layers, isolated by
7//! module boundary:
8//!
9//! - `raw` — low-level COM bindings via the `windows` crate
10//! (Windows-only).
11//! - [`realtime`] — allocation-free, lock-free primitives intended
12//! for use from the `APOProcess` realtime callback. Cross-platform
13//! so that the realtime invariants can be unit-tested on any host.
14//! - Public API (this module plus [`apo`], [`instance`],
15//! [`mod@format`], and the other crate-root modules) — safe,
16//! idiomatic wrappers users implement against.
17//! - `aec` — Windows 11 Acoustic Echo Cancellation APO support.
18//! Windows-only and gated behind the `aec` Cargo feature.
19//!
20//! ## Realtime safety
21//!
22//! Any code reachable from the `APOProcess` callback must be
23//! allocation-free, lock-free, and free of blocking syscalls. The
24//! [`realtime`] module exposes a `RealtimeContext` marker that acts
25//! as a compile-time witness for the realtime context.
26
27#![cfg_attr(docsrs, feature(doc_cfg))]
28#![deny(missing_docs)]
29#![deny(unsafe_op_in_unsafe_fn)]
30
31pub mod apo;
32pub mod buffer;
33pub mod clsid;
34pub mod error;
35pub mod format;
36pub mod fx_properties;
37pub mod inf;
38pub mod instance;
39pub mod realtime;
40
41#[cfg(windows)]
42pub mod raw;
43
44#[cfg(all(windows, feature = "aec"))]
45#[cfg_attr(docsrs, doc(cfg(all(windows, feature = "aec"))))]
46pub mod aec;
47
48pub use apo::{ApoCategory, ProcessInput, ProcessingObject, SystemEffect, SystemEffectState};
49pub use buffer::{BufferFlags, ConnectionProperty, CONNECTION_PROPERTY_SIGNATURE};
50pub use clsid::Clsid;
51pub use error::HResult;
52pub use format::{Format, FormatNegotiation};
53
54/// Re-export of `windows_core::GUID` so the `register_apo!` macro's
55/// emitted entry-point signatures resolve without users having to
56/// add `windows-core` to their own `Cargo.toml`.
57#[cfg(windows)]
58pub use windows_core::GUID;
59
60/// Re-export of `windows_core::HRESULT`. Same rationale as [`GUID`].
61#[cfg(windows)]
62pub use windows_core::HRESULT;
63
64#[cfg(windows)]
65mod macros;