vinzenz/servicepoint
0
0
Fork 0
mirror of https://github.com/cccb/servicepoint.git synced 2025-01-18 18:10:14 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

add links to documentation, add some docs

Browse source
This commit is contained in:
Vinzenz Schroeter 2024-10-10 23:17:19 +02:00
parent d3e135e508
commit 26bace8990
8 changed files with 88 additions and 33 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

65
crates/servicepoint/src/command.rs
View file

@ -18,13 +18,36 @@ pub type Cp437Grid = PrimitiveGrid<u8>;
///
/// This struct and associated functions implement the UDP protocol for the display.
///
/// To send a `Command`, use a `Connection`.
/// To send a [Command], use a [connection][crate::Connection].
///
/// # Available commands
///
/// To send text, take a look at [Command::Cp437Data].
///
/// To draw pixels, the easiest command to use is [Command::BitmapLinearWin].
///
/// The other BitmapLinear-Commands operate on a region of pixel memory directly.
/// [Command::BitmapLinear] overwrites a region.
/// [Command::BitmapLinearOr], [Command::BitmapLinearAnd] and [Command::BitmapLinearXor] apply logical operations per pixel.
///
/// Out of bounds operations may be truncated or ignored by the display.
///
/// # Compression
///
/// Some commands can contain compressed payloads.
/// To get started, use [CompressionCode::Uncompressed].
///
/// If you want to archive the best performance (e.g. latency),
/// you can try the different compression algorithms for your hardware and use case.
///
/// In memory, the payload is not compressed in the [Command].
/// Payload (de-)compression happens when converting the [Command] into a [Packet] or vice versa.
///
/// # Examples
///
/// ```rust
/// # use servicepoint::{Brightness, Command, Connection, Packet};
///
/// #
/// // create command
/// let command = Command::Brightness(Brightness::MAX);
///
@ -56,6 +79,8 @@ pub enum Command {
/// Show text on the screen.
///
/// The text is sent in the form of a 2D grid of characters.
///
/// <div class="warning">
/// The library does not currently convert between UTF-8 and CP-437.
/// Because Rust expects UTF-8 strings, it might be necessary to only send ASCII for now.
@ -72,7 +97,29 @@ pub enum Command {
/// ```
Cp437Data(Origin<Tiles>, Cp437Grid),
/// Sets a window of pixels to the specified values
/// Overwrites a rectangular region of pixels.
///
/// Origin coordinates must be divisible by 8.
///
/// # Examples
///
/// ```rust
/// # use servicepoint::{Command, CompressionCode, Grid, PixelGrid};
/// # let connection = servicepoint::Connection::Fake;
/// #
/// let mut pixels = PixelGrid::max_sized();
/// // draw something to the pixels here
/// # pixels.set(2, 5, true);
///
/// // create command to send pixels
/// let command = Command::BitmapLinearWin(
/// servicepoint::Origin::new(0, 0),
/// pixels,
/// CompressionCode::Uncompressed
/// );
///
/// connection.send(command).expect("send failed");
/// ```
BitmapLinearWin(Origin<Pixels>, PixelGrid, CompressionCode),
/// Set the brightness of all tiles to the same value.
@ -95,7 +142,7 @@ pub enum Command {
/// The screen will continuously overwrite more pixel data without regarding the offset, meaning
/// once the starting row is full, overwriting will continue on column 0.
///
/// The contained `BitVec` is always uncompressed.
/// The contained [BitVec] is always uncompressed.
BitmapLinear(Offset, SpBitVec, CompressionCode),
/// Set pixel data according to an and-mask starting at the offset.
@ -103,7 +150,7 @@ pub enum Command {
/// The screen will continuously overwrite more pixel data without regarding the offset, meaning
/// once the starting row is full, overwriting will continue on column 0.
///
/// The contained `BitVec` is always uncompressed.
/// The contained [BitVec] is always uncompressed.
BitmapLinearAnd(Offset, SpBitVec, CompressionCode),
/// Set pixel data according to an or-mask starting at the offset.
@ -111,7 +158,7 @@ pub enum Command {
/// The screen will continuously overwrite more pixel data without regarding the offset, meaning
/// once the starting row is full, overwriting will continue on column 0.
///
/// The contained `BitVec` is always uncompressed.
/// The contained [BitVec] is always uncompressed.
BitmapLinearOr(Offset, SpBitVec, CompressionCode),
/// Set pixel data according to a xor-mask starting at the offset.
@ -119,7 +166,7 @@ pub enum Command {
/// The screen will continuously overwrite more pixel data without regarding the offset, meaning
/// once the starting row is full, overwriting will continue on column 0.
///
/// The contained `BitVec` is always uncompressed.
/// The contained [BitVec] is always uncompressed.
BitmapLinearXor(Offset, SpBitVec, CompressionCode),
/// Kills the udp daemon on the display, which usually results in a restart.
@ -166,7 +213,7 @@ pub enum Command {
}
#[derive(Debug)]
/// Err values for `Command::try_from`.
/// Err values for [Command::try_from].
#[derive(PartialEq)]
pub enum TryFromPacketError {
/// the contained command code does not correspond to a known command
@ -188,7 +235,7 @@ pub enum TryFromPacketError {
impl TryFrom<Packet> for Command {
type Error = TryFromPacketError;
/// Try to interpret the `Packet` as one containing a `Command`
/// Try to interpret the [Packet] as one containing a [Command]
fn try_from(packet: Packet) -> Result<Self, Self::Error> {
let Packet {
header: Header {

2
crates/servicepoint/src/command_code.rs
View file

@ -1,4 +1,4 @@
/// The u16 command codes used for the `Commands`.
/// The u16 command codes used for the [Command]s.
#[repr(u16)]
#[derive(Debug, Copy, Clone)]
pub(crate) enum CommandCode {

2
crates/servicepoint/src/connection.rs
View file

@ -7,6 +7,8 @@ use crate::Packet;
/// A connection to the display.
///
/// Used to send [Packets][Packet] or [Commands][crate::Command].
///
/// # Examples
/// ```rust
/// let connection = servicepoint::Connection::open("172.23.42.29:2342")

4
crates/servicepoint/src/lib.rs
View file

@ -1,5 +1,9 @@
//! Abstractions for the UDP protocol of the CCCB servicepoint display.
//!
//! Your starting point is a [Connection] to the display.
//! With a connection, you can send [Command]s.
//! When received, the display will update the state of the pixels.
//!
//! # Examples
//!
//! ```rust

2
crates/servicepoint/src/origin.rs
View file

@ -11,7 +11,7 @@ pub struct Origin<Unit: DisplayUnit> {
}
impl<Unit: DisplayUnit> Origin<Unit> {
/// Create a new `Origin` instance for the provided position.
/// Create a new [Origin] instance for the provided position.
pub fn new(x: usize, y: usize) -> Self {
Self {
x,

12
crates/servicepoint/src/packet.rs
View file

@ -38,6 +38,8 @@ pub type Payload = Vec<u8>;
///
/// Contents should probably only be used directly to use features not exposed by the library.
///
/// You may want to use [Command][crate::Command] instead.
///
/// # Examples
///
/// Converting a packet to a command and back:
@ -46,7 +48,7 @@ pub type Payload = Vec<u8>;
/// # use servicepoint::{Command, Packet};
/// # let command = Command::Clear;
/// let packet: Packet = command.into();
/// let command: Command = Command::try_from(packet).expect("could not read packet");
/// let command: Command = Command::try_from(packet).expect("could not read command from packet");
/// ```
///
/// Converting a packet to bytes and back:
@ -98,9 +100,9 @@ impl From<Packet> for Vec<u8> {
impl TryFrom<&[u8]> for Packet {
type Error = ();
/// Tries to interpret the bytes as a `Packet`.
/// Tries to interpret the bytes as a [Packet].
///
/// returns: `Error` if slice is not long enough to be a `Packet`
/// returns: `Error` if slice is not long enough to be a [Packet]
fn try_from(value: &[u8]) -> Result<Self, Self::Error> {
if value.len() < size_of::<Header>() {
return Err(());
@ -135,7 +137,7 @@ impl TryFrom<Vec<u8>> for Packet {
}
impl From<Command> for Packet {
/// Move the `Command` into a `Packet` instance for sending.
/// Move the [Command] into a [Packet] instance for sending.
#[allow(clippy::cast_possible_truncation)]
fn from(value: Command) -> Self {
match value {
@ -210,7 +212,7 @@ impl From<Command> for Packet {
}
impl Packet {
/// Helper method for `BitMapLinear*`-Commands into `Packet`
/// Helper method for `BitMapLinear*`-Commands into [Packet]
#[allow(clippy::cast_possible_truncation)]
fn bitmap_linear_into_packet(
command: CommandCode,

20
crates/servicepoint/src/pixel_grid.rs
View file

@ -13,14 +13,14 @@ pub struct PixelGrid {
}
impl PixelGrid {
/// Creates a new `PixelGrid` with the specified dimensions.
/// Creates a new [PixelGrid] with the specified dimensions.
///
/// # Arguments
///
/// - `width`: size in pixels in x-direction
/// - `height`: size in pixels in y-direction
///
/// returns: `PixelGrid` initialized to all pixels off
/// returns: [PixelGrid] initialized to all pixels off
///
/// # Panics
///
@ -40,14 +40,14 @@ impl PixelGrid {
Self::new(PIXEL_WIDTH, PIXEL_HEIGHT)
}
/// Loads a `PixelGrid` with the specified dimensions from the provided data.
/// Loads a [PixelGrid] with the specified dimensions from the provided data.
///
/// # Arguments
///
/// - `width`: size in pixels in x-direction
/// - `height`: size in pixels in y-direction
///
/// returns: `PixelGrid` that contains a copy of the provided data
/// returns: [PixelGrid] that contains a copy of the provided data
///
/// # Panics
///
@ -64,7 +64,7 @@ impl PixelGrid {
}
}
/// Iterate over all cells in `PixelGrid`.
/// Iterate over all cells in [PixelGrid].
///
/// Order is equivalent to the following loop:
/// ```
@ -80,7 +80,7 @@ impl PixelGrid {
self.bit_vec.iter().by_refs()
}
/// Iterate over all cells in `PixelGrid` mutably.
/// Iterate over all cells in [PixelGrid] mutably.
///
/// Order is equivalent to the following loop:
/// ```
@ -107,7 +107,7 @@ impl PixelGrid {
self.bit_vec.iter_mut()
}
/// Iterate over all rows in `PixelGrid` top to bottom.
/// Iterate over all rows in [PixelGrid] top to bottom.
pub fn iter_rows(&self) -> IterRows {
IterRows {
pixel_grid: self,
@ -117,7 +117,7 @@ impl PixelGrid {
}
impl Grid<bool> for PixelGrid {
/// Sets the value of the specified position in the `PixelGrid`.
/// Sets the value of the specified position in the [PixelGrid].
///
/// # Arguments
///
@ -139,7 +139,7 @@ impl Grid<bool> for PixelGrid {
self.bit_vec[x + y * self.width]
}
/// Sets the state of all pixels in the `PixelGrid`.
/// Sets the state of all pixels in the [PixelGrid].
///
/// # Arguments
///
@ -169,7 +169,7 @@ impl DataRef<u8> for PixelGrid {
}
impl From<PixelGrid> for Vec<u8> {
/// Turns a `PixelGrid` into the underlying `Vec<u8>`.
/// Turns a [PixelGrid] into the underlying [`Vec<u8>`].
fn from(value: PixelGrid) -> Self {
value.bit_vec.into()
}

14
crates/servicepoint/src/primitive_grid.rs
View file

@ -14,14 +14,14 @@ pub struct PrimitiveGrid<T: PrimitiveGridType> {
}
impl<T: PrimitiveGridType> PrimitiveGrid<T> {
/// Creates a new `PrimitiveGrid` with the specified dimensions.
/// Creates a new [PrimitiveGrid] with the specified dimensions.
///
/// # Arguments
///
/// - width: size in x-direction
/// - height: size in y-direction
///
/// returns: `PrimitiveGrid` initialized to default value.
/// returns: [PrimitiveGrid] initialized to default value.
pub fn new(width: usize, height: usize) -> Self {
Self {
data: vec![Default::default(); width * height],
@ -30,9 +30,9 @@ impl<T: PrimitiveGridType> PrimitiveGrid<T> {
}
}
/// Loads a `PrimitiveGrid` with the specified dimensions from the provided data.
/// Loads a [PrimitiveGrid] with the specified dimensions from the provided data.
///
/// returns: `PrimitiveGrid` that contains a copy of the provided data
/// returns: [PrimitiveGrid] that contains a copy of the provided data
///
/// # Panics
///
@ -47,7 +47,7 @@ impl<T: PrimitiveGridType> PrimitiveGrid<T> {
}
}
/// Iterate over all cells in `PrimitiveGrid`.
/// Iterate over all cells in [PrimitiveGrid].
///
/// Order is equivalent to the following loop:
/// ```
@ -63,7 +63,7 @@ impl<T: PrimitiveGridType> PrimitiveGrid<T> {
self.data.iter()
}
/// Iterate over all rows in `PrimitiveGrid` top to bottom.
/// Iterate over all rows in [PrimitiveGrid] top to bottom.
pub fn iter_rows(&self) -> IterRows<T> {
IterRows {
byte_grid: self,
@ -168,7 +168,7 @@ impl<T: PrimitiveGridType> DataRef<T> for PrimitiveGrid<T> {
}
impl<T: PrimitiveGridType> From<PrimitiveGrid<T>> for Vec<T> {
/// Turn into the underlying `Vec<u8>` containing the rows of bytes.
/// Turn into the underlying [`Vec<u8>`] containing the rows of bytes.
fn from(value: PrimitiveGrid<T>) -> Self {
value.data
}