alex/agb
1
0
Fork 0
mirror of https://github.com/italicsjenga/agb.git synced 2025-01-11 01:21:34 +11:00
Code Issues Packages Projects Releases Wiki Activity

Update the docs

Browse source
This commit is contained in:
Gwilym Kuiper 2022-10-08 21:39:48 +01:00
parent f125025409
commit cc66b65847
8 changed files with 42 additions and 41 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
agb/src/display/tiled/infinite_scrolled_map.rs
View file

@ -157,7 +157,7 @@ impl<'a> InfiniteScrolledMap<'a> {
/// # );
/// #
/// # let vblank = agb::interrupt::VBlank::get();
/// # let mut mixer = gba.mixer.mixer();
/// # let mut mixer = gba.mixer.mixer(agb::sound::mixer::Frequency::Hz10512);
/// let start_position = agb::fixnum::Vector2D::new(10, 10);
/// backdrop.init(&mut vram, start_position, &mut || {
/// vblank.wait_for_vblank();
@ -232,7 +232,7 @@ impl<'a> InfiniteScrolledMap<'a> {
/// # );
/// #
/// # let vblank = agb::interrupt::VBlank::get();
/// # let mut mixer = gba.mixer.mixer();
/// # let mut mixer = gba.mixer.mixer(agb::sound::mixer::Frequency::Hz10512);
/// let start_position = agb::fixnum::Vector2D::new(10, 10);
/// while backdrop.init_partial(&mut vram, start_position) == PartialUpdateStatus::Continue {
/// vblank.wait_for_vblank();

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

@ -14,17 +14,11 @@
//!
//! # 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 |
//! The mixer runs at a fixed frequency which is determined at initialisation time by
//! passing certain [`Frequency`] options.
//!
//! 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.
//! If you don't use this frequency, the sound will play either too slowly or too quickly.
//!
//! 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).
@ -38,12 +32,17 @@
//! ```rust,no_run
//! # #![no_std]
//! # #![no_main]
//! use agb::sound::mixer::Frequency;
//! # fn foo(gba: &mut agb::Gba) {
//! let mut mixer = gba.mixer.mixer();
//! let mut mixer = gba.mixer.mixer(Frequency::Hz10512);
//! mixer.enable();
//! # }
//! ```
//!
//! Pass a frequency option. This option must be used for the entire lifetime of the `mixer`
//! variable. If you want to change frequency, you will need to drop this one and create a new
//! one.
//!
//! ## Doing the per-frame work
//!
//! Then, you have a choice of whether you want to use interrupts or do the buffer swapping
@ -55,9 +54,10 @@
//! ```rust,no_run
//! # #![no_std]
//! # #![no_main]
//! use agb::sound::mixer::Frequency;
//! # fn foo(gba: &mut agb::Gba) {
//! # let mut mixer = gba.mixer.mixer();
//! # let vblank = agb::interrupt::VBlank::get();
//! let mut mixer = gba.mixer.mixer(Frequency::Hz10512);
//! let vblank = agb::interrupt::VBlank::get();
//! // Somewhere in your main loop:
//! mixer.frame();
//! vblank.wait_for_vblank();
@ -70,10 +70,13 @@
//! ```rust,no_run
//! # #![no_std]
//! # #![no_main]
//! use agb::sound::mixer::Frequency;
//! # fn foo(gba: &mut agb::Gba) {
//! # let mut mixer = gba.mixer.mixer();
//! # let vblank = agb::interrupt::VBlank::get();
//! let mut mixer = gba.mixer.mixer(agb::sound::mixer::Frequency::Hz32768);
//! let vblank = agb::interrupt::VBlank::get();
//! // outside your main loop, close to initialisation
//! // you must assign this to a variable (not to _ or ignored) or rust will immediately drop it
//! // and prevent the interrupt handler from firing.
//! let _mixer_interrupt = mixer.setup_interrupt_handler();
//!
//! // inside your main loop
@ -99,7 +102,7 @@
//! # #![no_std]
//! # #![no_main]
//! # fn foo(gba: &mut agb::Gba) {
//! # let mut mixer = gba.mixer.mixer();
//! # let mut mixer = gba.mixer.mixer(agb::sound::mixer::Frequency::Hz10512);
//! # let vblank = agb::interrupt::VBlank::get();
//! # use agb::{*, sound::mixer::*};
//! // Outside your main function in global scope:
@ -116,9 +119,6 @@
//!
//! 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;
@ -159,11 +159,10 @@ pub enum Frequency {
Hz10512,
/// 18157Hz
Hz18157,
/// 32768Hz - note that this option requires the timer to do the buffer swapping
/// 32768Hz - note that this option requires interrupts for buffer swapping
Hz32768,
}
// These work perfectly with swapping the buffers every vblank
// list here: http://deku.gbadev.org/program/sound1.html
impl Frequency {
pub(crate) fn frequency(self) -> i32 {
@ -223,7 +222,7 @@ impl Frequency {
///
/// // somewhere in code
/// # fn foo(gba: &mut Gba) {
/// # let mut mixer = gba.mixer.mixer();
/// # let mut mixer = gba.mixer.mixer(agb::sound::mixer::Frequency::Hz10512);
/// let mut bgm = SoundChannel::new_high_priority(MY_BGM);
/// bgm.stereo().should_loop();
/// let _ = mixer.play_sound(bgm);
@ -242,7 +241,7 @@ impl Frequency {
///
/// // somewhere in code
/// # fn foo(gba: &mut Gba) {
/// # let mut mixer = gba.mixer.mixer();
/// # let mut mixer = gba.mixer.mixer(agb::sound::mixer::Frequency::Hz10512);
/// let jump_sound = SoundChannel::new(JUMP_SOUND);
/// let _ = mixer.play_sound(jump_sound);
/// # }
@ -279,7 +278,7 @@ impl SoundChannel {
/// # use agb::sound::mixer::*;
/// # use agb::*;
/// # fn foo(gba: &mut Gba) {
/// # let mut mixer = gba.mixer.mixer();
/// # let mut mixer = gba.mixer.mixer(agb::sound::mixer::Frequency::Hz10512);
/// // in global scope:
/// const JUMP_SOUND: &[u8] = include_wav!("examples/sfx/jump.wav");
///
@ -321,7 +320,7 @@ impl SoundChannel {
/// # use agb::sound::mixer::*;
/// # use agb::*;
/// # fn foo(gba: &mut Gba) {
/// # let mut mixer = gba.mixer.mixer();
/// # let mut mixer = gba.mixer.mixer(agb::sound::mixer::Frequency::Hz10512);
/// // in global scope:
/// const MY_BGM: &[u8] = include_wav!("examples/sfx/my_bgm.wav");
///

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

@ -48,7 +48,7 @@ extern "C" {
/// # use agb::sound::mixer::*;
/// # use agb::*;
/// # fn foo(gba: &mut Gba) {
/// let mut mixer = gba.mixer.mixer();
/// let mut mixer = gba.mixer.mixer(Frequency::Hz10512);
/// # }
/// ```
///
@ -60,13 +60,13 @@ extern "C" {
/// # use agb::sound::mixer::*;
/// # use agb::*;
/// # fn foo(gba: &mut Gba) {
/// # let mut mixer = gba.mixer.mixer();
/// # let mut mixer = gba.mixer.mixer(agb::sound::mixer::Frequency::Hz10512);
/// # let vblank = agb::interrupt::VBlank::get();
/// // Outside your main function in global scope:
/// const MY_CRAZY_SOUND: &[u8] = include_wav!("examples/sfx/jump.wav");
///
/// // in your main function:
/// let mut mixer = gba.mixer.mixer();
/// let mut mixer = gba.mixer.mixer(Frequency::Hz10512);
/// let mut channel = SoundChannel::new(MY_CRAZY_SOUND);
/// channel.stereo();
/// let _ = mixer.play_sound(channel);
@ -99,7 +99,7 @@ pub struct Mixer {
/// # use agb::sound::mixer::*;
/// # use agb::*;
/// # fn foo(gba: &mut Gba) {
/// # let mut mixer = gba.mixer.mixer();
/// # let mut mixer = gba.mixer.mixer(agb::sound::mixer::Frequency::Hz10512);
/// # const MY_BGM: &[u8] = include_wav!("examples/sfx/my_bgm.wav");
/// 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
@ -142,7 +142,7 @@ impl Mixer {
/// # use agb::sound::mixer::*;
/// # use agb::*;
/// # fn foo(gba: &mut Gba) {
/// # let mut mixer = gba.mixer.mixer();
/// # let mut mixer = gba.mixer.mixer(agb::sound::mixer::Frequency::Hz10512);
/// # let vblank = agb::interrupt::VBlank::get();
/// loop {
/// mixer.frame();
@ -171,7 +171,7 @@ impl Mixer {
/// # use agb::sound::mixer::*;
/// # use agb::*;
/// # fn foo(gba: &mut Gba) {
/// # let mut mixer = gba.mixer.mixer();
/// # let mut mixer = gba.mixer.mixer(agb::sound::mixer::Frequency::Hz10512);
/// # let vblank = agb::interrupt::VBlank::get();
/// // you must set this to a named variable to ensure that the scope is long enough
/// let _mixer_interrupt = mixer.setup_interrupt_handler();
@ -209,7 +209,7 @@ impl Mixer {
/// # use agb::sound::mixer::*;
/// # use agb::*;
/// # fn foo(gba: &mut Gba) {
/// # let mut mixer = gba.mixer.mixer();
/// # let mut mixer = gba.mixer.mixer(agb::sound::mixer::Frequency::Hz10512);
/// # let vblank = agb::interrupt::VBlank::get();
/// loop {
/// mixer.frame();
@ -248,7 +248,7 @@ impl Mixer {
/// # use agb::sound::mixer::*;
/// # use agb::*;
/// # fn foo(gba: &mut Gba) {
/// # let mut mixer = gba.mixer.mixer();
/// # let mut mixer = gba.mixer.mixer(agb::sound::mixer::Frequency::Hz10512);
/// # const MY_BGM: &[u8] = include_wav!("examples/sfx/my_bgm.wav");
/// 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
@ -297,7 +297,7 @@ impl Mixer {
/// # use agb::sound::mixer::*;
/// # use agb::*;
/// # fn foo(gba: &mut Gba) {
/// # let mut mixer = gba.mixer.mixer();
/// # let mut mixer = gba.mixer.mixer(agb::sound::mixer::Frequency::Hz10512);
/// # const MY_BGM: &[u8] = include_wav!("examples/sfx/my_bgm.wav");
/// 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

2
examples/hyperspace-roll/Cargo.toml
View file

@ -7,7 +7,7 @@ edition = "2018"
# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
[dependencies]
agb = { version = "0.11.1", path = "../../agb", features = ["freq32768"] }
agb = { version = "0.11.1", path = "../../agb" }
bare-metal = "1"
[profile.dev]

4
examples/hyperspace-roll/src/main.rs
View file

@ -10,11 +10,11 @@
// which won't be a particularly clear error message.
#![no_main]
use agb::display;
use agb::display::object::ObjectController;
use agb::display::tiled::VRamManager;
use agb::display::Priority;
use agb::interrupt::VBlank;
use agb::{display, sound::mixer::Frequency};
extern crate alloc;
use alloc::vec;
@ -138,7 +138,7 @@ fn main(mut gba: agb::Gba) -> ! {
let mut star_background = StarBackground::new(&mut background0, &mut background1, &mut vram);
star_background.commit(&mut vram);
let mut mixer = gba.mixer.mixer();
let mut mixer = gba.mixer.mixer(Frequency::Hz32768);
mixer.enable();
let _interrupt_handler = mixer.setup_interrupt_handler();

3
examples/the-hat-chooses-the-wizard/src/main.rs
View file

@ -17,6 +17,7 @@ use agb::{
},
fixnum::{FixedNum, Vector2D},
input::{self, Button, ButtonController},
sound::mixer::Frequency,
};
use alloc::boxed::Box;
@ -820,7 +821,7 @@ pub fn main(mut agb: agb::Gba) -> ! {
vram.set_background_palettes(tile_sheet::background.palettes);
let object = agb.display.object.get();
let mut mixer = agb.mixer.mixer();
let mut mixer = agb.mixer.mixer(Frequency::Hz10512);
mixer.enable();
let mut music_box = sfx::MusicBox::new();

2
examples/the-purple-night/Cargo.toml
View file

@ -7,7 +7,7 @@ edition = "2018"
# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
[dependencies]
agb = { path = "../../agb", version = "0.11.1", features = ["freq18157"]}
agb = { path = "../../agb", version = "0.11.1" }
generational-arena = { version = "0.2", default-features = false }
[build-dependencies]

3
examples/the-purple-night/src/main.rs
View file

@ -22,6 +22,7 @@ use agb::{
input::{Button, ButtonController, Tri},
interrupt::VBlank,
rng,
sound::mixer::Frequency,
};
use generational_arena::Arena;
use sfx::Sfx;
@ -2205,7 +2206,7 @@ fn game_with_level(gba: &mut agb::Gba) {
let vblank = agb::interrupt::VBlank::get();
vblank.wait_for_vblank();
let mut mixer = gba.mixer.mixer();
let mut mixer = gba.mixer.mixer(Frequency::Hz18157);
mixer.enable();
let mut sfx = sfx::Sfx::new(&mut mixer);