From ba80dbefd14a6e5796fae239ed6e3bd8c5e86d55 Mon Sep 17 00:00:00 2001 From: Corwin Kuiper Date: Thu, 3 Jun 2021 19:22:26 +0100 Subject: [PATCH] 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;