alex/agb
1
0
Fork 0
mirror of https://github.com/italicsjenga/agb.git synced 2024-10-17 23:51:36 +11:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #250 from gwilymk/docs-for-mixer

Browse source 
Docs for mixer
This commit is contained in:
Gwilym Kuiper 2022-07-12 13:54:43 +01:00 committed by GitHub
parent 4a21cb0768 4c63058ba0
commit a01c0f9e4e
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 360 additions and 13 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

14
agb/examples/mixer_basic.rs
View file

@ -4,7 +4,7 @@
use agb::fixnum::Num;
use agb::input::{Button, ButtonController, Tri};
use agb::sound::mixer::SoundChannel;
use agb::{include_wav, Gba};
use agb::{include_wav, Gba, fixnum::num};
// Music - "Dead Code" by Josh Woodward, free download at http://joshwoodward.com
const DEAD_CODE: &[u8] = include_wav!("examples/JoshWoodward-DeadCode.wav");
@ -25,26 +25,26 @@ fn main(mut gba: Gba) -> ! {
{
if let Some(channel) = mixer.channel(&channel_id) {
let half: Num<i16, 4> = Num::new(1) / 2;
let half_usize: Num<usize, 8> = Num::new(1) / 2;
let half: Num<i16, 4> = num!(0.5);
let half_usize: Num<usize, 8> = num!(0.5);
match input.x_tri() {
Tri::Negative => channel.panning(-half),
Tri::Zero => channel.panning(0.into()),
Tri::Zero => channel.panning(0),
Tri::Positive => channel.panning(half),
};
match input.y_tri() {
Tri::Negative => channel.playback(half_usize.change_base() + 1),
Tri::Zero => channel.playback(1.into()),
Tri::Zero => channel.playback(1),
Tri::Positive => channel.playback(half_usize),
};
if input.is_pressed(Button::L) {
channel.volume(half);
} else if input.is_pressed(Button::R) {
channel.volume(20.into()); // intentionally introduce clipping
channel.volume(20); // intentionally introduce clipping
} else {
channel.volume(1.into());
channel.volume(1);
}
}
}

218
agb/src/sound/mixer/mod.rs
View file

@ -1,3 +1,101 @@
#![deny(missing_docs)]
//! # agb mixer
//!
//! The agb software mixer allows for high performance playing of background music
//! and sound effects.
//!
//! Most games will need some form of sound effects or background music. The GBA has
//! no hardware sound mixer, so in order to play more than one sound at once, you
//! have to use a software mixer.
//!
//! agb's software mixer allows for up to 8 simultaneous sounds played at once at
//! various speeds and volumes.
//!
//! # Concepts
//!
//! The mixer runs at a fixed frequency which is determined at compile time by enabling
//! certain features within the crate. The following features are currently available:
//!
//! | Feature | Frequency |
//! |---------|-----------|
//! | none | 10512Hz |
//! | freq18157 | 18157Hz |
//! | freq32768[^32768Hz] | 32768Hz |
//!
//! All wav files you use within your application / game must use this _exact_ frequency.
//! You will get a compile error if you use the incorrect frequency for your file.
//!
//! The mixer can play both mono and stereo sounds, but only mono sound effects can have
//! effects applied to them (such as changing the speed at which they play or the panning).
//! Since the sound mixer runs in software, you must do some sound mixing every frame.
//!
//! ## Creating the mixer
//!
//! To create a sound mixer, you will need to get it out of the [`Gba`](crate::Gba) struct
//! as follows:
//!
//! ```
//! let mut mixer = gba.mixer.mixer();
//! mixer.enable();
//! ```
//!
//! ## Doing the per-frame work
//!
//! Then, you have a choice of whether you want to use interrupts or do the buffer swapping
//! yourself after a vblank interrupt. If you are using 32768Hz as the frequency of your
//! files, you _must_ use the interrupt version.
//!
//! Without interrupts:
//!
//! ```
//! // Somewhere in your main loop:
//! mixer.frame();
//! vblank.wait_for_vblank();
//! mixer.after_vblank();
//! ```
//!
//! Or with interrupts:
//!
//! ```
//! // outside your main loop, close to initialisation
//! let _mixer_interrupt = mixer.setup_interrupt_handler();
//!
//! // inside your main loop
//! mixer.frame();
//! vblank.wait_for_vblank();
//! ```
//!
//! Despite being high performance, the mixer still takes a sizable portion of CPU time (6-10%
//! depending on number of channels and frequency) to do the per-frame tasks, so should be done
//! towards the end of the frame time (just before waiting for vblank) in order to give as much
//! time during vblank as possible for rendering related tasks.
//!
//! ## Loading a sample
//!
//! To load a sample, you must have it in `wav` format (both stereo and mono work) at exactly the
//! selected frequency based on the features enabled in the agb crate.
//!
//! Use the [`include_wav!`](crate::include_wav) macro in order to load the sound. This will produce
//! an error if your wav file is of the wrong frequency.
//!
//! ```
//! // Outside your main function in global scope:
//! const MY_CRAZY_SOUND: &[u8] = include_wav!("sfx/my_crazy_sound.wav");
//!
//! // Then to play the sound:
//! let mut channel = SoundChannel::new(MY_CRAZY_SOUND);
//! channel.stereo();
//! let _ = mixer.play_sound(channel); // we don't mind if this sound doesn't actually play
//! ```
//!
//! See the [`SoundChannel`] struct for more details on how you can configure the sounds to play.
//!
//! Once you have run [`play_sound`](Mixer::play_sound), the mixer will play that sound until
//! it has finished.
//!
//! [^32768Hz]: You must use interrupts when using 32768Hz
mod hw;
mod sw_mixer;
@ -6,6 +104,8 @@ pub use sw_mixer::Mixer;
use crate::fixnum::Num;
/// Controls access to the mixer and the underlying hardware it uses. A zero sized type that
/// ensures that mixer access is exclusive.
#[non_exhaustive]
pub struct MixerController {}
@ -14,6 +114,7 @@ impl MixerController {
MixerController {}
}
/// Get a [`Mixer`] in order to start producing sounds.
pub fn mixer(&mut self) -> Mixer {
Mixer::new()
}
@ -25,6 +126,52 @@ enum SoundPriority {
Low,
}
/// Describes one sound which should be playing. This could be a sound effect or
/// the background music. Use the factory methods on this to modify how it is played.
///
/// You _must_ set stereo sounds with [`.stereo()`](SoundChannel::stereo) or it will play as mono and at
/// half the intended speed.
///
/// SoundChannels are very cheap to create, so don't worry about creating a brand new
/// one for every single sound you want to play.
///
/// SoundChannels can be either 'low priority' or 'high priority'. A high priority
/// sound channel will override 'low priority' sound channels which are already playing
/// to ensure that it is always running. A 'low priority' sound channel will not override
/// any other channel.
///
/// This is because you can only play up to 8 channels at once, and so high priority channels
/// are prioritised over low priority channels to ensure that sounds that you always want
/// playing will always play.
///
/// # Example
///
/// ## Playing background music (stereo)
///
/// Background music is generally considered 'high priority' because you likely want it to
/// play regardless of whether you have lots of sound effects playing. You create a high
/// priority sound channel using [`new_high_priority`](SoundChannel::new_high_priority).
///
/// ```
/// // in global scope:
/// const MY_BGM: [u8] = include_wav!("sfx/my_bgm.wav");
///
/// // somewhere in code
/// let mut bgm = SoundChannel::new_high_priority(MY_BGM);
/// bgm.stereo().should_loop();
/// let _ = mixer.play_sound(bgm);
/// ```
///
/// ## Playing a sound effect
///
/// ```
/// // in global scope:
/// const JUMP_SOUND: [u8] = include_wav!("sfx/jump_sound.wav");
///
/// // somewhere in code
/// let jump_sound = SoundChannel::new(MY_JUMP_SOUND);
/// let _ = mixer.play_sound(jump_sound);
/// ```
pub struct SoundChannel {
data: &'static [u8],
pos: Num<usize, 8>,
@ -42,6 +189,23 @@ pub struct SoundChannel {
}
impl SoundChannel {
/// Creates a new low priority [`SoundChannel`].
///
/// A low priority sound channel will be overridden by a high priority one if
/// the mixer runs out of channels.
///
/// Low priority sound channels are intended for sound effects.
///
/// # Example
///
/// ```
/// // in global scope:
/// const JUMP_SOUND: [u8] = include_wav!("sfx/jump_sound.wav");
///
/// // somewhere in code
/// let jump_sound = SoundChannel::new(MY_JUMP_SOUND);
/// let _ = mixer.play_sound(jump_sound);
/// ```
#[inline(always)]
#[must_use]
pub fn new(data: &'static [u8]) -> Self {
@ -58,6 +222,26 @@ impl SoundChannel {
}
}
/// Creates a new high priority [`SoundChannel`].
///
/// A high priority sound channel will override low priority ones if
/// the mixer runs out of channels. They will also never be overriden
/// by other high priority channels.
///
/// High priority channels are intended for background music and for
/// important, game breaking sound effects if you have any.
///
/// # Example
///
/// ```
/// // in global scope:
/// const MY_BGM: [u8] = include_wav!("sfx/my_bgm.wav");
///
/// // somewhere in code
/// let mut bgm = SoundChannel::new_high_priority(MY_BGM);
/// bgm.stereo().should_loop();
/// let _ = mixer.play_sound(bgm);
/// ```
#[inline(always)]
#[must_use]
pub fn new_high_priority(data: &'static [u8]) -> Self {
@ -74,20 +258,36 @@ impl SoundChannel {
}
}
/// Sets that a sound channel should loop back to the start once it has
/// finished playing rather than stopping.
#[inline(always)]
pub fn should_loop(&mut self) -> &mut Self {
self.should_loop = true;
self
}
/// Sets the speed at which this should channel should be played. Defaults
/// to 1 with values between 0 and 1 being slower above 1 being faster.
///
/// Note that this only works for mono sounds. Stereo sounds will not change
/// how fast they play.
#[inline(always)]
pub fn playback(&mut self, playback_speed: Num<usize, 8>) -> &mut Self {
self.playback_speed = playback_speed;
pub fn playback(&mut self, playback_speed: impl Into<Num<usize, 8>>) -> &mut Self {
self.playback_speed = playback_speed.into();
self
}
/// Sets how far left or right the sound effect should be played.
/// Must be a value between -1 and 1 (inclusive). -1 means fully played
/// on the left, 1 fully on the right and values in between allowing for
/// partial levels.
///
/// Defaults to 0 (meaning equal on left and right) and doesn't affect stereo
/// sounds.
#[inline(always)]
pub fn panning(&mut self, panning: Num<i16, 4>) -> &mut Self {
pub fn panning(&mut self, panning: impl Into<Num<i16, 4>>) -> &mut Self {
let panning = panning.into();
debug_assert!(panning >= Num::new(-1), "panning value must be >= -1");
debug_assert!(panning <= Num::new(1), "panning value must be <= 1");
@ -95,14 +295,23 @@ impl SoundChannel {
self
}
/// Sets the volume for how loud the sound should be played. Note that if
/// you play it too loud, the sound will clip sounding pretty terrible.
///
/// Must be a value >= 0 and defaults to 1.
#[inline(always)]
pub fn volume(&mut self, volume: Num<i16, 4>) -> &mut Self {
pub fn volume(&mut self, volume: impl Into<Num<i16, 4>>) -> &mut Self {
let volume = volume.into();
assert!(volume >= Num::new(0), "volume must be >= 0");
self.volume = volume;
self
}
/// Sets that the sound effect should be played in stereo. Not setting this
/// will result in the sound playing at half speed and mono. Setting this on
/// a mono sound will cause some interesting results (and play it at double speed).
#[inline(always)]
pub fn stereo(&mut self) -> &mut Self {
self.is_stereo = true;
@ -110,6 +319,7 @@ impl SoundChannel {
self
}
/// Stops the sound from playing.
#[inline(always)]
pub fn stop(&mut self) {
self.is_done = true;

126
agb/src/sound/mixer/sw_mixer.rs
View file

@ -30,6 +30,34 @@ extern "C" {
fn agb_rs__mixer_collapse(sound_buffer: *mut i8, input_buffer: *const Num<i16, 4>);
}
/// The main software mixer struct.
///
/// Tracks which sound channels are currently playing and handles actually playing them.
/// You should not create this struct directly, instead creating it through the [`Gba`](crate::Gba)
/// struct as follows:
///
/// ```
/// let mut mixer = gba.mixer.mixer();
/// ```
///
/// # Example
///
/// ```
/// // Outside your main function in global scope:
/// const MY_CRAZY_SOUND: &[u8] = include_wav!("sfx/my_crazy_sound.wav");
///
/// // in your main function:
/// let mut mixer = gba.mixer.mixer();
/// let mut channel = SoundChannel::new(MY_CRAZY_SOUND);
/// channel.stereo();
/// let _ = mixer.play_sound(channel);
///
/// loop {
/// mixer.frame();
/// vblank.wait_for_vblank();
/// mixer.after_vblank();
/// }
/// ```
pub struct Mixer {
buffer: MixerBuffer,
channels: [Option<SoundChannel>; 8],
@ -38,6 +66,19 @@ pub struct Mixer {
timer: Timer,
}
/// A pointer to a currently playing channel.
///
/// This is used to modify a channel that is already playing.
///
/// # Example
///
/// ```
/// let mut channel = SoundChannel::new_high_priority(MY_BGM);
/// let bgm_channel_id = mixer.play_sound(channel).unwrap(); // will always be Some if high priority
///
/// // Later, stop that particular channel
/// mixer.channel(bgm_channel_id).stop();
/// ```
pub struct ChannelId(usize, i32);
impl Mixer {
@ -51,18 +92,50 @@ impl Mixer {
}
}
/// Enable sound output
///
/// You must call this method in order to start playing sound. You can do as much set up before
/// this as you like, but you will not get any sound out of the console until this method is called.
pub fn enable(&mut self) {
hw::set_timer_counter_for_frequency_and_enable(&mut self.timer, constants::SOUND_FREQUENCY);
hw::set_sound_control_register_for_mixer();
}
/// Do post-vblank work. You can use either this or [`setup_interrupt_handler()`](Mixer::setup_interrupt_handler),
/// but not both. Note that this is not available if using 32768Hz sounds since those require more irregular timings.
///
/// # Example
///
/// ```
/// loop {
/// mixer.frame();
/// vblank.wait_for_vblank();
/// mixer.after_vblank();
/// }
/// ```
#[cfg(not(feature = "freq32768"))]
pub fn after_vblank(&mut self) {
free(|cs| self.buffer.swap(cs));
}
/// Note that if you set up an interrupt handler, you should not call `after_vblank` any more
/// You are still required to call `frame`
/// Use timer interrupts to do the timing required for ensuring the music runs smoothly.
///
/// Note that if you set up an interrupt handler, you should not call [`after_vblank`](Mixer::after_vblank) any more
/// You are still required to call [`frame`](Mixer::frame).
///
/// This is required if using 32768Hz music, but optional for other frequencies.
///
/// # Example
///
/// ```
/// // you must set this to a named variable to ensure that the scope is long enough
/// let _mixer_interrupt = mixer.setup_interrupt_handler();
///
/// loop {
/// mixer.frame();
/// vblank.wait_for_vblank();
/// }
/// ```
pub fn setup_interrupt_handler(&self) -> InterruptHandler<'_> {
let mut timer1 = unsafe { Timer::new(1) };
timer1
@ -75,6 +148,22 @@ impl Mixer {
add_interrupt_handler(timer1.interrupt(), move |cs| self.buffer.swap(cs))
}
/// Do the CPU intensive mixing for the next frame's worth of data.
///
/// This is where almost all of the CPU time for the mixer is done, and must be done every frame
/// or you will get crackling sounds.
///
/// Normally you would run this during vdraw, just before the vblank interrupt.
///
/// # Example
///
/// ```
/// loop {
/// mixer.frame();
/// vblank.wait_for_vblank();
/// mixer.after_vblank(); // optional, only if not using interrupts
/// }
/// ```
pub fn frame(&mut self) {
if !self.buffer.should_calculate() {
return;
@ -84,6 +173,25 @@ impl Mixer {
.write_channels(self.channels.iter_mut().flatten());
}
/// Start playing a given [`SoundChannel`].
///
/// Returns a [`ChannelId`] which you can later use to modify the playing sound.
///
/// Will first try to play the sound in an unused channel (of the 8 possible channels)
/// followed by overriding a low priority sound (if the sound channel being passed in
/// is high priority).
///
/// Returns Some if the channel is now playing (which is guaranteed if the channel is
/// high priority) or None if it failed to find a slot.
///
/// Panics if you try to play a high priority sound and there are no free channels.
///
/// # Example
///
/// ```
/// let mut channel = SoundChannel::new_high_priority(MY_BGM);
/// let bgm_channel_id = mixer.play_sound(channel).unwrap(); // will always be Some if high priority
/// ```
pub fn play_sound(&mut self, new_channel: SoundChannel) -> Option<ChannelId> {
for (i, channel) in self.channels.iter_mut().enumerate() {
if let Some(some_channel) = channel {
@ -114,6 +222,20 @@ impl Mixer {
panic!("Cannot play more than 8 sounds at once");
}
/// Lets you modify an already playing channel.
///
/// Allows you to change the volume, panning or stop an already playing channel.
/// Will return Some if the channel is still playing, or None if it has already finished.
///
/// # Example
///
/// ```
/// let mut channel = SoundChannel::new_high_priority(MY_BGM);
/// let bgm_channel_id = mixer.play_sound(channel).unwrap(); // will always be Some if high priority
///
/// // Later, stop that particular channel
/// mixer.channel(bgm_channel_id).stop();
/// ```
pub fn channel(&mut self, id: &ChannelId) -> Option<&'_ mut SoundChannel> {
if let Some(channel) = &mut self.channels[id.0] {
if self.indices[id.0] == id.1 && !channel.is_done {

15
agb/src/sound/mod.rs
View file

@ -1,2 +1,17 @@
//! # Game Boy Advance audio
//!
//! The GBA has 2 different ways of producing sound, which agb has support for.
//! You currently cannot use both at the same time, and currently there is no
//! compile time prevention of using both, but you should either use the DMG
//! which allows for Game Boy and Game Boy Color style sound effects, or the mixer
//! which allows for more advanced sounds.
//!
//! The [`dmg`](crate::sound::dmg) module is very rudimentry and doesn't support most of the possible
//! sounds possible. However, it may be expanded in the future.
//!
//! The [`mixer`](crate::sound::mixer) module is high performance, and allows for playing wav files at
//! various levels of quality. Check out the module documentation for more.
pub mod dmg;
pub mod mixer;