Struct flipdot_core::Page

pub struct Page<'a> { /* private fields */ }

A page of a message for display on a sign.

Examples

use flipdot_core::{Page, PageId};

let mut page = Page::new(PageId(1), 30, 10); // Create 30x10 page with ID 1
page.set_pixel(3, 5, true); // Turn on pixel at column 3 and row 5

Format Details

Data is stored in the native format, which consists of a 4-byte header and the data itself, padded to a a multiple of 16 bytes. The pixel data is column-major, with one or more bytes per column and one bit per pixel. The least significant bit is oriented toward the top of the display. The ID field is a “page number” used to identify individual pages in multi-page messages. The other bytes in the header are unknown, but from inspection of real ODKs seem to be most commonly 0x10 0x00 0x00, which is what Page::new currently uses.

                  ┌─┬ ┄ ┬─┐
             Bits │7│...│0│
                  └─┴ ┄ ┴─┘
                   \     /
┌────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬ ┄ ┬────┬ ┄ ┬────┐
│ ID │ ?? │ ?? │ ?? │  0 │  1 │  2 │  3 │  4 │  5 │...│0xFF│...│0xFF│
└────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴ ┄ ┴────┴ ┄ ┴────┘
┆   4-byte header   ┆            Data bytes           ┆   Padding   ┆

Depending on the intended dimensions of the sign, the same data will be interpreted differently:

                7 height                         16 height

                                           Bytes   0   2   4  ...
 Bytes   0   1   2   3   4   5  ...                1   3   5  ...
       ┌───┬───┬───┬───┬───┬───┬ ┄               ┌───┬───┬───┬ ┄
   0   │ 0 │ 0 │ 0 │ 0 │ 0 │ 0 │             0   │ 0 │ 0 │ 0 │
   |   ├───┼───┼───┼───┼───┼───┼ ┄           |   ├───┼───┼───┼ ┄
  Row  │...│...│...│...│...│...│             |   │...│...│...│
   |   ├───┼───┼───┼───┼───┼───┼ ┄           |   ├───┼───┼───┼ ┄
   7   │ 6 │ 6 │ 6 │ 6 │ 6 │ 6 │             |   │ 7 │ 7 │ 7 │
       └───┴───┴───┴───┴───┴───┴ ┄          Row  ╞═══╪═══╪═══╪ ┄
         0 - - - Column- - - 5               |   │ 0 │ 0 │ 0 │
                                             |   ├───┼───┼───┼ ┄
             (bit 7 unused)                  |   │...│...│...│
                                             |   ├───┼───┼───┼ ┄
                                            15   │ 7 │ 7 │ 7 │
                                                 └───┴───┴───┴ ┄
                                                  0 - Col - 2

Implementations

impl<'a> Page<'a>

pub fn new(id: PageId, width: u32, height: u32) -> Self

Creates a new Page with given ID and dimensions.

All pixels are initially set to off. The data is owned by this Page.

Examples

let page = Page::new(PageId(1), 90, 7); // Create 90x7 page with ID 1
assert_eq!(false, page.get_pixel(75, 3)); // All pixels initially off

pub fn from_bytes<T: Into<Cow<'a, [u8]>>>( width: u32, height: u32, bytes: T ) -> Result<Self, PageError>

Creates a new Page with given dimensions from the underlying byte representation.

The data must be convertible to Cow, which allows us to create efficient views of Pages over existing data without making copies.

It is the caller’s responsibility to ensure that the header and padding bytes are set appropriately as they are not validated.

Errors

Returns PageError::WrongPageLength if the data length does not match the specified dimensions.

Examples

let data: Vec<u8> = vec![1, 16, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 255, 255, 255, 255];
let page = Page::from_bytes(8, 8, data)?;
assert_eq!(PageId(1), page.id());
assert_eq!(true, page.get_pixel(0, 0));
assert_eq!(false, page.get_pixel(1, 0));

let bad_data: Vec<u8> = vec![1, 0, 0, 0, 1];
let bad_page = Page::from_bytes(1, 8, bad_data);
assert!(bad_page.is_err());

pub fn id(&self) -> PageId

Returns the ID (page number) of this page.

Examples

let page = Page::new(PageId(1), 90, 7);
println!("This is page {}", page.id().0);

pub fn width(&self) -> u32

Returns the width of this page.

Examples

let page = Page::new(PageId(1), 90, 7);
println!("Page is {} pixels wide", page.width());

pub fn height(&self) -> u32

Returns the height of this page.

Examples

let page = Page::new(PageId(1), 90, 7);
println!("Page is {} pixels tall", page.height());

pub fn get_pixel(&self, x: u32, y: u32) -> bool

Returns whether or not the pixel at the given (x, y) coordinate is on.

Panics

Panics if x or y is out of bounds.

Examples

let page = Page::new(PageId(1), 90, 7);
let (x, y) = (45, 2);
println!("Pixel at {}, {} on? {}", x, y, page.get_pixel(x, y));

pub fn set_pixel(&mut self, x: u32, y: u32, value: bool)

Turns the pixel at the given (x, y) coordinate on or off.

Panics

Panics if x or y is out of bounds.

Examples

let mut page = Page::new(PageId(1), 90, 7);
page.set_pixel(5, 5, true); // Turn on pixel...
page.set_pixel(5, 5, false); // And turn it back off.

pub fn set_all_pixels(&mut self, value: bool)

Turns all the pixels on the page on or off.

Examples

let mut page = Page::new(PageId(1), 90, 7);
// Turn on a couple pixels
page.set_pixel(5, 5, true);
page.set_pixel(6, 6, true);

// And clear the page again
page.set_all_pixels(false);

pub fn as_bytes(&self) -> &[u8]

Returns the raw byte representation of this page.

This is generally called on your behalf when sending a page to a sign.

Examples

let mut page = Page::new(PageId(1), 8, 8);
page.set_pixel(0, 0, true);
let bytes = page.as_bytes();
assert_eq!(vec![1, 16, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 255, 255, 255, 255], bytes);

Trait Implementations

impl<'a> Clone for Page<'a>

fn clone(&self) -> Page<'a>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for Page<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Page<'_>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the page for display using ASCII art.

Produces a multiline string with one character per pixel and a border. Should be displayed in a fixed-width font.

impl<'a> Hash for Page<'a>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'a> PartialEq for Page<'a>

fn eq(&self, other: &Page<'a>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a> Eq for Page<'a>

impl<'a> StructuralPartialEq for Page<'a>