Merge pull request #37 from corwinkuiper/documentation

Documentation for objects and other

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<u16> = unsafe { MemoryMapped::new(0x0400_0000) };

agb/src/display/object.rs

@@ -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;

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))]