AudioNimbus

https://docs.rs/audionimbus
Admin
AudioNimbus is a Rust wrapper around Steam Audio that provides spatial audio capabilities with...
Tokens:673,111
Snippets:6,584
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Basic Simulation Workflow Example

Source: https://docs.rs/audionimbus/latest/src/audionimbus/simulation.rs.html

Demonstrates the typical setup and execution of a direct sound simulation. Ensure you have a valid context and scene before proceeding. This example outlines the steps from simulator creation to configuring simulation inputs.

```rust
use audionimbus::{
    Context,
    Simulator,
    Scene,
    Source,
    SourceSettings,
    SimulationFlags,
    DirectSimulationSettings,
    SimulationSettings,
    SimulationInputs,
    SimulationSharedInputs,
    CoordinateSystem,
    DirectSimulationParameters,
    ReflectionsSharedInputs,
    DistanceAttenuationModel,
};
let context = Context::default();
// Create a simulator.
let settings = SimulationSettings::new(48000, 1024, 2)
    .with_direct(DirectSimulationSettings {
        max_num_occlusion_samples: 4,
    });
let mut simulator = Simulator::try_new(&context, &settings)?;

// Set up a scene.
let scene = Scene::try_new(&context)?;

// ... add and commit geometry to the scene ...

simulator.set_scene(&scene);
simulator.commit();

// Create and add a source.
let source_settings = SourceSettings {
    flags: SimulationFlags::DIRECT,
};
let mut source = Source::try_new(&simulator, &source_settings)?;

simulator.add_source(&source);

// Configure simulation parameters.
let simulation_inputs = SimulationInputs::new(CoordinateSystem::default())
    .with_direct(DirectSimulationParameters::new()
        .with_distance_attenuation(DistanceAttenuationModel::default()));
source.set_inputs(SimulationFlags::DIRECT, simulation_inputs);

// Set shared parameters.
let shared_inputs = SimulationSharedInputs::new(CoordinateSystem::default());
simulator.set_shared_inputs(SimulationFlags::DIRECT, &shared_inputs);
```

--------------------------------

### ReflectionEffect Usage Example

Source: https://docs.rs/audionimbus/latest/audionimbus/effect/reflections/struct.ReflectionEffect.html

This example demonstrates how to set up a simulator, run a reflections simulation, and then apply the resulting reflection effect to an audio buffer using ReflectionEffect.

```APIDOC
## ReflectionEffect Usage Example

### Description
This example demonstrates the process of setting up a physics-based reflections simulation using `Simulator` and then applying the simulated reflections to an audio buffer via the `ReflectionEffect` struct. It covers scene setup, source configuration, simulation execution, and effect application.

### Method
This is a usage example, not a direct API call.

### Endpoint
N/A

### Parameters
N/A

### Request Body
N/A

### Request Example
```rust
let context = Context::default();

const SAMPLING_RATE: u32 = 48_000;
const FRAME_SIZE: u32 = 1024;
let audio_settings = AudioSettings {
    sampling_rate: SAMPLING_RATE,
    frame_size: FRAME_SIZE,
};

// Create a simulator with reflections.
let simulation_settings = SimulationSettings::new(SAMPLING_RATE, FRAME_SIZE, 1)
    .with_reflections(ReflectionsSimulationSettings::Convolution {
        max_num_rays: 4096,
        num_diffuse_samples: 32,
        max_duration: 2.0,
        max_num_sources: 8,
        num_threads: 2,
    });
let mut simulator = Simulator::try_new(&context, &simulation_settings)?;

let scene = Scene::try_new(&context)?;
simulator.set_scene(&scene);

let mut source = Source::try_new(
    &simulator,
    &SourceSettings {
        flags: SimulationFlags::REFLECTIONS,
    },
)?;

source.set_inputs(
    SimulationFlags::REFLECTIONS,
    SimulationInputs::new(CoordinateSystem::default()).with_reflections(
        ReflectionsSimulationParameters::Convolution {
            baked_data_identifier: None,
        },
    ),
);

simulator.add_source(&source);
simulator.set_shared_inputs(
    SimulationFlags::REFLECTIONS,
    &SimulationSharedInputs::new(CoordinateSystem::default()).with_reflections(
        ReflectionsSharedInputs {
            num_rays: 4096,
            num_bounces: 16,
            duration: 2.0,
            order: 1,
            irradiance_min_distance: 1.0,
        },
    ),
);
simulator.commit();

simulator.run_reflections();
let outputs = source.get_outputs(SimulationFlags::REFLECTIONS)?;

const NUM_CHANNELS: u32 = num_ambisonics_channels(1); // 1st order ambisonics
let mut effect = ReflectionEffect::<Convolution>::try_new(
    &context,
    &audio_settings,
    &ReflectionEffectSettings {
        impulse_response_size: 2 * SAMPLING_RATE, // 2 seconds
        num_channels: NUM_CHANNELS,
    },
)?;

let input = vec![0.5; FRAME_SIZE as usize];
let input_buffer = AudioBuffer::try_with_data(&input)?;
let mut output = vec![0.0; (NUM_CHANNELS * FRAME_SIZE) as usize]; // 4 channels
let output_buffer = AudioBuffer::try_with_data_and_settings(
    &mut output,
    AudioBufferSettings::with_num_channels(NUM_CHANNELS),
)?;

let params = outputs.reflections();
let _ = effect.apply(&params, &input_buffer, &output_buffer);
```

### Response
N/A

### Response Example
N/A
```

--------------------------------

### Basic Audio Spatialization Example

Source: https://docs.rs/audionimbus/latest/src/audionimbus/lib.rs.html

This example demonstrates initializing the audio context, setting up HRTF for binaural rendering, creating a binaural effect, and preparing input/output audio buffers for spatialization.

```rust
use audionimbus::*

// Initialize the audio context.
let context = Context::default();

let audio_settings = AudioSettings {
    sampling_rate: 48000,
    frame_size: 1024,
};

// Set up HRTF for binaural rendering.
let hrtf = Hrtf::try_new(&context, &audio_settings, &HrtfSettings::default())?;

// Create a binaural effect.
let mut binaural_effect = BinauralEffect::try_new(
    &context,
    &audio_settings,
    &BinauralEffectSettings { hrtf: &hrtf },
)?;

// Generate an input frame (in this case, a single-channel sine wave).
let input: Vec<Sample> = (0..audio_settings.frame_size)
    .map(|i| {
        (i as f32 * 2.0 * std::f32::consts::PI * 440.0 / audio_settings.sampling_rate as f32)
            .sin()
    })
    .collect();
// Create an audio buffer over the input data.
let input_buffer = AudioBuffer::try_with_data(&input)?;

let num_channels: u32 = 2; // Stereo
// Allocate memory to store processed samples.
let mut output = vec![0.0; (audio_settings.frame_size * num_channels) as usize];
// Create another audio buffer over the output container.
let output_buffer = AudioBuffer::try_with_data_and_settings(
    &mut output,
    AudioBufferSettings::with_num_channels(num_channels),
)?;
```

--------------------------------

### Test Parametric Reflection Bake Setup

Source: https://docs.rs/audionimbus/latest/src/audionimbus/baking/reflections.rs.html

Initializes the setup for testing parametric reflection baking. This includes creating the context, scene, probe batch, and baker instance.

```rust
// Parametric
        {
            let context = Context::default();
            let scene = test_scene(&context);
            let mut probe_batch = test_probe_batch(&context, &scene);

            let baker = ReflectionsBaker::<DefaultRayTracer>::new();

            let params = ReflectionsBakeParams {

```

--------------------------------

### Setup and Run Reflections Simulation

Source: https://docs.rs/audionimbus/latest/src/audionimbus/effect/reflections.rs.html

Demonstrates the setup and execution of a reflections simulation using Audionimbus. This includes configuring the simulator, scene, source, and shared inputs, then running the simulation and retrieving outputs.

```rust
const SAMPLING_RATE: u32 = 48000;
const FRAME_SIZE: u32 = 1024;
const IR_SIZE: u32 = 2 * SAMPLING_RATE;
const MAX_ORDER: u32 = 1;

let context = Context::default();

let audio_settings = AudioSettings::default();

let simulation_settings =
    SimulationSettings::new(SAMPLING_RATE, FRAME_SIZE, MAX_ORDER).with_reflections(
        ReflectionsSimulationSettings::Convolution {
            max_num_rays: 4096,
            num_diffuse_samples: 32,
            max_duration: 2.0,
            max_num_sources: 8,
            num_threads: 1,
        },
    );
let mut simulator = Simulator::try_new(&context, &simulation_settings).unwrap();

let scene = Scene::try_new(&context).unwrap();
simulator.set_scene(&scene);

let source_settings = SourceSettings {
    flags: SimulationFlags::REFLECTIONS,
};
let mut source = Source::<(), Reflections, ()>::try_new(&simulator, &source_settings).unwrap();
simulator.add_source(&source);

let simulation_shared_inputs = SimulationSharedInputs::new(
    CoordinateSystem::default(),
)
.with_reflections(ReflectionsSharedInputs {
    num_rays: 4096,
    num_bounces: 16,
    duration: 2.0,
    order: 1,
    irradiance_min_distance: 1.0,
});
simulator
    .set_shared_inputs(SimulationFlags::REFLECTIONS, &simulation_shared_inputs)
    .unwrap();

simulator.commit();

assert!(simulator.run_reflections().is_ok());
let simulation_outputs = source.get_outputs(SimulationFlags::REFLECTIONS).unwrap();
```

--------------------------------

### Context::default

Source: https://docs.rs/audionimbus/latest/audionimbus/context/struct.Context.html

Creates a new Steam Audio context with default settings. This is a convenient way to get started without explicit configuration.

```APIDOC
## pub fn default() -> Self

### Description
Returns the default value for a `Context`.

### Returns
* `Self` - A new `Context` instance initialized with default settings.

### Example
```rust
use audionimbus::Context;

let context = Context::default();
```
```

--------------------------------

### AudioBuffer Example: Mono and Stereo Buffers

Source: https://docs.rs/audionimbus/latest/src/audionimbus/audio_buffer.rs.html

Demonstrates how to create `AudioBuffer` instances for mono and stereo audio data using safe constructors. These examples show the usage of `try_with_data` and `try_with_data_and_settings`.

```rust
use audionimbus::{AudioBuffer, AudioBufferSettings};

// Mono buffer
let samples = vec![0.0; 1024];
let buffer = AudioBuffer::try_with_data(&samples)?;

// Stereo buffer
let stereo_samples = vec![0.0; 2048];
let buffer = AudioBuffer::try_with_data_and_settings(
    &stereo_samples,
    AudioBufferSettings::with_num_channels(2),
)?;
# Ok::<(), audionimbus::AudioBufferError>(())
```

--------------------------------

### Standard Material Properties Examples

Source: https://docs.rs/audionimbus-sys/latest/audionimbus_sys/struct.IPLMaterial.html

Provides example values for acoustic material properties for common materials like generic, brick, concrete, and wood. These examples illustrate how to populate the IPLMaterial struct for different acoustic behaviors.

```rust
{"generic",{0.10f,0.20f,0.30f,0.05f,0.100f,0.050f,0.030f}}
```

```rust
{"brick",{0.03f,0.04f,0.07f,0.05f,0.015f,0.015f,0.015f}}
```

```rust
{"concrete",{0.05f,0.07f,0.08f,0.05f,0.015f,0.002f,0.001f}}
```

```rust
{"ceramic",{0.01f,0.02f,0.02f,0.05f,0.060f,0.044f,0.011f}}
```

```rust
{"gravel",{0.60f,0.70f,0.80f,0.05f,0.031f,0.012f,0.008f}}
```

```rust
{"carpet",{0.24f,0.69f,0.73f,0.05f,0.020f,0.005f,0.003f}}
```

```rust
{"glass",{0.06f,0.03f,0.02f,0.05f,0.060f,0.044f,0.011f}}
```

```rust
{"plaster",{0.12f,0.06f,0.04f,0.05f,0.056f,0.056f,0.004f}}
```

```rust
{"wood",{0.11f,0.07f,0.06f,0.05f,0.070f,0.014f,0.005f}}
```

```rust
{"metal",{0.20f,0.07f,0.06f,0.05f,0.200f,0.025f,0.010f}}
```

```rust
{"rock",{0.13f,0.20f,0.24f,0.05f,0.015f,0.002f,0.001f}}
```

--------------------------------

### Applying Reflections Simulation to Audio

Source: https://docs.rs/audionimbus/latest/src/audionimbus/effect/reflections.rs.html

Example demonstrating the full workflow of setting up a simulation, running reflections, and applying the effect to an audio buffer.

```rust
# use audionimbus::*
let context = Context::default();

const SAMPLING_RATE: u32 = 48_000;
const FRAME_SIZE: u32 = 1024;
let audio_settings = AudioSettings {
    sampling_rate: SAMPLING_RATE,
    frame_size: FRAME_SIZE,
};

// Create a simulator with reflections.
let simulation_settings = SimulationSettings::new(SAMPLING_RATE, FRAME_SIZE, 1)
    .with_reflections(ReflectionsSimulationSettings::Convolution {
        max_num_rays: 4096,
        num_diffuse_samples: 32,
        max_duration: 2.0,
        max_num_sources: 8,
        num_threads: 2,
    });
let mut simulator = Simulator::try_new(&context, &simulation_settings)?;

let scene = Scene::try_new(&context)?;
simulator.set_scene(&scene);

let mut source = Source::try_new(
    &simulator,
    &SourceSettings {
        flags: SimulationFlags::REFLECTIONS,
    },
)?;

source.set_inputs(
    SimulationFlags::REFLECTIONS,
    SimulationInputs::new(CoordinateSystem::default()).with_reflections(
        ReflectionsSimulationParameters::Convolution {
            baked_data_identifier: None,
        },
    ),
);

simulator.add_source(&source);
simulator.set_shared_inputs(
    SimulationFlags::REFLECTIONS,
    &SimulationSharedInputs::new(CoordinateSystem::default()).with_reflections(
        ReflectionsSharedInputs {
            num_rays: 4096,
            num_bounces: 16,
            duration: 2.0,
            order: 1,
            irradiance_min_distance: 1.0,
        },
    ),
);
simulator.commit();

simulator.run_reflections();
let outputs = source.get_outputs(SimulationFlags::REFLECTIONS)?;

const NUM_CHANNELS: u32 = num_ambisonics_channels(1); // 1st order ambisonics
let mut effect = ReflectionEffect::<Convolution>::try_new(
    &context,
    &audio_settings,
    &ReflectionEffectSettings {
        impulse_response_size: 2 * SAMPLING_RATE, // 2 seconds
        num_channels: NUM_CHANNELS,
    },
)?;

let input = vec![0.5; FRAME_SIZE as usize];
let input_buffer = AudioBuffer::try_with_data(&input)?;
let mut output = vec![0.0; (NUM_CHANNELS * FRAME_SIZE) as usize]; // 4 channels
let output_buffer = AudioBuffer::try_with_data_and_settings(
    &mut output,
    AudioBufferSettings::with_num_channels(NUM_CHANNELS),
)?;

```

--------------------------------

### Test Custom Ray Tracer Setup

Source: https://docs.rs/audionimbus/latest/src/audionimbus/geometry/scene.rs.html

Configures and tests the creation of a scene with custom ray tracing callbacks.

```rust
#[test]
fn test_custom_ray_tracer() {
    let context = Context::default();

    let closest_hit = ClosestHitCallback::new(|_ray, _min_dist, _max_dist| None);

    let any_hit = AnyHitCallback::new(|_ray, _min_dist, _max_dist| false);

    let batched_closest_hit =
        BatchedClosestHitCallback::new(|rays, _min_dists, _max_dists| vec![None; rays.len()]);

    let batched_any_hit =
        BatchedAnyHitCallback::new(|rays, _min_dists, _max_dists| vec![false; rays.len()]);

    let callbacks = CustomRayTracingCallbacks::new(
        closest_hit,
        any_hit,
        batched_closest_hit,
        batched_any_hit,
    );

    assert!(Scene::<CustomRayTracer>::try_with_custom(&context, &callbacks).is_ok());
}
```

--------------------------------

### Test Scene Setup

Source: https://docs.rs/audionimbus/latest/src/audionimbus/baking/pathing.rs.html

Creates a simple room mesh for testing pathing functionalities. This includes defining vertices, triangles, and materials.

```rust
fn test_scene(context: &Context) -> Scene<'_, DefaultRayTracer> {
        let mut scene = Scene::try_new(context).unwrap();

        // Create a simple room mesh.
        let vertices = vec![
            // Floor
            Vector3::new(-5.0, 0.0, -5.0),
            Vector3::new(5.0, 0.0, -5.0),
            Vector3::new(5.0, 0.0, 5.0),
            Vector3::new(-5.0, 0.0, 5.0),
            // Ceiling
            Vector3::new(-5.0, 3.0, -5.0),
            Vector3::new(5.0, 3.0, -5.0),
            Vector3::new(5.0, 3.0, 5.0),
            Vector3::new(-5.0, 3.0, 5.0),
        ];

        let triangles = [
            // Floor
            [0, 1, 2],
            [0, 2, 3],
            // Ceiling
            [4, 6, 5],
            [4, 7, 6],
            // Walls
            [0, 4, 5],
            [0, 5, 1],
            [1, 5, 6],
            [1, 6, 2],
            [2, 6, 7],
            [2, 7, 3],
            [3, 7, 4],
            [3, 4, 0],
        ]
        .iter()
        .map(|indices| Triangle::new(indices[0], indices[1], indices[2]))
        .collect::<Vec<_>>();

        let material_indices = vec![0; triangles.len()];
        let materials = vec![Material::default()];

        let settings = StaticMeshSettings {
            vertices: &vertices,
            triangles: &triangles,
            material_indices: &material_indices,
            materials: &materials,
        };
        let static_mesh = StaticMesh::try_new(&scene, &settings).unwrap();
        scene.add_static_mesh(static_mesh);
        scene.commit();

        scene
    }
```

--------------------------------

### Named Callback Allocation Example

Source: https://docs.rs/audionimbus/latest/audionimbus/macro.allocate_callback.html

Demonstrates how to define a named memory allocation callback using the allocate_callback macro and then use it with ContextSettings.

```rust
use std::alloc::{alloc, Layout};
use std::ffi::c_void;

allocate_callback!(my_allocator, |size, alignment| {
    unsafe {
        let layout = Layout::from_size_align_unchecked(size, alignment);
        alloc(layout) as *mut c_void
    }
});

let settings = ContextSettings::new()
    .with_allocate_callback(my_allocator)
    .with_free_callback(my_free);
let context = Context::try_new(&settings)?;
```

--------------------------------

### Context::default

Source: https://docs.rs/audionimbus/latest/src/audionimbus/context.rs.html

Creates a new Audionimbus context with default settings. This is a convenient way to get started without explicit configuration.

```APIDOC
## Context::default

### Description
Creates a new context with default settings.

### Method
```rust
impl Default for Context
```

### Usage Example
```rust
let context = Context::default();
```

### Panics
Panics if the default context creation fails.
```

--------------------------------

### Basic Simulator Workflow

Source: https://docs.rs/audionimbus/latest/audionimbus/simulation/struct.Simulator.html

Demonstrates the typical workflow for setting up and running a direct sound simulation using the Simulator. This includes creating the simulator, setting up the scene, adding a source, configuring simulation parameters, and retrieving results.

```rust
// Create a simulator.
let settings = SimulationSettings::new(48000, 1024, 2)
    .with_direct(DirectSimulationSettings {
        max_num_occlusion_samples: 4,
    });
let mut simulator = Simulator::try_new(&context, &settings)?;

// Set up a scene.
let scene = Scene::try_new(&context)?;

// ... add and commit geometry to the scene ...

simulator.set_scene(&scene);
simulator.commit();

// Create and add a source.
let source_settings = SourceSettings {
    flags: SimulationFlags::DIRECT,
};
let mut source = Source::try_new(&simulator, &source_settings)?;

simulator.add_source(&source);

// Configure simulation parameters.
let simulation_inputs = SimulationInputs::new(CoordinateSystem::default())
    .with_direct(DirectSimulationParameters::new()
        .with_distance_attenuation(DistanceAttenuationModel::default()));
source.set_inputs(SimulationFlags::DIRECT, simulation_inputs);

// Set shared parameters.
let shared_inputs = SimulationSharedInputs::new(CoordinateSystem::default());
simulator.set_shared_inputs(SimulationFlags::DIRECT, &shared_inputs);

// Run the simulation.
simulator.run_direct();

// Get results.
let outputs = source.get_outputs(SimulationFlags::DIRECT)?;
```

--------------------------------

### Add Audionimbus to Cargo.toml

Source: https://docs.rs/audionimbus/latest/src/audionimbus/lib.rs.html

Include Audionimbus in your Cargo.toml with the 'auto-install' feature for automatic Steam Audio library setup. This is the recommended installation method.

```toml
[
dependencies]
audionimbus = { version = "0.13.0", features = ["auto-install"] }

```

--------------------------------

### Setup and Run Reflections Simulation

Source: https://docs.rs/audionimbus/latest/src/audionimbus/effect/reflections.rs.html

Sets up the simulation environment, including context, audio settings, simulation settings, scene, source, and shared inputs for reflections. Commits the simulation and runs the reflections calculation.

```rust
const SAMPLING_RATE: u32 = 48000;
                const FRAME_SIZE: u32 = 1024;
                const IR_SIZE: u32 = 2 * SAMPLING_RATE;
                const MAX_ORDER: u32 = 1;

                let context = Context::default();

                let audio_settings = AudioSettings::default();

                let simulation_settings =
                    SimulationSettings::new(SAMPLING_RATE, FRAME_SIZE, MAX_ORDER).with_reflections(
                        ReflectionsSimulationSettings::Convolution {
                            max_num_rays: 4096,
                            num_diffuse_samples: 32,
                            max_duration: 2.0,
                            max_num_sources: 8,
                            num_threads: 1,
                        },
                    );
                let mut simulator = Simulator::try_new(&context, &simulation_settings).unwrap();

                let scene = Scene::try_new(&context).unwrap();
                simulator.set_scene(&scene);

                let source_settings = SourceSettings {
                    flags: SimulationFlags::REFLECTIONS,
                };
                let mut source = 
                    Source::<(), Reflections, ()>::try_new(&simulator, &source_settings).unwrap();
                simulator.add_source(&source);

                let simulation_shared_inputs = SimulationSharedInputs::new(
                    CoordinateSystem::default(),
                )
                .with_reflections(ReflectionsSharedInputs {
                    num_rays: 4096,
                    num_bounces: 16,
                    duration: 2.0,
                    order: 1,
                    irradiance_min_distance: 1.0,
                });
                simulator
                    .set_shared_inputs(SimulationFlags::REFLECTIONS, &simulation_shared_inputs)
                    .unwrap();

                simulator.commit();

                assert!(simulator.run_reflections().is_ok());
                let simulation_outputs = source.get_outputs(SimulationFlags::REFLECTIONS).unwrap();

                let num_output_channels = num_ambisonics_channels(1);
                let reflection_effect_settings = ReflectionEffectSettings {
                    impulse_response_size: IR_SIZE,
                    num_channels: num_output_channels,
                };
                let mut reflection_effect = ReflectionEffect::<Convolution>::try_new(
                    &context,
                    &audio_settings,
                    &reflection_effect_settings,
                )
                .unwrap();
```

--------------------------------

### reset

Source: https://docs.rs/audionimbus/latest/src/audionimbus/effect/ambisonics/decode.rs.html

Resets the internal processing state of the ambisonics decode effect. This is useful for reinitializing the effect, for example, when starting a new audio stream or seeking within an audio file.

```APIDOC
## reset

### Description
Resets the internal processing state of the ambisonics decode effect. This is useful for reinitializing the effect, for example, when starting a new audio stream or seeking within an audio file.

### Method
`pub fn reset(&mut self)`

### Parameters
None

### Response
#### Success Response (200)
No explicit response body, indicates successful reset.
```

--------------------------------

### Create Simulator with Multiple Simulation Settings

Source: https://docs.rs/audionimbus/latest/audionimbus/simulation/struct.Simulator.html

Shows how to create a Simulator instance with detailed settings for direct sound, reflections, and pathing simulations. Ensure all necessary parameters for each simulation type are provided.

```rust
let settings = SimulationSettings::new(48000, 1024, 2)
    .with_direct(DirectSimulationSettings {
        max_num_occlusion_samples: 4,
    })
    .with_reflections(ReflectionsSimulationSettings::Convolution {
        max_num_rays: 4096,
        num_diffuse_samples: 32,
        max_duration: 2.0,
        max_num_sources: 8,
        num_threads: 2,
    })
    .with_pathing(PathingSimulationSettings {
        num_visibility_samples: 4,
    });
let simulator = Simulator::try_new(&context, &settings)?;
```

--------------------------------

### log_callback Macro - Anonymous Callback Example

Source: https://docs.rs/audionimbus/latest/src/audionimbus/callback.rs.html

Example showing the usage of the log_callback macro to create an inline, anonymous logging callback.

```rust
# use audionimbus::{log_callback, Context, ContextSettings};
let settings = ContextSettings::new().with_log_callback(log_callback!(|level, message| {
    println!(ירת{level:?}: {message});
}));
let context = Context::try_new(&settings)?;
# Ok::<(), audionimbus::SteamAudioError>(())
```

--------------------------------

### Setup and Run Reflections Simulation

Source: https://docs.rs/audionimbus/latest/src/audionimbus/effect/reflections.rs.html

Initializes the simulator, sets up a scene, adds a reflection source, configures shared inputs, and runs the reflections simulation. This is typically used for setting up the simulation environment before processing.

```rust
let scene = Scene::try_new(&context).unwrap();
simulator.set_scene(&scene);

let source_settings = SourceSettings {
    flags: SimulationFlags::REFLECTIONS,
};
let mut source = Source::<(), Reflections, ()>::try_new(&simulator, &source_settings).unwrap();
simulator.add_source(&source);

let simulation_shared_inputs = SimulationSharedInputs::new(
    CoordinateSystem::default(),
)
.with_reflections(ReflectionsSharedInputs {
    num_rays: 4096,
    num_bounces: 16,
    duration: 2.0,
    order: 1,
    irradiance_min_distance: 1.0,
});
simulator
    .set_shared_inputs(SimulationFlags::REFLECTIONS, &simulation_shared_inputs)
    .unwrap();

simulator.commit();

assert!(simulator.run_reflections().is_ok());
let simulation_outputs = source.get_outputs(SimulationFlags::REFLECTIONS).unwrap();
```

--------------------------------

### log_callback Macro - Named Callback Example

Source: https://docs.rs/audionimbus/latest/src/audionimbus/callback.rs.html

Example demonstrating how to use the log_callback macro to create a reusable, named logging function.

```rust
# use audionimbus::{log_callback, Context, ContextSettings, LogLevel};
log_callback!(my_logger, |level, message| {
    println!(ירת{level:?}: {message});
});

let settings = ContextSettings::new().with_log_callback(my_logger);
let context = Context::try_new(&settings)?;
# Ok::<(), audionimbus::SteamAudioError>(())
```

--------------------------------

### Add Audionimbus with Auto-Install

Source: https://docs.rs/audionimbus

Use this dependency configuration for automatic installation of Steam Audio libraries. Ensure you have curl or wget and Clang 9.0+ installed.

```toml
[dependencies]
audionimbus = { version = "0.13.0", features = ["auto-install"] }
```

--------------------------------

### Initialize and Run Direct Simulation

Source: https://docs.rs/audionimbus/latest/src/audionimbus/simulation.rs.html

Sets up a simulation context, creates a simulator with specific settings, configures a source with direct simulation flags and parameters, runs the direct simulation, and retrieves reflection outputs.

```rust
fn panic_on_invalid_flags() {
    let context = Context::default();

    const SAMPLING_RATE: u32 = 48_000;
    const FRAME_SIZE: u32 = 1024;
    const MAX_ORDER: u32 = 1;

    let simulation_settings =
        SimulationSettings::new(SAMPLING_RATE, FRAME_SIZE, MAX_ORDER).with_direct(
            DirectSimulationSettings {
                max_num_occlusion_samples: 4,
            },
        );
    let mut simulator = Simulator::try_new(&context, &simulation_settings).unwrap();

    let scene = Scene::try_new(&context).unwrap();
    simulator.set_scene(&scene);

    let source_settings = SourceSettings {
        flags: SimulationFlags::DIRECT | SimulationFlags::REFLECTIONS,
    };
    let mut source = Source::try_new(&simulator, &source_settings).unwrap();

    let simulation_inputs = SimulationInputs::new(CoordinateSystem {
        right: Vector3::new(1.0, 0.0, 0.0),
        up: Vector3::new(0.0, 1.0, 0.0),
        ahead: Vector3::new(0.0, 0.0, 1.0),
        origin: Vector3::new(0.0, 0.0, 0.0),
    })
    .with_direct(
        DirectSimulationParameters::new()
            .with_distance_attenuation(DistanceAttenuationModel::default())
            .with_air_absorption(AirAbsorptionModel::default())
            .with_directivity(Directivity::default())
            .with_occlusion(
                Occlusion::new(OcclusionAlgorithm::Raycast).with_transmission(
                    TransmissionParameters {
                        num_transmission_rays: 1,
                    },
                ),
            ),
    );
    source
        .set_inputs(SimulationFlags::DIRECT, simulation_inputs)
        .unwrap();

    simulator.run_direct();
    let _ = source.get_outputs(SimulationFlags::REFLECTIONS).unwrap();
}
```

--------------------------------

### Add Audionimbus with Auto-Install and Wwise

Source: https://docs.rs/audionimbus

Integrate Audionimbus with automatic installation and Wwise support. Ensure the WWISESDK environment variable points to your Wwise SDK installation.

```toml
[dependencies]
audionimbus = { version = "0.13.0", features = ["auto-install", "wwise"] }
```

--------------------------------

### Get Mutable Reference to First Element via Mutable Slice

Source: https://docs.rs/audionimbus-sys/latest/audionimbus_sys/type.IPLBatchedClosestHitCallback.html

Demonstrates using `as_mut_slice().first_mut()` to get a mutable reference to the single element in an Option.

```rust
assert_eq!(Some(123).as_mut_slice().first_mut(), Some(&mut 123))
```

--------------------------------

### Applying Reflections with ReflectionEffect

Source: https://docs.rs/audionimbus/latest/audionimbus/effect/reflections/struct.ReflectionEffect.html

Demonstrates the complete process of setting up a simulation, running reflections, and applying the ReflectionEffect to an audio buffer. This includes initializing the context, simulator, scene, sources, and configuring simulation parameters. Ensure the simulation is committed and run before retrieving outputs for the effect.

```rust
let context = Context::default();

const SAMPLING_RATE: u32 = 48_000;
const FRAME_SIZE: u32 = 1024;
let audio_settings = AudioSettings {
    sampling_rate: SAMPLING_RATE,
    frame_size: FRAME_SIZE,
};

// Create a simulator with reflections.
let simulation_settings = SimulationSettings::new(SAMPLING_RATE, FRAME_SIZE, 1)
    .with_reflections(ReflectionsSimulationSettings::Convolution {
        max_num_rays: 4096,
        num_diffuse_samples: 32,
        max_duration: 2.0,
        max_num_sources: 8,
        num_threads: 2,
    });
let mut simulator = Simulator::try_new(&context, &simulation_settings)?;

let scene = Scene::try_new(&context)?;
simulator.set_scene(&scene);

let mut source = Source::try_new(
    &simulator,
    &SourceSettings {
        flags: SimulationFlags::REFLECTIONS,
    },
)?;

source.set_inputs(
    SimulationFlags::REFLECTIONS,
    SimulationInputs::new(CoordinateSystem::default()).with_reflections(
        ReflectionsSimulationParameters::Convolution {
            baked_data_identifier: None,
        },
    ),
);

simulator.add_source(&source);
simulator.set_shared_inputs(
    SimulationFlags::REFLECTIONS,
    &SimulationSharedInputs::new(CoordinateSystem::default()).with_reflections(
        ReflectionsSharedInputs {
            num_rays: 4096,
            num_bounces: 16,
            duration: 2.0,
            order: 1,
            irradiance_min_distance: 1.0,
        },
    ),
);
simulator.commit();

simulator.run_reflections();
let outputs = source.get_outputs(SimulationFlags::REFLECTIONS)?;

const NUM_CHANNELS: u32 = num_ambisonics_channels(1); // 1st order ambisonics
let mut effect = ReflectionEffect::<Convolution>::try_new(
    &context,
    &audio_settings,
    &ReflectionEffectSettings {
        impulse_response_size: 2 * SAMPLING_RATE, // 2 seconds
        num_channels: NUM_CHANNELS,
    },
)?;

let input = vec![0.5; FRAME_SIZE as usize];
let input_buffer = AudioBuffer::try_with_data(&input)?;
let mut output = vec![0.0; (NUM_CHANNELS * FRAME_SIZE) as usize]; // 4 channels
let output_buffer = AudioBuffer::try_with_data_and_settings(
    &mut output,
    AudioBufferSettings::with_num_channels(NUM_CHANNELS),
)?;

let params = outputs.reflections();
let _ = effect.apply(&params, &input_buffer, &output_buffer);

```

--------------------------------

### Scene::from_ffi_create

Source: https://docs.rs/audionimbus/latest/src/audionimbus/geometry/scene.rs.html

Creates a scene from FFI settings, initializing it with provided context and settings.

```APIDOC
## Scene::from_ffi_create

### Description
Creates a scene from FFI settings.

### Parameters
- `context`: A reference to the `Context`.
- `settings`: A mutable reference to `audionimbus_sys::IPLSceneSettings`.
- `callback_user_data`: An optional `Box<CustomRayTracingUserData>` for custom ray tracing.

### Returns
A `Result` containing the created `Scene` or a `SteamAudioError` if creation fails.

### Example
```rust
// Assuming context, settings, and callback_user_data are properly initialized
// let scene = Scene::from_ffi_create(&context, &mut settings, callback_user_data)?;
```
```

--------------------------------

### Add Audionimbus with Manual Installation

Source: https://docs.rs/audionimbus

Use this basic dependency configuration when performing a manual installation of Steam Audio. Ensure Steam Audio libraries are correctly linked.

```toml
[dependencies]
audionimbus = "0.13.0"
```

--------------------------------

### Create SimulationSettings

Source: https://docs.rs/audionimbus/latest/audionimbus/simulation/struct.SimulationSettings.html

Initializes SimulationSettings with basic parameters and enables direct, reflections, and pathing simulations with custom configurations.

```rust
let settings = SimulationSettings::new(48000, 1024, 2)
    .with_direct(DirectSimulationSettings {
        max_num_occlusion_samples: 4,
    })
    .with_reflections(ReflectionsSimulationSettings::Convolution {
        max_num_rays: 4096,
        num_diffuse_samples: 32,
        max_duration: 2.0,
        max_num_sources: 8,
        num_threads: 2,
    })
    .with_pathing(PathingSimulationSettings {
        num_visibility_samples: 4,
    });
```

--------------------------------

### OpenCL Device Creation and Cloning

Source: https://docs.rs/audionimbus/latest/src/audionimbus/device/open_cl.rs.html

Demonstrates creating an OpenCL device from a context and device list, cloning it, and verifying pointer equality. Ensures the original device is dropped while the clone remains valid.

```rust
let device = OpenClDevice::try_new(&context, &device_list, 0).unwrap();
let clone = device.clone();
assert_eq!(device.raw_ptr(), clone.raw_ptr());
drop(device);
assert!(!clone.raw_ptr().is_null());
```

--------------------------------

### Configure and Run Pathing Simulation

Source: https://docs.rs/audionimbus/latest/src/audionimbus/effect/pathing.rs.html

Sets up simulation inputs for pathing, adds a source to the simulator, and runs the pathing simulation. Ensure probe batch and simulation parameters are correctly defined.

```rust
///             .with_air_absorption(AirAbsorptionModel::default())
///             .with_directivity(Directivity::default())
///             .with_occlusion(
///                 Occlusion::new(OcclusionAlgorithm::Raycast).with_transmission(
///                     TransmissionParameters {
///                         num_transmission_rays: 1,
///                     },
///                 ),
///             ),
///     )
///     .with_reflections(ReflectionsSimulationParameters::Convolution {
///         baked_data_identifier: None,
///     })
///     .with_pathing(PathingSimulationParameters {
///         pathing_probes: &probe_batch,
///         visibility_radius: 1.0,
///         visibility_threshold: 10.0,
///         visibility_range: 10.0,
///         pathing_order: 1,
///         enable_validation: true,
///         find_alternate_paths: true,
///         deviation: DeviationModel::default(),
///     });
/// source.set_inputs(SimulationFlags::PATHING, simulation_inputs);
/// simulator.add_source(&source);
///
/// simulator.commit();
/// simulator.run_pathing();
///
/// let audio_settings = AudioSettings::default();
/// let path_effect_settings = PathEffectSettings {
///     max_order: MAX_ORDER,
///     spatialization: None,
/// };
/// let mut path_effect = PathEffect::try_new(&context, &audio_settings, &path_effect_settings)?;
///
/// let input = vec![0.5; FRAME_SIZE as usize];
/// let input_buffer = AudioBuffer::try_with_data(&input)?;
///
/// // Must have 4 channels (1st order Ambisonics) for this example.
/// const NUM_CHANNELS: u32 = num_ambisonics_channels(1);
/// let mut output_container = vec![0.0; (NUM_CHANNELS * input_buffer.num_samples()) as usize];
/// let output_buffer = AudioBuffer::try_with_data_and_settings(
///     &mut output_container,
///     AudioBufferSettings::with_num_channels(NUM_CHANNELS),
/// )?;
///
/// let simulation_outputs = source.get_outputs(SimulationFlags::PATHING)?;
/// let path_effect_params = simulation_outputs.pathing();
/// let _ = path_effect.apply(&path_effect_params, &input_buffer, &output_buffer);
/// # Ok::<(), Box<dyn std::error::Error>>(())
```

--------------------------------

### impl<T> Any for T

Source: https://docs.rs/audionimbus/latest/audionimbus/effect/panning/struct.PanningEffect.html

Gets the `TypeId` of `self`.

```APIDOC
## PanningEffect::type_id

### Description
Gets the `TypeId` of `self`.

### Returns
- TypeId - The `TypeId` of `self`.
```

--------------------------------

### Initialize and Configure Simulation Settings

Source: https://docs.rs/audionimbus/latest/src/audionimbus/simulation.rs.html

Create and customize simulation settings for Audionimbus. This example shows how to set the sampling rate, frame size, and maximum order, and then configure specific settings for direct, reflections, and pathing simulations.

```rust
use audionimbus::{Context, Simulator, DirectSimulationSettings, ReflectionsSimulationSettings, PathingSimulationSettings, SimulationSettings};
let settings = SimulationSettings::new(48000, 1024, 2)
    .with_direct(DirectSimulationSettings {
        max_num_occlusion_samples: 4,
    })
    .with_reflections(ReflectionsSimulationSettings::Convolution {
        max_num_rays: 4096,
        num_diffuse_samples: 32,
        max_duration: 2.0,
        max_num_sources: 8,
        num_threads: 2,
    })
    .with_pathing(PathingSimulationSettings {
        num_visibility_samples: 4,
    });
Ok::<(), audionimbus::SteamAudioError>(())
```

--------------------------------

### type_id

Source: https://docs.rs/audionimbus-sys/latest/audionimbus_sys/struct._IPLImpulseResponse_t.html

Gets the `TypeId` of `self`.

```APIDOC
## type_id

### Description
Gets the `TypeId` of `self`.

### Signature
```rust
fn type_id(&self) -> TypeId
```
```

--------------------------------

### Initialize Simulator with Parametric Settings

Source: https://docs.rs/audionimbus/latest/src/audionimbus/effect/reflections.rs.html

Initializes the simulator with specific audio and simulation settings, including parametric reflections.

```rust
const SAMPLING_RATE: u32 = 48000;
const FRAME_SIZE: u32 = 1024;
const IR_SIZE: u32 = 2 * SAMPLING_RATE;
const MAX_ORDER: u32 = 1;

let context = Context::default();

let audio_settings = AudioSettings::default();

let simulation_settings = SimulationSettings::new(SAMPLING_RATE, FRAME_SIZE, MAX_ORDER).with_reflections(
    ReflectionsSimulationSettings::Parametric {
        max_num_rays: 4096,
        num_diffuse_samples: 32,
        max_duration: 2.0,
        max_num_sources: 8,
        num_threads: 1,
    },
);
let mut simulator = Simulator::try_new(&context, &simulation_settings).unwrap();
```

--------------------------------

### Hrtf::type_id

Source: https://docs.rs/audionimbus/latest/audionimbus/hrtf/struct.Hrtf.html

Gets the `TypeId` of `self`.

```APIDOC
## Hrtf::type_id

### Description
Gets the `TypeId` of `self`.

### Method
```rust
fn type_id(&self) -> TypeId
```

### Returns
- **TypeId** - The `TypeId` of the `Hrtf` instance.
```

--------------------------------

### Configure and Run Reflections Simulation

Source: https://docs.rs/audionimbus/latest/src/audionimbus/effect/reflections.rs.html

Sets up a reflections simulation with parametric settings, adds a source, runs the simulation, and applies the resulting reflection effect.

```rust
let mut simulator = Simulator::try_new(&context, &simulation_settings).unwrap();

let scene = Scene::try_new(&context).unwrap();
simulator.set_scene(&scene);

let source_settings = SourceSettings {
    flags: SimulationFlags::REFLECTIONS,
};
let mut source = Source::<(), Reflections, ()>::try_new(&simulator, &source_settings).unwrap();
simulator.add_source(&source);

let simulation_shared_inputs = SimulationSharedInputs::new(
    CoordinateSystem::default(),
)
.with_reflections(ReflectionsSharedInputs {
    num_rays: 4096,
    num_bounces: 16,
    duration: 2.0,
    order: 1,
    irradiance_min_distance: 1.0,
});
simulator
    .set_shared_inputs(SimulationFlags::REFLECTIONS, &simulation_shared_inputs)
    .unwrap();

simulator.commit();

assert!(simulator.run_reflections().is_ok());
let simulation_outputs = source.get_outputs(SimulationFlags::REFLECTIONS).unwrap();

let num_output_channels = num_ambisonics_channels(1);
let reflection_effect_settings = ReflectionEffectSettings {
    impulse_response_size: IR_SIZE,
    num_channels: num_output_channels,
};

let mut mixer = ReflectionMixer::<Convolution>::try_new(
    &context,
    &audio_settings,
    &reflection_effect_settings,
)
.unwrap();

let mut output_container = vec![0.0; (num_output_channels * FRAME_SIZE) as usize];
let output_buffer = AudioBuffer::try_with_data_and_settings(
    &mut output_container,
    AudioBufferSettings::with_num_channels(num_output_channels),
)
.unwrap();

let mut reflection_effect_params = simulation_outputs.reflections();
assert!(mixer
    .apply(&mut reflection_effect_params, &output_buffer)
    .is_ok());
```

--------------------------------

### Simulate Reverb with ReflectionEffect

Source: https://docs.rs/audionimbus/latest/audionimbus/effect/reflections/struct.ReflectionEffect.html

This example demonstrates how to simulate reverb by creating a ReflectionEffect and positioning a source at the listener's location. It covers setting up the simulator, scene, sources, and applying the effect to an audio buffer.

```rust
let mut context = Context::default();
const SAMPLING_RATE: u32 = 48_000;
const FRAME_SIZE: u32 = 1024;
let audio_settings = AudioSettings {
    sampling_rate: SAMPLING_RATE,
    frame_size: FRAME_SIZE,
};

// Create simulator with reflections
let simulation_settings = SimulationSettings::new(SAMPLING_RATE, FRAME_SIZE, 1)
    .with_reflections(ReflectionsSimulationSettings::Convolution {
        max_num_rays: 2048,
        num_diffuse_samples: 32,
        max_duration: 2.0,
        max_num_sources: 8,
        num_threads: 2,
    });
let mut simulator = Simulator::try_new(&context, &simulation_settings)?;

let scene = Scene::try_new(&context)?;
simulator.set_scene(&scene);

// Create a reverb source positioned at the listener.
let mut reverb_source = Source::try_new(
    &simulator,
    &SourceSettings {
        flags: SimulationFlags::REFLECTIONS,
    },
)?;

let listener_position = CoordinateSystem {
    origin: Vector3::new(0.0, 1.5, 0.0), // Listener at head height
    ..Default::default() 
};

// Set source position to match listener position.
reverb_source.set_inputs(
    SimulationFlags::REFLECTIONS,
    SimulationInputs::new(listener_position) // Source at listener = reverb
        .with_reflections(ReflectionsSimulationParameters::Convolution {
            baked_data_identifier: None,
        }),
);

simulator.add_source(&reverb_source);
simulator.set_shared_inputs(
    SimulationFlags::REFLECTIONS,
    &SimulationSharedInputs::new(CoordinateSystem::default()).with_reflections(
        ReflectionsSharedInputs {
            num_rays: 4096,
            num_bounces: 16,
            duration: 2.0,
            order: 1,
            irradiance_min_distance: 1.0,
        },
    ),
);
simulator.commit();

// Run simulation.
simulator.run_reflections();
let reverb_outputs = reverb_source.get_outputs(SimulationFlags::REFLECTIONS)?;
let reverb_params = reverb_outputs.reflections();

const NUM_CHANNELS: u32 = num_ambisonics_channels(1); // 1st order ambisonics
let mut reverb_effect = ReflectionEffect::<Convolution>::try_new(
    &context,
    &audio_settings,
    &ReflectionEffectSettings {
        impulse_response_size: 2 * SAMPLING_RATE,
        num_channels: NUM_CHANNELS,
    },
)?;

let input = vec![0.5; FRAME_SIZE as usize];
let input_buffer = AudioBuffer::try_with_data(&input)?;
let mut reverb_output = vec![0.0; (NUM_CHANNELS * FRAME_SIZE) as usize];
let output_buffer = AudioBuffer::try_with_data_and_settings(
    &mut reverb_output,
    AudioBufferSettings::with_num_channels(NUM_CHANNELS),
)?;

let _ = reverb_effect.apply(&reverb_params, &input_buffer, &output_buffer);

// Mix with dry signal (e.g., 70% dry, 30% reverb)
// Then decode the ambisonics output for final playback

```

--------------------------------

### Create a new PathBaker

Source: https://docs.rs/audionimbus/latest/src/audionimbus/baking/pathing.rs.html

Instantiates a new PathBaker. No setup is required.

```rust
pub const fn new() -> Self {
    Self {
        _marker: PhantomData,
    }
}
```
Tokens:
Raw