add documentation for object functions and structs

This commit is contained in:
Corwin Kuiper 2021-06-03 19:22:26 +01:00
parent b023807bc0
commit ba80dbefd1

View file

@ -4,28 +4,35 @@ use crate::memory_mapped::MemoryMapped1DArray;
const OBJECT_ATTRIBUTE_MEMORY: MemoryMapped1DArray<u16, 512> =
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<u8>,
}
/// 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;