From 26bace8990cfb4c91b40006639733e75c80e316a Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Thu, 10 Oct 2024 23:17:19 +0200 Subject: [PATCH] add links to documentation, add some docs --- crates/servicepoint/src/command.rs | 65 +++++++++++++++++++---- crates/servicepoint/src/command_code.rs | 2 +- crates/servicepoint/src/connection.rs | 2 + crates/servicepoint/src/lib.rs | 4 ++ crates/servicepoint/src/origin.rs | 2 +- crates/servicepoint/src/packet.rs | 12 +++-- crates/servicepoint/src/pixel_grid.rs | 20 +++---- crates/servicepoint/src/primitive_grid.rs | 14 ++--- 8 files changed, 88 insertions(+), 33 deletions(-) diff --git a/crates/servicepoint/src/command.rs b/crates/servicepoint/src/command.rs index d799696..24cf84c 100644 --- a/crates/servicepoint/src/command.rs +++ b/crates/servicepoint/src/command.rs @@ -18,13 +18,36 @@ pub type Cp437Grid = PrimitiveGrid; /// /// 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. + /// ///
/// 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, 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, 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 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 { let Packet { header: Header { diff --git a/crates/servicepoint/src/command_code.rs b/crates/servicepoint/src/command_code.rs index 25df1c9..4735e44 100644 --- a/crates/servicepoint/src/command_code.rs +++ b/crates/servicepoint/src/command_code.rs @@ -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 { diff --git a/crates/servicepoint/src/connection.rs b/crates/servicepoint/src/connection.rs index 032ffeb..40c9a5c 100644 --- a/crates/servicepoint/src/connection.rs +++ b/crates/servicepoint/src/connection.rs @@ -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") diff --git a/crates/servicepoint/src/lib.rs b/crates/servicepoint/src/lib.rs index d71e1fa..e646e24 100644 --- a/crates/servicepoint/src/lib.rs +++ b/crates/servicepoint/src/lib.rs @@ -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 diff --git a/crates/servicepoint/src/origin.rs b/crates/servicepoint/src/origin.rs index 88758a5..0e7680a 100644 --- a/crates/servicepoint/src/origin.rs +++ b/crates/servicepoint/src/origin.rs @@ -11,7 +11,7 @@ pub struct Origin { } impl Origin { - /// 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, diff --git a/crates/servicepoint/src/packet.rs b/crates/servicepoint/src/packet.rs index 67c96b4..c09cb42 100644 --- a/crates/servicepoint/src/packet.rs +++ b/crates/servicepoint/src/packet.rs @@ -38,6 +38,8 @@ pub type Payload = Vec; /// /// 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; /// # 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 for Vec { 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 { if value.len() < size_of::
() { return Err(()); @@ -135,7 +137,7 @@ impl TryFrom> for Packet { } impl From 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 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, diff --git a/crates/servicepoint/src/pixel_grid.rs b/crates/servicepoint/src/pixel_grid.rs index 4b8bcc7..746f2ac 100644 --- a/crates/servicepoint/src/pixel_grid.rs +++ b/crates/servicepoint/src/pixel_grid.rs @@ -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 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 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 for PixelGrid { } impl From for Vec { - /// Turns a `PixelGrid` into the underlying `Vec`. + /// Turns a [PixelGrid] into the underlying [`Vec`]. fn from(value: PixelGrid) -> Self { value.bit_vec.into() } diff --git a/crates/servicepoint/src/primitive_grid.rs b/crates/servicepoint/src/primitive_grid.rs index d1a507e..2b02ca3 100644 --- a/crates/servicepoint/src/primitive_grid.rs +++ b/crates/servicepoint/src/primitive_grid.rs @@ -14,14 +14,14 @@ pub struct PrimitiveGrid { } impl PrimitiveGrid { - /// 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 PrimitiveGrid { } } - /// 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 PrimitiveGrid { } } - /// Iterate over all cells in `PrimitiveGrid`. + /// Iterate over all cells in [PrimitiveGrid]. /// /// Order is equivalent to the following loop: /// ``` @@ -63,7 +63,7 @@ impl PrimitiveGrid { 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 { IterRows { byte_grid: self, @@ -168,7 +168,7 @@ impl DataRef for PrimitiveGrid { } impl From> for Vec { - /// Turn into the underlying `Vec` containing the rows of bytes. + /// Turn into the underlying [`Vec`] containing the rows of bytes. fn from(value: PrimitiveGrid) -> Self { value.data }