From e1448f7d81a8ea7957780f9926c6c87c3d14a06a Mon Sep 17 00:00:00 2001 From: Corwin Date: Sat, 6 Aug 2022 12:33:06 +0100 Subject: [PATCH] write docs for windows --- agb/src/display/window.rs | 47 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/agb/src/display/window.rs b/agb/src/display/window.rs index 3f537c02..d10f41cd 100644 --- a/agb/src/display/window.rs +++ b/agb/src/display/window.rs @@ -1,7 +1,11 @@ +#![deny(missing_docs)] use crate::{fixnum::Rect, memory_mapped::MemoryMapped}; use super::{tiled::BackgroundID, DISPLAY_CONTROL, HEIGHT, WIDTH}; +/// The windows feature of the Game Boy Advance can selectively display +/// backgrounds or objects on the screen and can selectively enable and disable +/// effects. This gives out references and holds changes before they can be committed. pub struct Windows { wins: [MovableWindow; 2], out: Window, @@ -13,8 +17,11 @@ const REG_VERTICAL_BASE: *mut u16 = 0x0400_0044 as *mut _; const REG_WINDOW_CONTROL_BASE: *mut u16 = 0x0400_0048 as *mut _; +/// The two Windows that have an effect inside of them pub enum WinIn { + /// The higher priority window Win0, + /// The lower priority window Win1, } @@ -29,21 +36,27 @@ impl Windows { s } + /// Returns a reference to the window that is used when outside all other windows #[inline(always)] pub fn win_out(&mut self) -> &mut Window { &mut self.out } + /// Gives a reference to the specified window that has effect when inside of it's boundary #[inline(always)] pub fn win_in(&mut self, id: WinIn) -> &mut MovableWindow { &mut self.wins[id as usize] } + /// Gives a reference to the window that is controlled by sprites and objects #[inline(always)] pub fn win_obj(&mut self) -> &mut Window { &mut self.obj } + /// Commits the state of the windows as dictated by the various functions to + /// modify them. This should be done during vblank shortly after the wait + /// for next vblank call. pub fn commit(&self) { for (id, win) in self.wins.iter().enumerate() { win.commit(id); @@ -58,10 +71,12 @@ impl Windows { } } +/// A non movable window pub struct Window { window_bits: u8, } +/// A window that can be moved pub struct MovableWindow { inner: Window, rect: Rect, @@ -72,6 +87,9 @@ impl Window { Self { window_bits: 0 } } + /// Enables the window, must call [Windows::commit] for this change to be + /// seen. If a window is not enabled it will not have an effect on the + /// display. #[inline(always)] pub fn enable(&mut self) -> &mut Self { self.set_bit(7, true); @@ -79,6 +97,8 @@ impl Window { self } + /// Disables the window, must call [Windows::commit] for this change to be + /// seen. #[inline(always)] pub fn disable(&mut self) -> &mut Self { self.set_bit(7, false); @@ -95,24 +115,33 @@ impl Window { self.window_bits |= (value as u8) << bit; } + /// Resets the window to it's default state, must call [Windows::commit] for + /// this change to be seen. The default state is the window disabled with + /// nothing rendered. #[inline(always)] pub fn reset(&mut self) -> &mut Self { *self = Self::new(); self } + /// Sets whether the blend is enabled inside of this window, must call + /// [Windows::commit] for this change to be seen. #[inline(always)] pub fn set_blend_enable(&mut self, blnd: bool) -> &mut Self { self.set_bit(5, blnd); self } + /// Sets whether the given background will be rendered inside this window, + /// must call [Windows::commit] for this change to be seen. #[inline(always)] pub fn set_background_enable(&mut self, back: BackgroundID, enable: bool) -> &mut Self { self.set_bit(back.0 as usize, enable); self } + /// Sets whether objects will be rendered inside this window, must call + /// [Windows::commit] for this change to be seen. #[inline(always)] pub fn set_object_enable(&mut self, obj: bool) -> &mut Self { self.set_bit(4, obj); @@ -139,6 +168,9 @@ impl MovableWindow { } } + /// Enables the window, must call [Windows::commit] for this change to be + /// seen. If a window is not enabled it will not have an effect on the + /// display. #[inline(always)] pub fn enable(&mut self) -> &mut Self { self.inner.enable(); @@ -146,6 +178,8 @@ impl MovableWindow { self } + /// Disables the window, must call [Windows::commit] for this change to be + /// seen. #[inline(always)] pub fn disable(&mut self) -> &mut Self { self.inner.disable(); @@ -157,22 +191,31 @@ impl MovableWindow { self.inner.is_enabled() } + /// Resets the window to it's default state, must call [Windows::commit] for + /// this change to be seen. The default state is the window disabled with + /// nothing rendered and represents a 0x0 rectangle at (0, 0). #[inline(always)] pub fn reset(&mut self) -> &mut Self { *self = Self::new(); self } + /// Sets whether the blend is enabled inside of this window, must call + /// [Windows::commit] for this change to be seen. #[inline(always)] pub fn set_blend_enable(&mut self, blnd: bool) -> &mut Self { self.inner.set_blend_enable(blnd); self } + /// Sets whether the given background will be rendered inside this window, + /// must call [Windows::commit] for this change to be seen. #[inline(always)] pub fn set_background_enable(&mut self, back: BackgroundID, enable: bool) -> &mut Self { self.inner.set_background_enable(back, enable); self } + /// Sets whether objects will be rendered inside this window, must call + /// [Windows::commit] for this change to be seen. #[inline(always)] pub fn set_object_enable(&mut self, obj: bool) -> &mut Self { self.inner.set_object_enable(obj); @@ -193,6 +236,9 @@ impl MovableWindow { } } + /// Sets the area of what is inside the window using [u8] representation, + /// which is closest to what the GBA uses. Most of the time [set_position] + /// should be used. #[inline(always)] pub fn set_position_u8(&mut self, rect: Rect) -> &mut Self { self.rect = rect; @@ -200,6 +246,7 @@ impl MovableWindow { self } + /// Sets the position of the area that is inside the window. #[inline(always)] pub fn set_position(&mut self, rect: &Rect) -> &mut Self { let new_rect = Rect::new(