Struct libaudioverse::nodes::environment_node::EnvironmentNode

pub struct EnvironmentNode { /* fields omitted */ }

This is the entry point to the 3D simulation capabilities. Environment nodes hold the information needed to pan sources, as well as acting as an aggregate output for all sources that use this environment. Note that the various properties for default values do not affect already created sources. It is best to configure these first. Any functionality to change a property on all sources needs to be implemented by the app, and is not offered by Libaudioverse.

This node has no inputs.

Outputs:

index	channels	description
0	Depends on the output_channels property.	The output of the 3D environment.

Methods

impl EnvironmentNode

fn new(server: &Server, hrtf_path: &CString) -> Result<EnvironmentNode>

Creates a new environment node.

fn default_reverb_distance(&self) -> FloatProperty

Returns the default_reverb_distance property.

Range: [0.0, INFINITY]

Default value: 75.0

The distance at which a source will be heard only in the reverb. See documentation on the SourceNode node for a specific explanation. By default, sources get the value of this property from the environment. To control this property on a per-source basis, set Lav_SOURCE_CONTROL_REVERB to true on the source.

fn default_size(&self) -> FloatProperty

Returns the default_size property.

Range: [0.0, INFINITY]

Default value: 0.0

The default size for new sources. Sources aare approximated as spheres, with 0 being the special case of a point source. Size is used to determine the listener’s distance from a source.

fn distance_model(&self) -> DistanceModelProperty

Returns the distance_model property.

Range: a value from the DistanceModel enumeration

Default value: DistanceModel::Linear

Distance models control how quickly sources get quieter as they move away from the listener. By default, sources are configured to delegate to the environment when looking for values to use for the distance model parameters. This behavior may be changed by setting Lav_SOURCE_CONTROL_DISTANCE_MODEL to true.

fn max_distance(&self) -> FloatProperty

Returns the max_distance property.

Range: [0.0, INFINITY]

Default value: 150.0

The maximum distance at which a source is audible. Consider this property to be in meters. By default, sources are configured to delegate to the environment when looking for values to use for the distance model parameters. This behavior may be changed by setting Lav_SOURCE_CONTROL_DISTANCE_MODEL to true.

fn max_reverb_level(&self) -> FloatProperty

Returns the max_reverb_level property.

Range: [0.0, 1.0]

Default value: 0.6

The maximum amount of audio to be diverted to reverb sends, if any. Behavior is undefined if this property is ever less than Lav_ENVIRONMENT_MIN_REVERB_LEVEL. By default, sources look to their environmlent for the value of this property. If you wish to set it on a per-source basis, set Lav_SOURCE_CONTROL_REVERB to true on the source.

fn min_reverb_level(&self) -> FloatProperty

Returns the min_reverb_level property.

Range: [0.0, 1.0]

Default value: 0.15

The minimum reverb level allowed. if a send is configured to be a reverb send, this is the minimum amount of audio that will be diverted to it. Behavior is undefined if this property is ever greater than the value of Lav_ENVIRONMENT_MAX_REVERB_LEVEL. By default, sources look to their environment for the value of this property. If you wish to set it on a per-source basis, set Lav_SOURCE_CONTROL_REVERB to true on the source.

fn orientation(&self) -> Float6Property

Returns the orientation property.

Default Value: [0.0, 0.0, -1.0, 0.0, 1.0, 0.0]

The orientation of the listener. The first three elements are a vector representing the direction in which the listener is looking and the second 3 a vector representing the direction in which a rod pointing out of the top of the listener’s head would be pointing.

This property packs these vectors because they must never be modified separately. Additionally, they should both be unit vectors and must also be orthoganal.

the default situates the listener such that positive x is right, positive y is up, and positive z is behind the listener. The setting (0, 1, 0, 0, 0, 1) will situate the listener such that positive x is right and positive y is forward. For those not familiar with trigonometry and who wish to consider positive x east and positivve y north, the following formula will turn the listener to face a scertain direction specified in radians clockwise of north: (sin(theta), cos(theta), 0, 0, 0, 1). As usual, note that radians=degrees*PI/180.

fn output_channels(&self) -> IntProperty

Returns the output_channels property.

Range: [0, 8]

Default value: 2

Environments are not smart enough to determine the number of channels their output needs to have. If you are using something greater than stereo, i.e. 5.1, you need to change this property. The specific issue solved by this property is the case in which one source is set to something different than all others, or where the app changes the panning strategies of sources after creation. Values besides 2, 4, 6, or 8 do not usually have much meaning.

fn panning_strategy(&self) -> PanningStrategyProperty

Returns the panning_strategy property.

Range: a value from the PanningStrategy enumeration

Default value: PanningStrategy::Stereo

The panning strategy for any source configured to delegate to the environment. All new sources delegate to the environment by default. If you want to change this property for a specific source, set Lav_SOURCE_CONTROL_PANNING on the source to true.

fn position(&self) -> Float3Property

Returns the position property.

Default value: [0.0, 0.0, 0.0]

The position of the listener, in world coordinates.

fn play_async(
    &self,
    buffer: &Buffer,
    x: f32,
    y: f32,
    z: f32,
    is_dry: bool
) -> Result<()>

Play a buffer, using the specified position and the currently set defaults on the world for distance model and panning strategy. This is the same as creating a buffer and a source, but Libaudioverse retains control of these objects. When the buffer finishes playing, the source is automatically disposed of. If is_dry is true, we avoid sending to the effect sends configured as defaults.

Trait Implementations

impl Node for EnvironmentNode

fn connect(&self, output: i32, destination: &Node, input: i32) -> Result<()>

Connect the specified output of the specified node to the specified input of the specified node. It is an error if this would cause a cycle in the graph of nodes.

fn connect_property(
    &self,
    output: i32,
    destination: &Node,
    slot: i32
) -> Result<()>

Connect a node’s output to an automatable property.

fn connect_server(&self, output: i32) -> Result<()>

Connect the specified output of the specified node to the server’s input. Any node which is connected directly or indirectly to the server will remain alive even if your program lets go of it. For more details on the subject of node lifetimes, see the Libaudioverse manual.

fn disconnect(&self, output: i32, destination: &Node, input: i32) -> Result<()>

Disconnect the output of the specified node.

fn get_input_connection_count(&self) -> Result<u32>

Get the number of inputs this node has.

fn get_output_connection_count(&self) -> Result<u32>

Get the number of outputs this node has.

fn isolate(&self) -> Result<()>

Equivalent to disconnecting all of the outputs of this node. After a call to isolate, this node will no longer be affecting audio in any way.

fn reset(&self) -> Result<()>

Reset a node. What this means depends on the node in question. Properties are not touched by node resetting.

fn add(&self) -> FloatProperty

Returns the add property.

fn mul(&self) -> FloatProperty

Returns the mul property.

fn state(&self) -> NodeStateProperty

Returns the state property.