From afa9ef9109937aec2c47808ad618f104d5d00121 Mon Sep 17 00:00:00 2001
From: Corwin <corwin@kuiper.dev>
Date: Sat, 6 Aug 2022 21:15:38 +0100
Subject: [PATCH] add docs for blend

---
 agb/src/display/blend.rs | 42 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/agb/src/display/blend.rs b/agb/src/display/blend.rs
index 4b6ee18..68848dc 100644
--- a/agb/src/display/blend.rs
+++ b/agb/src/display/blend.rs
@@ -1,21 +1,48 @@
+//! This controls the blending modes on the GBA.
+//!
+//! For now a description of how blending can be used is found on [the tonc page
+//! for graphic
+//! effects](https://www.coranac.com/tonc/text/gfx.htm#ssec-bld-gba). See the
+//! [Blend] struct for all the functions to manage blend effects. You accquire
+//! the Blend struct through the [Display][super::Display] struct.
+//! ```no_run
+//! # #![no_main]
+//! # #![no_std]
+//! # fn blend(mut gba: agb::Gba) {
+//! let mut blend = gba.display.blend.get();
+//! // ...
+//! # }
+//! ```
+//! where `gba` is a mutable [Gba][crate::Gba] struct.
+
 use crate::{fixnum::Num, memory_mapped::set_bits};
 
 use super::tiled::BackgroundID;
 
+/// The layers, top layer will be blended into the bottom layer
 #[derive(Clone, Copy, Debug)]
 pub enum Layer {
+    /// Top layer gets blended into the bottom layer
     Top = 0,
+    /// The bottom layer of the blend
     Bottom = 1,
 }
 
+/// The different blend modes avaliable on the GBA
 #[derive(Clone, Copy, Debug)]
 pub enum BlendMode {
+    // No blending
     Off = 0,
+    // Aditive blending, use the [Blend::set_blend_weight] function to use this
     Normal = 0b01,
+    // Brighten, use the [Blend::set_fade] to use this
     FadeToWhite = 0b10,
+    // Darken, use the [Blend::set_fade] to use this
     FadeToBlack = 0b11,
 }
 
+/// Manages the blending, won't cause anything to change unless [Blend::commit]
+/// is called.
 pub struct Blend {
     targets: u16,
     blend_weights: u16,
@@ -39,28 +66,34 @@ impl Blend {
         blend
     }
 
+    /// Reset the targets to all disabled, the targets control which layers are
+    /// enabled for blending.
     pub fn reset_targets(&mut self) -> &mut Self {
         self.targets = 0;
 
         self
     }
 
+    /// Reset the blend weights
     pub fn reset_weights(&mut self) -> &mut Self {
         self.blend_weights = 0;
 
         self
     }
 
+    /// Reset the brighten and darken weights
     pub fn reset_fades(&mut self) -> &mut Self {
         self.fade_weight = 0;
 
         self
     }
 
+    /// Reset targers, blend weights, and fades
     pub fn reset(&mut self) -> &mut Self {
         self.reset_targets().reset_fades().reset_weights()
     }
 
+    /// Set whether a background is enabled for blending on a particular layer.
     pub fn set_background_enable(
         &mut self,
         layer: Layer,
@@ -73,6 +106,7 @@ impl Blend {
         self
     }
 
+    /// Set whether objects are enabled for blending on a particular layer
     pub fn set_object_enable(&mut self, layer: Layer, enable: bool) -> &mut Self {
         let bit_to_modify = 0x4 + (layer as usize * 8);
         self.targets = set_bits(self.targets, enable as u16, 1, bit_to_modify);
@@ -80,6 +114,9 @@ impl Blend {
         self
     }
 
+    /// Set whether the backdrop contributes to the blend on a particular layer.
+    /// The backdrop is transparent colour, the colour rendered when nothing is
+    /// in it's place.
     pub fn set_backdrop_enable(&mut self, layer: Layer, enable: bool) -> &mut Self {
         let bit_to_modify = 0x5 + (layer as usize * 8);
         self.targets = set_bits(self.targets, enable as u16, 1, bit_to_modify);
@@ -87,6 +124,7 @@ impl Blend {
         self
     }
 
+    /// Set the weight for the blend on a particular layer.
     pub fn set_blend_weight(&mut self, layer: Layer, value: Num<u8, 4>) -> &mut Self {
         self.blend_weights = set_bits(
             self.blend_weights,
@@ -98,18 +136,22 @@ impl Blend {
         self
     }
 
+    /// Set the fade of brighten or darken
     pub fn set_fade(&mut self, value: Num<u8, 4>) -> &mut Self {
         self.fade_weight = value.to_raw() as u16;
 
         self
     }
 
+    /// Set the current blend mode
     pub fn set_blend_mode(&mut self, blend_mode: BlendMode) -> &mut Self {
         self.targets = set_bits(self.targets, blend_mode as u16, 2, 0x6);
 
         self
     }
 
+    /// Commits the current state, should be called near after a call to wait
+    /// for next vblank.
     pub fn commit(&self) {
         unsafe {
             BLEND_CONTROL.write_volatile(self.targets);