mirror of
https://github.com/italicsjenga/agb.git
synced 2024-12-23 16:21:33 +11:00
Merge pull request #37 from corwinkuiper/documentation
Documentation for objects and other
This commit is contained in:
commit
acee8351b9
|
@ -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) };
|
||||
|
|
|
@ -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;
|
||||
|
|
|
@ -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))]
|
||||
|
|
Loading…
Reference in a new issue