Document the lcd module

Author: phil-opp

src/lcd/color.rs

@@ -1,20 +1,28 @@
+/// Represents a color with alpha, red, green, and blue channels.
 #[derive(Debug, Clone, Copy)]
 pub struct Color {
+    /// The red channel.
     pub red: u8,
+    /// The green channel.
     pub green: u8,
+    /// The blue channel.
     pub blue: u8,
+    /// The alpha channel (0 is transparent, 255 is opaque).
     pub alpha: u8,
 }
 
 impl Color {
+    /// Creates a color from the passed RGB values. The alpha channel is set to 255 (opaque).
     pub fn rgb(red: u8, green: u8, blue: u8) -> Color {
         Self::rgba(red, green, blue, 255)
     }
 
+    /// Converts the color to RGB. The alpha channel is ignored.
     pub fn to_rgb(&self) -> u32 {
         (u32::from(self.red) << 16) | (u32::from(self.green) << 8) | u32::from(self.blue)
     }
 
+    /// Creates a color from the passed values.
     pub fn rgba(red: u8, green: u8, blue: u8, alpha: u8) -> Color {
         Color {
             red: red,
@@ -24,6 +32,7 @@ impl Color {
         }
     }
 
+    /// Creates a color from the passed hex RGB value. The alpha channel is set to 255 (opaque).
     pub fn from_hex(color: u32) -> Color {
         assert_eq!(color >> (8 * 3), 0);
         Color {
@@ -34,18 +43,22 @@ impl Color {
         }
     }
 
+    /// Converts the color to RGB. The alpha channel is ignored.
     pub fn to_rgb888(&self) -> u32 {
         self.to_rgb()
     }
 
+    /// Creates a color from the passed RGB value. The alpha channel is set to 255 (opaque).
     pub fn from_rgb888(color: u32) -> Color {
         Color::from_hex(color)
     }
 
+    /// Converts the color to ARGB.
     pub fn to_argb8888(&self) -> u32 {
         (u32::from(self.alpha) << 24) | self.to_rgb888()
     }
 
+    /// Creates a color from the passed ARGB value.
     pub fn from_argb8888(color: u32) -> Color {
         Color {
             red: (color >> 16) as u8,
@@ -55,13 +68,15 @@ impl Color {
         }
     }
 
+    /// Converts the color to ARGB1555.
     pub fn to_argb1555(&self) -> u16 {
         (u16::from(self.alpha) & 0x80) << 8
             | (u16::from(self.red) & 0xf8) << 7
             | (u16::from(self.green) & 0xf8) << 2
             | (u16::from(self.blue) & 0xf8) >> 3
     }
 
+    /// Creates a color from the passed ARGB1555 value.
     pub fn from_argb1555(color: u16) -> Color {
         Color {
             alpha: ((color >> 8) & 0x80) as u8,
@@ -71,6 +86,7 @@ impl Color {
         }
     }
 
+    /// Creates a color from the passed HSV value.
     pub fn from_hsv(hue: i32, saturation: f32, value: f32) -> Color {
         let mut h = hue % 360;
         if h < 0 {

src/lcd/init.rs

@@ -1,6 +1,12 @@
 use super::Lcd;
 use stm32f7::stm32f7x6::{LTDC, RCC};
 
+/// Initializes the LCD controller.
+///
+/// The SDRAM must be initialized before this function is called. See the
+/// [`init_sdram`] function for more information.
+///
+/// [`init_sdram`]: crate::init::init_sdram
 pub fn init<'a>(ltdc: &'a mut LTDC, rcc: &mut RCC) -> Lcd<'a> {
     use crate::lcd::{self, LAYER_1_START, LAYER_2_START};
     const HEIGHT: u16 = lcd::HEIGHT as u16;

src/lcd/mod.rs

@@ -1,3 +1,8 @@
+//! Functions for accessing and writing text to the LCD.
+//!
+//! The display has two layers that are blended on top of each other, and a background layer
+//! with an uniform color.
+
 pub use self::color::Color;
 pub use self::init::init;
 pub use self::stdout::init as init_stdout;
@@ -10,18 +15,28 @@ pub mod stdout;
 mod color;
 mod init;
 
+/// The height of the display in pixels.
 pub const HEIGHT: usize = 272;
+/// The width of the display in pixels.
 pub const WIDTH: usize = 480;
 
+/// The number of bytes per pixel for layer 1.
 pub const LAYER_1_OCTETS_PER_PIXEL: usize = 4;
+/// The length of the layer 1 buffer in bytes.
 pub const LAYER_1_LENGTH: usize = HEIGHT * WIDTH * LAYER_1_OCTETS_PER_PIXEL;
+/// The number of bytes per pixel for layer 2.
 pub const LAYER_2_OCTETS_PER_PIXEL: usize = 2;
+/// The length of the layer 1 buffer in bytes.
 pub const LAYER_2_LENGTH: usize = HEIGHT * WIDTH * LAYER_2_OCTETS_PER_PIXEL;
 
+/// Start address of the SDRAM where the framebuffers live.
 pub const SDRAM_START: usize = 0xC000_0000;
+/// Start address of the layer 1 framebuffer.
 pub const LAYER_1_START: usize = SDRAM_START;
+/// Start address of the layer 2 framebuffer.
 pub const LAYER_2_START: usize = SDRAM_START + LAYER_1_LENGTH;
 
+/// Represents the LCD and provides methods to access both layers.
 pub struct Lcd<'a> {
     controller: &'a mut LTDC,
     layer_1_in_use: bool,
@@ -37,12 +52,14 @@ impl<'a> Lcd<'a> {
         }
     }
 
+    /// Sets the color of the background layer.
     pub fn set_background_color(&mut self, color: Color) {
         self.controller
             .bccr
             .modify(|_, w| unsafe { w.bc().bits(color.to_rgb()) });
     }
 
+    /// Returns a reference to layer 1.
     pub fn layer_1(&mut self) -> Option<Layer<FramebufferArgb8888>> {
         if self.layer_1_in_use {
             None
@@ -53,6 +70,7 @@ impl<'a> Lcd<'a> {
         }
     }
 
+    /// Returns a reference to layer 2.
     pub fn layer_2(&mut self) -> Option<Layer<FramebufferAl88>> {
         if self.layer_2_in_use {
             None
@@ -64,10 +82,15 @@ impl<'a> Lcd<'a> {
     }
 }
 
+/// Represents a buffer of pixels.
 pub trait Framebuffer {
+    /// Set the pixel at the specified coordinates to the specified color.
     fn set_pixel(&mut self, x: usize, y: usize, color: Color);
 }
 
+/// A framebuffer in the ARGB8888 format.
+///
+/// It uses 8bits for alpha, red, green, and black respectively, totaling in 32bits per pixel.
 pub struct FramebufferArgb8888 {
     base_addr: usize,
 }
@@ -86,6 +109,10 @@ impl Framebuffer for FramebufferArgb8888 {
     }
 }
 
+/// A framebuffer in the AL88 format.
+///
+/// There are 8bits for the alpha channel and 8 bits for specifying a color using a
+/// lookup table. Thus, each pixel is represented by 16bits.
 pub struct FramebufferAl88 {
     base_addr: usize,
 }
@@ -104,11 +131,15 @@ impl Framebuffer for FramebufferAl88 {
     }
 }
 
+/// Represents a layer of the LCD controller.
 pub struct Layer<T> {
     framebuffer: T,
 }
 
 impl<T: Framebuffer> Layer<T> {
+    /// Fill the layer with horizontal stripes.
+    ///
+    /// Useful for testing.
     pub fn horizontal_stripes(&mut self) {
         let colors = [
             0xffffff, 0xcccccc, 0x999999, 0x666666, 0x333333, 0x0, 0xff0000, 0x0000ff,
@@ -126,6 +157,9 @@ impl<T: Framebuffer> Layer<T> {
         }
     }
 
+    /// Fill the layer with vertical stripes.
+    ///
+    /// Useful for testing.
     pub fn vertical_stripes(&mut self) {
         let colors = [
             0xcccccc, 0x999999, 0x666666, 0x333333, 0x0, 0xff0000, 0x0000ff, 0xffffff,
@@ -143,6 +177,9 @@ impl<T: Framebuffer> Layer<T> {
         }
     }
 
+    /// Clear all pixels.
+    ///
+    /// This method sets each pixel to transparent or black, depending on the framebuffer format.
     pub fn clear(&mut self) {
         for i in 0..HEIGHT {
             for j in 0..WIDTH {
@@ -151,17 +188,20 @@ impl<T: Framebuffer> Layer<T> {
         }
     }
 
+    /// Sets the pixel at the specified coordinates to white.
     pub fn print_point_at(&mut self, x: usize, y: usize) {
         self.print_point_color_at(x, y, Color::from_hex(0xffffff));
     }
 
+    /// Sets the pixel at the specified coordinates to the specified color.
     pub fn print_point_color_at(&mut self, x: usize, y: usize, color: Color) {
         assert!(x < WIDTH);
         assert!(y < HEIGHT);
 
         self.framebuffer.set_pixel(x, y, color);
     }
 
+    /// Creates a text writer on this layer.
     pub fn text_writer(&mut self) -> TextWriter<T> {
         TextWriter {
             layer: self,
@@ -171,13 +211,15 @@ impl<T: Framebuffer> Layer<T> {
     }
 }
 
+/// Allows to print audio data.
 pub struct AudioWriter {
     next_pixel: usize,
     next_col: usize,
     prev_value: (usize, usize),
 }
 
 impl AudioWriter {
+    /// Creates a new audio writer starting at the left edge of the screen.
     pub fn new() -> Self {
         AudioWriter {
             next_pixel: 0,
@@ -186,11 +228,15 @@ impl AudioWriter {
         }
     }
 
+    /// Sets the next pixel on the layer.
+    ///
+    /// Useful for testing.
     pub fn set_next_pixel<F: Framebuffer>(&mut self, layer: &mut Layer<F>, color: Color) {
         layer.print_point_color_at(self.next_pixel % WIDTH, self.next_pixel / WIDTH, color);
         self.next_pixel = (self.next_pixel + 1) % (HEIGHT * WIDTH);
     }
 
+    /// Sets the next column of the screen according to the passed audio data.
     pub fn set_next_col<F: Framebuffer>(&mut self, layer: &mut Layer<F>, value0: u32, value1: u32) {
         let value0 = value0 + 2u32.pow(15);
         let value0 = value0 as u16 as usize;
@@ -232,6 +278,10 @@ impl AudioWriter {
     }
 }
 
+/// Allows writing text to the wrapped layer.
+///
+/// This struct implements the [fmt::Write](core::fmt::Write) trait, which makes it possible
+/// to use the `writeln!` macro with this struct.
 pub struct TextWriter<'a, T: Framebuffer + 'a> {
     layer: &'a mut Layer<T>,
     x_pos: usize,

src/lcd/stdout.rs

@@ -1,3 +1,5 @@
+//! Initialize a LCD layer as standard output.
+
 use super::{FramebufferAl88, Layer, TextWriter};
 use core::fmt;
 use cortex_m::interrupt;
@@ -13,6 +15,10 @@ impl<'a> Stdout<'a> {
     }
 }
 
+/// Initialize the passed layer as standard output.
+///
+/// Subsequent calls to [`print`](print) or [`println!`](println!) will then print
+/// to the layer.
 pub fn init(layer: Layer<FramebufferAl88>) {
     static mut LAYER: Option<Layer<FramebufferAl88>> = None;
 
@@ -22,19 +28,32 @@ pub fn init(layer: Layer<FramebufferAl88>) {
     });
 }
 
+/// Prints to the LCD screen, appending a newline.
+///
+/// The LCD stdout must be initialized. See the [`lcd::stdout::print`](lcd::stdout::print)
+/// function for more information.
 #[macro_export]
 macro_rules! println {
     ($fmt:expr) => (print!(concat!($fmt, "\n")));
     ($fmt:expr, $($arg:tt)*) => (print!(concat!($fmt, "\n"), $($arg)*));
 }
 
+/// Prints to the LCD screen.
+///
+/// The LCD stdout must be initialized. See the [`lcd::stdout::print`](lcd::stdout::print)
+/// function for more information.
 #[macro_export]
 macro_rules! print {
     ($($arg:tt)*) => ({
         $crate::lcd::stdout::print(format_args!($($arg)*));
     });
 }
 
+/// Print to the standard output.
+///
+/// The easiest way to use this function is through the `write!`/`writeln` macros.
+///
+/// Panics if the standard output is not yet initialized.
 pub fn print(args: fmt::Arguments) {
     use core::fmt::Write;
     let mut uninitialized = false;
@@ -50,6 +69,7 @@ pub fn print(args: fmt::Arguments) {
     }
 }
 
+/// Returns whether the [`init`](init) function has already been called.
 pub fn is_initialized() -> bool {
     let mut initialized = false;
     STDOUT.with(|stdout| {