diff --git a/.envrc b/.envrc new file mode 100644 index 0000000..1d953f4 --- /dev/null +++ b/.envrc @@ -0,0 +1 @@ +use nix diff --git a/Cargo.lock b/Cargo.lock index e253757..0b18f51 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -540,7 +540,7 @@ dependencies = [ [[package]] name = "servicepoint" -version = "0.5.0" +version = "0.5.1" dependencies = [ "bzip2", "clap 4.5.4", @@ -553,7 +553,7 @@ dependencies = [ [[package]] name = "servicepoint_binding_c" -version = "0.5.0" +version = "0.5.1" dependencies = [ "cbindgen", "servicepoint", @@ -561,7 +561,7 @@ dependencies = [ [[package]] name = "servicepoint_binding_cs" -version = "0.5.0" +version = "0.5.1" dependencies = [ "csbindgen", "servicepoint", diff --git a/Cargo.toml b/Cargo.toml index 6379c5c..f63ed07 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -8,4 +8,7 @@ members = [ ] [workspace.package] -version = "0.5.0" +version = "0.5.1" + +[workspace.lints.rust] +missing-docs = "warn" diff --git a/crates/servicepoint/Cargo.toml b/crates/servicepoint/Cargo.toml index 6ae0b0e..5e748e3 100644 --- a/crates/servicepoint/Cargo.toml +++ b/crates/servicepoint/Cargo.toml @@ -30,4 +30,7 @@ all_compressions = ["compression_zlib", "compression_bzip2", "compression_lzma", [dev-dependencies] # for examples clap = { version = "4.5", features = ["derive"] } -rand = "0.8" \ No newline at end of file +rand = "0.8" + +[lints] +workspace = true diff --git a/crates/servicepoint/README.md b/crates/servicepoint/README.md index 9d7064b..ed412ab 100644 --- a/crates/servicepoint/README.md +++ b/crates/servicepoint/README.md @@ -18,7 +18,7 @@ fn main() { .expect("connection failed"); // clear screen content - connection.send(servicepoint::Command::Clear.into()) + connection.send(servicepoint::Command::Clear) .expect("send failed"); } ``` @@ -46,7 +46,7 @@ In the likely case you only need one of them, you can include that one specifica ```toml [dependencies] -servicepoint = { version = "0.5.0", default-features = false, features = ["compression-bz"] } +servicepoint = { version = "0.5.1", default-features = false, features = ["compression-bz"] } ``` ## Everything else diff --git a/crates/servicepoint/examples/announce.rs b/crates/servicepoint/examples/announce.rs index 31d19d2..b165135 100644 --- a/crates/servicepoint/examples/announce.rs +++ b/crates/servicepoint/examples/announce.rs @@ -1,3 +1,5 @@ +//! An example for how to send text to the display. + use clap::Parser; use servicepoint::{ByteGrid, Command, Connection, Grid, Origin}; diff --git a/crates/servicepoint/examples/game_of_life.rs b/crates/servicepoint/examples/game_of_life.rs index aef929e..9fff62e 100644 --- a/crates/servicepoint/examples/game_of_life.rs +++ b/crates/servicepoint/examples/game_of_life.rs @@ -1,3 +1,5 @@ +//! A simple game of life implementation to show how to render graphics to the display. + use std::thread; use clap::Parser; diff --git a/crates/servicepoint/examples/moving_line.rs b/crates/servicepoint/examples/moving_line.rs index 2037146..f0353be 100644 --- a/crates/servicepoint/examples/moving_line.rs +++ b/crates/servicepoint/examples/moving_line.rs @@ -1,3 +1,5 @@ +//! A simple example for how to send pixel data to the display. + use std::thread; use clap::Parser; diff --git a/crates/servicepoint/examples/random_brightness.rs b/crates/servicepoint/examples/random_brightness.rs index 7e3c4e8..d9ea583 100644 --- a/crates/servicepoint/examples/random_brightness.rs +++ b/crates/servicepoint/examples/random_brightness.rs @@ -1,3 +1,6 @@ +//! A simple example for how to set brightnesses for tiles on the screen. +//! Continuously changes the tiles in a random window to random brightnesses. + use std::time::Duration; use clap::Parser; diff --git a/crates/servicepoint/examples/wiping_clear.rs b/crates/servicepoint/examples/wiping_clear.rs index 3f255d8..1295fc4 100644 --- a/crates/servicepoint/examples/wiping_clear.rs +++ b/crates/servicepoint/examples/wiping_clear.rs @@ -1,3 +1,4 @@ +//! An example on how to modify the image on screen without knowing the current content. use std::thread; use std::time::Duration; diff --git a/crates/servicepoint/src/bit_vec.rs b/crates/servicepoint/src/bit_vec.rs index 0f3e262..7b2d5c1 100644 --- a/crates/servicepoint/src/bit_vec.rs +++ b/crates/servicepoint/src/bit_vec.rs @@ -1,6 +1,6 @@ use crate::DataRef; -/// A vector of bits +/// A fixed-size vector of bits #[derive(Debug, Clone, PartialEq)] pub struct BitVec { size: usize, @@ -8,17 +8,17 @@ pub struct BitVec { } impl BitVec { - /// Create a new bit vector. + /// Create a new `BitVec`. /// /// # Arguments /// - /// * `size`: size in bits. Must be dividable by 8. + /// * `size`: size in bits. /// - /// returns: bit vector with all bits set to false. + /// returns: `BitVec` with all bits set to false. /// /// # Panics /// - /// When size is not a multiple of 8. + /// When `size` is not divisible by 8. #[must_use] pub fn new(size: usize) -> BitVec { assert_eq!(size % 8, 0); @@ -36,6 +36,10 @@ impl BitVec { /// * `value`: the value to set the bit to /// /// returns: old value of the bit + /// + /// # Panics + /// + /// When accessing `index` out of bounds. pub fn set(&mut self, index: usize, value: bool) -> bool { let (byte_index, bit_mask) = self.get_indexes(index); @@ -58,6 +62,10 @@ impl BitVec { /// * `index`: the bit index to read /// /// returns: value of the bit + /// + /// # Panics + /// + /// When accessing `index` out of bounds. #[must_use] pub fn get(&self, index: usize) -> bool { let (byte_index, bit_mask) = self.get_indexes(index); diff --git a/crates/servicepoint/src/byte_grid.rs b/crates/servicepoint/src/byte_grid.rs index 9a17ead..d9b515c 100644 --- a/crates/servicepoint/src/byte_grid.rs +++ b/crates/servicepoint/src/byte_grid.rs @@ -52,6 +52,18 @@ impl Grid for ByteGrid { } } + /// Sets the value of the cell at the specified position in the `ByteGrid. + /// + /// # Arguments + /// + /// * `x` and `y`: position of the cell + /// * `value`: the value to write to the cell + /// + /// returns: old value of the cell. + /// + /// # Panics + /// + /// When accessing `x` or `y` out of bounds. fn set(&mut self, x: usize, y: usize, value: u8) -> u8 { self.check_indexes(x, y); let pos = &mut self.data[x + y * self.width]; @@ -60,6 +72,15 @@ impl Grid for ByteGrid { old_val } + /// Gets the current value at the specified position. + /// + /// # Arguments + /// + /// * `x` and `y`: position of the cell to read + /// + /// # Panics + /// + /// When accessing `x` or `y` out of bounds. fn get(&self, x: usize, y: usize) -> u8 { self.check_indexes(x, y); self.data[x + y * self.width] diff --git a/crates/servicepoint/src/compression_code.rs b/crates/servicepoint/src/compression_code.rs index 19984ad..44bed3c 100644 --- a/crates/servicepoint/src/compression_code.rs +++ b/crates/servicepoint/src/compression_code.rs @@ -2,14 +2,19 @@ #[repr(u16)] #[derive(Debug, Clone, Copy, PartialEq)] pub enum CompressionCode { + /// no compression Uncompressed = 0x0, #[cfg(feature = "compression_zlib")] + /// compress using flate2 with zlib header Zlib = 0x677a, #[cfg(feature = "compression_bzip2")] + /// compress using bzip2 Bzip2 = 0x627a, #[cfg(feature = "compression_lzma")] + /// compress using lzma Lzma = 0x6c7a, #[cfg(feature = "compression_zstd")] + /// compress using Zstandard Zstd = 0x7a73, } diff --git a/crates/servicepoint/src/grid.rs b/crates/servicepoint/src/grid.rs index 55cab90..1a53f77 100644 --- a/crates/servicepoint/src/grid.rs +++ b/crates/servicepoint/src/grid.rs @@ -1,5 +1,14 @@ +/// A two-dimensional grid of `T` pub trait Grid { #[must_use] + /// Creates a new Grid with the specified dimensions. + /// + /// # Arguments + /// + /// - width: size in x-direction + /// - height: size in y-direction + /// + /// returns: Grid with all cells initialized to default state. fn new(width: usize, height: usize) -> Self; /// Sets the value at the specified position diff --git a/crates/servicepoint/src/lib.rs b/crates/servicepoint/src/lib.rs index 5b3bcea..d68801c 100644 --- a/crates/servicepoint/src/lib.rs +++ b/crates/servicepoint/src/lib.rs @@ -1,3 +1,5 @@ +//! Abstractions for the UDP protocol of the CCCB servicepoint display. + use std::time::Duration; pub use crate::bit_vec::BitVec; @@ -42,3 +44,8 @@ pub const PIXEL_COUNT: usize = PIXEL_WIDTH * PIXEL_HEIGHT; /// Actual hardware limit is around 28-29ms/frame. Rounded up for less dropped packets. pub const FRAME_PACING: Duration = Duration::from_millis(30); + +// include README.md in doctest +#[doc = include_str!("../README.md")] +#[cfg(doctest)] +pub struct ReadmeDocTests; diff --git a/crates/servicepoint/src/pixel_grid.rs b/crates/servicepoint/src/pixel_grid.rs index bead3da..2b7ec20 100644 --- a/crates/servicepoint/src/pixel_grid.rs +++ b/crates/servicepoint/src/pixel_grid.rs @@ -75,15 +75,42 @@ impl Grid for PixelGrid { } } + /// Sets the value of the specified position in the `PixelGrid`. + /// + /// # Arguments + /// + /// * `x` and `y`: position of the cell + /// * `value`: the value to write to the cell + /// + /// returns: old value of the cell + /// + /// # Panics + /// + /// When accessing `x` or `y` out of bounds. fn set(&mut self, x: usize, y: usize, value: bool) -> bool { self.check_indexes(x, y); self.bit_vec.set(x + y * self.width, value) } + /// Gets the current value at the specified position. + /// + /// # Arguments + /// + /// * `x` and `y`: position of the cell to read + /// + /// # Panics + /// + /// When accessing `x` or `y` out of bounds. fn get(&self, x: usize, y: usize) -> bool { self.bit_vec.get(x + y * self.width) } + /// Sets the state of all pixels in the `PixelGrid`. + /// + /// # Arguments + /// + /// * `this`: instance to write to + /// * `value`: the value to set all pixels to fn fill(&mut self, value: bool) { self.bit_vec.fill(value); } diff --git a/crates/servicepoint_binding_c/Cargo.toml b/crates/servicepoint_binding_c/Cargo.toml index 4146255..ccb4514 100644 --- a/crates/servicepoint_binding_c/Cargo.toml +++ b/crates/servicepoint_binding_c/Cargo.toml @@ -1,11 +1,11 @@ [package] name = "servicepoint_binding_c" version.workspace = true -publish = false +publish = true edition = "2021" license = "GPL-3.0-or-later" description = "C bindings for the servicepoint crate." -homepage = "https://docs.rs/crate/servicepoint" +homepage = "https://docs.rs/crate/servicepoint_binding_c" repository = "https://github.com/cccb/servicepoint" readme = "README.md" links = "servicepoint" @@ -17,6 +17,9 @@ crate-type = ["staticlib", "cdylib", "rlib"] cbindgen = "0.26.0" [dependencies.servicepoint] -version = "0.5.0" +version = "0.5.1" path = "../servicepoint" features = ["all_compressions"] + +[lints] +workspace = true diff --git a/crates/servicepoint_binding_c/README.md b/crates/servicepoint_binding_c/README.md index 1a86753..fb2c70c 100644 --- a/crates/servicepoint_binding_c/README.md +++ b/crates/servicepoint_binding_c/README.md @@ -5,8 +5,9 @@ [![docs.rs](https://img.shields.io/docsrs/servicepoint_binding_c)](https://docs.rs/servicepoint/latest/servicepoint/) [![GPLv3 licensed](https://img.shields.io/crates/l/servicepoint_binding_c)](../../LICENSE) -In [CCCB](https://berlin.ccc.de/), there is a big pixel matrix hanging on the wall. It is called "Service Point -Display" or "Airport Display". +In [CCCB](https://berlin.ccc.de/), there is a big pixel matrix hanging on the wall. +It is called "Service Point Display" or "Airport Display". + This crate contains C bindings for the `servicepoint` library, enabling users to parse, encode and send packets to this display via UDP. ## Examples diff --git a/crates/servicepoint_binding_c/build.rs b/crates/servicepoint_binding_c/build.rs index 10505b0..93bf703 100644 --- a/crates/servicepoint_binding_c/build.rs +++ b/crates/servicepoint_binding_c/build.rs @@ -1,3 +1,9 @@ +//! Build script generating the header for the `servicepoint` C library. +//! +//! When the environment variable `SERVICEPOINT_HEADER_OUT` is set, the header is copied there from +//! the out directory. This can be used to use the build script as a command line tool from other +//! build tools. + use std::{env, fs::copy}; use cbindgen::{generate_with_config, Config}; diff --git a/crates/servicepoint_binding_c/examples/lang_c/Makefile b/crates/servicepoint_binding_c/examples/lang_c/Makefile index 787d38e..86cf49c 100644 --- a/crates/servicepoint_binding_c/examples/lang_c/Makefile +++ b/crates/servicepoint_binding_c/examples/lang_c/Makefile @@ -1,7 +1,7 @@ CC := gcc THIS_DIR := $(dir $(realpath $(lastword $(MAKEFILE_LIST)))) -REPO_ROOT := $(THIS_DIR)/../.. +REPO_ROOT := $(THIS_DIR)/../../../.. build: out/lang_c diff --git a/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h b/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h index cc1e903..465a89a 100644 --- a/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h +++ b/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h @@ -44,10 +44,25 @@ enum sp_CompressionCode : uint16_t #endif // __cplusplus { + /** + * no compression + */ Uncompressed = 0, + /** + * compress using flate2 with zlib header + */ Zlib = 26490, + /** + * compress using bzip2 + */ Bzip2 = 25210, + /** + * compress using lzma + */ Lzma = 27770, + /** + * compress using Zstandard + */ Zstd = 31347, }; #ifndef __cplusplus @@ -55,7 +70,7 @@ typedef uint16_t sp_CompressionCode; #endif // __cplusplus /** - * A vector of bits + * A fixed-size vector of bits */ typedef struct sp_BitVec sp_BitVec; @@ -87,7 +102,13 @@ typedef struct sp_PixelGrid sp_PixelGrid; /** * Represents a span of memory (`&mut [u8]` ) as a struct usable by C code. * - * Usage of this type is inherently unsafe. + * # Safety + * + * The caller has to make sure that: + * + * - accesses to the memory pointed to with `start` is never accessed outside `length` + * - the lifetime of the `CByteSlice` does not outlive the memory it points to, as described in + * the function returning this type. */ typedef struct sp_CByteSlice { /** @@ -116,51 +137,150 @@ extern "C" { /** * Clones a `BitVec`. - * The returned instance has to be freed with `bit_vec_dealloc`. + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `BitVec` + * - `this` is not written to concurrently + * - the returned instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_bit_vec_dealloc`. */ struct sp_BitVec *sp_bit_vec_clone(const struct sp_BitVec *this_); /** * Deallocates a `BitVec`. * - * Note: do not call this if the grid has been consumed in another way, e.g. to create a command. + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `BitVec` + * - `this` is not used concurrently or after this call + * - `this` was not passed to another consuming function, e.g. to create a `Command` */ void sp_bit_vec_dealloc(struct sp_BitVec *this_); /** * Sets the value of all bits in the `BitVec`. + * + * # Arguments + * + * * `value`: the value to set all bits to + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `BitVec` + * - `this` is not written to or read from concurrently */ void sp_bit_vec_fill(struct sp_BitVec *this_, bool value); /** * Gets the value of a bit from the `BitVec`. + * + * # Arguments + * + * * `this`: instance to read from + * * `index`: the bit index to read + * + * returns: value of the bit + * + * # Panics + * + * When accessing `index` out of bounds. + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `BitVec` + * - `this` is not written to concurrently */ bool sp_bit_vec_get(const struct sp_BitVec *this_, size_t index); /** * Returns true if length is 0. + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `BitVec` */ bool sp_bit_vec_is_empty(const struct sp_BitVec *this_); /** * Gets the length of the `BitVec` in bits. + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `BitVec` */ size_t sp_bit_vec_len(const struct sp_BitVec *this_); /** - * Loads a `BitVec` from the provided data. - * The returned instance has to be freed with `bit_vec_dealloc`. + * Interpret the data as a series of bits and load then into a new `BitVec` instance. + * + * # Safety + * + * The caller has to make sure that: + * + * - `data` points to a valid memory location of at least `data_length` + * bytes in size. + * - the returned instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_bit_vec_dealloc`. */ -struct sp_BitVec *sp_bit_vec_load(const uint8_t *data, size_t data_length); +struct sp_BitVec *sp_bit_vec_load(const uint8_t *data, + size_t data_length); /** * Creates a new `BitVec` instance. - * The returned instance has to be freed with `bit_vec_dealloc`. + * + * # Arguments + * + * * `size`: size in bits. + * + * returns: `BitVec` with all bits set to false. + * + * # Panics + * + * When `size` is not divisible by 8. + * + * # Safety + * + * The caller has to make sure that: + * + * - the returned instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_bit_vec_dealloc`. */ struct sp_BitVec *sp_bit_vec_new(size_t size); /** * Sets the value of a bit in the `BitVec`. + * + * # Arguments + * + * * `this`: instance to write to + * * `index`: the bit index to edit + * * `value`: the value to set the bit to + * + * returns: old value of the bit + * + * # Panics + * + * When accessing `index` out of bounds. + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `BitVec` + * - `this` is not written to or read from concurrently */ bool sp_bit_vec_set(struct sp_BitVec *this_, size_t index, bool value); @@ -169,45 +289,109 @@ bool sp_bit_vec_set(struct sp_BitVec *this_, size_t index, bool value); * * ## Safety * - * The caller has to make sure to never access the returned memory after the `BitVec` - * instance has been consumed or manually deallocated. + * The caller has to make sure that: * - * Reading and writing concurrently to either the original instance or the returned data will - * result in undefined behavior. + * - `this` points to a valid `BitVec` + * - the returned memory range is never accessed after the passed `BitVec` has been freed + * - the returned memory range is never accessed concurrently, either via the `BitVec` or directly */ struct sp_CByteSlice sp_bit_vec_unsafe_data_ref(struct sp_BitVec *this_); /** * Clones a `ByteGrid`. - * The returned instance has to be freed with `byte_grid_dealloc`. + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `ByteGrid` + * - `this` is not written to concurrently + * - the returned instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_byte_grid_dealloc`. */ struct sp_ByteGrid *sp_byte_grid_clone(const struct sp_ByteGrid *this_); /** * Deallocates a `ByteGrid`. * - * Note: do not call this if the grid has been consumed in another way, e.g. to create a command. + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `ByteGrid` + * - `this` is not used concurrently or after this call + * - `this` was not passed to another consuming function, e.g. to create a `Command` */ void sp_byte_grid_dealloc(struct sp_ByteGrid *this_); /** - * Fills the whole `ByteGrid` with the specified value + * Sets the value of all cells in the `ByteGrid`. + * + * # Arguments + * + * * `this`: instance to write to + * * `value`: the value to set all cells to + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `ByteGrid` + * - `this` is not written to or read from concurrently */ void sp_byte_grid_fill(struct sp_ByteGrid *this_, uint8_t value); /** - * Get the current value at the specified position + * Gets the current value at the specified position. + * + * # Arguments + * + * * `this`: instance to read from + * * `x` and `y`: position of the cell to read + * + * # Panics + * + * When accessing `x` or `y` out of bounds. + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `ByteGrid` + * - `this` is not written to concurrently */ uint8_t sp_byte_grid_get(const struct sp_ByteGrid *this_, size_t x, size_t y); /** - * Gets the height in pixels of the `ByteGrid` instance. + * Gets the height of the `ByteGrid` instance. + * + * # Arguments + * + * * `this`: instance to read from + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `ByteGrid` */ size_t sp_byte_grid_height(const struct sp_ByteGrid *this_); /** * Loads a `ByteGrid` with the specified dimensions from the provided data. - * The returned instance has to be freed with `byte_grid_dealloc`. + * + * # Panics + * + * When the provided `data_length` is not sufficient for the `height` and `width` + * + * # Safety + * + * The caller has to make sure that: + * + * - `data` points to a valid memory location of at least `data_length` + * bytes in size. + * - the returned instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_byte_grid_dealloc`. */ struct sp_ByteGrid *sp_byte_grid_load(size_t width, size_t height, @@ -215,13 +399,41 @@ struct sp_ByteGrid *sp_byte_grid_load(size_t width, size_t data_length); /** - * Creates a new `ByteGrid` instance. - * The returned instance has to be freed with `byte_grid_dealloc`. + * Creates a new `ByteGrid` with the specified dimensions. + * + * returns: `ByteGrid` initialized to 0. + * + * # Safety + * + * The caller has to make sure that: + * + * - the returned instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_byte_grid_dealloc`. */ -struct sp_ByteGrid *sp_byte_grid_new(size_t width, size_t height); +struct sp_ByteGrid *sp_byte_grid_new(size_t width, + size_t height); /** - * Sets the current value at the specified position + * Sets the value of the specified position in the `ByteGrid`. + * + * # Arguments + * + * * `this`: instance to write to + * * `x` and `y`: position of the cell + * * `value`: the value to write to the cell + * + * returns: old value of the cell + * + * # Panics + * + * When accessing `x` or `y` out of bounds. + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `BitVec` + * - `this` is not written to or read from concurrently */ void sp_byte_grid_set(struct sp_ByteGrid *this_, size_t x, @@ -233,22 +445,42 @@ void sp_byte_grid_set(struct sp_ByteGrid *this_, * * ## Safety * - * The caller has to make sure to never access the returned memory after the `ByteGrid` - * instance has been consumed or manually deallocated. + * The caller has to make sure that: * - * Reading and writing concurrently to either the original instance or the returned data will - * result in undefined behavior. + * - `this` points to a valid `ByteGrid` + * - the returned memory range is never accessed after the passed `ByteGrid` has been freed + * - the returned memory range is never accessed concurrently, either via the `ByteGrid` or directly */ struct sp_CByteSlice sp_byte_grid_unsafe_data_ref(struct sp_ByteGrid *this_); /** - * Gets the width in pixels of the `ByteGrid` instance. + * Gets the width of the `ByteGrid` instance. + * + * # Arguments + * + * * `this`: instance to read from + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `ByteGrid` */ size_t sp_byte_grid_width(const struct sp_ByteGrid *this_); /** * Allocates a new `Command::BitmapLinear` instance. - * The passed `BitVec` gets deallocated in the process. + * The passed `BitVec` gets consumed. + * + * # Safety + * + * The caller has to make sure that: + * + * - `bit_vec` points to a valid instance of `BitVec` + * - `bit_vec` is not used concurrently or after this call + * - `compression` matches one of the allowed enum values + * - the returned `Command` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_command_dealloc`. */ struct sp_Command *sp_command_bitmap_linear(sp_Offset offset, struct sp_BitVec *bit_vec, @@ -256,7 +488,17 @@ struct sp_Command *sp_command_bitmap_linear(sp_Offset offset, /** * Allocates a new `Command::BitmapLinearAnd` instance. - * The passed `BitVec` gets deallocated in the process. + * The passed `BitVec` gets consumed. + * + * # Safety + * + * The caller has to make sure that: + * + * - `bit_vec` points to a valid instance of `BitVec` + * - `bit_vec` is not used concurrently or after this call + * - `compression` matches one of the allowed enum values + * - the returned `Command` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_command_dealloc`. */ struct sp_Command *sp_command_bitmap_linear_and(sp_Offset offset, struct sp_BitVec *bit_vec, @@ -264,7 +506,17 @@ struct sp_Command *sp_command_bitmap_linear_and(sp_Offset offset, /** * Allocates a new `Command::BitmapLinearOr` instance. - * The passed `BitVec` gets deallocated in the process. + * The passed `BitVec` gets consumed. + * + * # Safety + * + * The caller has to make sure that: + * + * - `bit_vec` points to a valid instance of `BitVec` + * - `bit_vec` is not used concurrently or after this call + * - `compression` matches one of the allowed enum values + * - the returned `Command` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_command_dealloc`. */ struct sp_Command *sp_command_bitmap_linear_or(sp_Offset offset, struct sp_BitVec *bit_vec, @@ -272,95 +524,213 @@ struct sp_Command *sp_command_bitmap_linear_or(sp_Offset offset, /** * Allocates a new `Command::BitmapLinearWin` instance. - * The passed `PixelGrid` gets deallocated in the process. + * The passed `PixelGrid` gets consumed. + * + * # Safety + * + * The caller has to make sure that: + * + * - `pixel_grid` points to a valid instance of `PixelGrid` + * - `pixel_grid` is not used concurrently or after this call + * - `compression` matches one of the allowed enum values + * - the returned `Command` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_command_dealloc`. */ struct sp_Command *sp_command_bitmap_linear_win(size_t x, size_t y, - struct sp_PixelGrid *byte_grid, + struct sp_PixelGrid *pixel_grid, sp_CompressionCode compression_code); /** * Allocates a new `Command::BitmapLinearXor` instance. - * The passed `BitVec` gets deallocated in the process. + * The passed `BitVec` gets consumed. + * + * # Safety + * + * The caller has to make sure that: + * + * - `bit_vec` points to a valid instance of `BitVec` + * - `bit_vec` is not used concurrently or after this call + * - `compression` matches one of the allowed enum values + * - the returned `Command` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_command_dealloc`. */ struct sp_Command *sp_command_bitmap_linear_xor(sp_Offset offset, struct sp_BitVec *bit_vec, sp_CompressionCode compression); /** - * Allocates a new `Command::Brightness` instance + * Allocates a new `Command::Brightness` instance. + * + * # Safety + * + * The caller has to make sure that: + * + * - the returned `Command` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_command_dealloc`. */ struct sp_Command *sp_command_brightness(sp_Brightness brightness); /** * Allocates a new `Command::CharBrightness` instance. - * The passed `ByteGrid` gets deallocated in the process. + * The passed `ByteGrid` gets consumed. + * + * # Safety + * + * The caller has to make sure that: + * + * - `byte_grid` points to a valid instance of `ByteGrid` + * - `byte_grid` is not used concurrently or after this call + * - the returned `Command` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_command_dealloc`. */ struct sp_Command *sp_command_char_brightness(size_t x, size_t y, struct sp_ByteGrid *byte_grid); /** - * Allocates a new `Command::Clear` instance + * Allocates a new `Command::Clear` instance. + * + * # Safety + * + * The caller has to make sure that: + * + * - the returned `Command` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_command_dealloc`. */ struct sp_Command *sp_command_clear(void); /** - * Clones a `Command` instance + * Clones a `Command` instance. + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid instance of `Command` + * - `this` is not written to concurrently + * - the returned `Command` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_command_dealloc`. */ struct sp_Command *sp_command_clone(const struct sp_Command *original); /** * Allocates a new `Command::Cp437Data` instance. - * The passed `ByteGrid` gets deallocated in the process. + * The passed `ByteGrid` gets consumed. + * + * # Safety + * + * The caller has to make sure that: + * + * - `byte_grid` points to a valid instance of `ByteGrid` + * - `byte_grid` is not used concurrently or after this call + * - the returned `Command` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_command_dealloc`. */ struct sp_Command *sp_command_cp437_data(size_t x, size_t y, struct sp_ByteGrid *byte_grid); /** - * Deallocates a `Command`. Note that connection_send does this implicitly, so you only need - * to do this if you use the library for parsing commands. + * Deallocates a `Command`. + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `Command` + * - `this` is not used concurrently or after this call + * - `this` was not passed to another consuming function, e.g. to create a `Packet` */ void sp_command_dealloc(struct sp_Command *ptr); /** - * Allocates a new `Command::FadeOut` instance + * Allocates a new `Command::FadeOut` instance. + * + * # Safety + * + * The caller has to make sure that: + * + * - the returned `Command` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_command_dealloc`. */ struct sp_Command *sp_command_fade_out(void); /** - * Allocates a new `Command::HardReset` instance + * Allocates a new `Command::HardReset` instance. + * + * # Safety + * + * The caller has to make sure that: + * + * - the returned `Command` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_command_dealloc`. */ struct sp_Command *sp_command_hard_reset(void); /** - * Tries to turn a `Packet` into a `Command`. The packet is gets deallocated in the process. + * Tries to turn a `Packet` into a `Command`. The packet is deallocated in the process. * - * Returns: pointer to command or NULL + * Returns: pointer to new `Command` instance or NULL + * + * # Safety + * + * The caller has to make sure that: + * + * - `packet` points to a valid instance of `Packet` + * - `packet` is not used concurrently or after this call + * - the result is checked for NULL + * - the returned `Command` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_command_dealloc`. */ struct sp_Command *sp_command_try_from_packet(struct sp_Packet *packet); /** - * Closes and deallocates a connection instance + * Closes and deallocates a `Connection`. + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `Connection` + * - `this` is not used concurrently or after this call */ void sp_connection_dealloc(struct sp_Connection *ptr); /** - * Creates a new instance of Connection. - * The returned instance has to be deallocated with `connection_dealloc`. + * Creates a new instance of `Connection`. * - * returns: NULL if connection fails or connected instance + * returns: NULL if connection fails, or connected instance * - * Panics: bad string encoding + * # Panics + * + * Bad string encoding + * + * # Safety + * + * The caller has to make sure that: + * + * - the returned instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_connection_dealloc`. */ struct sp_Connection *sp_connection_open(const char *host); /** - * Sends the command instance. The instance is consumed / destroyed and cannot be used after this call. + * Sends a `Packet` to the display using the `Connection`. + * The passed `Packet` gets consumed. + * + * returns: true in case of success + * + * # Safety + * + * The caller has to make sure that: + * + * - `connection` points to a valid instance of `Connection` + * - `packet` points to a valid instance of `Packet` + * - `packet` is not used concurrently or after this call */ bool sp_connection_send(const struct sp_Connection *connection, - struct sp_Packet *command_ptr); + struct sp_Packet *packet); /** * Deallocates a `Packet`. @@ -370,7 +740,17 @@ bool sp_connection_send(const struct sp_Connection *connection, void sp_packet_dealloc(struct sp_Packet *this_); /** - * Turns a `Command` into a `Packet`. The command gets deallocated in the process. + * Turns a `Command` into a `Packet`. + * The `Command` gets consumed. + * + * # Safety + * + * The caller has to make sure that: + * + * - `command` points to a valid instance of `Command` + * - `command` is not used concurrently or after this call + * - the returned `Packet` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_packet_dealloc`. */ struct sp_Packet *sp_packet_from_command(struct sp_Command *command); @@ -378,40 +758,121 @@ struct sp_Packet *sp_packet_from_command(struct sp_Command *command); * Tries to load a `Packet` from the passed array with the specified length. * * returns: NULL in case of an error, pointer to the allocated packet otherwise + * + * # Safety + * + * The caller has to make sure that: + * + * - `data` points to a valid memory region of at least `length` bytes + * - `data` is not written to concurrently + * - the returned `Packet` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_packet_dealloc`. */ -struct sp_Packet *sp_packet_try_load(const uint8_t *data, size_t length); +struct sp_Packet *sp_packet_try_load(const uint8_t *data, + size_t length); /** * Clones a `PixelGrid`. - * The returned instance has to be freed with `pixel_grid_dealloc`. + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `PixelGrid` + * - `this` is not written to concurrently + * - the returned instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_pixel_grid_dealloc`. */ struct sp_PixelGrid *sp_pixel_grid_clone(const struct sp_PixelGrid *this_); /** * Deallocates a `PixelGrid`. * - * Note: do not call this if the grid has been consumed in another way, e.g. to create a command. + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `PixelGrid` + * - `this` is not used concurrently or after this call + * - `this` was not passed to another consuming function, e.g. to create a `Command` */ void sp_pixel_grid_dealloc(struct sp_PixelGrid *this_); /** - * Fills the whole `PixelGrid` with the specified value + * Sets the state of all pixels in the `PixelGrid`. + * + * # Arguments + * + * * `this`: instance to write to + * * `value`: the value to set all pixels to + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `PixelGrid` + * - `this` is not written to or read from concurrently */ void sp_pixel_grid_fill(struct sp_PixelGrid *this_, bool value); /** - * Get the current value at the specified position + * Gets the current value at the specified position in the `PixelGrid`. + * + * # Arguments + * + * * `this`: instance to read from + * * `x` and `y`: position of the cell to read + * + * # Panics + * + * When accessing `x` or `y` out of bounds. + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `PixelGrid` + * - `this` is not written to concurrently */ bool sp_pixel_grid_get(const struct sp_PixelGrid *this_, size_t x, size_t y); /** * Gets the height in pixels of the `PixelGrid` instance. + * + * # Arguments + * + * * `this`: instance to read from + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `PixelGrid` */ size_t sp_pixel_grid_height(const struct sp_PixelGrid *this_); /** * Loads a `PixelGrid` with the specified dimensions from the provided data. - * The returned instance has to be freed with `pixel_grid_dealloc`. + * + * # 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 + * + * # Panics + * + * - when the dimensions and data size do not match exactly. + * - when the width is not dividable by 8 + * + * # Safety + * + * The caller has to make sure that: + * + * - `data` points to a valid memory location of at least `data_length` bytes in size. + * - the returned instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_pixel_grid_dealloc`. */ struct sp_PixelGrid *sp_pixel_grid_load(size_t width, size_t height, @@ -419,13 +880,50 @@ struct sp_PixelGrid *sp_pixel_grid_load(size_t width, size_t data_length); /** - * Creates a new `PixelGrid` instance. - * The returned instance has to be freed with `pixel_grid_dealloc`. + * 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 + * + * # Panics + * + * - when the width is not dividable by 8 + * + * # Safety + * + * The caller has to make sure that: + * + * - the returned instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_pixel_grid_dealloc`. */ -struct sp_PixelGrid *sp_pixel_grid_new(size_t width, size_t height); +struct sp_PixelGrid *sp_pixel_grid_new(size_t width, + size_t height); /** - * Sets the current value at the specified position + * Sets the value of the specified position in the `PixelGrid`. + * + * # Arguments + * + * * `this`: instance to write to + * * `x` and `y`: position of the cell + * * `value`: the value to write to the cell + * + * returns: old value of the cell + * + * # Panics + * + * When accessing `x` or `y` out of bounds. + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `PixelGrid` + * - `this` is not written to or read from concurrently */ void sp_pixel_grid_set(struct sp_PixelGrid *this_, size_t x, @@ -437,16 +935,26 @@ void sp_pixel_grid_set(struct sp_PixelGrid *this_, * * ## Safety * - * The caller has to make sure to never access the returned memory after the `PixelGrid` - * instance has been consumed or manually deallocated. + * The caller has to make sure that: * - * Reading and writing concurrently to either the original instance or the returned data will - * result in undefined behavior. + * - `this` points to a valid `PixelGrid` + * - the returned memory range is never accessed after the passed `PixelGrid` has been freed + * - the returned memory range is never accessed concurrently, either via the `PixelGrid` or directly */ struct sp_CByteSlice sp_pixel_grid_unsafe_data_ref(struct sp_PixelGrid *this_); /** * Gets the width in pixels of the `PixelGrid` instance. + * + * # Arguments + * + * * `this`: instance to read from + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `PixelGrid` */ size_t sp_pixel_grid_width(const struct sp_PixelGrid *this_); diff --git a/crates/servicepoint_binding_c/src/bit_vec.rs b/crates/servicepoint_binding_c/src/bit_vec.rs index dfeb5d4..582e97d 100644 --- a/crates/servicepoint_binding_c/src/bit_vec.rs +++ b/crates/servicepoint_binding_c/src/bit_vec.rs @@ -4,14 +4,38 @@ use servicepoint::DataRef; use crate::c_slice::CByteSlice; /// Creates a new `BitVec` instance. -/// The returned instance has to be freed with `bit_vec_dealloc`. +/// +/// # Arguments +/// +/// * `size`: size in bits. +/// +/// returns: `BitVec` with all bits set to false. +/// +/// # Panics +/// +/// When `size` is not divisible by 8. +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - the returned instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_bit_vec_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_bit_vec_new(size: usize) -> *mut BitVec { Box::into_raw(Box::new(BitVec::new(size))) } -/// Loads a `BitVec` from the provided data. -/// The returned instance has to be freed with `bit_vec_dealloc`. +/// Interpret the data as a series of bits and load then into a new `BitVec` instance. +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `data` points to a valid memory location of at least `data_length` +/// bytes in size. +/// - the returned instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_bit_vec_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_bit_vec_load( data: *const u8, @@ -22,7 +46,15 @@ pub unsafe extern "C" fn sp_bit_vec_load( } /// Clones a `BitVec`. -/// The returned instance has to be freed with `bit_vec_dealloc`. +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `this` points to a valid `BitVec` +/// - `this` is not written to concurrently +/// - the returned instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_bit_vec_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_bit_vec_clone(this: *const BitVec) -> *mut BitVec { Box::into_raw(Box::new((*this).clone())) @@ -30,13 +62,37 @@ pub unsafe extern "C" fn sp_bit_vec_clone(this: *const BitVec) -> *mut BitVec { /// Deallocates a `BitVec`. /// -/// Note: do not call this if the grid has been consumed in another way, e.g. to create a command. +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `this` points to a valid `BitVec` +/// - `this` is not used concurrently or after this call +/// - `this` was not passed to another consuming function, e.g. to create a `Command` #[no_mangle] pub unsafe extern "C" fn sp_bit_vec_dealloc(this: *mut BitVec) { _ = Box::from_raw(this); } /// Gets the value of a bit from the `BitVec`. +/// +/// # Arguments +/// +/// * `this`: instance to read from +/// * `index`: the bit index to read +/// +/// returns: value of the bit +/// +/// # Panics +/// +/// When accessing `index` out of bounds. +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `this` points to a valid `BitVec` +/// - `this` is not written to concurrently #[no_mangle] pub unsafe extern "C" fn sp_bit_vec_get( this: *const BitVec, @@ -46,6 +102,25 @@ pub unsafe extern "C" fn sp_bit_vec_get( } /// Sets the value of a bit in the `BitVec`. +/// +/// # Arguments +/// +/// * `this`: instance to write to +/// * `index`: the bit index to edit +/// * `value`: the value to set the bit to +/// +/// returns: old value of the bit +/// +/// # Panics +/// +/// When accessing `index` out of bounds. +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `this` points to a valid `BitVec` +/// - `this` is not written to or read from concurrently #[no_mangle] pub unsafe extern "C" fn sp_bit_vec_set( this: *mut BitVec, @@ -56,18 +131,41 @@ pub unsafe extern "C" fn sp_bit_vec_set( } /// Sets the value of all bits in the `BitVec`. +/// +/// # Arguments +/// +/// * `value`: the value to set all bits to +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `this` points to a valid `BitVec` +/// - `this` is not written to or read from concurrently #[no_mangle] pub unsafe extern "C" fn sp_bit_vec_fill(this: *mut BitVec, value: bool) { (*this).fill(value) } /// Gets the length of the `BitVec` in bits. +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `this` points to a valid `BitVec` #[no_mangle] pub unsafe extern "C" fn sp_bit_vec_len(this: *const BitVec) -> usize { (*this).len() } /// Returns true if length is 0. +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `this` points to a valid `BitVec` #[no_mangle] pub unsafe extern "C" fn sp_bit_vec_is_empty(this: *const BitVec) -> bool { (*this).is_empty() @@ -77,11 +175,11 @@ pub unsafe extern "C" fn sp_bit_vec_is_empty(this: *const BitVec) -> bool { /// /// ## Safety /// -/// The caller has to make sure to never access the returned memory after the `BitVec` -/// instance has been consumed or manually deallocated. +/// The caller has to make sure that: /// -/// Reading and writing concurrently to either the original instance or the returned data will -/// result in undefined behavior. +/// - `this` points to a valid `BitVec` +/// - the returned memory range is never accessed after the passed `BitVec` has been freed +/// - the returned memory range is never accessed concurrently, either via the `BitVec` or directly #[no_mangle] pub unsafe extern "C" fn sp_bit_vec_unsafe_data_ref( this: *mut BitVec, diff --git a/crates/servicepoint_binding_c/src/byte_grid.rs b/crates/servicepoint_binding_c/src/byte_grid.rs index 124420f..d5dabb1 100644 --- a/crates/servicepoint_binding_c/src/byte_grid.rs +++ b/crates/servicepoint_binding_c/src/byte_grid.rs @@ -3,8 +3,16 @@ use servicepoint::{DataRef, Grid}; use crate::c_slice::CByteSlice; -/// Creates a new `ByteGrid` instance. -/// The returned instance has to be freed with `byte_grid_dealloc`. +/// Creates a new `ByteGrid` with the specified dimensions. +/// +/// returns: `ByteGrid` initialized to 0. +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - the returned instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_byte_grid_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_byte_grid_new( width: usize, @@ -14,7 +22,19 @@ pub unsafe extern "C" fn sp_byte_grid_new( } /// Loads a `ByteGrid` with the specified dimensions from the provided data. -/// The returned instance has to be freed with `byte_grid_dealloc`. +/// +/// # Panics +/// +/// When the provided `data_length` is not sufficient for the `height` and `width` +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `data` points to a valid memory location of at least `data_length` +/// bytes in size. +/// - the returned instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_byte_grid_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_byte_grid_load( width: usize, @@ -27,7 +47,15 @@ pub unsafe extern "C" fn sp_byte_grid_load( } /// Clones a `ByteGrid`. -/// The returned instance has to be freed with `byte_grid_dealloc`. +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `this` points to a valid `ByteGrid` +/// - `this` is not written to concurrently +/// - the returned instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_byte_grid_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_byte_grid_clone( this: *const ByteGrid, @@ -37,13 +65,35 @@ pub unsafe extern "C" fn sp_byte_grid_clone( /// Deallocates a `ByteGrid`. /// -/// Note: do not call this if the grid has been consumed in another way, e.g. to create a command. +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `this` points to a valid `ByteGrid` +/// - `this` is not used concurrently or after this call +/// - `this` was not passed to another consuming function, e.g. to create a `Command` #[no_mangle] pub unsafe extern "C" fn sp_byte_grid_dealloc(this: *mut ByteGrid) { _ = Box::from_raw(this); } -/// Get the current value at the specified position +/// Gets the current value at the specified position. +/// +/// # Arguments +/// +/// * `this`: instance to read from +/// * `x` and `y`: position of the cell to read +/// +/// # Panics +/// +/// When accessing `x` or `y` out of bounds. +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `this` points to a valid `ByteGrid` +/// - `this` is not written to concurrently #[no_mangle] pub unsafe extern "C" fn sp_byte_grid_get( this: *const ByteGrid, @@ -53,7 +103,26 @@ pub unsafe extern "C" fn sp_byte_grid_get( (*this).get(x, y) } -/// Sets the current value at the specified position +/// Sets the value of the specified position in the `ByteGrid`. +/// +/// # Arguments +/// +/// * `this`: instance to write to +/// * `x` and `y`: position of the cell +/// * `value`: the value to write to the cell +/// +/// returns: old value of the cell +/// +/// # Panics +/// +/// When accessing `x` or `y` out of bounds. +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `this` points to a valid `BitVec` +/// - `this` is not written to or read from concurrently #[no_mangle] pub unsafe extern "C" fn sp_byte_grid_set( this: *mut ByteGrid, @@ -64,19 +133,51 @@ pub unsafe extern "C" fn sp_byte_grid_set( (*this).set(x, y, value); } -/// Fills the whole `ByteGrid` with the specified value +/// Sets the value of all cells in the `ByteGrid`. +/// +/// # Arguments +/// +/// * `this`: instance to write to +/// * `value`: the value to set all cells to +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `this` points to a valid `ByteGrid` +/// - `this` is not written to or read from concurrently #[no_mangle] pub unsafe extern "C" fn sp_byte_grid_fill(this: *mut ByteGrid, value: u8) { (*this).fill(value); } -/// Gets the width in pixels of the `ByteGrid` instance. +/// Gets the width of the `ByteGrid` instance. +/// +/// # Arguments +/// +/// * `this`: instance to read from +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `this` points to a valid `ByteGrid` #[no_mangle] pub unsafe extern "C" fn sp_byte_grid_width(this: *const ByteGrid) -> usize { (*this).width() } -/// Gets the height in pixels of the `ByteGrid` instance. +/// Gets the height of the `ByteGrid` instance. +/// +/// # Arguments +/// +/// * `this`: instance to read from +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `this` points to a valid `ByteGrid` #[no_mangle] pub unsafe extern "C" fn sp_byte_grid_height(this: *const ByteGrid) -> usize { (*this).height() @@ -86,11 +187,11 @@ pub unsafe extern "C" fn sp_byte_grid_height(this: *const ByteGrid) -> usize { /// /// ## Safety /// -/// The caller has to make sure to never access the returned memory after the `ByteGrid` -/// instance has been consumed or manually deallocated. +/// The caller has to make sure that: /// -/// Reading and writing concurrently to either the original instance or the returned data will -/// result in undefined behavior. +/// - `this` points to a valid `ByteGrid` +/// - the returned memory range is never accessed after the passed `ByteGrid` has been freed +/// - the returned memory range is never accessed concurrently, either via the `ByteGrid` or directly #[no_mangle] pub unsafe extern "C" fn sp_byte_grid_unsafe_data_ref( this: *mut ByteGrid, diff --git a/crates/servicepoint_binding_c/src/c_slice.rs b/crates/servicepoint_binding_c/src/c_slice.rs index 9609906..b255c1b 100644 --- a/crates/servicepoint_binding_c/src/c_slice.rs +++ b/crates/servicepoint_binding_c/src/c_slice.rs @@ -1,7 +1,13 @@ #[repr(C)] /// Represents a span of memory (`&mut [u8]` ) as a struct usable by C code. /// -/// Usage of this type is inherently unsafe. +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - accesses to the memory pointed to with `start` is never accessed outside `length` +/// - the lifetime of the `CByteSlice` does not outlive the memory it points to, as described in +/// the function returning this type. pub struct CByteSlice { /// The start address of the memory pub start: *mut u8, diff --git a/crates/servicepoint_binding_c/src/command.rs b/crates/servicepoint_binding_c/src/command.rs index 2d4e7a1..23b9b7a 100644 --- a/crates/servicepoint_binding_c/src/command.rs +++ b/crates/servicepoint_binding_c/src/command.rs @@ -5,9 +5,19 @@ use servicepoint::{ }; pub use servicepoint::{Brightness, Command, Offset}; -/// Tries to turn a `Packet` into a `Command`. The packet is gets deallocated in the process. +/// Tries to turn a `Packet` into a `Command`. The packet is deallocated in the process. /// -/// Returns: pointer to command or NULL +/// Returns: pointer to new `Command` instance or NULL +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `packet` points to a valid instance of `Packet` +/// - `packet` is not used concurrently or after this call +/// - the result is checked for NULL +/// - the returned `Command` instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_command_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_command_try_from_packet( packet: *mut Packet, @@ -19,7 +29,16 @@ pub unsafe extern "C" fn sp_command_try_from_packet( } } -/// Clones a `Command` instance +/// Clones a `Command` instance. +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `this` points to a valid instance of `Command` +/// - `this` is not written to concurrently +/// - the returned `Command` instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_command_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_command_clone( original: *const Command, @@ -27,25 +46,53 @@ pub unsafe extern "C" fn sp_command_clone( Box::into_raw(Box::new((*original).clone())) } -/// Allocates a new `Command::Clear` instance +/// Allocates a new `Command::Clear` instance. +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - the returned `Command` instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_command_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_command_clear() -> *mut Command { Box::into_raw(Box::new(Command::Clear)) } -/// Allocates a new `Command::HardReset` instance +/// Allocates a new `Command::HardReset` instance. +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - the returned `Command` instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_command_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_command_hard_reset() -> *mut Command { Box::into_raw(Box::new(Command::HardReset)) } -/// Allocates a new `Command::FadeOut` instance +/// Allocates a new `Command::FadeOut` instance. +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - the returned `Command` instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_command_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_command_fade_out() -> *mut Command { Box::into_raw(Box::new(Command::FadeOut)) } -/// Allocates a new `Command::Brightness` instance +/// Allocates a new `Command::Brightness` instance. +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - the returned `Command` instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_command_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_command_brightness( brightness: Brightness, @@ -54,7 +101,16 @@ pub unsafe extern "C" fn sp_command_brightness( } /// Allocates a new `Command::CharBrightness` instance. -/// The passed `ByteGrid` gets deallocated in the process. +/// The passed `ByteGrid` gets consumed. +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `byte_grid` points to a valid instance of `ByteGrid` +/// - `byte_grid` is not used concurrently or after this call +/// - the returned `Command` instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_command_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_command_char_brightness( x: usize, @@ -66,7 +122,17 @@ pub unsafe extern "C" fn sp_command_char_brightness( } /// Allocates a new `Command::BitmapLinear` instance. -/// The passed `BitVec` gets deallocated in the process. +/// The passed `BitVec` gets consumed. +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `bit_vec` points to a valid instance of `BitVec` +/// - `bit_vec` is not used concurrently or after this call +/// - `compression` matches one of the allowed enum values +/// - the returned `Command` instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_command_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_command_bitmap_linear( offset: Offset, @@ -82,7 +148,17 @@ pub unsafe extern "C" fn sp_command_bitmap_linear( } /// Allocates a new `Command::BitmapLinearAnd` instance. -/// The passed `BitVec` gets deallocated in the process. +/// The passed `BitVec` gets consumed. +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `bit_vec` points to a valid instance of `BitVec` +/// - `bit_vec` is not used concurrently or after this call +/// - `compression` matches one of the allowed enum values +/// - the returned `Command` instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_command_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_command_bitmap_linear_and( offset: Offset, @@ -98,7 +174,17 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_and( } /// Allocates a new `Command::BitmapLinearOr` instance. -/// The passed `BitVec` gets deallocated in the process. +/// The passed `BitVec` gets consumed. +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `bit_vec` points to a valid instance of `BitVec` +/// - `bit_vec` is not used concurrently or after this call +/// - `compression` matches one of the allowed enum values +/// - the returned `Command` instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_command_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_command_bitmap_linear_or( offset: Offset, @@ -114,7 +200,17 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_or( } /// Allocates a new `Command::BitmapLinearXor` instance. -/// The passed `BitVec` gets deallocated in the process. +/// The passed `BitVec` gets consumed. +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `bit_vec` points to a valid instance of `BitVec` +/// - `bit_vec` is not used concurrently or after this call +/// - `compression` matches one of the allowed enum values +/// - the returned `Command` instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_command_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_command_bitmap_linear_xor( offset: Offset, @@ -130,7 +226,16 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_xor( } /// Allocates a new `Command::Cp437Data` instance. -/// The passed `ByteGrid` gets deallocated in the process. +/// The passed `ByteGrid` gets consumed. +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `byte_grid` points to a valid instance of `ByteGrid` +/// - `byte_grid` is not used concurrently or after this call +/// - the returned `Command` instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_command_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_command_cp437_data( x: usize, @@ -142,15 +247,25 @@ pub unsafe extern "C" fn sp_command_cp437_data( } /// Allocates a new `Command::BitmapLinearWin` instance. -/// The passed `PixelGrid` gets deallocated in the process. +/// The passed `PixelGrid` gets consumed. +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `pixel_grid` points to a valid instance of `PixelGrid` +/// - `pixel_grid` is not used concurrently or after this call +/// - `compression` matches one of the allowed enum values +/// - the returned `Command` instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_command_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_command_bitmap_linear_win( x: usize, y: usize, - byte_grid: *mut PixelGrid, + pixel_grid: *mut PixelGrid, compression_code: CompressionCode, ) -> *mut Command { - let byte_grid = *Box::from_raw(byte_grid); + let byte_grid = *Box::from_raw(pixel_grid); Box::into_raw(Box::new(Command::BitmapLinearWin( Origin(x, y), byte_grid, @@ -158,8 +273,15 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_win( ))) } -/// Deallocates a `Command`. Note that connection_send does this implicitly, so you only need -/// to do this if you use the library for parsing commands. +/// Deallocates a `Command`. +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `this` points to a valid `Command` +/// - `this` is not used concurrently or after this call +/// - `this` was not passed to another consuming function, e.g. to create a `Packet` #[no_mangle] pub unsafe extern "C" fn sp_command_dealloc(ptr: *mut Command) { _ = Box::from_raw(ptr); diff --git a/crates/servicepoint_binding_c/src/connection.rs b/crates/servicepoint_binding_c/src/connection.rs index b1ea334..355dd7c 100644 --- a/crates/servicepoint_binding_c/src/connection.rs +++ b/crates/servicepoint_binding_c/src/connection.rs @@ -4,12 +4,20 @@ use std::ptr::null_mut; pub use servicepoint::Connection; use servicepoint::Packet; -/// Creates a new instance of Connection. -/// The returned instance has to be deallocated with `connection_dealloc`. +/// Creates a new instance of `Connection`. /// -/// returns: NULL if connection fails or connected instance +/// returns: NULL if connection fails, or connected instance /// -/// Panics: bad string encoding +/// # Panics +/// +/// Bad string encoding +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - the returned instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_connection_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_connection_open( host: *const c_char, @@ -23,17 +31,35 @@ pub unsafe extern "C" fn sp_connection_open( Box::into_raw(Box::new(connection)) } -/// Sends the command instance. The instance is consumed / destroyed and cannot be used after this call. +/// Sends a `Packet` to the display using the `Connection`. +/// The passed `Packet` gets consumed. +/// +/// returns: true in case of success +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `connection` points to a valid instance of `Connection` +/// - `packet` points to a valid instance of `Packet` +/// - `packet` is not used concurrently or after this call #[no_mangle] pub unsafe extern "C" fn sp_connection_send( connection: *const Connection, - command_ptr: *mut Packet, + packet: *mut Packet, ) -> bool { - let packet = Box::from_raw(command_ptr); + let packet = Box::from_raw(packet); (*connection).send(*packet).is_ok() } -/// Closes and deallocates a connection instance +/// Closes and deallocates a `Connection`. +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `this` points to a valid `Connection` +/// - `this` is not used concurrently or after this call #[no_mangle] pub unsafe extern "C" fn sp_connection_dealloc(ptr: *mut Connection) { _ = Box::from_raw(ptr); diff --git a/crates/servicepoint_binding_c/src/lib.rs b/crates/servicepoint_binding_c/src/lib.rs index 4ecbd5d..48aa258 100644 --- a/crates/servicepoint_binding_c/src/lib.rs +++ b/crates/servicepoint_binding_c/src/lib.rs @@ -1,14 +1,43 @@ +//! C API wrapper for the `servicepoint` crate. + pub use servicepoint::{ CompressionCode, PIXEL_COUNT, PIXEL_HEIGHT, PIXEL_WIDTH, TILE_HEIGHT, TILE_SIZE, TILE_WIDTH, }; +pub use crate::c_slice::CByteSlice; + +/// C functions for interacting with `BitVec`s +/// +/// prefix `sp_bit_vec_` pub mod bit_vec; + +/// C functions for interacting with `ByteGrid`s +/// +/// prefix `sp_byte_grid_` pub mod byte_grid; -pub mod c_slice; + +/// C functions for interacting with `Command`s +/// +/// prefix `sp_command_` pub mod command; + +/// C functions for interacting with `Connection`s +/// +/// prefix `sp_connection_` pub mod connection; + +/// C functions for interacting with `Packet`s +/// +/// prefix `sp_packet_` pub mod packet; + +/// C functions for interacting with `PixelGrid`s +/// +/// prefix `sp_pixel_grid_` pub mod pixel_grid; +/// The minimum time needed for the display to refresh the screen in ms. pub const FRAME_PACING_MS: u32 = servicepoint::FRAME_PACING.as_millis() as u32; + +mod c_slice; diff --git a/crates/servicepoint_binding_c/src/packet.rs b/crates/servicepoint_binding_c/src/packet.rs index 9e90f3f..48cdd9b 100644 --- a/crates/servicepoint_binding_c/src/packet.rs +++ b/crates/servicepoint_binding_c/src/packet.rs @@ -3,7 +3,17 @@ use std::ptr::null_mut; use servicepoint::Command; pub use servicepoint::Packet; -/// Turns a `Command` into a `Packet`. The command gets deallocated in the process. +/// Turns a `Command` into a `Packet`. +/// The `Command` gets consumed. +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `command` points to a valid instance of `Command` +/// - `command` is not used concurrently or after this call +/// - the returned `Packet` instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_packet_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_packet_from_command( command: *mut Command, @@ -16,6 +26,15 @@ pub unsafe extern "C" fn sp_packet_from_command( /// Tries to load a `Packet` from the passed array with the specified length. /// /// returns: NULL in case of an error, pointer to the allocated packet otherwise +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `data` points to a valid memory region of at least `length` bytes +/// - `data` is not written to concurrently +/// - the returned `Packet` instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_packet_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_packet_try_load( data: *const u8, diff --git a/crates/servicepoint_binding_c/src/pixel_grid.rs b/crates/servicepoint_binding_c/src/pixel_grid.rs index 87090d9..0f07f5d 100644 --- a/crates/servicepoint_binding_c/src/pixel_grid.rs +++ b/crates/servicepoint_binding_c/src/pixel_grid.rs @@ -2,8 +2,25 @@ use servicepoint::{DataRef, Grid, PixelGrid}; use crate::c_slice::CByteSlice; -/// Creates a new `PixelGrid` instance. -/// The returned instance has to be freed with `pixel_grid_dealloc`. +/// 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 +/// +/// # Panics +/// +/// - when the width is not dividable by 8 +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - the returned instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_pixel_grid_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_pixel_grid_new( width: usize, @@ -13,7 +30,26 @@ pub unsafe extern "C" fn sp_pixel_grid_new( } /// Loads a `PixelGrid` with the specified dimensions from the provided data. -/// The returned instance has to be freed with `pixel_grid_dealloc`. +/// +/// # 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 +/// +/// # Panics +/// +/// - when the dimensions and data size do not match exactly. +/// - when the width is not dividable by 8 +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `data` points to a valid memory location of at least `data_length` bytes in size. +/// - the returned instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_pixel_grid_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_pixel_grid_load( width: usize, @@ -26,7 +62,15 @@ pub unsafe extern "C" fn sp_pixel_grid_load( } /// Clones a `PixelGrid`. -/// The returned instance has to be freed with `pixel_grid_dealloc`. +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `this` points to a valid `PixelGrid` +/// - `this` is not written to concurrently +/// - the returned instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_pixel_grid_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_pixel_grid_clone( this: *const PixelGrid, @@ -36,13 +80,35 @@ pub unsafe extern "C" fn sp_pixel_grid_clone( /// Deallocates a `PixelGrid`. /// -/// Note: do not call this if the grid has been consumed in another way, e.g. to create a command. +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `this` points to a valid `PixelGrid` +/// - `this` is not used concurrently or after this call +/// - `this` was not passed to another consuming function, e.g. to create a `Command` #[no_mangle] pub unsafe extern "C" fn sp_pixel_grid_dealloc(this: *mut PixelGrid) { _ = Box::from_raw(this); } -/// Get the current value at the specified position +/// Gets the current value at the specified position in the `PixelGrid`. +/// +/// # Arguments +/// +/// * `this`: instance to read from +/// * `x` and `y`: position of the cell to read +/// +/// # Panics +/// +/// When accessing `x` or `y` out of bounds. +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `this` points to a valid `PixelGrid` +/// - `this` is not written to concurrently #[no_mangle] pub unsafe extern "C" fn sp_pixel_grid_get( this: *const PixelGrid, @@ -52,7 +118,26 @@ pub unsafe extern "C" fn sp_pixel_grid_get( (*this).get(x, y) } -/// Sets the current value at the specified position +/// Sets the value of the specified position in the `PixelGrid`. +/// +/// # Arguments +/// +/// * `this`: instance to write to +/// * `x` and `y`: position of the cell +/// * `value`: the value to write to the cell +/// +/// returns: old value of the cell +/// +/// # Panics +/// +/// When accessing `x` or `y` out of bounds. +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `this` points to a valid `PixelGrid` +/// - `this` is not written to or read from concurrently #[no_mangle] pub unsafe extern "C" fn sp_pixel_grid_set( this: *mut PixelGrid, @@ -63,19 +148,51 @@ pub unsafe extern "C" fn sp_pixel_grid_set( (*this).set(x, y, value); } -/// Fills the whole `PixelGrid` with the specified value +/// Sets the state of all pixels in the `PixelGrid`. +/// +/// # Arguments +/// +/// * `this`: instance to write to +/// * `value`: the value to set all pixels to +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `this` points to a valid `PixelGrid` +/// - `this` is not written to or read from concurrently #[no_mangle] pub unsafe extern "C" fn sp_pixel_grid_fill(this: *mut PixelGrid, value: bool) { (*this).fill(value); } /// Gets the width in pixels of the `PixelGrid` instance. +/// +/// # Arguments +/// +/// * `this`: instance to read from +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `this` points to a valid `PixelGrid` #[no_mangle] pub unsafe extern "C" fn sp_pixel_grid_width(this: *const PixelGrid) -> usize { (*this).width() } /// Gets the height in pixels of the `PixelGrid` instance. +/// +/// # Arguments +/// +/// * `this`: instance to read from +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `this` points to a valid `PixelGrid` #[no_mangle] pub unsafe extern "C" fn sp_pixel_grid_height(this: *const PixelGrid) -> usize { (*this).height() @@ -85,11 +202,11 @@ pub unsafe extern "C" fn sp_pixel_grid_height(this: *const PixelGrid) -> usize { /// /// ## Safety /// -/// The caller has to make sure to never access the returned memory after the `PixelGrid` -/// instance has been consumed or manually deallocated. +/// The caller has to make sure that: /// -/// Reading and writing concurrently to either the original instance or the returned data will -/// result in undefined behavior. +/// - `this` points to a valid `PixelGrid` +/// - the returned memory range is never accessed after the passed `PixelGrid` has been freed +/// - the returned memory range is never accessed concurrently, either via the `PixelGrid` or directly #[no_mangle] pub unsafe extern "C" fn sp_pixel_grid_unsafe_data_ref( this: *mut PixelGrid, diff --git a/crates/servicepoint_binding_cs/Cargo.toml b/crates/servicepoint_binding_cs/Cargo.toml index 7282c1d..aa2e910 100644 --- a/crates/servicepoint_binding_cs/Cargo.toml +++ b/crates/servicepoint_binding_cs/Cargo.toml @@ -13,5 +13,8 @@ test = false csbindgen = "1.8.0" [dependencies] -servicepoint_binding_c = { version = "0.5.0", path = "../servicepoint_binding_c" } -servicepoint = { version = "0.5.0", path = "../servicepoint" } +servicepoint_binding_c = { version = "0.5.1", path = "../servicepoint_binding_c" } +servicepoint = { version = "0.5.1", path = "../servicepoint" } + +[lints] +workspace = true diff --git a/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs b/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs index fd8f466..0d926ef 100644 --- a/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs +++ b/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs @@ -19,204 +19,204 @@ namespace ServicePoint.BindGen public const nuint TILE_HEIGHT = 20; - /// Creates a new `BitVec` instance. The returned instance has to be freed with `bit_vec_dealloc`. + /// Creates a new `BitVec` instance. # Arguments * `size`: size in bits. returns: `BitVec` with all bits set to false. # Panics When `size` is not divisible by 8. # Safety The caller has to make sure that: - the returned instance is freed in some way, either by using a consuming function or by explicitly calling `sp_bit_vec_dealloc`. [DllImport(__DllName, EntryPoint = "sp_bit_vec_new", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern BitVec* sp_bit_vec_new(nuint size); - /// Loads a `BitVec` from the provided data. The returned instance has to be freed with `bit_vec_dealloc`. + /// Interpret the data as a series of bits and load then into a new `BitVec` instance. # Safety The caller has to make sure that: - `data` points to a valid memory location of at least `data_length` bytes in size. - the returned instance is freed in some way, either by using a consuming function or by explicitly calling `sp_bit_vec_dealloc`. [DllImport(__DllName, EntryPoint = "sp_bit_vec_load", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern BitVec* sp_bit_vec_load(byte* data, nuint data_length); - /// Clones a `BitVec`. The returned instance has to be freed with `bit_vec_dealloc`. + /// Clones a `BitVec`. # Safety The caller has to make sure that: - `this` points to a valid `BitVec` - `this` is not written to concurrently - the returned instance is freed in some way, either by using a consuming function or by explicitly calling `sp_bit_vec_dealloc`. [DllImport(__DllName, EntryPoint = "sp_bit_vec_clone", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern BitVec* sp_bit_vec_clone(BitVec* @this); - /// Deallocates a `BitVec`. Note: do not call this if the grid has been consumed in another way, e.g. to create a command. + /// Deallocates a `BitVec`. # Safety The caller has to make sure that: - `this` points to a valid `BitVec` - `this` is not used concurrently or after this call - `this` was not passed to another consuming function, e.g. to create a `Command` [DllImport(__DllName, EntryPoint = "sp_bit_vec_dealloc", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_bit_vec_dealloc(BitVec* @this); - /// Gets the value of a bit from the `BitVec`. + /// Gets the value of a bit from the `BitVec`. # Arguments * `this`: instance to read from * `index`: the bit index to read returns: value of the bit # Panics When accessing `index` out of bounds. # Safety The caller has to make sure that: - `this` points to a valid `BitVec` - `this` is not written to concurrently [DllImport(__DllName, EntryPoint = "sp_bit_vec_get", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] [return: MarshalAs(UnmanagedType.U1)] public static extern bool sp_bit_vec_get(BitVec* @this, nuint index); - /// Sets the value of a bit in the `BitVec`. + /// Sets the value of a bit in the `BitVec`. # Arguments * `this`: instance to write to * `index`: the bit index to edit * `value`: the value to set the bit to returns: old value of the bit # Panics When accessing `index` out of bounds. # Safety The caller has to make sure that: - `this` points to a valid `BitVec` - `this` is not written to or read from concurrently [DllImport(__DllName, EntryPoint = "sp_bit_vec_set", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] [return: MarshalAs(UnmanagedType.U1)] public static extern bool sp_bit_vec_set(BitVec* @this, nuint index, [MarshalAs(UnmanagedType.U1)] bool value); - /// Sets the value of all bits in the `BitVec`. + /// Sets the value of all bits in the `BitVec`. # Arguments * `value`: the value to set all bits to # Safety The caller has to make sure that: - `this` points to a valid `BitVec` - `this` is not written to or read from concurrently [DllImport(__DllName, EntryPoint = "sp_bit_vec_fill", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_bit_vec_fill(BitVec* @this, [MarshalAs(UnmanagedType.U1)] bool value); - /// Gets the length of the `BitVec` in bits. + /// Gets the length of the `BitVec` in bits. # Safety The caller has to make sure that: - `this` points to a valid `BitVec` [DllImport(__DllName, EntryPoint = "sp_bit_vec_len", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern nuint sp_bit_vec_len(BitVec* @this); - /// Returns true if length is 0. + /// Returns true if length is 0. # Safety The caller has to make sure that: - `this` points to a valid `BitVec` [DllImport(__DllName, EntryPoint = "sp_bit_vec_is_empty", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] [return: MarshalAs(UnmanagedType.U1)] public static extern bool sp_bit_vec_is_empty(BitVec* @this); - /// Gets an unsafe reference to the data of the `BitVec` instance. ## Safety The caller has to make sure to never access the returned memory after the `BitVec` instance has been consumed or manually deallocated. Reading and writing concurrently to either the original instance or the returned data will result in undefined behavior. + /// Gets an unsafe reference to the data of the `BitVec` instance. ## Safety The caller has to make sure that: - `this` points to a valid `BitVec` - the returned memory range is never accessed after the passed `BitVec` has been freed - the returned memory range is never accessed concurrently, either via the `BitVec` or directly [DllImport(__DllName, EntryPoint = "sp_bit_vec_unsafe_data_ref", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern CByteSlice sp_bit_vec_unsafe_data_ref(BitVec* @this); - /// Creates a new `ByteGrid` instance. The returned instance has to be freed with `byte_grid_dealloc`. + /// Creates a new `ByteGrid` with the specified dimensions. returns: `ByteGrid` initialized to 0. # Safety The caller has to make sure that: - the returned instance is freed in some way, either by using a consuming function or by explicitly calling `sp_byte_grid_dealloc`. [DllImport(__DllName, EntryPoint = "sp_byte_grid_new", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern ByteGrid* sp_byte_grid_new(nuint width, nuint height); - /// Loads a `ByteGrid` with the specified dimensions from the provided data. The returned instance has to be freed with `byte_grid_dealloc`. + /// Loads a `ByteGrid` with the specified dimensions from the provided data. # Panics When the provided `data_length` is not sufficient for the `height` and `width` # Safety The caller has to make sure that: - `data` points to a valid memory location of at least `data_length` bytes in size. - the returned instance is freed in some way, either by using a consuming function or by explicitly calling `sp_byte_grid_dealloc`. [DllImport(__DllName, EntryPoint = "sp_byte_grid_load", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern ByteGrid* sp_byte_grid_load(nuint width, nuint height, byte* data, nuint data_length); - /// Clones a `ByteGrid`. The returned instance has to be freed with `byte_grid_dealloc`. + /// Clones a `ByteGrid`. # Safety The caller has to make sure that: - `this` points to a valid `ByteGrid` - `this` is not written to concurrently - the returned instance is freed in some way, either by using a consuming function or by explicitly calling `sp_byte_grid_dealloc`. [DllImport(__DllName, EntryPoint = "sp_byte_grid_clone", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern ByteGrid* sp_byte_grid_clone(ByteGrid* @this); - /// Deallocates a `ByteGrid`. Note: do not call this if the grid has been consumed in another way, e.g. to create a command. + /// Deallocates a `ByteGrid`. # Safety The caller has to make sure that: - `this` points to a valid `ByteGrid` - `this` is not used concurrently or after this call - `this` was not passed to another consuming function, e.g. to create a `Command` [DllImport(__DllName, EntryPoint = "sp_byte_grid_dealloc", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_byte_grid_dealloc(ByteGrid* @this); - /// Get the current value at the specified position + /// Gets the current value at the specified position. # Arguments * `this`: instance to read from * `x` and `y`: position of the cell to read # Panics When accessing `x` or `y` out of bounds. # Safety The caller has to make sure that: - `this` points to a valid `ByteGrid` - `this` is not written to concurrently [DllImport(__DllName, EntryPoint = "sp_byte_grid_get", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern byte sp_byte_grid_get(ByteGrid* @this, nuint x, nuint y); - /// Sets the current value at the specified position + /// Sets the value of the specified position in the `ByteGrid`. # Arguments * `this`: instance to write to * `x` and `y`: position of the cell * `value`: the value to write to the cell returns: old value of the cell # Panics When accessing `x` or `y` out of bounds. # Safety The caller has to make sure that: - `this` points to a valid `BitVec` - `this` is not written to or read from concurrently [DllImport(__DllName, EntryPoint = "sp_byte_grid_set", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_byte_grid_set(ByteGrid* @this, nuint x, nuint y, byte value); - /// Fills the whole `ByteGrid` with the specified value + /// Sets the value of all cells in the `ByteGrid`. # Arguments * `this`: instance to write to * `value`: the value to set all cells to # Safety The caller has to make sure that: - `this` points to a valid `ByteGrid` - `this` is not written to or read from concurrently [DllImport(__DllName, EntryPoint = "sp_byte_grid_fill", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_byte_grid_fill(ByteGrid* @this, byte value); - /// Gets the width in pixels of the `ByteGrid` instance. + /// Gets the width of the `ByteGrid` instance. # Arguments * `this`: instance to read from # Safety The caller has to make sure that: - `this` points to a valid `ByteGrid` [DllImport(__DllName, EntryPoint = "sp_byte_grid_width", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern nuint sp_byte_grid_width(ByteGrid* @this); - /// Gets the height in pixels of the `ByteGrid` instance. + /// Gets the height of the `ByteGrid` instance. # Arguments * `this`: instance to read from # Safety The caller has to make sure that: - `this` points to a valid `ByteGrid` [DllImport(__DllName, EntryPoint = "sp_byte_grid_height", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern nuint sp_byte_grid_height(ByteGrid* @this); - /// Gets an unsafe reference to the data of the `ByteGrid` instance. ## Safety The caller has to make sure to never access the returned memory after the `ByteGrid` instance has been consumed or manually deallocated. Reading and writing concurrently to either the original instance or the returned data will result in undefined behavior. + /// Gets an unsafe reference to the data of the `ByteGrid` instance. ## Safety The caller has to make sure that: - `this` points to a valid `ByteGrid` - the returned memory range is never accessed after the passed `ByteGrid` has been freed - the returned memory range is never accessed concurrently, either via the `ByteGrid` or directly [DllImport(__DllName, EntryPoint = "sp_byte_grid_unsafe_data_ref", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern CByteSlice sp_byte_grid_unsafe_data_ref(ByteGrid* @this); - /// Tries to turn a `Packet` into a `Command`. The packet is gets deallocated in the process. Returns: pointer to command or NULL + /// Tries to turn a `Packet` into a `Command`. The packet is deallocated in the process. Returns: pointer to new `Command` instance or NULL # Safety The caller has to make sure that: - `packet` points to a valid instance of `Packet` - `packet` is not used concurrently or after this call - the result is checked for NULL - the returned `Command` instance is freed in some way, either by using a consuming function or by explicitly calling `sp_command_dealloc`. [DllImport(__DllName, EntryPoint = "sp_command_try_from_packet", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern Command* sp_command_try_from_packet(Packet* packet); - /// Clones a `Command` instance + /// Clones a `Command` instance. # Safety The caller has to make sure that: - `this` points to a valid instance of `Command` - `this` is not written to concurrently - the returned `Command` instance is freed in some way, either by using a consuming function or by explicitly calling `sp_command_dealloc`. [DllImport(__DllName, EntryPoint = "sp_command_clone", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern Command* sp_command_clone(Command* original); - /// Allocates a new `Command::Clear` instance + /// Allocates a new `Command::Clear` instance. # Safety The caller has to make sure that: - the returned `Command` instance is freed in some way, either by using a consuming function or by explicitly calling `sp_command_dealloc`. [DllImport(__DllName, EntryPoint = "sp_command_clear", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern Command* sp_command_clear(); - /// Allocates a new `Command::HardReset` instance + /// Allocates a new `Command::HardReset` instance. # Safety The caller has to make sure that: - the returned `Command` instance is freed in some way, either by using a consuming function or by explicitly calling `sp_command_dealloc`. [DllImport(__DllName, EntryPoint = "sp_command_hard_reset", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern Command* sp_command_hard_reset(); - /// Allocates a new `Command::FadeOut` instance + /// Allocates a new `Command::FadeOut` instance. # Safety The caller has to make sure that: - the returned `Command` instance is freed in some way, either by using a consuming function or by explicitly calling `sp_command_dealloc`. [DllImport(__DllName, EntryPoint = "sp_command_fade_out", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern Command* sp_command_fade_out(); - /// Allocates a new `Command::Brightness` instance + /// Allocates a new `Command::Brightness` instance. # Safety The caller has to make sure that: - the returned `Command` instance is freed in some way, either by using a consuming function or by explicitly calling `sp_command_dealloc`. [DllImport(__DllName, EntryPoint = "sp_command_brightness", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern Command* sp_command_brightness(byte brightness); - /// Allocates a new `Command::CharBrightness` instance. The passed `ByteGrid` gets deallocated in the process. + /// Allocates a new `Command::CharBrightness` instance. The passed `ByteGrid` gets consumed. # Safety The caller has to make sure that: - `byte_grid` points to a valid instance of `ByteGrid` - `byte_grid` is not used concurrently or after this call - the returned `Command` instance is freed in some way, either by using a consuming function or by explicitly calling `sp_command_dealloc`. [DllImport(__DllName, EntryPoint = "sp_command_char_brightness", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern Command* sp_command_char_brightness(nuint x, nuint y, ByteGrid* byte_grid); - /// Allocates a new `Command::BitmapLinear` instance. The passed `BitVec` gets deallocated in the process. + /// Allocates a new `Command::BitmapLinear` instance. The passed `BitVec` gets consumed. # Safety The caller has to make sure that: - `bit_vec` points to a valid instance of `BitVec` - `bit_vec` is not used concurrently or after this call - `compression` matches one of the allowed enum values - the returned `Command` instance is freed in some way, either by using a consuming function or by explicitly calling `sp_command_dealloc`. [DllImport(__DllName, EntryPoint = "sp_command_bitmap_linear", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern Command* sp_command_bitmap_linear(nuint offset, BitVec* bit_vec, CompressionCode compression); - /// Allocates a new `Command::BitmapLinearAnd` instance. The passed `BitVec` gets deallocated in the process. + /// Allocates a new `Command::BitmapLinearAnd` instance. The passed `BitVec` gets consumed. # Safety The caller has to make sure that: - `bit_vec` points to a valid instance of `BitVec` - `bit_vec` is not used concurrently or after this call - `compression` matches one of the allowed enum values - the returned `Command` instance is freed in some way, either by using a consuming function or by explicitly calling `sp_command_dealloc`. [DllImport(__DllName, EntryPoint = "sp_command_bitmap_linear_and", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern Command* sp_command_bitmap_linear_and(nuint offset, BitVec* bit_vec, CompressionCode compression); - /// Allocates a new `Command::BitmapLinearOr` instance. The passed `BitVec` gets deallocated in the process. + /// Allocates a new `Command::BitmapLinearOr` instance. The passed `BitVec` gets consumed. # Safety The caller has to make sure that: - `bit_vec` points to a valid instance of `BitVec` - `bit_vec` is not used concurrently or after this call - `compression` matches one of the allowed enum values - the returned `Command` instance is freed in some way, either by using a consuming function or by explicitly calling `sp_command_dealloc`. [DllImport(__DllName, EntryPoint = "sp_command_bitmap_linear_or", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern Command* sp_command_bitmap_linear_or(nuint offset, BitVec* bit_vec, CompressionCode compression); - /// Allocates a new `Command::BitmapLinearXor` instance. The passed `BitVec` gets deallocated in the process. + /// Allocates a new `Command::BitmapLinearXor` instance. The passed `BitVec` gets consumed. # Safety The caller has to make sure that: - `bit_vec` points to a valid instance of `BitVec` - `bit_vec` is not used concurrently or after this call - `compression` matches one of the allowed enum values - the returned `Command` instance is freed in some way, either by using a consuming function or by explicitly calling `sp_command_dealloc`. [DllImport(__DllName, EntryPoint = "sp_command_bitmap_linear_xor", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern Command* sp_command_bitmap_linear_xor(nuint offset, BitVec* bit_vec, CompressionCode compression); - /// Allocates a new `Command::Cp437Data` instance. The passed `ByteGrid` gets deallocated in the process. + /// Allocates a new `Command::Cp437Data` instance. The passed `ByteGrid` gets consumed. # Safety The caller has to make sure that: - `byte_grid` points to a valid instance of `ByteGrid` - `byte_grid` is not used concurrently or after this call - the returned `Command` instance is freed in some way, either by using a consuming function or by explicitly calling `sp_command_dealloc`. [DllImport(__DllName, EntryPoint = "sp_command_cp437_data", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern Command* sp_command_cp437_data(nuint x, nuint y, ByteGrid* byte_grid); - /// Allocates a new `Command::BitmapLinearWin` instance. The passed `PixelGrid` gets deallocated in the process. + /// Allocates a new `Command::BitmapLinearWin` instance. The passed `PixelGrid` gets consumed. # Safety The caller has to make sure that: - `pixel_grid` points to a valid instance of `PixelGrid` - `pixel_grid` is not used concurrently or after this call - `compression` matches one of the allowed enum values - the returned `Command` instance is freed in some way, either by using a consuming function or by explicitly calling `sp_command_dealloc`. [DllImport(__DllName, EntryPoint = "sp_command_bitmap_linear_win", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern Command* sp_command_bitmap_linear_win(nuint x, nuint y, PixelGrid* byte_grid, CompressionCode compression_code); + public static extern Command* sp_command_bitmap_linear_win(nuint x, nuint y, PixelGrid* pixel_grid, CompressionCode compression_code); - /// Deallocates a `Command`. Note that connection_send does this implicitly, so you only need to do this if you use the library for parsing commands. + /// Deallocates a `Command`. # Safety The caller has to make sure that: - `this` points to a valid `Command` - `this` is not used concurrently or after this call - `this` was not passed to another consuming function, e.g. to create a `Packet` [DllImport(__DllName, EntryPoint = "sp_command_dealloc", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_command_dealloc(Command* ptr); - /// Creates a new instance of Connection. The returned instance has to be deallocated with `connection_dealloc`. returns: NULL if connection fails or connected instance Panics: bad string encoding + /// Creates a new instance of `Connection`. returns: NULL if connection fails, or connected instance # Panics Bad string encoding # Safety The caller has to make sure that: - the returned instance is freed in some way, either by using a consuming function or by explicitly calling `sp_connection_dealloc`. [DllImport(__DllName, EntryPoint = "sp_connection_open", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern Connection* sp_connection_open(byte* host); - /// Sends the command instance. The instance is consumed / destroyed and cannot be used after this call. + /// Sends a `Packet` to the display using the `Connection`. The passed `Packet` gets consumed. returns: true in case of success # Safety The caller has to make sure that: - `connection` points to a valid instance of `Connection` - `packet` points to a valid instance of `Packet` - `packet` is not used concurrently or after this call [DllImport(__DllName, EntryPoint = "sp_connection_send", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] [return: MarshalAs(UnmanagedType.U1)] - public static extern bool sp_connection_send(Connection* connection, Packet* command_ptr); + public static extern bool sp_connection_send(Connection* connection, Packet* packet); - /// Closes and deallocates a connection instance + /// Closes and deallocates a `Connection`. # Safety The caller has to make sure that: - `this` points to a valid `Connection` - `this` is not used concurrently or after this call [DllImport(__DllName, EntryPoint = "sp_connection_dealloc", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_connection_dealloc(Connection* ptr); - /// Creates a new `PixelGrid` instance. The returned instance has to be freed with `pixel_grid_dealloc`. + /// 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 # Panics - when the width is not dividable by 8 # Safety The caller has to make sure that: - the returned instance is freed in some way, either by using a consuming function or by explicitly calling `sp_pixel_grid_dealloc`. [DllImport(__DllName, EntryPoint = "sp_pixel_grid_new", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern PixelGrid* sp_pixel_grid_new(nuint width, nuint height); - /// Loads a `PixelGrid` with the specified dimensions from the provided data. The returned instance has to be freed with `pixel_grid_dealloc`. + /// 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 # Panics - when the dimensions and data size do not match exactly. - when the width is not dividable by 8 # Safety The caller has to make sure that: - `data` points to a valid memory location of at least `data_length` bytes in size. - the returned instance is freed in some way, either by using a consuming function or by explicitly calling `sp_pixel_grid_dealloc`. [DllImport(__DllName, EntryPoint = "sp_pixel_grid_load", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern PixelGrid* sp_pixel_grid_load(nuint width, nuint height, byte* data, nuint data_length); - /// Clones a `PixelGrid`. The returned instance has to be freed with `pixel_grid_dealloc`. + /// Clones a `PixelGrid`. # Safety The caller has to make sure that: - `this` points to a valid `PixelGrid` - `this` is not written to concurrently - the returned instance is freed in some way, either by using a consuming function or by explicitly calling `sp_pixel_grid_dealloc`. [DllImport(__DllName, EntryPoint = "sp_pixel_grid_clone", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern PixelGrid* sp_pixel_grid_clone(PixelGrid* @this); - /// Deallocates a `PixelGrid`. Note: do not call this if the grid has been consumed in another way, e.g. to create a command. + /// Deallocates a `PixelGrid`. # Safety The caller has to make sure that: - `this` points to a valid `PixelGrid` - `this` is not used concurrently or after this call - `this` was not passed to another consuming function, e.g. to create a `Command` [DllImport(__DllName, EntryPoint = "sp_pixel_grid_dealloc", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_pixel_grid_dealloc(PixelGrid* @this); - /// Get the current value at the specified position + /// Gets the current value at the specified position in the `PixelGrid`. # Arguments * `this`: instance to read from * `x` and `y`: position of the cell to read # Panics When accessing `x` or `y` out of bounds. # Safety The caller has to make sure that: - `this` points to a valid `PixelGrid` - `this` is not written to concurrently [DllImport(__DllName, EntryPoint = "sp_pixel_grid_get", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] [return: MarshalAs(UnmanagedType.U1)] public static extern bool sp_pixel_grid_get(PixelGrid* @this, nuint x, nuint y); - /// Sets the current value at the specified position + /// Sets the value of the specified position in the `PixelGrid`. # Arguments * `this`: instance to write to * `x` and `y`: position of the cell * `value`: the value to write to the cell returns: old value of the cell # Panics When accessing `x` or `y` out of bounds. # Safety The caller has to make sure that: - `this` points to a valid `PixelGrid` - `this` is not written to or read from concurrently [DllImport(__DllName, EntryPoint = "sp_pixel_grid_set", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_pixel_grid_set(PixelGrid* @this, nuint x, nuint y, [MarshalAs(UnmanagedType.U1)] bool value); - /// Fills the whole `PixelGrid` with the specified value + /// Sets the state of all pixels in the `PixelGrid`. # Arguments * `this`: instance to write to * `value`: the value to set all pixels to # Safety The caller has to make sure that: - `this` points to a valid `PixelGrid` - `this` is not written to or read from concurrently [DllImport(__DllName, EntryPoint = "sp_pixel_grid_fill", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_pixel_grid_fill(PixelGrid* @this, [MarshalAs(UnmanagedType.U1)] bool value); - /// Gets the width in pixels of the `PixelGrid` instance. + /// Gets the width in pixels of the `PixelGrid` instance. # Arguments * `this`: instance to read from # Safety The caller has to make sure that: - `this` points to a valid `PixelGrid` [DllImport(__DllName, EntryPoint = "sp_pixel_grid_width", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern nuint sp_pixel_grid_width(PixelGrid* @this); - /// Gets the height in pixels of the `PixelGrid` instance. + /// Gets the height in pixels of the `PixelGrid` instance. # Arguments * `this`: instance to read from # Safety The caller has to make sure that: - `this` points to a valid `PixelGrid` [DllImport(__DllName, EntryPoint = "sp_pixel_grid_height", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern nuint sp_pixel_grid_height(PixelGrid* @this); - /// Gets an unsafe reference to the data of the `PixelGrid` instance. ## Safety The caller has to make sure to never access the returned memory after the `PixelGrid` instance has been consumed or manually deallocated. Reading and writing concurrently to either the original instance or the returned data will result in undefined behavior. + /// Gets an unsafe reference to the data of the `PixelGrid` instance. ## Safety The caller has to make sure that: - `this` points to a valid `PixelGrid` - the returned memory range is never accessed after the passed `PixelGrid` has been freed - the returned memory range is never accessed concurrently, either via the `PixelGrid` or directly [DllImport(__DllName, EntryPoint = "sp_pixel_grid_unsafe_data_ref", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern CByteSlice sp_pixel_grid_unsafe_data_ref(PixelGrid* @this); - /// Turns a `Command` into a `Packet`. The command gets deallocated in the process. + /// Turns a `Command` into a `Packet`. The `Command` gets consumed. # Safety The caller has to make sure that: - `command` points to a valid instance of `Command` - `command` is not used concurrently or after this call - the returned `Packet` instance is freed in some way, either by using a consuming function or by explicitly calling `sp_packet_dealloc`. [DllImport(__DllName, EntryPoint = "sp_packet_from_command", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern Packet* sp_packet_from_command(Command* command); - /// Tries to load a `Packet` from the passed array with the specified length. returns: NULL in case of an error, pointer to the allocated packet otherwise + /// Tries to load a `Packet` from the passed array with the specified length. returns: NULL in case of an error, pointer to the allocated packet otherwise # Safety The caller has to make sure that: - `data` points to a valid memory region of at least `length` bytes - `data` is not written to concurrently - the returned `Packet` instance is freed in some way, either by using a consuming function or by explicitly calling `sp_packet_dealloc`. [DllImport(__DllName, EntryPoint = "sp_packet_try_load", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern Packet* sp_packet_try_load(byte* data, nuint length); diff --git a/crates/servicepoint_binding_cs/ServicePoint/ServicePoint.csproj b/crates/servicepoint_binding_cs/ServicePoint/ServicePoint.csproj index d871fcd..94691e7 100644 --- a/crates/servicepoint_binding_cs/ServicePoint/ServicePoint.csproj +++ b/crates/servicepoint_binding_cs/ServicePoint/ServicePoint.csproj @@ -12,7 +12,7 @@ ServicePoint - 0.5.0 + 0.5.1 Repository Authors None ServicePoint diff --git a/crates/servicepoint_binding_cs/build.rs b/crates/servicepoint_binding_cs/build.rs index ec5aa81..7f64dcf 100644 --- a/crates/servicepoint_binding_cs/build.rs +++ b/crates/servicepoint_binding_cs/build.rs @@ -1,3 +1,5 @@ +//! Build script generating the C# code needed to call methods from the `servicepoint` C library. + fn main() { println!("cargo:rerun-if-changed=../servicepoint_binding_c/src"); println!("cargo:rerun-if-changed=build.rs"); diff --git a/crates/servicepoint_binding_cs/src/lib.rs b/crates/servicepoint_binding_cs/src/lib.rs index 8b13789..c7bcac6 100644 --- a/crates/servicepoint_binding_cs/src/lib.rs +++ b/crates/servicepoint_binding_cs/src/lib.rs @@ -1 +1 @@ - +//! This crate is intentionally left empty. Only the build script is relevant here.