kira 0.12.0

Expressive audio library for games
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126

use std::sync::{
	Arc,
	atomic::{AtomicU32, Ordering},
};

use crate::Frame;

use super::resources::Resources;

#[derive(Debug)]
pub(crate) struct RendererShared {
	pub(crate) sample_rate: AtomicU32,
}

impl RendererShared {
	#[must_use]
	pub fn new(sample_rate: u32) -> Self {
		Self {
			sample_rate: AtomicU32::new(sample_rate),
		}
	}
}

/// Produces [`Frame`]s of audio data to be consumed by a
/// low-level audio API.
///
/// You will probably not need to interact with [`Renderer`]s
/// directly unless you're writing a [`Backend`](super::Backend).
pub struct Renderer {
	dt: f64,
	shared: Arc<RendererShared>,
	resources: Resources,
	internal_buffer_size: usize,
	temp_buffer: Vec<Frame>,
}

impl Renderer {
	#[must_use]
	pub(crate) fn new(
		shared: Arc<RendererShared>,
		internal_buffer_size: usize,
		resources: Resources,
	) -> Self {
		Self {
			dt: 1.0 / shared.sample_rate.load(Ordering::SeqCst) as f64,
			shared,
			resources,
			internal_buffer_size,
			temp_buffer: vec![Frame::ZERO; internal_buffer_size],
		}
	}

	/// Called by the backend when the sample rate of the
	/// audio output changes.
	pub fn on_change_sample_rate(&mut self, sample_rate: u32) {
		self.dt = 1.0 / sample_rate as f64;
		self.shared.sample_rate.store(sample_rate, Ordering::SeqCst);
		self.resources.mixer.on_change_sample_rate(sample_rate);
	}

	/// Called by the backend when it's time to process
	/// a new batch of samples.
	pub fn on_start_processing(&mut self) {
		self.resources.mixer.on_start_processing();
		self.resources.clocks.on_start_processing();
		self.resources.listeners.on_start_processing();
		self.resources.modulators.on_start_processing();
	}

	/// Produces the next [`Frame`]s of audio.
	pub fn process(&mut self, out: &mut [f32], num_channels: u16) {
		for chunk in out.chunks_mut(self.internal_buffer_size * num_channels as usize) {
			self.process_chunk(chunk, num_channels);
		}
	}

	fn process_chunk(&mut self, chunk: &mut [f32], num_channels: u16) {
		let num_frames = chunk.len() / num_channels as usize;

		self.resources.modulators.process(
			self.dt * num_frames as f64,
			&self.resources.clocks,
			&self.resources.listeners,
		);
		self.resources.clocks.update(
			self.dt * num_frames as f64,
			&self.resources.modulators,
			&self.resources.listeners,
		);
		self.resources.listeners.update(
			self.dt * num_frames as f64,
			&self.resources.clocks,
			&self.resources.modulators,
		);

		self.resources.mixer.process(
			&mut self.temp_buffer[..num_frames],
			self.dt,
			&self.resources.clocks,
			&self.resources.modulators,
			&self.resources.listeners,
		);

		// convert from frames to requested number of channels
		for (i, channels) in chunk.chunks_mut(num_channels.into()).enumerate() {
			let mut frame = self.temp_buffer[i];
			frame.left = frame.left.clamp(-1.0, 1.0);
			frame.right = frame.right.clamp(-1.0, 1.0);
			if num_channels == 1 {
				channels[0] = (frame.left + frame.right) / 2.0;
			} else {
				channels[0] = frame.left;
				channels[1] = frame.right;
				/*
					if there's more channels, send silence to them. if we don't,
					we might get bad sounds outputted to those channels.
					(https://github.com/tesselode/kira/issues/50)
				*/
				for channel in channels.iter_mut().skip(2) {
					*channel = 0.0;
				}
			}
		}
		self.temp_buffer.fill(Frame::ZERO);
	}
}