### Quick Start: PetalSonic Audio Setup and Playback

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/index.html

Demonstrates the basic setup for PetalSonic, including world and engine creation, audio loading, source registration, playback, listener positioning, and event polling. Ensure audio files are accessible and error handling is implemented for production use.

```rust
use petalsonic::*;
use petalsonic::math::{Pose, Vec3};
use std::sync::Arc;

// Create a world configuration
let config = PetalSonicWorldDesc::default();

// Create the audio world
let world = Arc::new(PetalSonicWorld::new(config.clone())?);

// Create and start the audio engine
let mut engine = PetalSonicEngine::new(config, world.clone())?;
engine.start()?;

// Load audio data
let audio_data = audio_data::PetalSonicAudioData::from_path("audio.wav")?;

// Register audio with spatial configuration
let source_id = world.register_audio(
    audio_data,
    SourceConfig::spatial(Pose::from_position(Vec3::new(5.0, 0.0, 0.0)))
)?;

// Play the audio
world.play(source_id, playback::LoopMode::Once)?;

// Update listener position as your camera/player moves
world.set_listener_pose(Pose::from_position(Vec3::new(0.0, 0.0, 0.0)));

// Poll for events
for event in engine.poll_events() {
    match event {
        PetalSonicEvent::SourceCompleted { source_id } => {
            println!("Audio completed: {:?}", source_id);
        }
        _ => {}
    }
}
```

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

### Quick Start: Initialize and Play Spatial Audio

Source: https://docs.rs/petalsonic

This snippet demonstrates the basic setup for PetalSonic, including creating the audio world, engine, loading audio data, registering a spatial source, and playing it. It also shows how to update the listener's position and poll for events.

```Rust
use petalsonic::*
use petalsonic::math::{Pose, Vec3}
use std::sync::Arc

// Create a world configuration
let config = PetalSonicWorldDesc::default();

// Create the audio world
let world = Arc::new(PetalSonicWorld::new(config.clone())?);

// Create and start the audio engine
let mut engine = PetalSonicEngine::new(config, world.clone())?;
engine.start()?;

// Load audio data
let audio_data = audio_data::PetalSonicAudioData::from_path("audio.wav")?;

// Register audio with spatial configuration
let source_id = world.register_audio(
    audio_data,
    SourceConfig::spatial(Pose::from_position(Vec3::new(5.0, 0.0, 0.0)))
)?;

// Play the audio
world.play(source_id, playback::LoopMode::Once)?;

// Update listener position as your camera/player moves
world.set_listener_pose(Pose::from_position(Vec3::new(0.0, 0.0, 0.0)));

// Poll for events
for event in engine.poll_events() {
    match event {
        PetalSonicEvent::SourceCompleted { source_id } => {
            println!("Audio completed: {:?}", source_id);
        }
        _ => {}
    }
}
```

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

### Update Listener Position Example

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/world/struct.PetalSonicAudioListener.html

Example demonstrating how to move the listener to a specific position and orientation in the 3D audio world.

```rust
// Move listener to position (10, 0, 5) facing forward
let pose = Pose::from_position(Vec3::new(10.0, 0.0, 5.0));
world.set_listener_pose(pose);
```

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

### PetalSonicEngine::start

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/engine/struct.PetalSonicEngine.html

Starts the audio engine, enabling automatic playback management.

```APIDOC
## PetalSonicEngine::start

### Description
Start the audio engine with automatic playback management.

### Returns
* `Result<()>` - Ok(()) if successful, or an error if the engine fails to start.
```

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

### Start Audio Engine

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/engine/struct.PetalSonicEngine.html

Starts the audio engine, enabling automatic playback management. This operation returns a Result, which may contain an error if the engine fails to start.

```rust
pub fn start(&mut self) -> Result<()>
```

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

### Custom AudioDataLoader Implementation Example

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/audio_data/trait.AudioDataLoader.html

Example of how to implement the AudioDataLoader trait for custom audio loading logic. This snippet shows the basic structure required for a custom loader.

```rust
use petalsonic_core::audio_data::{AudioDataLoader, LoadOptions, PetalSonicAudioData};
use petalsonic_core::error::Result;
use std::sync::Arc;

struct MyCustomLoader;

impl AudioDataLoader for MyCustomLoader {
    fn load(&self, path: &str, options: &LoadOptions) -> Result<Arc<PetalSonicAudioData>> {
        // Your custom loading logic here
        todo!()
    }
}
```

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

### Create LoadOptions with Mono Conversion

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/audio_data/struct.LoadOptions.html

Example of creating LoadOptions and forcing conversion to mono audio.

```rust
let options = LoadOptions::new()
    .convert_to_mono(ConvertToMono::ForceMono);
```

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

### Create Default LoadOptions

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/audio_data/struct.LoadOptions.html

Example of creating LoadOptions using the default settings, which preserves original audio channels.

```rust
let options = LoadOptions::default();
```

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

### Get Ambisonics Backend

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/spatial/struct.SpatialProcessor.html

Retrieves the currently configured ambisonics backend.

```rust
pub fn ambisonics_backend(&self) -> AmbisonicsBackend
```

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

### Get Listener

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/world/struct.PetalSonicWorld.html

Returns a copy of the current listener's pose and configuration.

```rust
pub fn listener(&self) -> PetalSonicAudioListener
```

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

### Get HRTF Backend

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/spatial/struct.SpatialProcessor.html

Retrieves the currently configured HRTF backend.

```rust
pub fn hrtf_backend(&self) -> HrtfBackend
```

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

### Get Direct Path Backend

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/spatial/struct.SpatialProcessor.html

Retrieves the currently configured direct path backend.

```rust
pub fn direct_path_backend(&self) -> DirectPathBackend
```

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

### Get Spatial Backends

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/engine/struct.PetalSonicEngine.html

Retrieves the currently configured HRTF and direct path backends for spatial audio processing.

```rust
pub fn spatial_backends(&self) -> (HrtfBackend, DirectPathBackend)
```

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

### play

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/world/struct.PetalSonicWorld.html

Starts playing an audio source by its SourceId. Sends a play command to the audio engine thread. The audio will begin playing from its current position.

```APIDOC
## play

### Description
Starts playing an audio source by its SourceId. Sends a play command to the audio engine thread. The audio will begin playing from its current position (or from the beginning if not yet played).

### Method
`play`

### Parameters
#### Arguments
* `audio_id` - SourceId - The ID of the audio source to play.
* `loop_mode` - LoopMode - How the audio should loop (Once, Infinite, or Count(n)).

### Errors
Returns an error if the audio source ID is not found in the world storage or if the command fails to send to the audio engine.
```

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

### Play Audio Source

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/world/struct.PetalSonicWorld.html

Starts playing an audio source by its SourceId. Sends a play command to the audio engine thread. The audio will begin playing from its current position.

```rust
pub fn play(&self, audio_id: SourceId, loop_mode: LoopMode) -> Result<()>
```

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

### Get All Audio Samples

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/audio_data/struct.PetalSonicAudioData.html

Retrieves a slice containing all audio samples in interleaved format.

```rust
pub fn samples(&self) -> &[f32]
```

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

### Get All Audio Source IDs

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/world/struct.PetalSonicWorld.html

Returns a list of all audio source IDs currently stored in the world.

```rust
pub fn get_audio_source_ids(&self) -> Vec<SourceId>
```

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

### Get Available Output Devices

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/engine/struct.PetalSonicEngine.html

Retrieves a list of available audio output devices. This function returns a Result containing a vector of `AudioOutputDeviceInfo` or an error.

```rust
pub fn available_output_devices() -> Result<Vec<AudioOutputDeviceInfo>>
```

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

### Get Samples for a Specific Channel

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/audio_data/struct.PetalSonicAudioData.html

Extracts and returns all samples for a specified channel (0-indexed).

```rust
pub fn channel_samples(&self, channel: usize) -> Result<Vec<f32>>
```

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

### Providing Default Values with unwrap_or

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/error/type.Result.html

Shows how to get the `Ok` value or a provided default if the Result is `Err`. The default value is eagerly evaluated.

```rust
let default = 2;
let x: Result<u32, &str> = Ok(9);
assert_eq!(x.unwrap_or(default), 9);

let x: Result<u32, &str> = Err("error");
assert_eq!(x.unwrap_or(default), default);
```

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

### Get Frames Processed

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/engine/struct.PetalSonicEngine.html

Returns the total number of audio frames that have been processed by the engine since it was started.

```rust
pub fn frames_processed(&self) -> usize
```

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

### Get Spatial Rendering Settings

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/engine/struct.PetalSonicEngine.html

Returns the current settings for spatial rendering, including HRTF backend, direct path backend, ambisonics usage, and ambisonics backend.

```rust
pub fn spatial_rendering( &self, ) -> (HrtfBackend, DirectPathBackend, bool, AmbisonicsBackend)
```

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

### PetalSonicWorld::new

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/world/struct.PetalSonicWorld.html

Creates a new PetalSonicWorld instance with the provided configuration. This is the entry point for initializing the audio engine.

```APIDOC
## PetalSonicWorld::new

### Description
Initializes and returns a new `PetalSonicWorld` instance. This struct is the main entry point for managing 3D audio sources and playback within the PetalSonic system.

### Method
`new`

### Parameters
#### Arguments
* `config` (PetalSonicWorldDesc) - The configuration object for the PetalSonicWorld.
```

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

### Register Procedural Audio Source

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/world/struct.PetalSonicWorld.html

Registers a procedural audio source factory. PetalSonic creates a fresh render-thread-owned source instance when playback starts.

```rust
pub fn register_procedural( &self, factory: Arc<dyn ProceduralAudioFactory>, config: SourceConfig, ) -> Result<SourceId>
```

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

### Get Audio Source Position

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/world/struct.PetalSonicAudioSource.html

Retrieves the 3D position of the audio source. Use this to get the current spatial coordinates of the source.

```rust
pub fn position(&self) -> Vec3
```

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

### PetalSonicEngine::new

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/engine/struct.PetalSonicEngine.html

Creates a new PetalSonicEngine instance. This function initializes the audio engine with a specified world description and a shared world state.

```APIDOC
## PetalSonicEngine::new

### Description
Create a new audio engine with the given configuration and world.

### Arguments
* `desc` (PetalSonicWorldDesc) - The configuration for the audio world.
* `world` (Arc<PetalSonicWorld>) - A shared reference to the PetalSonic world state.
```

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

### SpatialProcessor::frame_size

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/spatial/struct.SpatialProcessor.html

Gets the configured frame size for audio processing.

```APIDOC
## SpatialProcessor::frame_size

### Description
Get the frame size.

### Returns
usize
```

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

### PlaybackInstance Methods

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/playback/struct.PlaybackInstance.html

This section details the methods available for interacting with a PlaybackInstance, allowing control over playback state, seeking, and buffer filling.

```APIDOC
## PlaybackInstance

Represents an active playback instance.

### Fields
* `audio_id`: SourceId of the audio data being played.
* `content`: Render-thread-owned static or procedural content.
* `info`: Current playback information.
* `config`: Source configuration (spatial/non-spatial).
* `loop_mode`: Loop mode for this playback.
* `direct_path_override`: Optional host-provided direct-path override used during spatial processing.

### Methods

#### `new(audio_id: SourceId, audio_data: Arc<PetalSonicAudioData>, config: SourceConfig, loop_mode: LoopMode) -> Self`
Creates a new PlaybackInstance.

#### `sample_rate(&self) -> u32`
Returns the sample rate of the audio.

#### `total_frames(&self) -> usize`
Returns the total number of frames in the audio.

#### `is_procedural(&self) -> bool`
Checks if the source is procedural.

#### `resume(&mut self)`
Resumes playback from the current position.

#### `reset(&mut self)`
Resets the playback cursor to the beginning.

#### `play_from_beginning(&mut self)`
Plays the audio from the beginning (resets and resumes).

#### `set_loop_mode(&mut self, loop_mode: LoopMode)`
Sets the loop mode for the playback instance.

#### `pause(&mut self)`
Pauses the current playback instance.

#### `stop(&mut self)`
Stops the playback instance, retaining the current position.

#### `seek(&mut self, progress: f32)`
Seeks to a specific progress position (0.0 = start, 1.0 = end). For procedural sources, this resets the generator state and playback time to the beginning.

#### `fill_mono_buffer(&mut self, buffer: &mut [f32], volume: f32) -> usize`
Fills a mono buffer for this instance and applies the specified volume. Returns the number of frames actually filled.

#### `fill_buffer(&mut self, buffer: &mut [f32], channels: u16) -> usize`
Fills an audio buffer for this instance. Returns the number of frames actually filled.

#### `check_and_clear_end_flag(&mut self) -> Option<LoopMode>`
Checks if this instance has reached the end of playback this iteration. Returns `true` if the end was reached, along with the loop mode for event determination. This is used by the mixer to emit appropriate events.
```

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

### New PlaybackInstance

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/playback/struct.PlaybackInstance.html

Creates a new PlaybackInstance. Requires a SourceId, audio data, source configuration, and loop mode.

```rust
pub fn new( audio_id: SourceId,
 audio_data: Arc<PetalSonicAudioData>,
 config: SourceConfig,
 loop_mode: LoopMode,
) -> Self
```

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

### LoadOptions::new() - Default Initialization

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/audio_data/struct.LoadOptions.html

Demonstrates creating a new LoadOptions instance with default settings. This is equivalent to calling LoadOptions::default().

```rust
pub fn new() -> Self {
    Self::default()
}
```

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

### Get Audio Duration

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/audio_data/struct.PetalSonicAudioData.html

Retrieves the total duration of the audio data.

```rust
pub fn duration(&self) -> Duration
```

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

### Create Spatial Source from Position with Volume (dB)

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/config/enum.SourceConfig.html

Creates a spatial audio source configuration from a position and volume in decibels, with an identity rotation. Useful for setting up spatial audio at a specific point.

```rust
pub fn spatial_from_position_with_volume_db( position: Vec3, volume_db: f32, ) -> Self
```

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

### File Metadata Retrieval with and_then

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/error/type.Result.html

Shows how to chain fallible operations like getting file metadata and its modification time. The `and_then` method is used to process the `Ok` value of the first operation.

```rust
use std::{io::ErrorKind, path::Path};

// Note: on Windows "/" maps to "C:\"
let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());
assert!(root_modified_time.is_ok());

let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());
assert!(should_fail.is_err());
assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);
```

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

### Load Audio with Default Settings

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/audio_data/index.html

Loads an audio file using the default settings. Ensure the audio file exists at the specified path.

```rust
let audio = PetalSonicAudioData::from_path("music.mp3")?;
```

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

### Get Listener Pose

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/world/struct.PetalSonicAudioListener.html

Retrieves the current position and orientation of the audio listener.

```rust
pub fn pose(&self) -> Pose
```

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

### Initialize SpatialProcessor

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/spatial/struct.SpatialProcessor.html

Creates a new spatial processor with specified audio settings and paths. Ensure correct sample rate, frame size, and HRTF paths are provided.

```rust
pub fn new(
  sample_rate: u32,
  frame_size: usize,
  distance_scaler: f32,
  hrtf_path: Option<&str>,
  steam_hrtf_path: Option<&str>,
  native_hrtf_path: Option<&str>,
  hrtf_gain: f32,
  hrtf_backend: HrtfBackend,
  direct_path_backend: DirectPathBackend,
  use_ambisonics: bool,
  ambisonics_backend: AmbisonicsBackend,
  batched_any_hit_ray_tracer: Option<Arc<dyn BatchedAnyHitRayTracer>>,
  batched_closest_hit_ray_tracer: Option<Arc<dyn BatchedClosestHitRayTracer>>,
) -> Result<Self>
```

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

### Get NativeHrtfTable Reference

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/spatial/struct.NativeHrtfRenderer.html

Returns an immutable reference to the NativeHrtfTable used by the renderer.

```rust
pub fn table(&self) -> &NativeHrtfTable
```

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

### Get Number of Channels

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/audio_data/struct.PetalSonicAudioData.html

Retrieves the number of audio channels in the loaded data.

```rust
pub fn channels(&self) -> u16
```

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

### Create Spatial Source (Unity Gain)

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/config/enum.SourceConfig.html

Creates a spatial audio source configuration with a given pose and default volume (0 dB).

```rust
pub fn spatial(pose: Pose) -> Self
```

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

### Get Sample Rate

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/audio_data/struct.PetalSonicAudioData.html

Retrieves the sample rate of the loaded audio data.

```rust
pub fn sample_rate(&self) -> u32
```

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

### Play from Beginning

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/playback/struct.PlaybackInstance.html

Resets the playback cursor to the beginning and then resumes playback.

```rust
pub fn play_from_beginning(&mut self)
```

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

### Create Spatial Source from Position with Volume (Linear)

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/config/enum.SourceConfig.html

Creates a spatial audio source configuration from a position and volume as linear gain, with an identity rotation. Ideal for simple spatial audio placement.

```rust
pub fn spatial_from_position_with_volume_linear( position: Vec3, volume: f32, ) -> Self
```

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

### Get Engine Configuration

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/engine/struct.PetalSonicEngine.html

Retrieves a reference to the engine's configuration, which is of type `PetalSonicWorldDesc`.

```rust
pub fn config(&self) -> &PetalSonicWorldDesc
```

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

### Create Spatial Source with Volume (dB)

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/config/enum.SourceConfig.html

Creates a spatial audio source configuration with a specified pose and volume in decibels. This is useful for precise spatial audio control.

```rust
pub fn spatial_with_volume_db(pose: Pose, volume_db: f32) -> Self
```

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

### PlaybackInfo::new

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/playback/struct.PlaybackInfo.html

Creates a new PlaybackInfo instance with the specified total frames and sample rate.

```APIDOC
## fn new(total_frames: usize, sample_rate: u32) -> Self

Creates a new PlaybackInfo instance.
```

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

### PetalSonicEngine::frames_processed

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/engine/struct.PetalSonicEngine.html

Returns the total number of audio frames processed by the engine since it started.

```APIDOC
## PetalSonicEngine::frames_processed

### Description
Get the number of audio frames processed since start.

### Returns
* `usize` - The total number of audio frames processed.
```

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

### Create New Audio Listener

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/world/struct.PetalSonicAudioListener.html

Creates a new audio listener with a specified initial pose.

```rust
pub fn new(pose: Pose) -> Self
```

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

### SpatialProcessor::new

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/spatial/struct.SpatialProcessor.html

Creates a new instance of the SpatialProcessor. This is the primary constructor for setting up spatial audio processing.

```APIDOC
## SpatialProcessor::new

### Description
Creates a new spatial processor.

### Arguments
* `sample_rate` (u32) - Sample rate for audio processing
* `frame_size` (usize) - Number of frames to process per call
* `distance_scaler` (f32) - Scale factor to convert game units to meters (default: 10.0)
* `hrtf_path` (Option<&str>) - Optional path to backend-specific HRTF data
* `steam_hrtf_path` (Option<&str>) - Optional path to Steam Audio specific HRTF data
* `native_hrtf_path` (Option<&str>) - Optional path to native HRTF data
* `hrtf_gain` (f32) - HRTF gain compensation in decibels (default: 0.0 dB = no change)
* `hrtf_backend` (HrtfBackend) - The HRTF backend to use
* `direct_path_backend` (DirectPathBackend) - The direct path backend to use
* `use_ambisonics` (bool) - Whether to use ambisonics
* `ambisonics_backend` (AmbisonicsBackend) - The ambisonics backend to use
* `batched_any_hit_ray_tracer` (Option<Arc<dyn BatchedAnyHitRayTracer>>) - Optional batched any-hit ray tracer
* `batched_closest_hit_ray_tracer` (Option<Arc<dyn BatchedClosestHitRayTracer>>) - Optional batched closest-hit ray tracer

### Returns
Result<Self>
```

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

### PartialEq Implementation for AudioOutputDeviceInfo

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/engine/struct.AudioOutputDeviceInfo.html

Enables comparison of two AudioOutputDeviceInfo instances for equality.

```rust
fn eq(&self, other: &AudioOutputDeviceInfo) -> bool
```

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

### Get Total Number of Frames

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/audio_data/struct.PetalSonicAudioData.html

Retrieves the total number of audio frames in the loaded data.

```rust
pub fn total_frames(&self) -> usize
```

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

### Instantiate and Load Audio with DefaultAudioLoader

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/audio_data/struct.DefaultAudioLoader.html

Instantiates the DefaultAudioLoader and uses it to load audio data from a specified file path with default options. Ensure the file path is valid and the audio format is supported.

```rust
use petalsonic_core::audio_data::{DefaultAudioLoader, AudioDataLoader, LoadOptions);

let loader = DefaultAudioLoader;
let audio_data = loader.load("path/to/audio.mp3", &LoadOptions::default())?;
```

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

### Get Source Sample Rate

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/audio_data/struct.BatchResampler.html

Retrieves the source (input) sample rate of the BatchResampler in Hz.

```rust
pub fn source_sample_rate(&self) -> u32
```

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

### mix_playback_instances_with_metrics

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/mixer/fn.mix_playback_instances_with_metrics.html

Mixes audio playback instances and returns timing metrics for profiling. This is an enhanced version of `mix_playback_instances`.

```APIDOC
## Function mix_playback_instances_with_metrics

### Description
Mixes playback instances with metrics for profiling. This function provides the same functionality as `mix_playback_instances` but additionally returns timing metrics essential for performance profiling.

### Signature
```rust
pub fn mix_playback_instances_with_metrics(
    world_buffer: &mut [f32],
    channels: u16,
    active_playback: &Arc<Mutex<HashMap<SourceId, PlaybackInstance>>>,
    spatial_processor: Option<&mut SpatialProcessor>,
) -> (MixResult, MixProfilingSummary)
```

### Parameters
* `world_buffer`: A mutable slice of f32 representing the audio buffer to mix into.
* `channels`: A u16 value indicating the number of audio channels.
* `active_playback`: An Arc<Mutex<HashMap<SourceId, PlaybackInstance>>> containing the active playback instances.
* `spatial_processor`: An optional mutable reference to a `SpatialProcessor` for spatial audio processing.

### Returns
A tuple containing:
* `MixResult`: The result of the mixing operation.
* `MixProfilingSummary`: A summary of timing metrics collected during the mixing process.
```

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

### Get Target Sample Rate

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/audio_data/struct.BatchResampler.html

Retrieves the target (output) sample rate of the BatchResampler in Hz.

```rust
pub fn target_sample_rate(&self) -> u32
```

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

### Any Trait Implementation

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/acoustics/struct.AcousticHit.html

Provides a method to get the TypeId of a value, useful for runtime type identification.

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

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

### Create Spatial Source with Volume (Linear)

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/config/enum.SourceConfig.html

Creates a spatial audio source configuration with a specified pose and volume as a linear gain factor. Use this for straightforward spatial audio adjustments.

```rust
pub fn spatial_with_volume_linear(pose: Pose, volume: f32) -> Self
```

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

### Create Spatial Source from Position

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/config/enum.SourceConfig.html

Creates a spatial audio source configuration using only a position, with an identity rotation and default volume.

```rust
pub fn spatial_from_position(position: Vec3) -> Self
```

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

### Get Direction Count of NativeHrtfTable

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/spatial/struct.NativeHrtfTable.html

Returns the total number of directions for which HRTF data is available in this table.

```rust
pub fn direction_count(&self) -> usize
```

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

### Get Volume (Backwards-Compatible)

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/config/enum.SourceConfig.html

Provides backwards-compatible access to the volume as linear gain. Equivalent to calling `volume_linear`.

```rust
pub fn volume(&self) -> f32
```

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

### Create New PetalSonicEngine

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/engine/struct.PetalSonicEngine.html

Initializes a new PetalSonicEngine with a specified description and world. This function returns a Result, indicating potential errors during creation.

```rust
pub fn new( desc: PetalSonicWorldDesc, world: Arc<PetalSonicWorld>, ) -> Result<Self>
```

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

### Get Interleaved Samples for a Frame Range

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/audio_data/struct.PetalSonicAudioData.html

Extracts interleaved audio samples for a specified range of frames.

```rust
pub fn frame_range(
 &self,
 start_frame: usize,
 end_frame: usize,
) -> Result<Vec<f32>>
```

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

### Get Total Number of Samples

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/audio_data/struct.PetalSonicAudioData.html

Retrieves the total number of audio samples (interleaved) in the loaded data.

```rust
pub fn len(&self) -> usize
```

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

### SpatialProcessor::ambisonics_backend

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/spatial/struct.SpatialProcessor.html

Retrieves the currently configured ambisonics backend.

```APIDOC
## SpatialProcessor::ambisonics_backend

### Description
Get the currently configured ambisonics backend.

### Returns
AmbisonicsBackend
```

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

### lerp

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/math/struct.Quat.html

Performs a linear interpolation between two quaternions. The interpolation factor `s` determines the blend between the start and end quaternions.

```APIDOC
## pub fn lerp(self, end: Quat, s: f32) -> Quat

### Description
Performs a linear interpolation between `self` and `rhs` based on the value `s`.
When `s` is `0.0`, the result will be equal to `self`. When `s` is `1.0`, the result will be equal to `rhs`.

### Parameters
* `end` (Quat) - The end quaternion.
* `s` (f32) - The interpolation factor, ranging from 0.0 to 1.0.

### Returns
* `Quat` - The interpolated quaternion.

### Panics
Will panic if `self` or `end` are not normalized when `glam_assert` is enabled.
```

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

### Configure Spatial Rendering

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/spatial/struct.SpatialProcessor.html

Sets up the spatial rendering pipeline, including HRTF, direct path, and ambisonics backends. This configures how spatial audio is processed.

```rust
pub fn set_spatial_rendering(
  &mut self,
  hrtf_backend: HrtfBackend,
  direct_path_backend: DirectPathBackend,
  use_ambisonics: bool,
  ambisonics_backend: AmbisonicsBackend,
) -> Result<()>
```

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

### Quat::from_rotation_arc

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/math/struct.Quat.html

Gets the minimal rotation to transform a 'from' vector to a 'to' vector. Rotates at most 180 degrees.

```APIDOC
## Quat::from_rotation_arc

### Description
Gets the minimal rotation for transforming `from` to `to`. The rotation is in the plane spanned by the two vectors. Will rotate at most 180 degrees.
The inputs must be unit vectors.
`from_rotation_arc(from, to) * from ≈ to`.
For near-singular cases (from≈to and from≈-to) the current implementation is only accurate to about 0.001 (for `f32`).

### Parameters
- **from** (Vec3) - The starting unit vector.
- **to** (Vec3) - The target unit vector.

### Panics
Will panic if `from` or `to` are not normalized when `glam_assert` is enabled.

### Returns
- Quat: The minimal rotation quaternion transforming `from` to `to`.
```

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

### mix_playback_instances_with_metrics

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/mixer/index.html

Similar to `mix_playback_instances`, this function mixes active playback instances and also returns timing metrics for profiling.

```APIDOC
## mix_playback_instances_with_metrics

### Description
Same as `mix_playback_instances` but also returns timing metrics used for profiling.

### Returns
- `MixResult`: Contains the number of frames and loop events.
- Timing metrics for profiling.
```

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

### Get Taps Count of NativeHrtfTable

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/spatial/struct.NativeHrtfTable.html

Returns the number of taps per ear in the HRIR filters for this HRTF table.

```rust
pub fn taps(&self) -> usize
```

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

### Clone Implementation for AudioOutputDeviceInfo

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/engine/struct.AudioOutputDeviceInfo.html

Provides functionality to create a duplicate of an AudioOutputDeviceInfo instance.

```rust
fn clone(&self) -> AudioOutputDeviceInfo
```

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

### Get Position of Spatial Source

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/config/enum.SourceConfig.html

Retrieves the 3D position if the SourceConfig is spatial. Returns None for non-spatial sources.

```rust
pub fn position(&self) -> Option<Vec3>
```

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

### Get Input Chunk Size

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/audio_data/struct.StreamingResampler.html

Retrieves the fixed number of frames the resampler expects as input per chunk.

```rust
pub fn input_chunk_size(&self) -> usize
```

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

### Load Audio from Path with Options

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/audio_data/struct.PetalSonicAudioData.html

Loads audio data from a file path with custom loading options, such as converting to mono. Uses the built-in Symphonia-based loader.

```rust
pub fn from_path_with_options(
 path: &str,
 options: &LoadOptions,
) -> Result<Arc<Self>>
```

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

### Create Non-Spatial Source (Unity Gain)

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/config/enum.SourceConfig.html

Creates a non-spatial audio source configuration with default volume (0 dB).

```rust
pub fn non_spatial() -> Self
```

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

### from_rotation_arc_2d

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/math/struct.Quat.html

Gets the minimal rotation for transforming `from` to `to` around the z-axis. Will rotate at most 180 degrees. Inputs must be unit vectors.

```APIDOC
## pub fn from_rotation_arc_2d(from: Vec2, to: Vec2) -> Quat

### Description
Gets the minimal rotation for transforming `from` to `to`. The resulting rotation is around the z axis. Will rotate at most 180 degrees.

### Parameters
#### Path Parameters
- **from** (Vec2) - Required - The starting 2D vector.
- **to** (Vec2) - Required - The target 2D vector.

### Returns
- **Quat** - The minimal rotation quaternion.
```

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

### Get Specific Direction from NativeHrtfTable

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/spatial/struct.NativeHrtfTable.html

Retrieves a reference to the NativeHrtfDirection at the specified index, if it exists. Returns None if the index is out of bounds.

```rust
pub fn direction(&self, index: usize) -> Option<&NativeHrtfDirection>
```

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

### Create New StreamingResampler

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/audio_data/struct.StreamingResampler.html

Initializes a new StreamingResampler instance. Configure it with source and target sample rates, channel count, input frame size, and an optional resampler type.

```rust
pub fn new( source_sample_rate: u32,
 target_sample_rate: u32,
 channels: u16,
 input_frames: usize,
 resampler_type: Option<ResamplerType>,
) -> Result<Self>
```

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

### LoadOptions::convert_to_mono() - Method Chaining

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/audio_data/struct.LoadOptions.html

Shows how to set the mono conversion option for LoadOptions using method chaining. Accepts ConvertToMono::Original or ConvertToMono::ForceMono.

```rust
pub fn convert_to_mono(self, convert: ConvertToMono) -> Self {
    self.convert_to_mono = convert;
    self
}
```

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

### Collecting Results with checked_add

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/error/type.Result.html

Example of using collect on an iterator of Results, where each element is checked for overflow. The first overflow causes an Err.

```rust
let v = vec![1, 2];
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|
    x.checked_add(1).ok_or("Overflow!")
).collect();
assert_eq!(res, Ok(vec![2, 3]));
```

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

### SourceConfig::spatial_from_position_with_volume_db

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/config/enum.SourceConfig.html

Creates a spatial audio source configuration from a position and volume in decibels, with an identity rotation.

```APIDOC
## SourceConfig::spatial_from_position_with_volume_db

### Description
Creates a spatial source configuration from a position and volume in decibels (with identity rotation).

### Method
```rust
pub fn spatial_from_position_with_volume_db(position: Vec3, volume_db: f32) -> Self
```

### Parameters
#### Query Parameters
- **position** (Vec3) - Required - The 3D position of the audio source.
- **volume_db** (f32) - Required - Volume in decibels relative to unity.

### Returns
- `Self`: A `SourceConfig::Spatial` variant with the specified `position`, identity rotation, and `volume_db`.
```

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

### Get Frame Size

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/spatial/struct.SpatialProcessor.html

Returns the configured frame size for audio processing, which dictates the number of frames processed per call.

```rust
pub fn frame_size(&self) -> usize
```

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

### Get Pose of Spatial Source

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/config/enum.SourceConfig.html

Retrieves the 3D pose (position and orientation) if the SourceConfig is spatial. Returns None for non-spatial sources.

```rust
pub fn pose(&self) -> Option<Pose>
```

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

### Load Audio from Path (Default Loader)

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/audio_data/struct.PetalSonicAudioData.html

Loads audio data from a file path using the default Symphonia-based loader with default options. Supports common audio formats like WAV, MP3, FLAC, and OGG.

```rust
pub fn from_path(path: &str) -> Result<Arc<Self>>
```

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

### AcousticRay Struct Definition

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/acoustics/struct.AcousticRay.html

Defines the structure for an `AcousticRay`, which holds a starting point and a direction in world space. This is fundamental for raycasting in acoustic simulations.

```rust
pub struct AcousticRay {
    pub origin: Vec3,
    pub direction: Vec3,
}
```

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

### ProceduralAudioFactory create Method

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/procedural/trait.ProceduralAudioFactory.html

The required method for the ProceduralAudioFactory trait. It is responsible for creating a new instance of a procedural audio source at the specified sample rate.

```rust
fn create(&self, sample_rate: u32) -> Box<dyn ProceduralAudioSource>
```

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

### PetalSonicEngine::available_output_devices

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/engine/struct.PetalSonicEngine.html

Retrieves a list of available audio output devices.

```APIDOC
## PetalSonicEngine::available_output_devices

### Description
Get a list of available audio output devices.

### Returns
* `Result<Vec<AudioOutputDeviceInfo>>` - A vector of audio output device information, or an error if retrieval fails.
```

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

### Get Volume in Decibels

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/config/enum.SourceConfig.html

Returns the volume of the audio source in decibels, applicable to both spatial and non-spatial configurations. Use this for precise volume adjustments.

```rust
pub fn volume_db(&self) -> f32
```

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

### ProceduralAudioFactory Implementation for Fn

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/procedural/trait.ProceduralAudioFactory.html

An implementation of ProceduralAudioFactory for closures that match the required signature. This allows functions or closures to be used directly as procedural audio factories.

```rust
impl<F> ProceduralAudioFactory for F
where F: Fn(u32) -> Box<dyn ProceduralAudioSource> + Send + Sync,
```

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

### Get Direct Occlusion Debug Snapshot

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/engine/struct.PetalSonicEngine.html

Provides a debug snapshot for direct occlusion, if available. This is an optional value, returning `None` if no snapshot is available.

```rust
pub fn direct_occlusion_debug_snapshot( &self, ) -> Option<DirectOcclusionDebugSnapshot>
```

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

### LoadOptions Struct Definition

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/audio_data/struct.LoadOptions.html

Defines the structure for audio loading options, including a field for mono conversion.

```rust
pub struct LoadOptions {
    pub convert_to_mono: ConvertToMono,
}
```

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

### SourceConfig::spatial_with_volume_db

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/config/enum.SourceConfig.html

Creates a spatial audio source configuration with a specified pose and volume in decibels.

```APIDOC
## SourceConfig::spatial_with_volume_db

### Description
Creates a spatial source configuration with pose and volume in decibels.
`0.0` dB is unity, negative values attenuate, positive values amplify.

### Method
```rust
pub fn spatial_with_volume_db(pose: Pose, volume_db: f32) -> Self
```

### Parameters
#### Query Parameters
- **pose** (Pose) - Required - The 3D pose (position and orientation) of the audio source.
- **volume_db** (f32) - Required - Volume in decibels relative to unity.

### Returns
- `Self`: A `SourceConfig::Spatial` variant with the specified `pose` and `volume_db`.
```

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

### SourceConfig::spatial_from_position_with_volume_linear

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/config/enum.SourceConfig.html

Creates a spatial audio source configuration from a position and volume as linear gain, with an identity rotation.

```APIDOC
## SourceConfig::spatial_from_position_with_volume_linear

### Description
Creates a spatial source configuration from a position and volume as linear gain (with identity rotation).

### Method
```rust
pub fn spatial_from_position_with_volume_linear(position: Vec3, volume: f32) -> Self
```

### Parameters
#### Query Parameters
- **position** (Vec3) - Required - The 3D position of the audio source.
- **volume** (f32) - Required - Volume as linear gain.

### Returns
- `Self`: A `SourceConfig::Spatial` variant with the specified `position`, identity rotation, and linear volume.
```

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

### Termination for Result<T, E>

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/error/type.Result.html

Implementation of the Termination trait for Result. The `report` function is used to get the representation of the value as a status code, which is returned to the operating system.

```rust
impl<T, E> Termination for Result<T, E>
where T: Termination,
      E: Debug,
```

```rust
fn report(self) -> ExitCode
```

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

### Unwrap Err value

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/error/type.Result.html

Use `unwrap_err()` to get the contained `Err` value. This method will panic if the `Result` is an `Ok`, using the `Ok` value as the panic message.

```rust
let x: Result<u32, &str> = Ok(2);
x.unwrap_err(); // panics with `2`
```

```rust
let x: Result<u32, &str> = Err("emergency failure");
assert_eq!(x.unwrap_err(), "emergency failure");
```

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

### Unwrap Ok value

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/error/type.Result.html

Use `unwrap()` to get the contained `Ok` value. This method will panic if the `Result` is an `Err`. It is generally discouraged in favor of safer methods.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.unwrap(), 2);
```

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

### SourceConfig::spatial

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/config/enum.SourceConfig.html

Creates a spatial audio source configuration with a given pose and default volume (0 dB).

```APIDOC
## SourceConfig::spatial

### Description
Creates a spatial source configuration with the given pose at 0 dB (unity gain).

### Method
```rust
pub fn spatial(pose: Pose) -> Self
```

### Parameters
#### Query Parameters
- **pose** (Pose) - Required - The 3D pose (position and orientation) of the audio source.

### Returns
- `Self`: A `SourceConfig::Spatial` variant with the specified `pose` and `volume_db` set to 0.0.
```

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

### Clone Implementation for PlaybackInfo

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/playback/struct.PlaybackInfo.html

Provides methods to duplicate and copy PlaybackInfo instances. This is useful for maintaining independent playback states.

```rust
fn clone(&self) -> PlaybackInfo
```

```rust
fn clone_from(&mut self, source: &Self)
```

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

### Get references to Result contents

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/error/type.Result.html

Use `as_ref` to convert a `&Result<T, E>` into a `Result<&T, &E>`. This allows borrowing the contents without consuming the original Result.

```Rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.as_ref(), Ok(&2));

let x: Result<u32, &str> = Err("Error");
assert_eq!(x.as_ref(), Err(&"Error"));
```

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

### SpatialProcessor::direct_path_backend

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/spatial/struct.SpatialProcessor.html

Retrieves the currently configured direct path backend.

```APIDOC
## SpatialProcessor::direct_path_backend

### Description
Get the currently configured direct path backend.

### Returns
DirectPathBackend
```

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

### Pose::new Constructor

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/math/struct.Pose.html

Creates a new Pose instance with the specified position and rotation.

```rust
pub fn new(position: Vec3, rotation: Quat) -> Self
```

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

### Unwrap or return default value

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/error/type.Result.html

Use `unwrap_or_default()` to get the contained `Ok` value or a default value if the `Result` is an `Err`. This requires the type `T` to implement the `Default` trait.

```rust
let good_year_from_input = "1909";
let bad_year_from_input = "190blarg";
let good_year = good_year_from_input.parse().unwrap_or_default();
let bad_year = bad_year_from_input.parse().unwrap_or_default();

assert_eq!(1909, good_year);
assert_eq!(0, bad_year);
```

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

### Get mutable references to Result contents

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/error/type.Result.html

Use `as_mut` to convert a `&mut Result<T, E>` into a `Result<&mut T, &mut E>`. This allows mutable borrowing of the contents.

```Rust
fn mutate(r: &mut Result<i32, i32>) {
    match r.as_mut() {
        Ok(v) => *v = 42,
        Err(e) => *e = 0,
    }
}

let mut x: Result<i32, i32> = Ok(2);
mutate(&mut x);
assert_eq!(x.unwrap(), 42);

let mut x: Result<i32, i32> = Err(13);
mutate(&mut x);
assert_eq!(x.unwrap_err(), 0);
```

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

### Create Non-Spatial Source with Volume (dB)

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/config/enum.SourceConfig.html

Creates a non-spatial audio source configuration with a specified volume in decibels. Use this for precise volume control.

```rust
pub fn non_spatial_with_volume_db(volume_db: f32) -> Self
```

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

### Set Spatial Rendering Parameters

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/engine/struct.PetalSonicEngine.html

Configures spatial rendering, including HRTF, direct path, ambisonics backends, and whether to use ambisonics.

```rust
pub fn set_spatial_rendering( &mut self, hrtf_backend: HrtfBackend, direct_path_backend: DirectPathBackend, use_ambisonics: bool, ambisonics_backend: AmbisonicsBackend, ) -> Result<()>
```

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

### from_rotation_arc_colinear

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/math/struct.Quat.html

Gets the minimal rotation for transforming `from` to either `to` or `-to`. The rotation is in the plane spanned by the two vectors and will rotate at most 90 degrees. Inputs must be unit vectors.

```APIDOC
## pub fn from_rotation_arc_colinear(from: Vec3, to: Vec3) -> Quat

### Description
Gets the minimal rotation for transforming `from` to either `to` or `-to`. This means that the resulting quaternion will rotate `from` so that it is colinear with `to`. The rotation is in the plane spanned by the two vectors. Will rotate at most 90 degrees.

### Parameters
#### Path Parameters
- **from** (Vec3) - Required - The starting vector.
- **to** (Vec3) - Required - The target vector.

### Returns
- **Quat** - The minimal rotation quaternion.
```

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

### Get Volume as Linear Gain

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/config/enum.SourceConfig.html

Returns the volume of the audio source as a linear gain factor, applicable to both spatial and non-spatial configurations. Use this for simple volume scaling.

```rust
pub fn volume_linear(&self) -> f32
```

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

### PartialEq Implementation for AcousticHit

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/acoustics/struct.AcousticHit.html

Allows for equality comparison between AcousticHit instances.

```rust
fn eq(&self, other: &AcousticHit) -> bool
```

```rust
fn ne(&self, other: &Rhs) -> bool
```

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

### SpatialProcessor::hrtf_backend

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/spatial/struct.SpatialProcessor.html

Retrieves the currently configured HRTF backend.

```APIDOC
## SpatialProcessor::hrtf_backend

### Description
Get the currently configured HRTF backend.

### Returns
HrtfBackend
```

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

### SourceConfig::pose

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/config/enum.SourceConfig.html

Retrieves the pose of the audio source if it is spatial.

```APIDOC
## SourceConfig::pose

### Description
Returns the pose if this is a spatial source.

### Method
```rust
pub fn pose(&self) -> Option<Pose>
```

### Returns
- `Option<Pose>`: `Some(Pose)` if the source is spatial, `None` otherwise.
```

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

### Get Native Ambisonics Channel Count

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/spatial/fn.native_ambisonics_channel_count.html

Calculates the number of ACN channels for a specified Ambisonics order. This is useful for determining the correct buffer sizes or channel configurations for Ambisonics audio processing.

```rust
pub fn native_ambisonics_channel_count(order: u32) -> Result<usize>
```

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

### Create Effects for Source

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/spatial/struct.SpatialProcessor.html

Initializes the necessary audio effects for a given spatial source ID. This must be called before processing audio for a new source.

```rust
pub fn create_effects_for_source(&mut self, source_id: SourceId) -> Result<()>
```

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

### Register Audio Data

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/world/struct.PetalSonicWorld.html

Registers audio data in the world's internal storage, preparing it for playback. The audio data is automatically resampled if needed. Call `play()` with the returned SourceId to start playback.

```rust
pub fn register_audio( &self, audio_data: Arc<PetalSonicAudioData>, config: SourceConfig, ) -> Result<SourceId>
```

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

### Get Command Receiver

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/world/struct.PetalSonicWorld.html

Returns a reference to the command receiver for the audio engine. This receiver is used by the audio engine thread to poll for playback commands sent from the main thread. This method is primarily used internally when initializing the audio engine.

```rust
pub fn command_receiver(&self) -> &Receiver<PlaybackCommand>
```

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

### CloneToUninit Trait Implementation (Nightly)

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/acoustics/struct.AcousticHit.html

An experimental nightly-only API for performing copy-assignment to uninitialized memory.

```rust
unsafe fn clone_to_uninit(&self, dest: *mut u8)
```

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

### PartialEq Implementation for Pose

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/math/struct.Pose.html

Provides methods for comparing two Pose instances for equality.

```rust
fn eq(&self, other: &Pose) -> bool
```

```rust
fn ne(&self, other: &Rhs) -> bool
```

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

### SourceConfig::spatial_with_volume_linear

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/config/enum.SourceConfig.html

Creates a spatial audio source configuration with a specified pose and volume as linear gain.

```APIDOC
## SourceConfig::spatial_with_volume_linear

### Description
Creates a spatial source configuration with pose and volume as linear gain.
`1.0` is unity, `0.0` is silent, values > 1.0 amplify.

### Method
```rust
pub fn spatial_with_volume_linear(pose: Pose, volume: f32) -> Self
```

### Parameters
#### Query Parameters
- **pose** (Pose) - Required - The 3D pose (position and orientation) of the audio source.
- **volume** (f32) - Required - Volume as linear gain.

### Returns
- `Self`: A `SourceConfig::Spatial` variant with the specified `pose` and linear volume.
```

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

### Load Audio with Mono Conversion Option

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/audio_data/index.html

Loads an audio file and forces conversion to mono. This is useful for applications that only require mono audio.

```rust
let options = LoadOptions::new()
    .convert_to_mono(ConvertToMono::ForceMono);
let audio = PetalSonicAudioData::from_path_with_options("music.mp3", &options)?;
```

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

### Process Spatial Sources with Metrics

Source: https://docs.rs/petalsonic/0.5.0/petalsonic/spatial/struct.SpatialProcessor.html

Similar to `process_spatial_sources`, but also returns detailed timing metrics for the spatial processing. Useful for performance analysis.

```rust
pub fn process_spatial_sources_with_metrics(
  &mut self,
  instances: &mut [(SourceId, &mut PlaybackInstance)],
  output_buffer: &mut [f32],
) -> Result<SpatialProcessingSummary>
```