summaryrefslogtreecommitdiffstats
path: root/src
diff options
context:
space:
mode:
authorAgathe Porte <microjoe@microjoe.org>2020-02-27 18:26:56 +0100
committerAgathe Porte <microjoe@microjoe.org>2020-02-27 18:26:56 +0100
commitefd3048e098d3157774e3f39baeb7246f65423ff (patch)
tree328d34366bc523c6128e3219450e765ebb5f97ca /src
parentd01183e06c75a2a9d4ce619b63b808258cd7c100 (diff)
downloadcharlcd-efd3048e098d3157774e3f39baeb7246f65423ff.tar.gz
charlcd-efd3048e098d3157774e3f39baeb7246f65423ff.zip
first try at documenting custom_char module
Diffstat (limited to 'src')
-rw-r--r--src/custom_char.rs41
-rw-r--r--src/lib.rs31
2 files changed, 71 insertions, 1 deletions
diff --git a/src/custom_char.rs b/src/custom_char.rs
index 47f99f5..cd43cf7 100644
--- a/src/custom_char.rs
+++ b/src/custom_char.rs
@@ -1,3 +1,40 @@
+//! Create custom characters by defining their pixels.
+//!
+//! A custom character is considered as a 8x5 pixel array.
+//!
+//! You can declare a custom character by defining an array of type `[u8; 8]`
+//! where:
+//!
+//! - each byte represents a line;
+//! - each bit in the byte represent a pixel.
+//!
+//! Only the 5 lower bits of the byte are used, because the character width is
+//! 5 pixels.
+//!
+//! # Example
+//!
+//! ```
+//! /// ▸
+//! #[cfg_attr(rustfmt, rustfmt_skip)]
+//! pub const RIGHT_ARROW: [u8; 8] = [
+//! 0b00000,
+//! 0b01000,
+//! 0b01100,
+//! 0b01110,
+//! 0b01100,
+//! 0b01000,
+//! 0b00000,
+//! 0b00000,
+//! ];
+//! ```
+//!
+//! The `#[cfg_attr(rustfmt, rustfmt_skip)]` part is required in order to
+//! avoid `rustfmt` put each item after the next one so that we cannot see the
+//! visual pixel representation of the custom character anymore.
+//!
+//! The custom character can then be put into the screen's memory by using the
+//! [`Screen::custom_char`][super::Screen::custom_char] function.
+
/// X axis mirror of a custom LCD character
pub const fn mirror_x(src: [u8; 8]) -> [u8; 8] {
// const fn do not support for loops currently, hence manual unroll
@@ -21,6 +58,7 @@ pub const fn mirror_y(src: [u8; 8]) -> [u8; 8] {
]
}
+/// ▸
#[cfg_attr(rustfmt, rustfmt_skip)]
pub const RIGHT_ARROW: [u8; 8] = [
0b00000,
@@ -33,8 +71,10 @@ pub const RIGHT_ARROW: [u8; 8] = [
0b00000,
];
+/// ◂
pub const LEFT_ARROW: [u8; 8] = mirror_x(RIGHT_ARROW);
+/// ▴
#[cfg_attr(rustfmt, rustfmt_skip)]
pub const UP_ARROW: [u8; 8] = [
0b00000,
@@ -47,4 +87,5 @@ pub const UP_ARROW: [u8; 8] = [
0b00000,
];
+/// ▾
pub const DOWN_ARROW: [u8; 8] = mirror_y(UP_ARROW);
diff --git a/src/lib.rs b/src/lib.rs
index e69ade8..23c7830 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -762,7 +762,36 @@ where
write_simple_code!(self, SpecialCode::LargeFont)
}
- /// Custom character create
+ /// Store a custom character into the screen memory for future usage.
+ ///
+ /// See also [`custom_char`] module for a global explanation on how to
+ /// declare custom characters, as well as a list of already defined custom
+ /// characters.
+ ///
+ /// # Example
+ ///
+ /// ```no_run
+ /// extern crate charlcd;
+ ///
+ /// use std::io::Write;
+ /// use charlcd::{Screen, custom_char};
+ ///
+ /// fn main() -> std::io::Result<()> {
+ /// let mut screen = Screen::default()?;
+ ///
+ /// screen.reinit()?;
+ ///
+ /// // Store the custom ▸ character in the screen memory, code 0
+ /// screen.custom_char(0, custom_char::RIGHT_ARROW)?;
+ ///
+ /// // Print custom character from screen memory, code 0
+ /// screen.write(b"\x00")?;
+ /// screen.flush()?;
+ ///
+ /// Ok(())
+ /// }
+ /// ```
+ ///
pub fn custom_char(&mut self, code: u8, value: [u8; 8]) -> std::io::Result<()> {
let mut res = 0u64;
let mut i = 0;