From 6eb13473bbe7cbc6552d51da213f021ff69d769f Mon Sep 17 00:00:00 2001 From: Corwin Kuiper Date: Thu, 3 Jun 2021 19:22:08 +0100 Subject: [PATCH 1/3] add documentation for submodules --- agb/src/lib.rs | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/agb/src/lib.rs b/agb/src/lib.rs index c758db0a..658b99b2 100644 --- a/agb/src/lib.rs +++ b/agb/src/lib.rs @@ -7,16 +7,27 @@ #![test_runner(crate::test_runner)] #![reexport_test_harness_main = "test_main"] +//! # agb +//! `agb` is a library for making games on the Game Boy Advance using the Rust +//! programming language. It attempts to be a high level abstraction over the +//! internal workings of the Game Boy Advance whilst still being high +//! performance and memory efficient. + +/// Implements everything relating to things that are displayed on screen. pub mod display; +/// Button inputs to the system. pub mod input; +/// Implements sound output. pub mod sound; mod interrupt; mod memory_mapped; +/// Implements logging to the mgba emulator. pub mod mgba; -pub mod number; +mod number; mod single; +/// System BIOS calls / syscalls. pub mod syscall; #[cfg(not(test))] From b023807bc09e2799c9ded43262a7e252dd804772 Mon Sep 17 00:00:00 2001 From: Corwin Kuiper Date: Thu, 3 Jun 2021 19:22:16 +0100 Subject: [PATCH 2/3] add documentation for submodules --- agb/src/display/mod.rs | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/agb/src/display/mod.rs b/agb/src/display/mod.rs index 456b46c1..746250b6 100644 --- a/agb/src/display/mod.rs +++ b/agb/src/display/mod.rs @@ -4,13 +4,21 @@ use bitflags::bitflags; use vblank::VBlankGiver; use video::Video; +/// Graphics mode 3. Bitmap mode that provides a 16-bit colour framebuffer. pub mod bitmap3; +/// Graphics mode 4. Bitmap 4 provides two 8-bit paletted framebuffers with page switching. pub mod bitmap4; +/// Test logo of agb. pub mod example_logo; +/// Implements sprites. pub mod object; +/// Palette type. pub mod palette16; +/// Graphics mode 0. Four regular backgrounds. pub mod tiled0; +/// Syscall for waiting for vblank. pub mod vblank; +/// Giving out graphics mode. pub mod video; const DISPLAY_CONTROL: MemoryMapped = unsafe { MemoryMapped::new(0x0400_0000) }; From ba80dbefd14a6e5796fae239ed6e3bd8c5e86d55 Mon Sep 17 00:00:00 2001 From: Corwin Kuiper Date: Thu, 3 Jun 2021 19:22:26 +0100 Subject: [PATCH 3/3] add documentation for object functions and structs --- agb/src/display/object.rs | 57 ++++++++++++++++++++++++++++++++------- 1 file changed, 48 insertions(+), 9 deletions(-) diff --git a/agb/src/display/object.rs b/agb/src/display/object.rs index 0ab50abe..13fa766c 100644 --- a/agb/src/display/object.rs +++ b/agb/src/display/object.rs @@ -4,28 +4,35 @@ use crate::memory_mapped::MemoryMapped1DArray; const OBJECT_ATTRIBUTE_MEMORY: MemoryMapped1DArray = unsafe { MemoryMapped1DArray::new(0x0700_0000) }; -#[non_exhaustive] +/// Handles distributing objects and matricies along with operations that effect all objects. pub struct ObjectControl { object_count: u8, affine_count: u8, } +/// The standard object, without rotation. pub struct ObjectStandard { attributes: ObjectAttribute, id: u8, } +/// The affine object, with potential for using a transformation matrix to alter +/// how the sprite is rendered to screen. pub struct ObjectAffine { attributes: ObjectAttribute, id: u8, aff_id: Option, } +/// Refers to an affine matrix in the OAM. Includes both an index and the +/// components of the affine matrix. pub struct AffineMatrix { pub attributes: AffineMatrixAttributes, id: u8, } +/// The components of the affine matrix. The components are fixed point 8:8. +/// TODO is a type that can handle fixed point arithmetic. pub struct AffineMatrixAttributes { pub p_a: i16, pub p_b: i16, @@ -33,7 +40,7 @@ pub struct AffineMatrixAttributes { pub p_d: i16, } -pub enum Mode { +enum Mode { Normal = 0, Affine = 1, Hidden = 2, @@ -41,54 +48,71 @@ pub enum Mode { } impl ObjectStandard { + /// Commits the object to OAM such that the updated version is displayed on + /// screen. Recommend to do this during VBlank. pub fn commit(&self) { unsafe { self.attributes.commit(self.id) } } + /// Sets the x coordinate of the sprite on screen. pub fn set_x(&mut self, x: u8) { self.attributes.set_x(x) } + /// Sets the y coordinate of the sprite on screen. pub fn set_y(&mut self, y: u8) { self.attributes.set_y(y) } + /// Sets the index of the tile to use as the sprite. Potentially a temporary function. pub fn set_tile_id(&mut self, id: u16) { self.attributes.set_tile_id(id) } + /// Sets whether the sprite is horizontally mirrored or not. pub fn set_hflip(&mut self, hflip: bool) { self.attributes.set_hflip(hflip) } + /// Show the object on screen. pub fn show(&mut self) { self.attributes.set_mode(Mode::Normal) } + /// Hide the object and do not render. pub fn hide(&mut self) { self.attributes.set_mode(Mode::Hidden) } } impl ObjectAffine { + /// Commits the object to OAM such that the updated version is displayed on + /// screen. Recommend to do this during VBlank. pub fn commit(&self) { unsafe { self.attributes.commit(self.id) } } + /// Sets the x coordinate of the sprite on screen. pub fn set_x(&mut self, x: u8) { self.attributes.set_x(x) } + /// Sets the y coordinate of the sprite on screen. pub fn set_y(&mut self, y: u8) { self.attributes.set_y(y) } + /// Sets the index of the tile to use as the sprite. Potentially a temporary function. pub fn set_tile_id(&mut self, id: u16) { self.attributes.set_tile_id(id) } + /// Show the object on screen. Panics if affine matrix has not been set. pub fn show(&mut self) { if self.aff_id.is_none() { panic!("affine matrix should be set") } self.attributes.set_mode(Mode::Affine) } + /// Hide the object and do not render the sprite. pub fn hide(&mut self) { self.attributes.set_mode(Mode::Hidden) } + /// Sets the affine matrix to use. Changing the affine matrix will change + /// how the sprite is rendered. pub fn set_affine_mat(&mut self, aff: &AffineMatrix) { self.attributes.set_affine(aff.id); self.aff_id = Some(aff.id); @@ -100,7 +124,7 @@ fn set_bits(current: u16, value: u16, length: u16, shift: u16) -> u16 { (current & !(mask << shift)) | ((value & mask) << shift) } -pub struct ObjectAttribute { +struct ObjectAttribute { a0: u16, a1: u16, a2: u16, @@ -113,33 +137,34 @@ impl ObjectAttribute { OBJECT_ATTRIBUTE_MEMORY.set(index as usize * 4 + 2, self.a2); } - pub fn set_hflip(&mut self, hflip: bool) { + fn set_hflip(&mut self, hflip: bool) { self.a1 = set_bits(self.a1, hflip as u16, 1, 0xC); } - pub fn set_x(&mut self, x: u8) { + fn set_x(&mut self, x: u8) { self.a1 = set_bits(self.a1, x as u16, 8, 0); } - pub fn set_y(&mut self, y: u8) { + fn set_y(&mut self, y: u8) { self.a0 = set_bits(self.a0, y as u16, 8, 0) } - pub fn set_tile_id(&mut self, id: u16) { + fn set_tile_id(&mut self, id: u16) { self.a2 = set_bits(self.a2, id, 9, 0); } - pub fn set_mode(&mut self, mode: Mode) { + fn set_mode(&mut self, mode: Mode) { self.a0 = set_bits(self.a0, mode as u16, 2, 8); } - pub fn set_affine(&mut self, aff_id: u8) { + fn set_affine(&mut self, aff_id: u8) { self.a1 = set_bits(self.a1, aff_id as u16, 5, 8); } } impl AffineMatrix { #[allow(clippy::identity_op)] + /// Commits matrix to OAM, will cause any objects using this matrix to be updated. pub fn commit(&self) { let id = self.id as usize; OBJECT_ATTRIBUTE_MEMORY.set((id + 0) * 4 + 3, self.attributes.p_a as u16); @@ -172,18 +197,24 @@ impl ObjectControl { } } + /// Enable objects on the GBA. pub fn enable(&mut self) { let disp = DISPLAY_CONTROL.get(); let disp = disp | (1 << 0x0C); DISPLAY_CONTROL.set(disp); } + /// Disable objects, objects won't be rendered. pub fn disable(&mut self) { let disp = DISPLAY_CONTROL.get(); let disp = disp & !(1 << 0x0C); DISPLAY_CONTROL.set(disp); } + /// Get an unused standard object. Currently dropping an unused object will + /// not free this. You should either keep around all objects you need + /// forever or drop and reobtain ObjectControl. Panics if more than 128 + /// objects are obtained. pub fn get_object_standard(&mut self) -> ObjectStandard { let id = self.object_count; self.object_count += 1; @@ -194,6 +225,10 @@ impl ObjectControl { } } + /// Get an unused affine object. Currently dropping an unused object will + /// not free this. You should either keep around all objects you need + /// forever or drop and reobtain ObjectControl. Panics if more than 128 + /// objects are obtained. pub fn get_object_affine(&mut self) -> ObjectAffine { let id = self.object_count; self.object_count += 1; @@ -205,6 +240,10 @@ impl ObjectControl { } } + /// Get an unused affine matrix. Currently dropping an unused object will + /// not free this. You should either keep around all affine matricies you + /// need forever or drop and reobtain ObjectControl. Panics if more than 32 + /// affine matricies are obtained. pub fn get_affine(&mut self) -> AffineMatrix { let id = self.affine_count; self.affine_count += 1;