From 14faeb12388e9224c541affe89b7aef5625dd445 Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Thu, 29 Aug 2024 19:39:18 +0200 Subject: [PATCH 01/31] replace * with - for bullets in comments --- crates/servicepoint/src/connection.rs | 2 +- crates/servicepoint/src/grid.rs | 8 +- crates/servicepoint/src/pixel_grid.rs | 16 +- crates/servicepoint/src/primitive_grid.rs | 10 +- .../examples/lang_c/include/servicepoint.h | 215 ++++++++++++------ crates/servicepoint_binding_c/src/bit_vec.rs | 14 +- .../src/brightness_grid.rs | 25 +- .../servicepoint_binding_c/src/cp437_grid.rs | 18 +- .../servicepoint_binding_c/src/pixel_grid.rs | 26 +-- .../ServicePoint/BindGen/ServicePoint.g.cs | 4 +- 10 files changed, 211 insertions(+), 127 deletions(-) diff --git a/crates/servicepoint/src/connection.rs b/crates/servicepoint/src/connection.rs index d18d76b..456ae5d 100644 --- a/crates/servicepoint/src/connection.rs +++ b/crates/servicepoint/src/connection.rs @@ -44,7 +44,7 @@ impl Connection { /// /// # Arguments /// - /// * `packet`: the packet-like to send + /// - `packet`: the packet-like to send /// /// returns: Ok if packet was sent, otherwise socket error /// diff --git a/crates/servicepoint/src/grid.rs b/crates/servicepoint/src/grid.rs index 7e71532..cb8f5e7 100644 --- a/crates/servicepoint/src/grid.rs +++ b/crates/servicepoint/src/grid.rs @@ -4,7 +4,7 @@ pub trait Grid { /// /// # Arguments /// - /// * `x` and `y`: position of the cell to read + /// - `x` and `y`: position of the cell to read /// /// # Panics /// @@ -15,7 +15,7 @@ pub trait Grid { /// /// # Arguments /// - /// * `x` and `y`: position of the cell to read + /// - `x` and `y`: position of the cell to read /// /// # Panics /// @@ -26,7 +26,7 @@ pub trait Grid { /// /// # Arguments /// - /// * `x` and `y`: position of the cell to read + /// - `x` and `y`: position of the cell to read /// /// returns: Value at position or None fn get_optional(&self, x: isize, y: isize) -> Option { @@ -41,7 +41,7 @@ pub trait Grid { /// /// # Arguments /// - /// * `x` and `y`: position of the cell to read + /// - `x` and `y`: position of the cell to read /// /// returns: the old value or None fn set_optional(&mut self, x: isize, y: isize, value: T) -> bool { diff --git a/crates/servicepoint/src/pixel_grid.rs b/crates/servicepoint/src/pixel_grid.rs index 82e45d1..4b8bcc7 100644 --- a/crates/servicepoint/src/pixel_grid.rs +++ b/crates/servicepoint/src/pixel_grid.rs @@ -17,8 +17,8 @@ impl PixelGrid { /// /// # Arguments /// - /// * `width`: size in pixels in x-direction - /// * `height`: size in pixels in y-direction + /// - `width`: size in pixels in x-direction + /// - `height`: size in pixels in y-direction /// /// returns: `PixelGrid` initialized to all pixels off /// @@ -44,8 +44,8 @@ impl PixelGrid { /// /// # Arguments /// - /// * `width`: size in pixels in x-direction - /// * `height`: size in pixels in y-direction + /// - `width`: size in pixels in x-direction + /// - `height`: size in pixels in y-direction /// /// returns: `PixelGrid` that contains a copy of the provided data /// @@ -121,8 +121,8 @@ impl Grid for PixelGrid { /// /// # Arguments /// - /// * `x` and `y`: position of the cell - /// * `value`: the value to write to the cell + /// - `x` and `y`: position of the cell + /// - `value`: the value to write to the cell /// /// returns: old value of the cell /// @@ -143,8 +143,8 @@ impl Grid for PixelGrid { /// /// # Arguments /// - /// * `this`: instance to write to - /// * `value`: the value to set all pixels to + /// - `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/src/primitive_grid.rs b/crates/servicepoint/src/primitive_grid.rs index 578379e..d1a507e 100644 --- a/crates/servicepoint/src/primitive_grid.rs +++ b/crates/servicepoint/src/primitive_grid.rs @@ -82,7 +82,7 @@ impl PrimitiveGrid { /// /// # Arguments /// - /// * `x` and `y`: position of the cell + /// - `x` and `y`: position of the cell /// /// # Panics /// @@ -96,7 +96,7 @@ impl PrimitiveGrid { /// /// # Arguments /// - /// * `x` and `y`: position of the cell + /// - `x` and `y`: position of the cell /// /// returns: Reference to cell or None pub fn get_ref_mut_optional( @@ -117,8 +117,8 @@ impl Grid for PrimitiveGrid { /// /// # Arguments /// - /// * `x` and `y`: position of the cell - /// * `value`: the value to write to the cell + /// - `x` and `y`: position of the cell + /// - `value`: the value to write to the cell /// /// # Panics /// @@ -132,7 +132,7 @@ impl Grid for PrimitiveGrid { /// /// # Arguments /// - /// * `x` and `y`: position of the cell to read + /// - `x` and `y`: position of the cell to read /// /// # Panics /// 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 270bb5c..d45f50f 100644 --- a/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h +++ b/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h @@ -12,17 +12,38 @@ #define sp_PIXEL_COUNT (sp_PIXEL_WIDTH * sp_PIXEL_HEIGHT) /** - * screen height in pixels + * Display height in pixels + * + * # Examples + * + * ```rust + * # use servicepoint::{PIXEL_HEIGHT, PIXEL_WIDTH, PixelGrid}; + * let grid = PixelGrid::new(PIXEL_WIDTH, PIXEL_HEIGHT); + * ``` */ #define sp_PIXEL_HEIGHT (sp_TILE_HEIGHT * sp_TILE_SIZE) /** - * screen width in pixels + * Display width in pixels + * + * # Examples + * + * ```rust + * # use servicepoint::{PIXEL_HEIGHT, PIXEL_WIDTH, PixelGrid}; + * let grid = PixelGrid::new(PIXEL_WIDTH, PIXEL_HEIGHT); + * ``` */ #define sp_PIXEL_WIDTH (sp_TILE_WIDTH * sp_TILE_SIZE) /** - * tile count in the y-direction + * Display tile count in the y-direction + * + * # Examples + * + * ```rust + * # use servicepoint::{Cp437Grid, TILE_HEIGHT, TILE_WIDTH}; + * let grid = Cp437Grid::new(TILE_WIDTH, TILE_HEIGHT); + * ``` */ #define sp_TILE_HEIGHT 20 @@ -32,12 +53,32 @@ #define sp_TILE_SIZE 8 /** - * tile count in the x-direction + * Display tile count in the x-direction + * + * # Examples + * + * ```rust + * # use servicepoint::{Cp437Grid, TILE_HEIGHT, TILE_WIDTH}; + * let grid = Cp437Grid::new(TILE_WIDTH, TILE_HEIGHT); + * ``` */ #define sp_TILE_WIDTH 56 /** * Specifies the kind of compression to use. Availability depends on features. + * + * # Examples + * + * ```rust + * # use servicepoint::{Command, CompressionCode, Origin, PixelGrid}; + * // create command without payload compression + * # let pixels = PixelGrid::max_sized(); + * _ = Command::BitmapLinearWin(Origin::new(0, 0), pixels, CompressionCode::Uncompressed); + * + * // create command with payload compressed with lzma and appropriate header flags + * # let pixels = PixelGrid::max_sized(); + * _ = Command::BitmapLinearWin(Origin::new(0, 0), pixels, CompressionCode::Lzma); + * ``` */ enum sp_CompressionCode #ifdef __cplusplus @@ -71,6 +112,18 @@ typedef uint16_t sp_CompressionCode; /** * A display brightness value, checked for correct value range + * + * # Examples + * + * ``` + * # use servicepoint::{Brightness, Command, Connection}; + * let b = Brightness::MAX; + * let val: u8 = b.into(); + * + * let b = Brightness::try_from(7).unwrap(); + * # let connection = Connection::open("127.0.0.1:2342").unwrap(); + * let result = connection.send(Command::Brightness(b)); + * ``` */ typedef struct sp_Brightness sp_Brightness; @@ -79,17 +132,60 @@ typedef struct sp_Brightness sp_Brightness; */ typedef struct sp_CBitVec sp_CBitVec; +/** + * C-wrapper for grid containing brightness values. + */ typedef struct sp_CBrightnessGrid sp_CBrightnessGrid; +/** + * A C-wrapper for grid containing codepage 437 characters. + * + * The encoding is currently not enforced. + */ typedef struct sp_CCp437Grid sp_CCp437Grid; /** - * A command to send to the display. + * A low-level display command. + * + * This struct and associated functions implement the UDP protocol for the display. + * + * To send a `Command`, use a `Connection`. + * + * # Examples + * + * ```rust + * # use servicepoint::{Brightness, Command, Connection, Packet}; + * + * // create command + * let command = Command::Brightness(Brightness::MAX); + * + * // turn command into Packet + * let packet: Packet = command.clone().into(); + * + * // read command from packet + * let round_tripped = Command::try_from(packet).unwrap(); + * + * // round tripping produces exact copy + * assert_eq!(command, round_tripped); + * + * // send command + * # let connection = Connection::open("127.0.0.1:2342").unwrap(); + * connection.send(command).unwrap(); + * ``` */ typedef struct sp_Command sp_Command; /** * A connection to the display. + * + * # Examples + * ```rust + * # use servicepoint::Command; + * let connection = servicepoint::Connection::open("172.23.42.29:2342") + * .expect("connection failed"); + * connection.send(Command::Clear) + * .expect("send failed"); + * ``` */ typedef struct sp_Connection sp_Connection; @@ -103,16 +199,6 @@ typedef struct sp_Packet sp_Packet; */ typedef struct sp_PixelGrid sp_PixelGrid; -/** - * A 2D grid of bytes - */ -typedef struct sp_PrimitiveGrid_Brightness sp_PrimitiveGrid_Brightness; - -/** - * A 2D grid of bytes - */ -typedef struct sp_PrimitiveGrid_u8 sp_PrimitiveGrid_u8; - /** * Represents a span of memory (`&mut [u8]` ) as a struct usable by C code. * @@ -140,18 +226,6 @@ typedef struct sp_CByteSlice { */ typedef size_t sp_Offset; -/** - * A grid containing brightness values. - */ -typedef struct sp_PrimitiveGrid_Brightness sp_BrightnessGrid; - -/** - * A grid containing codepage 437 characters. - * - * The encoding is currently not enforced. - */ -typedef struct sp_PrimitiveGrid_u8 sp_Cp437Grid; - @@ -192,7 +266,7 @@ void sp_bit_vec_dealloc(struct sp_CBitVec *this_); * * # Arguments * - * * `value`: the value to set all bits to + * - `value`: the value to set all bits to * * # Safety * @@ -208,8 +282,8 @@ void sp_bit_vec_fill(struct sp_CBitVec *this_, bool value); * * # Arguments * - * * `this`: instance to read from - * * `index`: the bit index to read + * - `this`: instance to read from + * - `index`: the bit index to read * * returns: value of the bit * @@ -268,7 +342,7 @@ struct sp_CBitVec *sp_bit_vec_load(const uint8_t *data, * * # Arguments * - * * `size`: size in bits. + * - `size`: size in bits. * * returns: `BitVec` with all bits set to false. * @@ -290,9 +364,9 @@ struct sp_CBitVec *sp_bit_vec_new(size_t size); * * # Arguments * - * * `this`: instance to write to - * * `index`: the bit index to edit - * * `value`: the value to set the bit to + * - `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 * @@ -354,8 +428,12 @@ void sp_brightness_grid_dealloc(struct sp_CBrightnessGrid *this_); * * # Arguments * - * * `this`: instance to write to - * * `value`: the value to set all cells to + * - `this`: instance to write to + * - `value`: the value to set all cells to + * + * # Panics + * + * - When providing an invalid brightness value * * # Safety * @@ -371,8 +449,8 @@ void sp_brightness_grid_fill(struct sp_CBrightnessGrid *this_, uint8_t value); * * # Arguments * - * * `this`: instance to read from - * * `x` and `y`: position of the cell to read + * - `this`: instance to read from + * - `x` and `y`: position of the cell to read * * # Panics * @@ -394,7 +472,7 @@ uint8_t sp_brightness_grid_get(const struct sp_CBrightnessGrid *this_, * * # Arguments * - * * `this`: instance to read from + * - `this`: instance to read from * * # Safety * @@ -445,15 +523,16 @@ struct sp_CBrightnessGrid *sp_brightness_grid_new(size_t width, * * # Arguments * - * * `this`: instance to write to - * * `x` and `y`: position of the cell - * * `value`: the value to write to the cell + * - `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. + * - When accessing `x` or `y` out of bounds. + * - When providing an invalid brightness value * * # Safety * @@ -485,7 +564,7 @@ struct sp_CByteSlice sp_brightness_grid_unsafe_data_ref(struct sp_CBrightnessGri * * # Arguments * - * * `this`: instance to read from + * - `this`: instance to read from * * # Safety * @@ -618,7 +697,7 @@ struct sp_Command *sp_command_brightness(uint8_t brightness); */ struct sp_Command *sp_command_char_brightness(size_t x, size_t y, - sp_BrightnessGrid *byte_grid); + struct sp_CBrightnessGrid *byte_grid); /** * Allocates a new `Command::Clear` instance. @@ -661,7 +740,7 @@ struct sp_Command *sp_command_clone(const struct sp_Command *original); */ struct sp_Command *sp_command_cp437_data(size_t x, size_t y, - sp_Cp437Grid *byte_grid); + struct sp_CCp437Grid *byte_grid); /** * Deallocates a `Command`. @@ -796,8 +875,8 @@ void sp_cp437_grid_dealloc(struct sp_CCp437Grid *this_); * * # Arguments * - * * `this`: instance to write to - * * `value`: the value to set all cells to + * - `this`: instance to write to + * - `value`: the value to set all cells to * * # Safety * @@ -813,8 +892,8 @@ void sp_cp437_grid_fill(struct sp_CCp437Grid *this_, uint8_t value); * * # Arguments * - * * `this`: instance to read from - * * `x` and `y`: position of the cell to read + * - `this`: instance to read from + * - `x` and `y`: position of the cell to read * * # Panics * @@ -836,7 +915,7 @@ uint8_t sp_cp437_grid_get(const struct sp_CCp437Grid *this_, * * # Arguments * - * * `this`: instance to read from + * - `this`: instance to read from * * # Safety * @@ -887,9 +966,9 @@ struct sp_CCp437Grid *sp_cp437_grid_new(size_t width, * * # Arguments * - * * `this`: instance to write to - * * `x` and `y`: position of the cell - * * `value`: the value to write to the cell + * - `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 * @@ -927,7 +1006,7 @@ struct sp_CByteSlice sp_cp437_grid_unsafe_data_ref(struct sp_CCp437Grid *this_); * * # Arguments * - * * `this`: instance to read from + * - `this`: instance to read from * * # Safety * @@ -1013,8 +1092,8 @@ void sp_pixel_grid_dealloc(struct sp_PixelGrid *this_); * * # Arguments * - * * `this`: instance to write to - * * `value`: the value to set all pixels to + * - `this`: instance to write to + * - `value`: the value to set all pixels to * * # Safety * @@ -1030,8 +1109,8 @@ void sp_pixel_grid_fill(struct sp_PixelGrid *this_, bool value); * * # Arguments * - * * `this`: instance to read from - * * `x` and `y`: position of the cell to read + * - `this`: instance to read from + * - `x` and `y`: position of the cell to read * * # Panics * @@ -1051,7 +1130,7 @@ bool sp_pixel_grid_get(const struct sp_PixelGrid *this_, size_t x, size_t y); * * # Arguments * - * * `this`: instance to read from + * - `this`: instance to read from * * # Safety * @@ -1066,8 +1145,8 @@ size_t sp_pixel_grid_height(const struct sp_PixelGrid *this_); * * # Arguments * - * * `width`: size in pixels in x-direction - * * `height`: size in pixels in y-direction + * - `width`: size in pixels in x-direction + * - `height`: size in pixels in y-direction * * returns: `PixelGrid` that contains a copy of the provided data * @@ -1094,8 +1173,8 @@ struct sp_PixelGrid *sp_pixel_grid_load(size_t width, * * # Arguments * - * * `width`: size in pixels in x-direction - * * `height`: size in pixels in y-direction + * - `width`: size in pixels in x-direction + * - `height`: size in pixels in y-direction * * returns: `PixelGrid` initialized to all pixels off * @@ -1118,9 +1197,9 @@ struct sp_PixelGrid *sp_pixel_grid_new(size_t width, * * # Arguments * - * * `this`: instance to write to - * * `x` and `y`: position of the cell - * * `value`: the value to write to the cell + * - `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 * @@ -1158,7 +1237,7 @@ struct sp_CByteSlice sp_pixel_grid_unsafe_data_ref(struct sp_PixelGrid *this_); * * # Arguments * - * * `this`: instance to read from + * - `this`: instance to read from * * # Safety * diff --git a/crates/servicepoint_binding_c/src/bit_vec.rs b/crates/servicepoint_binding_c/src/bit_vec.rs index 2592aea..e930dbc 100644 --- a/crates/servicepoint_binding_c/src/bit_vec.rs +++ b/crates/servicepoint_binding_c/src/bit_vec.rs @@ -30,7 +30,7 @@ impl From for SpBitVec { /// /// # Arguments /// -/// * `size`: size in bits. +/// - `size`: size in bits. /// /// returns: `BitVec` with all bits set to false. /// @@ -107,8 +107,8 @@ pub unsafe extern "C" fn sp_bit_vec_dealloc(this: *mut CBitVec) { /// /// # Arguments /// -/// * `this`: instance to read from -/// * `index`: the bit index to read +/// - `this`: instance to read from +/// - `index`: the bit index to read /// /// returns: value of the bit /// @@ -134,9 +134,9 @@ pub unsafe extern "C" fn sp_bit_vec_get( /// /// # Arguments /// -/// * `this`: instance to write to -/// * `index`: the bit index to edit -/// * `value`: the value to set the bit to +/// - `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 /// @@ -163,7 +163,7 @@ pub unsafe extern "C" fn sp_bit_vec_set( /// /// # Arguments /// -/// * `value`: the value to set all bits to +/// - `value`: the value to set all bits to /// /// # Safety /// diff --git a/crates/servicepoint_binding_c/src/brightness_grid.rs b/crates/servicepoint_binding_c/src/brightness_grid.rs index 6fa2c5a..8f89906 100644 --- a/crates/servicepoint_binding_c/src/brightness_grid.rs +++ b/crates/servicepoint_binding_c/src/brightness_grid.rs @@ -96,8 +96,8 @@ pub unsafe extern "C" fn sp_brightness_grid_dealloc( /// /// # Arguments /// -/// * `this`: instance to read from -/// * `x` and `y`: position of the cell to read +/// - `this`: instance to read from +/// - `x` and `y`: position of the cell to read /// /// # Panics /// @@ -122,15 +122,16 @@ pub unsafe extern "C" fn sp_brightness_grid_get( /// /// # Arguments /// -/// * `this`: instance to write to -/// * `x` and `y`: position of the cell -/// * `value`: the value to write to the cell +/// - `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. +/// - When accessing `x` or `y` out of bounds. +/// - When providing an invalid brightness value /// /// # Safety /// @@ -154,8 +155,12 @@ pub unsafe extern "C" fn sp_brightness_grid_set( /// /// # Arguments /// -/// * `this`: instance to write to -/// * `value`: the value to set all cells to +/// - `this`: instance to write to +/// - `value`: the value to set all cells to +/// +/// # Panics +/// +/// - When providing an invalid brightness value /// /// # Safety /// @@ -177,7 +182,7 @@ pub unsafe extern "C" fn sp_brightness_grid_fill( /// /// # Arguments /// -/// * `this`: instance to read from +/// - `this`: instance to read from /// /// # Safety /// @@ -195,7 +200,7 @@ pub unsafe extern "C" fn sp_brightness_grid_width( /// /// # Arguments /// -/// * `this`: instance to read from +/// - `this`: instance to read from /// /// # Safety /// diff --git a/crates/servicepoint_binding_c/src/cp437_grid.rs b/crates/servicepoint_binding_c/src/cp437_grid.rs index f14c71d..a1d84a6 100644 --- a/crates/servicepoint_binding_c/src/cp437_grid.rs +++ b/crates/servicepoint_binding_c/src/cp437_grid.rs @@ -90,8 +90,8 @@ pub unsafe extern "C" fn sp_cp437_grid_dealloc(this: *mut CCp437Grid) { /// /// # Arguments /// -/// * `this`: instance to read from -/// * `x` and `y`: position of the cell to read +/// - `this`: instance to read from +/// - `x` and `y`: position of the cell to read /// /// # Panics /// @@ -116,9 +116,9 @@ pub unsafe extern "C" fn sp_cp437_grid_get( /// /// # Arguments /// -/// * `this`: instance to write to -/// * `x` and `y`: position of the cell -/// * `value`: the value to write to the cell +/// - `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 /// @@ -146,8 +146,8 @@ pub unsafe extern "C" fn sp_cp437_grid_set( /// /// # Arguments /// -/// * `this`: instance to write to -/// * `value`: the value to set all cells to +/// - `this`: instance to write to +/// - `value`: the value to set all cells to /// /// # Safety /// @@ -164,7 +164,7 @@ pub unsafe extern "C" fn sp_cp437_grid_fill(this: *mut CCp437Grid, value: u8) { /// /// # Arguments /// -/// * `this`: instance to read from +/// - `this`: instance to read from /// /// # Safety /// @@ -180,7 +180,7 @@ pub unsafe extern "C" fn sp_cp437_grid_width(this: *const CCp437Grid) -> usize { /// /// # Arguments /// -/// * `this`: instance to read from +/// - `this`: instance to read from /// /// # Safety /// diff --git a/crates/servicepoint_binding_c/src/pixel_grid.rs b/crates/servicepoint_binding_c/src/pixel_grid.rs index 10cff60..185017c 100644 --- a/crates/servicepoint_binding_c/src/pixel_grid.rs +++ b/crates/servicepoint_binding_c/src/pixel_grid.rs @@ -10,8 +10,8 @@ use crate::c_slice::CByteSlice; /// /// # Arguments /// -/// * `width`: size in pixels in x-direction -/// * `height`: size in pixels in y-direction +/// - `width`: size in pixels in x-direction +/// - `height`: size in pixels in y-direction /// /// returns: `PixelGrid` initialized to all pixels off /// @@ -37,8 +37,8 @@ pub unsafe extern "C" fn sp_pixel_grid_new( /// /// # Arguments /// -/// * `width`: size in pixels in x-direction -/// * `height`: size in pixels in y-direction +/// - `width`: size in pixels in x-direction +/// - `height`: size in pixels in y-direction /// /// returns: `PixelGrid` that contains a copy of the provided data /// @@ -100,8 +100,8 @@ pub unsafe extern "C" fn sp_pixel_grid_dealloc(this: *mut PixelGrid) { /// /// # Arguments /// -/// * `this`: instance to read from -/// * `x` and `y`: position of the cell to read +/// - `this`: instance to read from +/// - `x` and `y`: position of the cell to read /// /// # Panics /// @@ -126,9 +126,9 @@ pub unsafe extern "C" fn sp_pixel_grid_get( /// /// # Arguments /// -/// * `this`: instance to write to -/// * `x` and `y`: position of the cell -/// * `value`: the value to write to the cell +/// - `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 /// @@ -156,8 +156,8 @@ pub unsafe extern "C" fn sp_pixel_grid_set( /// /// # Arguments /// -/// * `this`: instance to write to -/// * `value`: the value to set all pixels to +/// - `this`: instance to write to +/// - `value`: the value to set all pixels to /// /// # Safety /// @@ -174,7 +174,7 @@ pub unsafe extern "C" fn sp_pixel_grid_fill(this: *mut PixelGrid, value: bool) { /// /// # Arguments /// -/// * `this`: instance to read from +/// - `this`: instance to read from /// /// # Safety /// @@ -190,7 +190,7 @@ pub unsafe extern "C" fn sp_pixel_grid_width(this: *const PixelGrid) -> usize { /// /// # Arguments /// -/// * `this`: instance to read from +/// - `this`: instance to read from /// /// # Safety /// diff --git a/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs b/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs index 009de2d..1751f84 100644 --- a/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs +++ b/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs @@ -81,11 +81,11 @@ namespace ServicePoint.BindGen [DllImport(__DllName, EntryPoint = "sp_brightness_grid_get", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern byte sp_brightness_grid_get(CBrightnessGrid* @this, nuint x, nuint y); - /// Sets the value of the specified position in the `BrightnessGrid`. # 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 + /// Sets the value of the specified position in the `BrightnessGrid`. # 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. - When providing an invalid brightness value # 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_brightness_grid_set", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_brightness_grid_set(CBrightnessGrid* @this, nuint x, nuint y, byte value); - /// Sets the value of all cells in the `BrightnessGrid`. # 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 `BrightnessGrid` - `this` is not written to or read from concurrently + /// Sets the value of all cells in the `BrightnessGrid`. # Arguments * `this`: instance to write to * `value`: the value to set all cells to # Panics - When providing an invalid brightness value # Safety The caller has to make sure that: - `this` points to a valid `BrightnessGrid` - `this` is not written to or read from concurrently [DllImport(__DllName, EntryPoint = "sp_brightness_grid_fill", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_brightness_grid_fill(CBrightnessGrid* @this, byte value); From a91e0e6eed56cf6e8fc592f6b0fe8c5d6f3f19fd Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Thu, 29 Aug 2024 20:03:07 +0200 Subject: [PATCH 02/31] update csbindgen to improve comment formatting --- Cargo.lock | 6 +- crates/servicepoint_binding_cs/Cargo.toml | 2 +- .../ServicePoint/BindGen/ServicePoint.g.cs | 926 ++++++++++++++++-- 3 files changed, 854 insertions(+), 80 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 0feeed0..9192eeb 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -245,12 +245,12 @@ dependencies = [ [[package]] name = "csbindgen" -version = "1.9.1" +version = "1.9.3" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "cf70eb656f35e0e6956cbde31c66431c53d8a546823489719099c71525767a9c" +checksum = "c26b9831049b947d154bba920e4124053def72447be6fb106a96f483874b482a" dependencies = [ "regex", - "syn 1.0.109", + "syn 2.0.68", ] [[package]] diff --git a/crates/servicepoint_binding_cs/Cargo.toml b/crates/servicepoint_binding_cs/Cargo.toml index e93b557..fe3c106 100644 --- a/crates/servicepoint_binding_cs/Cargo.toml +++ b/crates/servicepoint_binding_cs/Cargo.toml @@ -10,7 +10,7 @@ crate-type = ["cdylib"] test = false [build-dependencies] -csbindgen = "1.8.0" +csbindgen = "1.9.3" [dependencies] servicepoint_binding_c = { version = "0.7.0", path = "../servicepoint_binding_c" } diff --git a/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs b/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs index 1751f84..cf9fb4e 100644 --- a/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs +++ b/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs @@ -19,247 +19,1037 @@ namespace ServicePoint.BindGen public const nuint TILE_HEIGHT = 20; - /// 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`. + /// + /// 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 CBitVec* sp_bit_vec_new(nuint size); - /// 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`. + /// + /// 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 CBitVec* sp_bit_vec_load(byte* data, nuint data_length); - /// 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`. + /// + /// 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 CBitVec* sp_bit_vec_clone(CBitVec* @this); - /// 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` + /// + /// 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(CBitVec* @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 + /// + /// 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(CBitVec* @this, nuint index); - /// 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 + /// + /// 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)] public static extern void sp_bit_vec_set(CBitVec* @this, nuint index, [MarshalAs(UnmanagedType.U1)] bool value); - /// 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 + /// + /// 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(CBitVec* @this, [MarshalAs(UnmanagedType.U1)] bool value); - /// Gets the length of the `BitVec` in bits. # Safety The caller has to make sure that: - `this` points to a valid `BitVec` + /// + /// 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(CBitVec* @this); - /// Returns true if length is 0. # Safety The caller has to make sure that: - `this` points to a valid `BitVec` + /// + /// 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(CBitVec* @this); - /// 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 + /// + /// 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(CBitVec* @this); - /// Creates a new `BrightnessGrid` with the specified dimensions. returns: `BrightnessGrid` 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_brightness_grid_dealloc`. + /// + /// Creates a new `BrightnessGrid` with the specified dimensions. + /// + /// returns: `BrightnessGrid` 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_brightness_grid_dealloc`. + /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_new", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern CBrightnessGrid* sp_brightness_grid_new(nuint width, nuint height); - /// Loads a `BrightnessGrid` 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_brightness_grid_dealloc`. + /// + /// Loads a `BrightnessGrid` 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_brightness_grid_dealloc`. + /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_load", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern CBrightnessGrid* sp_brightness_grid_load(nuint width, nuint height, byte* data, nuint data_length); - /// Clones a `BrightnessGrid`. # Safety The caller has to make sure that: - `this` points to a valid `BrightnessGrid` - `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_brightness_grid_dealloc`. + /// + /// Clones a `BrightnessGrid`. + /// + /// # Safety + /// + /// The caller has to make sure that: + /// + /// - `this` points to a valid `BrightnessGrid` + /// - `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_brightness_grid_dealloc`. + /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_clone", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern CBrightnessGrid* sp_brightness_grid_clone(CBrightnessGrid* @this); - /// Deallocates a `BrightnessGrid`. # Safety The caller has to make sure that: - `this` points to a valid `BrightnessGrid` - `this` is not used concurrently or after this call - `this` was not passed to another consuming function, e.g. to create a `Command` + /// + /// Deallocates a `BrightnessGrid`. + /// + /// # Safety + /// + /// The caller has to make sure that: + /// + /// - `this` points to a valid `BrightnessGrid` + /// - `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_brightness_grid_dealloc", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_brightness_grid_dealloc(CBrightnessGrid* @this); - /// 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 `BrightnessGrid` - `this` is not written to concurrently + /// + /// 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 `BrightnessGrid` + /// - `this` is not written to concurrently + /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_get", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern byte sp_brightness_grid_get(CBrightnessGrid* @this, nuint x, nuint y); - /// Sets the value of the specified position in the `BrightnessGrid`. # 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. - When providing an invalid brightness value # Safety The caller has to make sure that: - `this` points to a valid `BitVec` - `this` is not written to or read from concurrently + /// + /// Sets the value of the specified position in the `BrightnessGrid`. + /// + /// # 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. + /// - When providing an invalid brightness value + /// + /// # 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_brightness_grid_set", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_brightness_grid_set(CBrightnessGrid* @this, nuint x, nuint y, byte value); - /// Sets the value of all cells in the `BrightnessGrid`. # Arguments * `this`: instance to write to * `value`: the value to set all cells to # Panics - When providing an invalid brightness value # Safety The caller has to make sure that: - `this` points to a valid `BrightnessGrid` - `this` is not written to or read from concurrently + /// + /// Sets the value of all cells in the `BrightnessGrid`. + /// + /// # Arguments + /// + /// - `this`: instance to write to + /// - `value`: the value to set all cells to + /// + /// # Panics + /// + /// - When providing an invalid brightness value + /// + /// # Safety + /// + /// The caller has to make sure that: + /// + /// - `this` points to a valid `BrightnessGrid` + /// - `this` is not written to or read from concurrently + /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_fill", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_brightness_grid_fill(CBrightnessGrid* @this, byte value); - /// Gets the width of the `BrightnessGrid` instance. # Arguments * `this`: instance to read from # Safety The caller has to make sure that: - `this` points to a valid `BrightnessGrid` + /// + /// Gets the width of the `BrightnessGrid` instance. + /// + /// # Arguments + /// + /// - `this`: instance to read from + /// + /// # Safety + /// + /// The caller has to make sure that: + /// + /// - `this` points to a valid `BrightnessGrid` + /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_width", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern nuint sp_brightness_grid_width(CBrightnessGrid* @this); - /// Gets the height of the `BrightnessGrid` instance. # Arguments * `this`: instance to read from # Safety The caller has to make sure that: - `this` points to a valid `BrightnessGrid` + /// + /// Gets the height of the `BrightnessGrid` instance. + /// + /// # Arguments + /// + /// - `this`: instance to read from + /// + /// # Safety + /// + /// The caller has to make sure that: + /// + /// - `this` points to a valid `BrightnessGrid` + /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_height", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern nuint sp_brightness_grid_height(CBrightnessGrid* @this); - /// Gets an unsafe reference to the data of the `BrightnessGrid` instance. ## Safety The caller has to make sure that: - `this` points to a valid `BrightnessGrid` - the returned memory range is never accessed after the passed `BrightnessGrid` has been freed - the returned memory range is never accessed concurrently, either via the `BrightnessGrid` or directly + /// + /// Gets an unsafe reference to the data of the `BrightnessGrid` instance. + /// + /// ## Safety + /// + /// The caller has to make sure that: + /// + /// - `this` points to a valid `BrightnessGrid` + /// - the returned memory range is never accessed after the passed `BrightnessGrid` has been freed + /// - the returned memory range is never accessed concurrently, either via the `BrightnessGrid` or directly + /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_unsafe_data_ref", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern CByteSlice sp_brightness_grid_unsafe_data_ref(CBrightnessGrid* @this); - /// Creates a new `Cp437Grid` with the specified dimensions. returns: `Cp437Grid` 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_cp437_grid_dealloc`. + /// + /// Creates a new `Cp437Grid` with the specified dimensions. + /// + /// returns: `Cp437Grid` 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_cp437_grid_dealloc`. + /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_new", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern CCp437Grid* sp_cp437_grid_new(nuint width, nuint height); - /// Loads a `Cp437Grid` 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_cp437_grid_dealloc`. + /// + /// Loads a `Cp437Grid` 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_cp437_grid_dealloc`. + /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_load", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern CCp437Grid* sp_cp437_grid_load(nuint width, nuint height, byte* data, nuint data_length); - /// Clones a `Cp437Grid`. # Safety The caller has to make sure that: - `this` points to a valid `Cp437Grid` - `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_cp437_grid_dealloc`. + /// + /// Clones a `Cp437Grid`. + /// + /// # Safety + /// + /// The caller has to make sure that: + /// + /// - `this` points to a valid `Cp437Grid` + /// - `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_cp437_grid_dealloc`. + /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_clone", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern CCp437Grid* sp_cp437_grid_clone(CCp437Grid* @this); - /// Deallocates a `Cp437Grid`. # Safety The caller has to make sure that: - `this` points to a valid `Cp437Grid` - `this` is not used concurrently or after this call - `this` was not passed to another consuming function, e.g. to create a `Command` + /// + /// Deallocates a `Cp437Grid`. + /// + /// # Safety + /// + /// The caller has to make sure that: + /// + /// - `this` points to a valid `Cp437Grid` + /// - `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_cp437_grid_dealloc", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_cp437_grid_dealloc(CCp437Grid* @this); - /// 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 `Cp437Grid` - `this` is not written to concurrently + /// + /// 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 `Cp437Grid` + /// - `this` is not written to concurrently + /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_get", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern byte sp_cp437_grid_get(CCp437Grid* @this, nuint x, nuint y); - /// Sets the value of the specified position in the `Cp437Grid`. # 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 + /// + /// Sets the value of the specified position in the `Cp437Grid`. + /// + /// # 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_cp437_grid_set", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_cp437_grid_set(CCp437Grid* @this, nuint x, nuint y, byte value); - /// Sets the value of all cells in the `Cp437Grid`. # 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 `Cp437Grid` - `this` is not written to or read from concurrently + /// + /// Sets the value of all cells in the `Cp437Grid`. + /// + /// # 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 `Cp437Grid` + /// - `this` is not written to or read from concurrently + /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_fill", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_cp437_grid_fill(CCp437Grid* @this, byte value); - /// Gets the width of the `Cp437Grid` instance. # Arguments * `this`: instance to read from # Safety The caller has to make sure that: - `this` points to a valid `Cp437Grid` + /// + /// Gets the width of the `Cp437Grid` instance. + /// + /// # Arguments + /// + /// - `this`: instance to read from + /// + /// # Safety + /// + /// The caller has to make sure that: + /// + /// - `this` points to a valid `Cp437Grid` + /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_width", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern nuint sp_cp437_grid_width(CCp437Grid* @this); - /// Gets the height of the `Cp437Grid` instance. # Arguments * `this`: instance to read from # Safety The caller has to make sure that: - `this` points to a valid `Cp437Grid` + /// + /// Gets the height of the `Cp437Grid` instance. + /// + /// # Arguments + /// + /// - `this`: instance to read from + /// + /// # Safety + /// + /// The caller has to make sure that: + /// + /// - `this` points to a valid `Cp437Grid` + /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_height", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern nuint sp_cp437_grid_height(CCp437Grid* @this); - /// Gets an unsafe reference to the data of the `Cp437Grid` instance. ## Safety The caller has to make sure that: - `this` points to a valid `Cp437Grid` - the returned memory range is never accessed after the passed `Cp437Grid` has been freed - the returned memory range is never accessed concurrently, either via the `Cp437Grid` or directly + /// + /// Gets an unsafe reference to the data of the `Cp437Grid` instance. + /// + /// ## Safety + /// + /// The caller has to make sure that: + /// + /// - `this` points to a valid `Cp437Grid` + /// - the returned memory range is never accessed after the passed `Cp437Grid` has been freed + /// - the returned memory range is never accessed concurrently, either via the `Cp437Grid` or directly + /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_unsafe_data_ref", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern CByteSlice sp_cp437_grid_unsafe_data_ref(CCp437Grid* @this); - /// 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`. + /// + /// 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. # 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`. + /// + /// 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. # 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`. + /// + /// 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. # 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`. + /// + /// 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. # 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`. + /// + /// 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 for setting the brightness of all tiles to the same value. # Panics - When the provided brightness value is out of range (0-11). # 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`. + /// + /// Allocates a new `Command::Brightness` instance for setting the brightness of all tiles to the + /// same value. + /// + /// # Panics + /// + /// - When the provided brightness value is out of range (0-11). + /// + /// # 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 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`. + /// + /// 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, CBrightnessGrid* byte_grid); - /// 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`. + /// + /// 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, CBitVec* bit_vec, CompressionCode compression); - /// 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`. + /// + /// 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, CBitVec* bit_vec, CompressionCode compression); - /// 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`. + /// + /// 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, CBitVec* bit_vec, CompressionCode compression); - /// 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`. + /// + /// 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, CBitVec* bit_vec, CompressionCode compression); - /// 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`. + /// + /// 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, CCp437Grid* byte_grid); - /// 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`. + /// + /// 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* pixel_grid, CompressionCode compression_code); - /// 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` + /// + /// 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`. 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`. + /// + /// 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 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 + /// + /// 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* packet); - /// 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 + /// + /// 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` 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`. + /// + /// 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. # 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`. + /// + /// 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`. # 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`. + /// + /// 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`. # 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` + /// + /// 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); - /// 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 + /// + /// 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 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 + /// + /// 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); - /// 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 + /// + /// 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. # Arguments * `this`: instance to read from # Safety The caller has to make sure that: - `this` points to a valid `PixelGrid` + /// + /// 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. # Arguments * `this`: instance to read from # Safety The caller has to make sure that: - `this` points to a valid `PixelGrid` + /// + /// 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 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 + /// + /// 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 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`. + /// + /// 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 # 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`. + /// + /// 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); - /// Deallocates a `Packet`. # Safety The caller has to make sure that: - `this` points to a valid `Packet` - `this` is not used concurrently or after this call + /// + /// Deallocates a `Packet`. + /// + /// # Safety + /// + /// The caller has to make sure that: + /// + /// - `this` points to a valid `Packet` + /// - `this` is not used concurrently or after this call + /// [DllImport(__DllName, EntryPoint = "sp_packet_dealloc", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_packet_dealloc(Packet* @this); @@ -304,22 +1094,6 @@ namespace ServicePoint.BindGen } - public enum Command - { - Clear, - Cp437Data, - BitmapLinearWin, - Brightness, - CharBrightness, - BitmapLinear, - BitmapLinearAnd, - BitmapLinearOr, - BitmapLinearXor, - HardReset, - FadeOut, - BitmapLegacy, - } - public enum CompressionCode : ushort { Uncompressed = 0, From d2369446ef8155fb592748d6cfd4372d318de5bd Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Thu, 29 Aug 2024 20:08:46 +0200 Subject: [PATCH 03/31] cargo update --- Cargo.lock | 243 ++++++++++++++++++++++++++++++++--------------------- 1 file changed, 145 insertions(+), 98 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 9192eeb..510a478 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -3,10 +3,10 @@ version = 3 [[package]] -name = "adler" -version = "1.0.2" +name = "adler2" +version = "2.0.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "f26201604c87b1e01bd3d98f8d5d9a8fcbb815e8cedb41ffccbeb4bf593a35fe" +checksum = "512761e0bb2578dd7380c6baaa0f4ce03e84f95e960231d1dec8bf4d7d6e2627" [[package]] name = "aho-corasick" @@ -19,9 +19,9 @@ dependencies = [ [[package]] name = "anstream" -version = "0.6.14" +version = "0.6.15" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "418c75fa768af9c03be99d17643f93f79bbba589895012a80e3452a19ddda15b" +checksum = "64e15c1ab1f89faffbf04a634d5e1962e9074f2741eef6d97f3c4e322426d526" dependencies = [ "anstyle", "anstyle-parse", @@ -34,36 +34,36 @@ dependencies = [ [[package]] name = "anstyle" -version = "1.0.7" +version = "1.0.8" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "038dfcf04a5feb68e9c60b21c9625a54c2c0616e79b72b0fd87075a056ae1d1b" +checksum = "1bec1de6f59aedf83baf9ff929c98f2ad654b97c9510f4e70cf6f661d49fd5b1" [[package]] name = "anstyle-parse" -version = "0.2.4" +version = "0.2.5" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "c03a11a9034d92058ceb6ee011ce58af4a9bf61491aa7e1e59ecd24bd40d22d4" +checksum = "eb47de1e80c2b463c735db5b217a0ddc39d612e7ac9e2e96a5aed1f57616c1cb" dependencies = [ "utf8parse", ] [[package]] name = "anstyle-query" -version = "1.1.0" +version = "1.1.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ad186efb764318d35165f1758e7dcef3b10628e26d41a44bc5550652e6804391" +checksum = "6d36fc52c7f6c869915e99412912f22093507da8d9e942ceaf66fe4b7c14422a" dependencies = [ - "windows-sys", + "windows-sys 0.52.0", ] [[package]] name = "anstyle-wincon" -version = "3.0.3" +version = "3.0.4" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "61a38449feb7068f52bb06c12759005cf459ee52bb4adc1d5a7c4322d716fb19" +checksum = "5bf74e1b6e971609db8ca7a9ce79fd5768ab6ae46441c572e46cf596f59e57f8" dependencies = [ "anstyle", - "windows-sys", + "windows-sys 0.52.0", ] [[package]] @@ -107,6 +107,12 @@ dependencies = [ "wyz", ] +[[package]] +name = "byteorder" +version = "1.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b" + [[package]] name = "bzip2" version = "0.4.4" @@ -149,13 +155,13 @@ dependencies = [ [[package]] name = "cc" -version = "1.0.101" +version = "1.1.15" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ac367972e516d45567c7eafc73d24e1c193dcf200a8d94e9db7b3d38b349572d" +checksum = "57b6a275aa2903740dc87da01c62040406b8812552e97129a63ea8850a17c6e6" dependencies = [ "jobserver", "libc", - "once_cell", + "shlex", ] [[package]] @@ -181,9 +187,9 @@ dependencies = [ [[package]] name = "clap" -version = "4.5.7" +version = "4.5.16" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "5db83dced34638ad474f39f250d7fea9598bdd239eaced1bdf45d597da0f433f" +checksum = "ed6719fffa43d0d87e5fd8caeab59be1554fb028cd30edc88fc4369b17971019" dependencies = [ "clap_builder", "clap_derive", @@ -191,26 +197,26 @@ dependencies = [ [[package]] name = "clap_builder" -version = "4.5.7" +version = "4.5.15" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "f7e204572485eb3fbf28f871612191521df159bc3e15a9f5064c66dba3a8c05f" +checksum = "216aec2b177652e3846684cbfe25c9964d18ec45234f0f5da5157b207ed1aab6" dependencies = [ "anstream", "anstyle", - "clap_lex 0.7.1", + "clap_lex 0.7.2", "strsim 0.11.1", ] [[package]] name = "clap_derive" -version = "4.5.5" +version = "4.5.13" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "c780290ccf4fb26629baa7a1081e68ced113f1d3ec302fa5948f1c381ebf06c6" +checksum = "501d359d5f3dcaf6ecdeee48833ae73ec6e42723a1e52419c79abf9507eec0a0" dependencies = [ "heck 0.5.0", "proc-macro2", "quote", - "syn 2.0.68", + "syn 2.0.76", ] [[package]] @@ -224,15 +230,15 @@ dependencies = [ [[package]] name = "clap_lex" -version = "0.7.1" +version = "0.7.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "4b82cf0babdbd58558212896d1a4272303a57bdb245c2bf1147185fb45640e70" +checksum = "1462739cb27611015575c0c11df5df7601141071f07518d56fcc1be504cbec97" [[package]] name = "colorchoice" -version = "1.0.1" +version = "1.0.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0b6a852b24ab71dffc585bcb46eaf7959d175cb865a7152e35b348d1b2960422" +checksum = "d3fd119d74b830634cea2a0f58bbd0d54540518a14397557951e79340abc28c0" [[package]] name = "crc32fast" @@ -250,7 +256,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "c26b9831049b947d154bba920e4124053def72447be6fb106a96f483874b482a" dependencies = [ "regex", - "syn 2.0.68", + "syn 2.0.76", ] [[package]] @@ -260,20 +266,20 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "534c5cf6194dfab3db3242765c03bbe257cf92f22b38f6bc0c58d59108a820ba" dependencies = [ "libc", - "windows-sys", + "windows-sys 0.52.0", ] [[package]] name = "fastrand" -version = "2.1.0" +version = "2.1.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "9fc0510504f03c51ada170672ac806f1f105a88aa97a5281117e1ddc3368e51a" +checksum = "e8c02a5121d4ea3eb16a80748c74f5549a5665e4c21333c6098f283870fbdea6" [[package]] name = "flate2" -version = "1.0.30" +version = "1.0.33" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "5f54427cfd1c7829e2a139fcefea601bf088ebca651d2bf53ebc600eac295dae" +checksum = "324a1be68054ef05ad64b861cc9eaf1d623d2d8cb25b4bf2cb9cdd902b4bf253" dependencies = [ "crc32fast", "miniz_oxide", @@ -335,9 +341,9 @@ dependencies = [ [[package]] name = "is_terminal_polyfill" -version = "1.70.0" +version = "1.70.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "f8478577c03552c21db0e2724ffb8986a5ce7af88107e6be5d2ee6e158c12800" +checksum = "7943c866cc5cd64cbc25b2e01621d07fa8eb2a1a23160ee81ce38704e97b8ecf" [[package]] name = "itoa" @@ -347,9 +353,9 @@ checksum = "49f1f14873335454500d59611f1cf4a4b0f786f9ac11f4312a78e4cf2566695b" [[package]] name = "jobserver" -version = "0.1.31" +version = "0.1.32" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "d2b099aaa34a9751c5bf0878add70444e1ed2dd73f347be99003d4577277de6e" +checksum = "48d1dbcbbeb6a7fec7e059840aa538bd62aaccf972c7346c4d9d2059312853d0" dependencies = [ "libc", ] @@ -364,9 +370,9 @@ dependencies = [ [[package]] name = "libc" -version = "0.2.155" +version = "0.2.158" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "97b3888a4aecf77e811145cadf6eef5901f4782c53886191b2f693f24761847c" +checksum = "d8adc4bb1803a324070e64a98ae98f38934d91957a99cfb3a43dcbc01bc56439" [[package]] name = "linux-raw-sys" @@ -376,9 +382,9 @@ checksum = "78b3ae25bc7c8c38cec158d1f2757ee79e9b3740fbc7ccf0e59e4b08d793fa89" [[package]] name = "log" -version = "0.4.21" +version = "0.4.22" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "90ed8c1e510134f979dbc4f070f87d4313098b704861a105fe34231c70a3901c" +checksum = "a7a70ba024b9dc04c27ea2f0c0548feb474ec5c54bba33a7f72f873a39d07b24" [[package]] name = "memchr" @@ -388,11 +394,11 @@ checksum = "78ca9ab1a0babb1e7d5695e3530886289c18cf2f87ec19a575a0abdce112e3a3" [[package]] name = "miniz_oxide" -version = "0.7.4" +version = "0.8.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "b8a240ddb74feaf34a79a7add65a741f3167852fba007066dcac1ca548d89c08" +checksum = "e2d80299ef12ff69b16a84bb182e3b9df68b5a91574d3d4fa6e41b65deec4df1" dependencies = [ - "adler", + "adler2", ] [[package]] @@ -415,9 +421,12 @@ checksum = "d231b230927b5e4ad203db57bbcbee2802f6bce620b1e4a9024a07d94e2907ec" [[package]] name = "ppv-lite86" -version = "0.2.17" +version = "0.2.20" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "5b40af805b3121feab8a3c29f04d8ad262fa8e0561883e7653e024ae4479e6de" +checksum = "77957b295656769bb8ad2b6a6b09d897d94f05c41b069aede1fcdaa675eaea04" +dependencies = [ + "zerocopy", +] [[package]] name = "proc-macro2" @@ -430,9 +439,9 @@ dependencies = [ [[package]] name = "quote" -version = "1.0.36" +version = "1.0.37" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0fa76aaf39101c457836aec0ce2316dbdc3ab723cdda1c6bd4e6ad4208acaca7" +checksum = "b5b9d34b8991d19d98081b46eacdd8eb58c6f2b201139f7c5f643cc155a633af" dependencies = [ "proc-macro2", ] @@ -475,9 +484,9 @@ dependencies = [ [[package]] name = "regex" -version = "1.10.5" +version = "1.10.6" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "b91213439dad192326a0d7c6ee3955910425f441d7038e0d6933b0aec5c4517f" +checksum = "4219d74c6b67a3654a9fbebc4b419e22126d13d2f3c4a07ee0cb61ff79a79619" dependencies = [ "aho-corasick", "memchr", @@ -514,15 +523,15 @@ dependencies = [ [[package]] name = "rustix" -version = "0.38.34" +version = "0.38.35" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "70dc5ec042f7a43c4a73241207cecc9873a06d45debb38b329f8541d85c2730f" +checksum = "a85d50532239da68e9addb745ba38ff4612a242c1c7ceea689c4bc7c2f43c36f" dependencies = [ "bitflags 2.6.0", "errno", "libc", "linux-raw-sys", - "windows-sys", + "windows-sys 0.52.0", ] [[package]] @@ -533,31 +542,32 @@ checksum = "f3cb5ba0dc43242ce17de99c180e96db90b235b8a9fdc9543c96d2209116bd9f" [[package]] name = "serde" -version = "1.0.203" +version = "1.0.209" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "7253ab4de971e72fb7be983802300c30b5a7f0c2e56fab8abfc6a214307c0094" +checksum = "99fce0ffe7310761ca6bf9faf5115afbc19688edd00171d81b1bb1b116c63e09" dependencies = [ "serde_derive", ] [[package]] name = "serde_derive" -version = "1.0.203" +version = "1.0.209" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "500cbc0ebeb6f46627f50f3f5811ccf6bf00643be300b4c3eabc0ef55dc5b5ba" +checksum = "a5831b979fd7b5439637af1752d535ff49f4860c0f341d1baeb6faf0f4242170" dependencies = [ "proc-macro2", "quote", - "syn 2.0.68", + "syn 2.0.76", ] [[package]] name = "serde_json" -version = "1.0.118" +version = "1.0.127" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "d947f6b3163d8857ea16c4fa0dd4840d52f3041039a85decd46867eb1abef2e4" +checksum = "8043c06d9f82bd7271361ed64f415fe5e12a77fdb52e573e7f06a516dea329ad" dependencies = [ "itoa", + "memchr", "ryu", "serde", ] @@ -568,7 +578,7 @@ version = "0.7.0" dependencies = [ "bitvec", "bzip2", - "clap 4.5.7", + "clap 4.5.16", "flate2", "log", "rand", @@ -593,6 +603,12 @@ dependencies = [ "servicepoint_binding_c", ] +[[package]] +name = "shlex" +version = "1.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64" + [[package]] name = "strsim" version = "0.10.0" @@ -618,9 +634,9 @@ dependencies = [ [[package]] name = "syn" -version = "2.0.68" +version = "2.0.76" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "901fa70d88b9d6c98022e23b4136f9f3e54e4662c3bc1bd1d84a42a9a0f0c1e9" +checksum = "578e081a14e0cefc3279b0472138c513f37b41a08d5a3cca9b6e4e8ceb6cd525" dependencies = [ "proc-macro2", "quote", @@ -635,14 +651,15 @@ checksum = "55937e1799185b12863d447f42597ed69d9928686b8d88a1df17376a097d8369" [[package]] name = "tempfile" -version = "3.10.1" +version = "3.12.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "85b77fafb263dd9d05cbeac119526425676db3784113aa9295c88498cbf8bff1" +checksum = "04cbcdd0c794ebb0d4cf35e88edd2f7d2c4c3e9a5a6dab322839b321c6a87a64" dependencies = [ "cfg-if", "fastrand", + "once_cell", "rustix", - "windows-sys", + "windows-sys 0.59.0", ] [[package]] @@ -711,11 +728,11 @@ checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6" [[package]] name = "winapi-util" -version = "0.1.8" +version = "0.1.9" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "4d4cc384e1e73b93bafa6fb4f1df8c41695c8a91cf9c4c64358067d15a7b6c6b" +checksum = "cf221c93e13a30d793f7645a0e7762c55d169dbb0a49671918a2319d289b10bb" dependencies = [ - "windows-sys", + "windows-sys 0.59.0", ] [[package]] @@ -734,10 +751,19 @@ dependencies = [ ] [[package]] -name = "windows-targets" -version = "0.52.5" +name = "windows-sys" +version = "0.59.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "6f0713a46559409d202e70e28227288446bf7841d3211583a4b53e3f6d96e7eb" +checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b" +dependencies = [ + "windows-targets", +] + +[[package]] +name = "windows-targets" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973" dependencies = [ "windows_aarch64_gnullvm", "windows_aarch64_msvc", @@ -751,51 +777,51 @@ dependencies = [ [[package]] name = "windows_aarch64_gnullvm" -version = "0.52.5" +version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "7088eed71e8b8dda258ecc8bac5fb1153c5cffaf2578fc8ff5d61e23578d3263" +checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3" [[package]] name = "windows_aarch64_msvc" -version = "0.52.5" +version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "9985fd1504e250c615ca5f281c3f7a6da76213ebd5ccc9561496568a2752afb6" +checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469" [[package]] name = "windows_i686_gnu" -version = "0.52.5" +version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "88ba073cf16d5372720ec942a8ccbf61626074c6d4dd2e745299726ce8b89670" +checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b" [[package]] name = "windows_i686_gnullvm" -version = "0.52.5" +version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "87f4261229030a858f36b459e748ae97545d6f1ec60e5e0d6a3d32e0dc232ee9" +checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66" [[package]] name = "windows_i686_msvc" -version = "0.52.5" +version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "db3c2bf3d13d5b658be73463284eaf12830ac9a26a90c717b7f771dfe97487bf" +checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66" [[package]] name = "windows_x86_64_gnu" -version = "0.52.5" +version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "4e4246f76bdeff09eb48875a0fd3e2af6aada79d409d33011886d3e1581517d9" +checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78" [[package]] name = "windows_x86_64_gnullvm" -version = "0.52.5" +version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "852298e482cd67c356ddd9570386e2862b5673c85bd5f88df9ab6802b334c596" +checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d" [[package]] name = "windows_x86_64_msvc" -version = "0.52.5" +version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "bec47e5bfd1bff0eeaf6d8b485cc1074891a197ab4225d504cb7a1ab88b02bf0" +checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec" [[package]] name = "wyz" @@ -807,28 +833,49 @@ dependencies = [ ] [[package]] -name = "zstd" -version = "0.13.1" +name = "zerocopy" +version = "0.7.35" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "2d789b1514203a1120ad2429eae43a7bd32b90976a7bb8a05f7ec02fa88cc23a" +checksum = "1b9b4fd18abc82b8136838da5d50bae7bdea537c574d8dc1a34ed098d6c166f0" +dependencies = [ + "byteorder", + "zerocopy-derive", +] + +[[package]] +name = "zerocopy-derive" +version = "0.7.35" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fa4f8080344d4671fb4e831a13ad1e68092748387dfc4f55e356242fae12ce3e" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.76", +] + +[[package]] +name = "zstd" +version = "0.13.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fcf2b778a664581e31e389454a7072dab1647606d44f7feea22cd5abb9c9f3f9" dependencies = [ "zstd-safe", ] [[package]] name = "zstd-safe" -version = "7.1.0" +version = "7.2.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "1cd99b45c6bc03a018c8b8a86025678c87e55526064e38f9df301989dce7ec0a" +checksum = "54a3ab4db68cea366acc5c897c7b4d4d1b8994a9cd6e6f841f8964566a419059" dependencies = [ "zstd-sys", ] [[package]] name = "zstd-sys" -version = "2.0.11+zstd.1.5.6" +version = "2.0.13+zstd.1.5.6" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "75652c55c0b6f3e6f12eb786fe1bc960396bf05a1eb3bf1f3691c3610ac2e6d4" +checksum = "38ff0f21cfee8f97d94cef41359e0c89aa6113028ab0291aa8ca0038995a95aa" dependencies = [ "cc", "pkg-config", From 956e5df8124855e252190b954a7bfdd7d4d954c5 Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Thu, 29 Aug 2024 20:39:42 +0200 Subject: [PATCH 04/31] CCommand (opaque wrapper around Command for C) --- .../examples/lang_c/include/servicepoint.h | 63 ++++++++------- .../examples/lang_c/src/main.c | 2 +- crates/servicepoint_binding_c/src/command.rs | 80 +++++++++++-------- crates/servicepoint_binding_c/src/packet.rs | 7 +- .../ServicePoint/BindGen/ServicePoint.g.cs | 33 ++++---- .../ServicePoint/Command.cs | 4 +- 6 files changed, 107 insertions(+), 82 deletions(-) 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 d45f50f..5fb4334 100644 --- a/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h +++ b/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h @@ -137,6 +137,11 @@ typedef struct sp_CBitVec sp_CBitVec; */ typedef struct sp_CBrightnessGrid sp_CBrightnessGrid; +/** + * Opaque struct needed for correct code generation. + */ +typedef struct sp_CCommand sp_CCommand; + /** * A C-wrapper for grid containing codepage 437 characters. * @@ -588,9 +593,9 @@ size_t sp_brightness_grid_width(const struct sp_CBrightnessGrid *this_); * - 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_CBitVec *bit_vec, - sp_CompressionCode compression); +struct sp_CCommand *sp_command_bitmap_linear(sp_Offset offset, + struct sp_CBitVec *bit_vec, + sp_CompressionCode compression); /** * Allocates a new `Command::BitmapLinearAnd` instance. @@ -606,9 +611,9 @@ struct sp_Command *sp_command_bitmap_linear(sp_Offset offset, * - 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_CBitVec *bit_vec, - sp_CompressionCode compression); +struct sp_CCommand *sp_command_bitmap_linear_and(sp_Offset offset, + struct sp_CBitVec *bit_vec, + sp_CompressionCode compression); /** * Allocates a new `Command::BitmapLinearOr` instance. @@ -624,9 +629,9 @@ struct sp_Command *sp_command_bitmap_linear_and(sp_Offset offset, * - 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_CBitVec *bit_vec, - sp_CompressionCode compression); +struct sp_CCommand *sp_command_bitmap_linear_or(sp_Offset offset, + struct sp_CBitVec *bit_vec, + sp_CompressionCode compression); /** * Allocates a new `Command::BitmapLinearWin` instance. @@ -642,10 +647,10 @@ struct sp_Command *sp_command_bitmap_linear_or(sp_Offset offset, * - 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 *pixel_grid, - sp_CompressionCode compression_code); +struct sp_CCommand *sp_command_bitmap_linear_win(size_t x, + size_t y, + struct sp_PixelGrid *pixel_grid, + sp_CompressionCode compression_code); /** * Allocates a new `Command::BitmapLinearXor` instance. @@ -661,9 +666,9 @@ struct sp_Command *sp_command_bitmap_linear_win(size_t x, * - 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_CBitVec *bit_vec, - sp_CompressionCode compression); +struct sp_CCommand *sp_command_bitmap_linear_xor(sp_Offset offset, + struct sp_CBitVec *bit_vec, + sp_CompressionCode compression); /** * Allocates a new `Command::Brightness` instance for setting the brightness of all tiles to the @@ -680,7 +685,7 @@ struct sp_Command *sp_command_bitmap_linear_xor(sp_Offset offset, * - 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(uint8_t brightness); +struct sp_CCommand *sp_command_brightness(uint8_t brightness); /** * Allocates a new `Command::CharBrightness` instance. @@ -695,9 +700,9 @@ struct sp_Command *sp_command_brightness(uint8_t brightness); * - 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_CBrightnessGrid *byte_grid); +struct sp_CCommand *sp_command_char_brightness(size_t x, + size_t y, + struct sp_CBrightnessGrid *byte_grid); /** * Allocates a new `Command::Clear` instance. @@ -709,7 +714,7 @@ struct sp_Command *sp_command_char_brightness(size_t x, * - 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); +struct sp_CCommand *sp_command_clear(void); /** * Clones a `Command` instance. @@ -723,7 +728,7 @@ struct sp_Command *sp_command_clear(void); * - 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); +struct sp_CCommand *sp_command_clone(const struct sp_CCommand *original); /** * Allocates a new `Command::Cp437Data` instance. @@ -738,9 +743,9 @@ struct sp_Command *sp_command_clone(const struct sp_Command *original); * - 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_CCp437Grid *byte_grid); +struct sp_CCommand *sp_command_cp437_data(size_t x, + size_t y, + struct sp_CCp437Grid *byte_grid); /** * Deallocates a `Command`. @@ -753,7 +758,7 @@ struct sp_Command *sp_command_cp437_data(size_t x, * - `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); +void sp_command_dealloc(struct sp_CCommand *ptr); /** * Allocates a new `Command::FadeOut` instance. @@ -765,7 +770,7 @@ void sp_command_dealloc(struct sp_Command *ptr); * - 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); +struct sp_CCommand *sp_command_fade_out(void); /** * Allocates a new `Command::HardReset` instance. @@ -777,7 +782,7 @@ struct sp_Command *sp_command_fade_out(void); * - 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); +struct sp_CCommand *sp_command_hard_reset(void); /** * Tries to turn a `Packet` into a `Command`. The packet is deallocated in the process. @@ -794,7 +799,7 @@ struct sp_Command *sp_command_hard_reset(void); * - 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); +struct sp_CCommand *sp_command_try_from_packet(struct sp_Packet *packet); /** * Closes and deallocates a `Connection`. diff --git a/crates/servicepoint_binding_c/examples/lang_c/src/main.c b/crates/servicepoint_binding_c/examples/lang_c/src/main.c index 3951293..10477a8 100644 --- a/crates/servicepoint_binding_c/examples/lang_c/src/main.c +++ b/crates/servicepoint_binding_c/examples/lang_c/src/main.c @@ -9,7 +9,7 @@ int main(void) { sp_PixelGrid *pixels = sp_pixel_grid_new(sp_PIXEL_WIDTH, sp_PIXEL_HEIGHT); sp_pixel_grid_fill(pixels, true); - sp_Command *command = sp_command_bitmap_linear_win(0, 0, pixels, Uncompressed); + sp_CCommand *command = sp_command_bitmap_linear_win(0, 0, pixels, Uncompressed); sp_Packet *packet = sp_packet_from_command(command); if (!sp_connection_send(connection, packet)) return 1; diff --git a/crates/servicepoint_binding_c/src/command.rs b/crates/servicepoint_binding_c/src/command.rs index 823e3d6..2e2bc7e 100644 --- a/crates/servicepoint_binding_c/src/command.rs +++ b/crates/servicepoint_binding_c/src/command.rs @@ -12,6 +12,15 @@ use crate::bit_vec::CBitVec; use crate::brightness_grid::CBrightnessGrid; use crate::cp437_grid::CCp437Grid; +/// Opaque struct needed for correct code generation. +pub struct CCommand(pub(crate) Command); + +impl Clone for CCommand { + fn clone(&self) -> Self { + CCommand(self.0.clone()) + } +} + /// Tries to turn a `Packet` into a `Command`. The packet is deallocated in the process. /// /// Returns: pointer to new `Command` instance or NULL @@ -28,11 +37,11 @@ use crate::cp437_grid::CCp437Grid; #[no_mangle] pub unsafe extern "C" fn sp_command_try_from_packet( packet: *mut Packet, -) -> *mut Command { +) -> *mut CCommand { let packet = *Box::from_raw(packet); match Command::try_from(packet) { Err(_) => null_mut(), - Ok(command) => Box::into_raw(Box::new(command)), + Ok(command) => Box::into_raw(Box::new(CCommand(command))), } } @@ -48,8 +57,8 @@ pub unsafe extern "C" fn sp_command_try_from_packet( /// by explicitly calling `sp_command_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_command_clone( - original: *const Command, -) -> *mut Command { + original: *const CCommand, +) -> *mut CCommand { Box::into_raw(Box::new((*original).clone())) } @@ -62,8 +71,8 @@ pub unsafe extern "C" fn sp_command_clone( /// - 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)) +pub unsafe extern "C" fn sp_command_clear() -> *mut CCommand { + Box::into_raw(Box::new(CCommand(Command::Clear))) } /// Allocates a new `Command::HardReset` instance. @@ -75,8 +84,8 @@ pub unsafe extern "C" fn sp_command_clear() -> *mut Command { /// - 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)) +pub unsafe extern "C" fn sp_command_hard_reset() -> *mut CCommand { + Box::into_raw(Box::new(CCommand(Command::HardReset))) } /// Allocates a new `Command::FadeOut` instance. @@ -88,8 +97,8 @@ pub unsafe extern "C" fn sp_command_hard_reset() -> *mut Command { /// - 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)) +pub unsafe extern "C" fn sp_command_fade_out() -> *mut CCommand { + Box::into_raw(Box::new(CCommand(Command::FadeOut))) } /// Allocates a new `Command::Brightness` instance for setting the brightness of all tiles to the @@ -106,10 +115,12 @@ pub unsafe extern "C" fn sp_command_fade_out() -> *mut Command { /// - 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: u8) -> *mut Command { +pub unsafe extern "C" fn sp_command_brightness( + brightness: u8, +) -> *mut CCommand { let brightness = Brightness::try_from(brightness).expect("invalid brightness"); - Box::into_raw(Box::new(Command::Brightness(brightness))) + Box::into_raw(Box::new(CCommand(Command::Brightness(brightness)))) } /// Allocates a new `Command::CharBrightness` instance. @@ -128,12 +139,12 @@ pub unsafe extern "C" fn sp_command_char_brightness( x: usize, y: usize, byte_grid: *mut CBrightnessGrid, -) -> *mut Command { +) -> *mut CCommand { let byte_grid = *Box::from_raw(byte_grid); - Box::into_raw(Box::new(Command::CharBrightness( + Box::into_raw(Box::new(CCommand(Command::CharBrightness( Origin::new(x, y), byte_grid.0, - ))) + )))) } /// Allocates a new `Command::BitmapLinear` instance. @@ -153,13 +164,13 @@ pub unsafe extern "C" fn sp_command_bitmap_linear( offset: Offset, bit_vec: *mut CBitVec, compression: CompressionCode, -) -> *mut Command { +) -> *mut CCommand { let bit_vec = *Box::from_raw(bit_vec); - Box::into_raw(Box::new(Command::BitmapLinear( + Box::into_raw(Box::new(CCommand(Command::BitmapLinear( offset, bit_vec.into(), compression, - ))) + )))) } /// Allocates a new `Command::BitmapLinearAnd` instance. @@ -179,13 +190,13 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_and( offset: Offset, bit_vec: *mut CBitVec, compression: CompressionCode, -) -> *mut Command { +) -> *mut CCommand { let bit_vec = *Box::from_raw(bit_vec); - Box::into_raw(Box::new(Command::BitmapLinearAnd( + Box::into_raw(Box::new(CCommand(Command::BitmapLinearAnd( offset, bit_vec.into(), compression, - ))) + )))) } /// Allocates a new `Command::BitmapLinearOr` instance. @@ -205,13 +216,13 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_or( offset: Offset, bit_vec: *mut CBitVec, compression: CompressionCode, -) -> *mut Command { +) -> *mut CCommand { let bit_vec = *Box::from_raw(bit_vec); - Box::into_raw(Box::new(Command::BitmapLinearOr( + Box::into_raw(Box::new(CCommand(Command::BitmapLinearOr( offset, bit_vec.into(), compression, - ))) + )))) } /// Allocates a new `Command::BitmapLinearXor` instance. @@ -231,13 +242,13 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_xor( offset: Offset, bit_vec: *mut CBitVec, compression: CompressionCode, -) -> *mut Command { +) -> *mut CCommand { let bit_vec = *Box::from_raw(bit_vec); - Box::into_raw(Box::new(Command::BitmapLinearXor( + Box::into_raw(Box::new(CCommand(Command::BitmapLinearXor( offset, bit_vec.into(), compression, - ))) + )))) } /// Allocates a new `Command::Cp437Data` instance. @@ -256,9 +267,12 @@ pub unsafe extern "C" fn sp_command_cp437_data( x: usize, y: usize, byte_grid: *mut CCp437Grid, -) -> *mut Command { +) -> *mut CCommand { let byte_grid = *Box::from_raw(byte_grid); - Box::into_raw(Box::new(Command::Cp437Data(Origin::new(x, y), byte_grid.0))) + Box::into_raw(Box::new(CCommand(Command::Cp437Data( + Origin::new(x, y), + byte_grid.0, + )))) } /// Allocates a new `Command::BitmapLinearWin` instance. @@ -279,13 +293,13 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_win( y: usize, pixel_grid: *mut PixelGrid, compression_code: CompressionCode, -) -> *mut Command { +) -> *mut CCommand { let byte_grid = *Box::from_raw(pixel_grid); - Box::into_raw(Box::new(Command::BitmapLinearWin( + Box::into_raw(Box::new(CCommand(Command::BitmapLinearWin( Origin::new(x, y), byte_grid, compression_code, - ))) + )))) } /// Deallocates a `Command`. @@ -298,6 +312,6 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_win( /// - `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) { +pub unsafe extern "C" fn sp_command_dealloc(ptr: *mut CCommand) { _ = Box::from_raw(ptr); } diff --git a/crates/servicepoint_binding_c/src/packet.rs b/crates/servicepoint_binding_c/src/packet.rs index 952ef1e..402418f 100644 --- a/crates/servicepoint_binding_c/src/packet.rs +++ b/crates/servicepoint_binding_c/src/packet.rs @@ -4,7 +4,8 @@ use std::ptr::null_mut; -use servicepoint::{Command, Packet}; +use crate::command::CCommand; +use servicepoint::Packet; /// Turns a `Command` into a `Packet`. /// The `Command` gets consumed. @@ -19,10 +20,10 @@ use servicepoint::{Command, Packet}; /// by explicitly calling `sp_packet_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_packet_from_command( - command: *mut Command, + command: *mut CCommand, ) -> *mut Packet { let command = *Box::from_raw(command); - let packet = command.into(); + let packet = command.0.into(); Box::into_raw(Box::new(packet)) } diff --git a/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs b/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs index cf9fb4e..6a743b0 100644 --- a/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs +++ b/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs @@ -561,7 +561,7 @@ namespace ServicePoint.BindGen /// 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); + public static extern CCommand* sp_command_try_from_packet(Packet* packet); /// /// Clones a `Command` instance. @@ -576,7 +576,7 @@ namespace ServicePoint.BindGen /// 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); + public static extern CCommand* sp_command_clone(CCommand* original); /// /// Allocates a new `Command::Clear` instance. @@ -589,7 +589,7 @@ namespace ServicePoint.BindGen /// by explicitly calling `sp_command_dealloc`. /// [DllImport(__DllName, EntryPoint = "sp_command_clear", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern Command* sp_command_clear(); + public static extern CCommand* sp_command_clear(); /// /// Allocates a new `Command::HardReset` instance. @@ -602,7 +602,7 @@ namespace ServicePoint.BindGen /// 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(); + public static extern CCommand* sp_command_hard_reset(); /// /// Allocates a new `Command::FadeOut` instance. @@ -615,7 +615,7 @@ namespace ServicePoint.BindGen /// 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(); + public static extern CCommand* sp_command_fade_out(); /// /// Allocates a new `Command::Brightness` instance for setting the brightness of all tiles to the @@ -633,7 +633,7 @@ namespace ServicePoint.BindGen /// 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); + public static extern CCommand* sp_command_brightness(byte brightness); /// /// Allocates a new `Command::CharBrightness` instance. @@ -649,7 +649,7 @@ namespace ServicePoint.BindGen /// 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, CBrightnessGrid* byte_grid); + public static extern CCommand* sp_command_char_brightness(nuint x, nuint y, CBrightnessGrid* byte_grid); /// /// Allocates a new `Command::BitmapLinear` instance. @@ -666,7 +666,7 @@ namespace ServicePoint.BindGen /// 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, CBitVec* bit_vec, CompressionCode compression); + public static extern CCommand* sp_command_bitmap_linear(nuint offset, CBitVec* bit_vec, CompressionCode compression); /// /// Allocates a new `Command::BitmapLinearAnd` instance. @@ -683,7 +683,7 @@ namespace ServicePoint.BindGen /// 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, CBitVec* bit_vec, CompressionCode compression); + public static extern CCommand* sp_command_bitmap_linear_and(nuint offset, CBitVec* bit_vec, CompressionCode compression); /// /// Allocates a new `Command::BitmapLinearOr` instance. @@ -700,7 +700,7 @@ namespace ServicePoint.BindGen /// 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, CBitVec* bit_vec, CompressionCode compression); + public static extern CCommand* sp_command_bitmap_linear_or(nuint offset, CBitVec* bit_vec, CompressionCode compression); /// /// Allocates a new `Command::BitmapLinearXor` instance. @@ -717,7 +717,7 @@ namespace ServicePoint.BindGen /// 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, CBitVec* bit_vec, CompressionCode compression); + public static extern CCommand* sp_command_bitmap_linear_xor(nuint offset, CBitVec* bit_vec, CompressionCode compression); /// /// Allocates a new `Command::Cp437Data` instance. @@ -733,7 +733,7 @@ namespace ServicePoint.BindGen /// 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, CCp437Grid* byte_grid); + public static extern CCommand* sp_command_cp437_data(nuint x, nuint y, CCp437Grid* byte_grid); /// /// Allocates a new `Command::BitmapLinearWin` instance. @@ -750,7 +750,7 @@ namespace ServicePoint.BindGen /// 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* pixel_grid, CompressionCode compression_code); + public static extern CCommand* sp_command_bitmap_linear_win(nuint x, nuint y, PixelGrid* pixel_grid, CompressionCode compression_code); /// /// Deallocates a `Command`. @@ -764,7 +764,7 @@ namespace ServicePoint.BindGen /// - `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); + public static extern void sp_command_dealloc(CCommand* ptr); /// /// Creates a new instance of `Connection`. @@ -1071,6 +1071,11 @@ namespace ServicePoint.BindGen { } + [StructLayout(LayoutKind.Sequential)] + public unsafe partial struct CCommand + { + } + [StructLayout(LayoutKind.Sequential)] public unsafe partial struct CByteSlice { diff --git a/crates/servicepoint_binding_cs/ServicePoint/Command.cs b/crates/servicepoint_binding_cs/ServicePoint/Command.cs index a0349c8..e9512a3 100644 --- a/crates/servicepoint_binding_cs/ServicePoint/Command.cs +++ b/crates/servicepoint_binding_cs/ServicePoint/Command.cs @@ -3,7 +3,7 @@ using ServicePoint.BindGen; namespace ServicePoint; -public sealed class Command : SpNativeInstance +public sealed class Command : SpNativeInstance { public static bool TryFromPacket(Packet packet, [MaybeNullWhen(false)] out Command command) { @@ -121,7 +121,7 @@ public sealed class Command : SpNativeInstance } } - private unsafe Command(BindGen.Command* instance) : base(instance) + private unsafe Command(BindGen.CCommand* instance) : base(instance) { } From e0d5eff494d8c7dc6f25c85dfde93e89a67eb68e Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Thu, 29 Aug 2024 21:40:33 +0200 Subject: [PATCH 05/31] remove C prefix in csbindgen --- .../ServicePoint/BindGen/ServicePoint.g.cs | 100 +++++++++--------- .../ServicePoint/BitVec.cs | 4 +- .../ServicePoint/BrightnessGrid.cs | 4 +- .../ServicePoint/Command.cs | 4 +- .../ServicePoint/Cp437Grid.cs | 4 +- crates/servicepoint_binding_cs/build.rs | 10 ++ 6 files changed, 68 insertions(+), 58 deletions(-) diff --git a/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs b/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs index 6a743b0..6545319 100644 --- a/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs +++ b/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs @@ -40,7 +40,7 @@ namespace ServicePoint.BindGen /// by explicitly calling `sp_bit_vec_dealloc`. /// [DllImport(__DllName, EntryPoint = "sp_bit_vec_new", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern CBitVec* sp_bit_vec_new(nuint size); + public static extern BitVec* sp_bit_vec_new(nuint size); /// /// Interpret the data as a series of bits and load then into a new `BitVec` instance. @@ -55,7 +55,7 @@ namespace ServicePoint.BindGen /// by explicitly calling `sp_bit_vec_dealloc`. /// [DllImport(__DllName, EntryPoint = "sp_bit_vec_load", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern CBitVec* sp_bit_vec_load(byte* data, nuint data_length); + public static extern BitVec* sp_bit_vec_load(byte* data, nuint data_length); /// /// Clones a `BitVec`. @@ -70,7 +70,7 @@ namespace ServicePoint.BindGen /// by explicitly calling `sp_bit_vec_dealloc`. /// [DllImport(__DllName, EntryPoint = "sp_bit_vec_clone", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern CBitVec* sp_bit_vec_clone(CBitVec* @this); + public static extern BitVec* sp_bit_vec_clone(BitVec* @this); /// /// Deallocates a `BitVec`. @@ -84,7 +84,7 @@ namespace ServicePoint.BindGen /// - `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(CBitVec* @this); + public static extern void sp_bit_vec_dealloc(BitVec* @this); /// /// Gets the value of a bit from the `BitVec`. @@ -109,7 +109,7 @@ namespace ServicePoint.BindGen /// [DllImport(__DllName, EntryPoint = "sp_bit_vec_get", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] [return: MarshalAs(UnmanagedType.U1)] - public static extern bool sp_bit_vec_get(CBitVec* @this, nuint index); + public static extern bool sp_bit_vec_get(BitVec* @this, nuint index); /// /// Sets the value of a bit in the `BitVec`. @@ -134,7 +134,7 @@ namespace ServicePoint.BindGen /// - `this` is not written to or read from concurrently /// [DllImport(__DllName, EntryPoint = "sp_bit_vec_set", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern void sp_bit_vec_set(CBitVec* @this, nuint index, [MarshalAs(UnmanagedType.U1)] bool value); + public static extern void sp_bit_vec_set(BitVec* @this, nuint index, [MarshalAs(UnmanagedType.U1)] bool value); /// /// Sets the value of all bits in the `BitVec`. @@ -151,7 +151,7 @@ namespace ServicePoint.BindGen /// - `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(CBitVec* @this, [MarshalAs(UnmanagedType.U1)] bool value); + public static extern void sp_bit_vec_fill(BitVec* @this, [MarshalAs(UnmanagedType.U1)] bool value); /// /// Gets the length of the `BitVec` in bits. @@ -163,7 +163,7 @@ namespace ServicePoint.BindGen /// - `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(CBitVec* @this); + public static extern nuint sp_bit_vec_len(BitVec* @this); /// /// Returns true if length is 0. @@ -176,7 +176,7 @@ namespace ServicePoint.BindGen /// [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(CBitVec* @this); + public static extern bool sp_bit_vec_is_empty(BitVec* @this); /// /// Gets an unsafe reference to the data of the `BitVec` instance. @@ -190,7 +190,7 @@ namespace ServicePoint.BindGen /// - 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(CBitVec* @this); + public static extern ByteSlice sp_bit_vec_unsafe_data_ref(BitVec* @this); /// /// Creates a new `BrightnessGrid` with the specified dimensions. @@ -205,7 +205,7 @@ namespace ServicePoint.BindGen /// by explicitly calling `sp_brightness_grid_dealloc`. /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_new", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern CBrightnessGrid* sp_brightness_grid_new(nuint width, nuint height); + public static extern BrightnessGrid* sp_brightness_grid_new(nuint width, nuint height); /// /// Loads a `BrightnessGrid` with the specified dimensions from the provided data. @@ -224,7 +224,7 @@ namespace ServicePoint.BindGen /// by explicitly calling `sp_brightness_grid_dealloc`. /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_load", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern CBrightnessGrid* sp_brightness_grid_load(nuint width, nuint height, byte* data, nuint data_length); + public static extern BrightnessGrid* sp_brightness_grid_load(nuint width, nuint height, byte* data, nuint data_length); /// /// Clones a `BrightnessGrid`. @@ -239,7 +239,7 @@ namespace ServicePoint.BindGen /// by explicitly calling `sp_brightness_grid_dealloc`. /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_clone", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern CBrightnessGrid* sp_brightness_grid_clone(CBrightnessGrid* @this); + public static extern BrightnessGrid* sp_brightness_grid_clone(BrightnessGrid* @this); /// /// Deallocates a `BrightnessGrid`. @@ -253,7 +253,7 @@ namespace ServicePoint.BindGen /// - `this` was not passed to another consuming function, e.g. to create a `Command` /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_dealloc", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern void sp_brightness_grid_dealloc(CBrightnessGrid* @this); + public static extern void sp_brightness_grid_dealloc(BrightnessGrid* @this); /// /// Gets the current value at the specified position. @@ -275,7 +275,7 @@ namespace ServicePoint.BindGen /// - `this` is not written to concurrently /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_get", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern byte sp_brightness_grid_get(CBrightnessGrid* @this, nuint x, nuint y); + public static extern byte sp_brightness_grid_get(BrightnessGrid* @this, nuint x, nuint y); /// /// Sets the value of the specified position in the `BrightnessGrid`. @@ -301,7 +301,7 @@ namespace ServicePoint.BindGen /// - `this` is not written to or read from concurrently /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_set", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern void sp_brightness_grid_set(CBrightnessGrid* @this, nuint x, nuint y, byte value); + public static extern void sp_brightness_grid_set(BrightnessGrid* @this, nuint x, nuint y, byte value); /// /// Sets the value of all cells in the `BrightnessGrid`. @@ -323,7 +323,7 @@ namespace ServicePoint.BindGen /// - `this` is not written to or read from concurrently /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_fill", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern void sp_brightness_grid_fill(CBrightnessGrid* @this, byte value); + public static extern void sp_brightness_grid_fill(BrightnessGrid* @this, byte value); /// /// Gets the width of the `BrightnessGrid` instance. @@ -339,7 +339,7 @@ namespace ServicePoint.BindGen /// - `this` points to a valid `BrightnessGrid` /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_width", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern nuint sp_brightness_grid_width(CBrightnessGrid* @this); + public static extern nuint sp_brightness_grid_width(BrightnessGrid* @this); /// /// Gets the height of the `BrightnessGrid` instance. @@ -355,7 +355,7 @@ namespace ServicePoint.BindGen /// - `this` points to a valid `BrightnessGrid` /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_height", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern nuint sp_brightness_grid_height(CBrightnessGrid* @this); + public static extern nuint sp_brightness_grid_height(BrightnessGrid* @this); /// /// Gets an unsafe reference to the data of the `BrightnessGrid` instance. @@ -369,7 +369,7 @@ namespace ServicePoint.BindGen /// - the returned memory range is never accessed concurrently, either via the `BrightnessGrid` or directly /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_unsafe_data_ref", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern CByteSlice sp_brightness_grid_unsafe_data_ref(CBrightnessGrid* @this); + public static extern ByteSlice sp_brightness_grid_unsafe_data_ref(BrightnessGrid* @this); /// /// Creates a new `Cp437Grid` with the specified dimensions. @@ -384,7 +384,7 @@ namespace ServicePoint.BindGen /// by explicitly calling `sp_cp437_grid_dealloc`. /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_new", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern CCp437Grid* sp_cp437_grid_new(nuint width, nuint height); + public static extern Cp437Grid* sp_cp437_grid_new(nuint width, nuint height); /// /// Loads a `Cp437Grid` with the specified dimensions from the provided data. @@ -403,7 +403,7 @@ namespace ServicePoint.BindGen /// by explicitly calling `sp_cp437_grid_dealloc`. /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_load", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern CCp437Grid* sp_cp437_grid_load(nuint width, nuint height, byte* data, nuint data_length); + public static extern Cp437Grid* sp_cp437_grid_load(nuint width, nuint height, byte* data, nuint data_length); /// /// Clones a `Cp437Grid`. @@ -418,7 +418,7 @@ namespace ServicePoint.BindGen /// by explicitly calling `sp_cp437_grid_dealloc`. /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_clone", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern CCp437Grid* sp_cp437_grid_clone(CCp437Grid* @this); + public static extern Cp437Grid* sp_cp437_grid_clone(Cp437Grid* @this); /// /// Deallocates a `Cp437Grid`. @@ -432,7 +432,7 @@ namespace ServicePoint.BindGen /// - `this` was not passed to another consuming function, e.g. to create a `Command` /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_dealloc", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern void sp_cp437_grid_dealloc(CCp437Grid* @this); + public static extern void sp_cp437_grid_dealloc(Cp437Grid* @this); /// /// Gets the current value at the specified position. @@ -454,7 +454,7 @@ namespace ServicePoint.BindGen /// - `this` is not written to concurrently /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_get", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern byte sp_cp437_grid_get(CCp437Grid* @this, nuint x, nuint y); + public static extern byte sp_cp437_grid_get(Cp437Grid* @this, nuint x, nuint y); /// /// Sets the value of the specified position in the `Cp437Grid`. @@ -479,7 +479,7 @@ namespace ServicePoint.BindGen /// - `this` is not written to or read from concurrently /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_set", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern void sp_cp437_grid_set(CCp437Grid* @this, nuint x, nuint y, byte value); + public static extern void sp_cp437_grid_set(Cp437Grid* @this, nuint x, nuint y, byte value); /// /// Sets the value of all cells in the `Cp437Grid`. @@ -497,7 +497,7 @@ namespace ServicePoint.BindGen /// - `this` is not written to or read from concurrently /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_fill", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern void sp_cp437_grid_fill(CCp437Grid* @this, byte value); + public static extern void sp_cp437_grid_fill(Cp437Grid* @this, byte value); /// /// Gets the width of the `Cp437Grid` instance. @@ -513,7 +513,7 @@ namespace ServicePoint.BindGen /// - `this` points to a valid `Cp437Grid` /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_width", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern nuint sp_cp437_grid_width(CCp437Grid* @this); + public static extern nuint sp_cp437_grid_width(Cp437Grid* @this); /// /// Gets the height of the `Cp437Grid` instance. @@ -529,7 +529,7 @@ namespace ServicePoint.BindGen /// - `this` points to a valid `Cp437Grid` /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_height", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern nuint sp_cp437_grid_height(CCp437Grid* @this); + public static extern nuint sp_cp437_grid_height(Cp437Grid* @this); /// /// Gets an unsafe reference to the data of the `Cp437Grid` instance. @@ -543,7 +543,7 @@ namespace ServicePoint.BindGen /// - the returned memory range is never accessed concurrently, either via the `Cp437Grid` or directly /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_unsafe_data_ref", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern CByteSlice sp_cp437_grid_unsafe_data_ref(CCp437Grid* @this); + public static extern ByteSlice sp_cp437_grid_unsafe_data_ref(Cp437Grid* @this); /// /// Tries to turn a `Packet` into a `Command`. The packet is deallocated in the process. @@ -561,7 +561,7 @@ namespace ServicePoint.BindGen /// by explicitly calling `sp_command_dealloc`. /// [DllImport(__DllName, EntryPoint = "sp_command_try_from_packet", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern CCommand* sp_command_try_from_packet(Packet* packet); + public static extern Command* sp_command_try_from_packet(Packet* packet); /// /// Clones a `Command` instance. @@ -576,7 +576,7 @@ namespace ServicePoint.BindGen /// by explicitly calling `sp_command_dealloc`. /// [DllImport(__DllName, EntryPoint = "sp_command_clone", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern CCommand* sp_command_clone(CCommand* original); + public static extern Command* sp_command_clone(Command* original); /// /// Allocates a new `Command::Clear` instance. @@ -589,7 +589,7 @@ namespace ServicePoint.BindGen /// by explicitly calling `sp_command_dealloc`. /// [DllImport(__DllName, EntryPoint = "sp_command_clear", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern CCommand* sp_command_clear(); + public static extern Command* sp_command_clear(); /// /// Allocates a new `Command::HardReset` instance. @@ -602,7 +602,7 @@ namespace ServicePoint.BindGen /// by explicitly calling `sp_command_dealloc`. /// [DllImport(__DllName, EntryPoint = "sp_command_hard_reset", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern CCommand* sp_command_hard_reset(); + public static extern Command* sp_command_hard_reset(); /// /// Allocates a new `Command::FadeOut` instance. @@ -615,7 +615,7 @@ namespace ServicePoint.BindGen /// by explicitly calling `sp_command_dealloc`. /// [DllImport(__DllName, EntryPoint = "sp_command_fade_out", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern CCommand* sp_command_fade_out(); + public static extern Command* sp_command_fade_out(); /// /// Allocates a new `Command::Brightness` instance for setting the brightness of all tiles to the @@ -633,7 +633,7 @@ namespace ServicePoint.BindGen /// by explicitly calling `sp_command_dealloc`. /// [DllImport(__DllName, EntryPoint = "sp_command_brightness", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern CCommand* sp_command_brightness(byte brightness); + public static extern Command* sp_command_brightness(byte brightness); /// /// Allocates a new `Command::CharBrightness` instance. @@ -649,7 +649,7 @@ namespace ServicePoint.BindGen /// by explicitly calling `sp_command_dealloc`. /// [DllImport(__DllName, EntryPoint = "sp_command_char_brightness", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern CCommand* sp_command_char_brightness(nuint x, nuint y, CBrightnessGrid* byte_grid); + public static extern Command* sp_command_char_brightness(nuint x, nuint y, BrightnessGrid* byte_grid); /// /// Allocates a new `Command::BitmapLinear` instance. @@ -666,7 +666,7 @@ namespace ServicePoint.BindGen /// by explicitly calling `sp_command_dealloc`. /// [DllImport(__DllName, EntryPoint = "sp_command_bitmap_linear", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern CCommand* sp_command_bitmap_linear(nuint offset, CBitVec* bit_vec, CompressionCode compression); + public static extern Command* sp_command_bitmap_linear(nuint offset, BitVec* bit_vec, CompressionCode compression); /// /// Allocates a new `Command::BitmapLinearAnd` instance. @@ -683,7 +683,7 @@ namespace ServicePoint.BindGen /// by explicitly calling `sp_command_dealloc`. /// [DllImport(__DllName, EntryPoint = "sp_command_bitmap_linear_and", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern CCommand* sp_command_bitmap_linear_and(nuint offset, CBitVec* bit_vec, CompressionCode compression); + public static extern Command* sp_command_bitmap_linear_and(nuint offset, BitVec* bit_vec, CompressionCode compression); /// /// Allocates a new `Command::BitmapLinearOr` instance. @@ -700,7 +700,7 @@ namespace ServicePoint.BindGen /// by explicitly calling `sp_command_dealloc`. /// [DllImport(__DllName, EntryPoint = "sp_command_bitmap_linear_or", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern CCommand* sp_command_bitmap_linear_or(nuint offset, CBitVec* bit_vec, CompressionCode compression); + public static extern Command* sp_command_bitmap_linear_or(nuint offset, BitVec* bit_vec, CompressionCode compression); /// /// Allocates a new `Command::BitmapLinearXor` instance. @@ -717,7 +717,7 @@ namespace ServicePoint.BindGen /// by explicitly calling `sp_command_dealloc`. /// [DllImport(__DllName, EntryPoint = "sp_command_bitmap_linear_xor", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern CCommand* sp_command_bitmap_linear_xor(nuint offset, CBitVec* bit_vec, CompressionCode compression); + public static extern Command* sp_command_bitmap_linear_xor(nuint offset, BitVec* bit_vec, CompressionCode compression); /// /// Allocates a new `Command::Cp437Data` instance. @@ -733,7 +733,7 @@ namespace ServicePoint.BindGen /// by explicitly calling `sp_command_dealloc`. /// [DllImport(__DllName, EntryPoint = "sp_command_cp437_data", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern CCommand* sp_command_cp437_data(nuint x, nuint y, CCp437Grid* byte_grid); + public static extern Command* sp_command_cp437_data(nuint x, nuint y, Cp437Grid* byte_grid); /// /// Allocates a new `Command::BitmapLinearWin` instance. @@ -750,7 +750,7 @@ namespace ServicePoint.BindGen /// by explicitly calling `sp_command_dealloc`. /// [DllImport(__DllName, EntryPoint = "sp_command_bitmap_linear_win", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern CCommand* sp_command_bitmap_linear_win(nuint x, nuint y, PixelGrid* pixel_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`. @@ -764,7 +764,7 @@ namespace ServicePoint.BindGen /// - `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(CCommand* ptr); + public static extern void sp_command_dealloc(Command* ptr); /// /// Creates a new instance of `Connection`. @@ -1005,7 +1005,7 @@ namespace ServicePoint.BindGen /// - 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); + public static extern ByteSlice sp_pixel_grid_unsafe_data_ref(PixelGrid* @this); /// /// Turns a `Command` into a `Packet`. @@ -1057,27 +1057,27 @@ namespace ServicePoint.BindGen } [StructLayout(LayoutKind.Sequential)] - public unsafe partial struct CBitVec + public unsafe partial struct BitVec { } [StructLayout(LayoutKind.Sequential)] - public unsafe partial struct CBrightnessGrid + public unsafe partial struct BrightnessGrid { } [StructLayout(LayoutKind.Sequential)] - public unsafe partial struct CCp437Grid + public unsafe partial struct Cp437Grid { } [StructLayout(LayoutKind.Sequential)] - public unsafe partial struct CCommand + public unsafe partial struct Command { } [StructLayout(LayoutKind.Sequential)] - public unsafe partial struct CByteSlice + public unsafe partial struct ByteSlice { public byte* start; public nuint length; diff --git a/crates/servicepoint_binding_cs/ServicePoint/BitVec.cs b/crates/servicepoint_binding_cs/ServicePoint/BitVec.cs index 53ee65c..13b2200 100644 --- a/crates/servicepoint_binding_cs/ServicePoint/BitVec.cs +++ b/crates/servicepoint_binding_cs/ServicePoint/BitVec.cs @@ -2,7 +2,7 @@ using ServicePoint.BindGen; namespace ServicePoint; -public sealed class BitVec : SpNativeInstance +public sealed class BitVec : SpNativeInstance { public static BitVec New(int size) { @@ -80,7 +80,7 @@ public sealed class BitVec : SpNativeInstance } } - private unsafe BitVec(BindGen.CBitVec* instance) : base(instance) + private unsafe BitVec(BindGen.BitVec* instance) : base(instance) { } diff --git a/crates/servicepoint_binding_cs/ServicePoint/BrightnessGrid.cs b/crates/servicepoint_binding_cs/ServicePoint/BrightnessGrid.cs index 36af6e0..b80f64f 100644 --- a/crates/servicepoint_binding_cs/ServicePoint/BrightnessGrid.cs +++ b/crates/servicepoint_binding_cs/ServicePoint/BrightnessGrid.cs @@ -2,7 +2,7 @@ using ServicePoint.BindGen; namespace ServicePoint; -public sealed class BrightnessGrid : SpNativeInstance +public sealed class BrightnessGrid : SpNativeInstance { public static BrightnessGrid New(int width, int height) { @@ -92,7 +92,7 @@ public sealed class BrightnessGrid : SpNativeInstance } } - private unsafe BrightnessGrid(BindGen.CBrightnessGrid* instance) : base(instance) + private unsafe BrightnessGrid(BindGen.BrightnessGrid* instance) : base(instance) { } diff --git a/crates/servicepoint_binding_cs/ServicePoint/Command.cs b/crates/servicepoint_binding_cs/ServicePoint/Command.cs index e9512a3..a0349c8 100644 --- a/crates/servicepoint_binding_cs/ServicePoint/Command.cs +++ b/crates/servicepoint_binding_cs/ServicePoint/Command.cs @@ -3,7 +3,7 @@ using ServicePoint.BindGen; namespace ServicePoint; -public sealed class Command : SpNativeInstance +public sealed class Command : SpNativeInstance { public static bool TryFromPacket(Packet packet, [MaybeNullWhen(false)] out Command command) { @@ -121,7 +121,7 @@ public sealed class Command : SpNativeInstance } } - private unsafe Command(BindGen.CCommand* instance) : base(instance) + private unsafe Command(BindGen.Command* instance) : base(instance) { } diff --git a/crates/servicepoint_binding_cs/ServicePoint/Cp437Grid.cs b/crates/servicepoint_binding_cs/ServicePoint/Cp437Grid.cs index 01a83fb..e795c85 100644 --- a/crates/servicepoint_binding_cs/ServicePoint/Cp437Grid.cs +++ b/crates/servicepoint_binding_cs/ServicePoint/Cp437Grid.cs @@ -3,7 +3,7 @@ using ServicePoint.BindGen; namespace ServicePoint; -public sealed class Cp437Grid : SpNativeInstance +public sealed class Cp437Grid : SpNativeInstance { public static Cp437Grid New(int width, int height) { @@ -123,7 +123,7 @@ public sealed class Cp437Grid : SpNativeInstance } } - private unsafe Cp437Grid(BindGen.CCp437Grid* instance) : base(instance) + private unsafe Cp437Grid(BindGen.Cp437Grid* instance) : base(instance) { } diff --git a/crates/servicepoint_binding_cs/build.rs b/crates/servicepoint_binding_cs/build.rs index ec2744e..648324d 100644 --- a/crates/servicepoint_binding_cs/build.rs +++ b/crates/servicepoint_binding_cs/build.rs @@ -24,6 +24,16 @@ fn main() { .csharp_use_nint_types(true) .csharp_class_accessibility("public") .csharp_generate_const_filter(|_| true) + .csharp_type_rename(move |name| { + if name.len() > 1 + && name.starts_with("C") + && name.chars().nth(1).unwrap().is_uppercase() + { + name[1..].to_string() + } else { + name + } + }) .generate_csharp_file("ServicePoint/BindGen/ServicePoint.g.cs") .unwrap(); } From c9c51dcdc2d94cd47af06ae68a5ae7707ca74b1b Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Thu, 29 Aug 2024 22:02:53 +0200 Subject: [PATCH 06/31] improve doc comments --- .../examples/lang_c/include/servicepoint.h | 41 ++++--------------- crates/servicepoint_binding_c/src/bit_vec.rs | 2 +- crates/servicepoint_binding_c/src/command.rs | 6 ++- 3 files changed, 13 insertions(+), 36 deletions(-) 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 5fb4334..d2f69b1 100644 --- a/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h +++ b/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h @@ -128,7 +128,7 @@ typedef uint16_t sp_CompressionCode; typedef struct sp_Brightness sp_Brightness; /** - * Opaque struct needed for correct code generation. + * A vector of bits */ typedef struct sp_CBitVec sp_CBitVec; @@ -138,7 +138,11 @@ typedef struct sp_CBitVec sp_CBitVec; typedef struct sp_CBrightnessGrid sp_CBrightnessGrid; /** - * Opaque struct needed for correct code generation. + * A low-level display command. + * + * This struct and associated functions implement the UDP protocol for the display. + * + * To send a `CCommand`, use a `Connection`. */ typedef struct sp_CCommand sp_CCommand; @@ -149,37 +153,6 @@ typedef struct sp_CCommand sp_CCommand; */ typedef struct sp_CCp437Grid sp_CCp437Grid; -/** - * A low-level display command. - * - * This struct and associated functions implement the UDP protocol for the display. - * - * To send a `Command`, use a `Connection`. - * - * # Examples - * - * ```rust - * # use servicepoint::{Brightness, Command, Connection, Packet}; - * - * // create command - * let command = Command::Brightness(Brightness::MAX); - * - * // turn command into Packet - * let packet: Packet = command.clone().into(); - * - * // read command from packet - * let round_tripped = Command::try_from(packet).unwrap(); - * - * // round tripping produces exact copy - * assert_eq!(command, round_tripped); - * - * // send command - * # let connection = Connection::open("127.0.0.1:2342").unwrap(); - * connection.send(command).unwrap(); - * ``` - */ -typedef struct sp_Command sp_Command; - /** * A connection to the display. * @@ -1046,7 +1019,7 @@ void sp_packet_dealloc(struct sp_Packet *this_); * - 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); +struct sp_Packet *sp_packet_from_command(struct sp_CCommand *command); /** * Tries to load a `Packet` from the passed array with the specified length. diff --git a/crates/servicepoint_binding_c/src/bit_vec.rs b/crates/servicepoint_binding_c/src/bit_vec.rs index e930dbc..73aeefb 100644 --- a/crates/servicepoint_binding_c/src/bit_vec.rs +++ b/crates/servicepoint_binding_c/src/bit_vec.rs @@ -8,7 +8,7 @@ use servicepoint::bitvec::prelude::{BitVec, Msb0}; /// cbindgen:no-export type SpBitVec = BitVec; -/// Opaque struct needed for correct code generation. +/// A vector of bits #[derive(Clone)] pub struct CBitVec { actual: SpBitVec, diff --git a/crates/servicepoint_binding_c/src/command.rs b/crates/servicepoint_binding_c/src/command.rs index 2e2bc7e..3a34bcf 100644 --- a/crates/servicepoint_binding_c/src/command.rs +++ b/crates/servicepoint_binding_c/src/command.rs @@ -12,7 +12,11 @@ use crate::bit_vec::CBitVec; use crate::brightness_grid::CBrightnessGrid; use crate::cp437_grid::CCp437Grid; -/// Opaque struct needed for correct code generation. +/// A low-level display command. +/// +/// This struct and associated functions implement the UDP protocol for the display. +/// +/// To send a `CCommand`, use a `Connection`. pub struct CCommand(pub(crate) Command); impl Clone for CCommand { From d385d8e1d4f3ffbb68c5d2e43f3ed511056eb280 Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Thu, 29 Aug 2024 22:21:21 +0200 Subject: [PATCH 07/31] add packet clone --- crates/servicepoint/src/packet.rs | 4 +-- .../examples/lang_c/include/servicepoint.h | 14 ++++++++ crates/servicepoint_binding_c/src/bit_vec.rs | 9 ++++- .../src/brightness_grid.rs | 36 +++++++++++-------- crates/servicepoint_binding_c/src/command.rs | 4 +-- .../servicepoint_binding_c/src/cp437_grid.rs | 36 ++++++++++++------- crates/servicepoint_binding_c/src/packet.rs | 15 ++++++++ 7 files changed, 87 insertions(+), 31 deletions(-) diff --git a/crates/servicepoint/src/packet.rs b/crates/servicepoint/src/packet.rs index 80ce052..3718e34 100644 --- a/crates/servicepoint/src/packet.rs +++ b/crates/servicepoint/src/packet.rs @@ -8,14 +8,14 @@ use crate::{ }; /// A raw header. Should probably not be used directly. -#[derive(Debug, PartialEq)] +#[derive(Copy, Clone, Debug, PartialEq)] pub struct Header(pub u16, pub u16, pub u16, pub u16, pub u16); /// The raw payload. Should probably not be used directly. pub type Payload = Vec; /// The raw packet. Should probably not be used directly. -#[derive(Debug, PartialEq)] +#[derive(Clone, Debug, PartialEq)] pub struct Packet(pub Header, pub Payload); impl From for Vec { 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 d2f69b1..eaf2e40 100644 --- a/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h +++ b/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h @@ -994,6 +994,20 @@ struct sp_CByteSlice sp_cp437_grid_unsafe_data_ref(struct sp_CCp437Grid *this_); */ size_t sp_cp437_grid_width(const struct sp_CCp437Grid *this_); +/** + * Clones a `Packet`. + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `Packet` + * - `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_packet_dealloc`. + */ +struct sp_Packet *sp_packet_clone(const struct sp_Packet *this_); + /** * Deallocates a `Packet`. * diff --git a/crates/servicepoint_binding_c/src/bit_vec.rs b/crates/servicepoint_binding_c/src/bit_vec.rs index 73aeefb..6a52a63 100644 --- a/crates/servicepoint_binding_c/src/bit_vec.rs +++ b/crates/servicepoint_binding_c/src/bit_vec.rs @@ -9,7 +9,6 @@ use servicepoint::bitvec::prelude::{BitVec, Msb0}; type SpBitVec = BitVec; /// A vector of bits -#[derive(Clone)] pub struct CBitVec { actual: SpBitVec, } @@ -26,6 +25,14 @@ impl From for SpBitVec { } } +impl Clone for CBitVec { + fn clone(&self) -> Self { + CBitVec { + actual: self.actual.clone(), + } + } +} + /// Creates a new `BitVec` instance. /// /// # Arguments diff --git a/crates/servicepoint_binding_c/src/brightness_grid.rs b/crates/servicepoint_binding_c/src/brightness_grid.rs index 8f89906..0ca0ec6 100644 --- a/crates/servicepoint_binding_c/src/brightness_grid.rs +++ b/crates/servicepoint_binding_c/src/brightness_grid.rs @@ -2,14 +2,22 @@ //! //! prefix `sp_brightness_grid_` +use crate::c_slice::CByteSlice; use servicepoint::{Brightness, BrightnessGrid, DataRef, Grid, PrimitiveGrid}; use std::intrinsics::transmute; -use crate::c_slice::CByteSlice; - /// C-wrapper for grid containing brightness values. -#[derive(Clone)] -pub struct CBrightnessGrid(pub(crate) BrightnessGrid); +pub struct CBrightnessGrid { + pub(crate) actual: BrightnessGrid, +} + +impl Clone for CBrightnessGrid { + fn clone(&self) -> Self { + CBrightnessGrid { + actual: self.actual.clone(), + } + } +} /// Creates a new `BrightnessGrid` with the specified dimensions. /// @@ -26,9 +34,9 @@ pub unsafe extern "C" fn sp_brightness_grid_new( width: usize, height: usize, ) -> *mut CBrightnessGrid { - Box::into_raw(Box::new(CBrightnessGrid(BrightnessGrid::new( - width, height, - )))) + Box::into_raw(Box::new(CBrightnessGrid { + actual: BrightnessGrid::new(width, height), + })) } /// Loads a `BrightnessGrid` with the specified dimensions from the provided data. @@ -56,7 +64,7 @@ pub unsafe extern "C" fn sp_brightness_grid_load( let grid = PrimitiveGrid::load(width, height, data); let grid = BrightnessGrid::try_from(grid).expect("invalid brightness value"); - Box::into_raw(Box::new(CBrightnessGrid(grid))) + Box::into_raw(Box::new(CBrightnessGrid { actual: grid })) } /// Clones a `BrightnessGrid`. @@ -115,7 +123,7 @@ pub unsafe extern "C" fn sp_brightness_grid_get( x: usize, y: usize, ) -> u8 { - (*this).0.get(x, y).into() + (*this).actual.get(x, y).into() } /// Sets the value of the specified position in the `BrightnessGrid`. @@ -148,7 +156,7 @@ pub unsafe extern "C" fn sp_brightness_grid_set( ) { let brightness = Brightness::try_from(value).expect("invalid brightness value"); - (*this).0.set(x, y, brightness); + (*this).actual.set(x, y, brightness); } /// Sets the value of all cells in the `BrightnessGrid`. @@ -175,7 +183,7 @@ pub unsafe extern "C" fn sp_brightness_grid_fill( ) { let brightness = Brightness::try_from(value).expect("invalid brightness value"); - (*this).0.fill(brightness); + (*this).actual.fill(brightness); } /// Gets the width of the `BrightnessGrid` instance. @@ -193,7 +201,7 @@ pub unsafe extern "C" fn sp_brightness_grid_fill( pub unsafe extern "C" fn sp_brightness_grid_width( this: *const CBrightnessGrid, ) -> usize { - (*this).0.width() + (*this).actual.width() } /// Gets the height of the `BrightnessGrid` instance. @@ -211,7 +219,7 @@ pub unsafe extern "C" fn sp_brightness_grid_width( pub unsafe extern "C" fn sp_brightness_grid_height( this: *const CBrightnessGrid, ) -> usize { - (*this).0.height() + (*this).actual.height() } /// Gets an unsafe reference to the data of the `BrightnessGrid` instance. @@ -229,7 +237,7 @@ pub unsafe extern "C" fn sp_brightness_grid_unsafe_data_ref( ) -> CByteSlice { assert_eq!(std::mem::size_of::(), 1); - let data = (*this).0.data_ref_mut(); + let data = (*this).actual.data_ref_mut(); let data: &mut [u8] = transmute(data); CByteSlice { start: data.as_mut_ptr_range().start, diff --git a/crates/servicepoint_binding_c/src/command.rs b/crates/servicepoint_binding_c/src/command.rs index 3a34bcf..6126284 100644 --- a/crates/servicepoint_binding_c/src/command.rs +++ b/crates/servicepoint_binding_c/src/command.rs @@ -147,7 +147,7 @@ pub unsafe extern "C" fn sp_command_char_brightness( let byte_grid = *Box::from_raw(byte_grid); Box::into_raw(Box::new(CCommand(Command::CharBrightness( Origin::new(x, y), - byte_grid.0, + byte_grid.actual, )))) } @@ -275,7 +275,7 @@ pub unsafe extern "C" fn sp_command_cp437_data( let byte_grid = *Box::from_raw(byte_grid); Box::into_raw(Box::new(CCommand(Command::Cp437Data( Origin::new(x, y), - byte_grid.0, + byte_grid.actual, )))) } diff --git a/crates/servicepoint_binding_c/src/cp437_grid.rs b/crates/servicepoint_binding_c/src/cp437_grid.rs index a1d84a6..79651bf 100644 --- a/crates/servicepoint_binding_c/src/cp437_grid.rs +++ b/crates/servicepoint_binding_c/src/cp437_grid.rs @@ -2,15 +2,23 @@ //! //! prefix `sp_cp437_grid_` -use servicepoint::{Cp437Grid, DataRef, Grid}; - use crate::c_slice::CByteSlice; +use servicepoint::{Cp437Grid, DataRef, Grid}; /// A C-wrapper for grid containing codepage 437 characters. /// /// The encoding is currently not enforced. -#[derive(Clone)] -pub struct CCp437Grid(pub(crate) Cp437Grid); +pub struct CCp437Grid { + pub(crate) actual: Cp437Grid, +} + +impl Clone for CCp437Grid { + fn clone(&self) -> Self { + CCp437Grid { + actual: self.actual.clone(), + } + } +} /// Creates a new `Cp437Grid` with the specified dimensions. /// @@ -27,7 +35,9 @@ pub unsafe extern "C" fn sp_cp437_grid_new( width: usize, height: usize, ) -> *mut CCp437Grid { - Box::into_raw(Box::new(CCp437Grid(Cp437Grid::new(width, height)))) + Box::into_raw(Box::new(CCp437Grid { + actual: Cp437Grid::new(width, height), + })) } /// Loads a `Cp437Grid` with the specified dimensions from the provided data. @@ -52,7 +62,9 @@ pub unsafe extern "C" fn sp_cp437_grid_load( data_length: usize, ) -> *mut CCp437Grid { let data = std::slice::from_raw_parts(data, data_length); - Box::into_raw(Box::new(CCp437Grid(Cp437Grid::load(width, height, data)))) + Box::into_raw(Box::new(CCp437Grid { + actual: Cp437Grid::load(width, height, data), + })) } /// Clones a `Cp437Grid`. @@ -109,7 +121,7 @@ pub unsafe extern "C" fn sp_cp437_grid_get( x: usize, y: usize, ) -> u8 { - (*this).0.get(x, y) + (*this).actual.get(x, y) } /// Sets the value of the specified position in the `Cp437Grid`. @@ -139,7 +151,7 @@ pub unsafe extern "C" fn sp_cp437_grid_set( y: usize, value: u8, ) { - (*this).0.set(x, y, value); + (*this).actual.set(x, y, value); } /// Sets the value of all cells in the `Cp437Grid`. @@ -157,7 +169,7 @@ pub unsafe extern "C" fn sp_cp437_grid_set( /// - `this` is not written to or read from concurrently #[no_mangle] pub unsafe extern "C" fn sp_cp437_grid_fill(this: *mut CCp437Grid, value: u8) { - (*this).0.fill(value); + (*this).actual.fill(value); } /// Gets the width of the `Cp437Grid` instance. @@ -173,7 +185,7 @@ pub unsafe extern "C" fn sp_cp437_grid_fill(this: *mut CCp437Grid, value: u8) { /// - `this` points to a valid `Cp437Grid` #[no_mangle] pub unsafe extern "C" fn sp_cp437_grid_width(this: *const CCp437Grid) -> usize { - (*this).0.width() + (*this).actual.width() } /// Gets the height of the `Cp437Grid` instance. @@ -191,7 +203,7 @@ pub unsafe extern "C" fn sp_cp437_grid_width(this: *const CCp437Grid) -> usize { pub unsafe extern "C" fn sp_cp437_grid_height( this: *const CCp437Grid, ) -> usize { - (*this).0.height() + (*this).actual.height() } /// Gets an unsafe reference to the data of the `Cp437Grid` instance. @@ -207,7 +219,7 @@ pub unsafe extern "C" fn sp_cp437_grid_height( pub unsafe extern "C" fn sp_cp437_grid_unsafe_data_ref( this: *mut CCp437Grid, ) -> CByteSlice { - let data = (*this).0.data_ref_mut(); + let data = (*this).actual.data_ref_mut(); CByteSlice { start: data.as_mut_ptr_range().start, length: data.len(), diff --git a/crates/servicepoint_binding_c/src/packet.rs b/crates/servicepoint_binding_c/src/packet.rs index 402418f..8c69410 100644 --- a/crates/servicepoint_binding_c/src/packet.rs +++ b/crates/servicepoint_binding_c/src/packet.rs @@ -51,6 +51,21 @@ pub unsafe extern "C" fn sp_packet_try_load( } } +/// Clones a `Packet`. +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `this` points to a valid `Packet` +/// - `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_packet_dealloc`. +#[no_mangle] +pub unsafe extern "C" fn sp_packet_clone(this: *const Packet) -> *mut Packet { + Box::into_raw(Box::new((*this).clone())) +} + /// Deallocates a `Packet`. /// /// # Safety From 5e141f1fbc1f5917d19f14d3b0ba6f485c0b6dad Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Thu, 29 Aug 2024 22:25:11 +0200 Subject: [PATCH 08/31] clone in c example --- crates/servicepoint_binding_c/examples/lang_c/src/main.c | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/crates/servicepoint_binding_c/examples/lang_c/src/main.c b/crates/servicepoint_binding_c/examples/lang_c/src/main.c index 10477a8..451abe7 100644 --- a/crates/servicepoint_binding_c/examples/lang_c/src/main.c +++ b/crates/servicepoint_binding_c/examples/lang_c/src/main.c @@ -2,7 +2,7 @@ #include "servicepoint.h" int main(void) { - sp_Connection *connection = sp_connection_open("localhost:2342"); + sp_Connection *connection = sp_connection_open("172.23.42.29:2342"); if (connection == NULL) return 1; @@ -11,9 +11,9 @@ int main(void) { sp_CCommand *command = sp_command_bitmap_linear_win(0, 0, pixels, Uncompressed); sp_Packet *packet = sp_packet_from_command(command); - if (!sp_connection_send(connection, packet)) - return 1; + while (sp_connection_send(connection, sp_packet_clone(packet))); + sp_packet_dealloc(packet); sp_connection_dealloc(connection); return 0; } From b9fc06117ec37c63536f613a92c39363d0aab8fd Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Thu, 29 Aug 2024 23:22:52 +0200 Subject: [PATCH 09/31] wip connection trait --- crates/servicepoint/src/connection.rs | 74 +++++++++++++++------------ crates/servicepoint/src/lib.rs | 2 +- 2 files changed, 41 insertions(+), 35 deletions(-) diff --git a/crates/servicepoint/src/connection.rs b/crates/servicepoint/src/connection.rs index 456ae5d..76945c3 100644 --- a/crates/servicepoint/src/connection.rs +++ b/crates/servicepoint/src/connection.rs @@ -9,17 +9,38 @@ use crate::Packet; /// /// # Examples /// ```rust -/// # use servicepoint::Command; -/// let connection = servicepoint::Connection::open("172.23.42.29:2342") +/// # use servicepoint::{Command, Connection}; +/// let connection = servicepoint::UdpConnection::open("172.23.42.29:2342") /// .expect("connection failed"); -/// connection.send(Command::Clear) -/// .expect("send failed"); +/// connection.send(Command::Clear); /// ``` -pub struct Connection { +pub trait Connection { + /// Send something packet-like to the display. Usually this is in the form of a Command. + /// + /// # Arguments + /// + /// - `packet`: the packet-like to send + /// + /// returns: true if packet was sent, otherwise false + /// + /// # Examples + /// + /// ```rust + /// # use servicepoint::{Command, Connection }; + /// # let connection = servicepoint::UdpConnection::open("172.23.42.29:2342") + /// # .expect("connection failed"); + /// // turn off all pixels on display + /// connection.send(Command::Clear); + /// ``` + fn send(&self, packet: impl Into) -> bool; +} + +/// A real connection using the UDP protocol +pub struct UdpConnection { socket: UdpSocket, } -impl Connection { +impl UdpConnection { /// Open a new UDP socket and connect to the provided host. /// /// Note that this is UDP, which means that the open call can succeed even if the display is unreachable. @@ -39,37 +60,22 @@ impl Connection { socket.connect(addr)?; Ok(Self { socket }) } +} - /// Send something packet-like to the display. Usually this is in the form of a Command. - /// - /// # Arguments - /// - /// - `packet`: the packet-like to send - /// - /// returns: Ok if packet was sent, otherwise socket error - /// - /// # Errors - /// - /// Any errors produced while sending using the underlying socket. - /// - /// # Examples - /// - /// ```rust - /// # use servicepoint::{Command, CompressionCode, Grid, PixelGrid}; - /// # let connection = servicepoint::Connection::open("172.23.42.29:2342") - /// # .expect("connection failed"); - /// // turn off all pixels on display - /// connection.send(Command::Clear) - /// .expect("send failed"); - /// ``` - pub fn send( - &self, - packet: impl Into, - ) -> Result<(), std::io::Error> { +impl Connection for UdpConnection { + fn send(&self, packet: impl Into) -> bool { let packet = packet.into(); debug!("sending {packet:?}"); let data: Vec = packet.into(); - self.socket.send(&data)?; - Ok(()) + self.socket.send(&data).is_err() + } +} + +/// A fake connection for testing that does not actually send anything +pub struct NoopConnection; + +impl Connection for NoopConnection { + fn send(&self, packet: impl Into) -> bool { + true } } diff --git a/crates/servicepoint/src/lib.rs b/crates/servicepoint/src/lib.rs index d71e1fa..a8956bb 100644 --- a/crates/servicepoint/src/lib.rs +++ b/crates/servicepoint/src/lib.rs @@ -39,7 +39,7 @@ use bitvec::prelude::{BitVec, Msb0}; pub use crate::brightness::{Brightness, BrightnessGrid}; pub use crate::command::{Command, Cp437Grid, Offset}; pub use crate::compression_code::CompressionCode; -pub use crate::connection::Connection; +pub use crate::connection::{Connection, UdpConnection}; pub use crate::data_ref::DataRef; pub use crate::grid::Grid; pub use crate::origin::{Origin, Pixels, Tiles}; From 051dbfabea41c169465c3a9dbbdcf3d90fa6d3b7 Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Thu, 5 Sep 2024 21:15:53 +0200 Subject: [PATCH 10/31] wrap and rename ALL the types --- crates/servicepoint/src/connection.rs | 79 ++-- crates/servicepoint/src/lib.rs | 2 +- crates/servicepoint_binding_c/cbindgen.toml | 13 +- .../examples/lang_c/Makefile | 5 +- .../examples/lang_c/include/servicepoint.h | 365 +++++++++--------- .../examples/lang_c/src/main.c | 8 +- crates/servicepoint_binding_c/src/bit_vec.rs | 80 ++-- .../src/brightness_grid.rs | 64 +-- crates/servicepoint_binding_c/src/c_slice.rs | 2 +- crates/servicepoint_binding_c/src/command.rs | 145 +++---- .../servicepoint_binding_c/src/connection.rs | 27 +- .../servicepoint_binding_c/src/constants.rs | 48 +++ .../servicepoint_binding_c/src/cp437_grid.rs | 49 ++- crates/servicepoint_binding_c/src/lib.rs | 13 +- crates/servicepoint_binding_c/src/packet.rs | 26 +- .../servicepoint_binding_c/src/pixel_grid.rs | 71 ++-- .../ServicePoint/BindGen/ServicePoint.g.cs | 45 ++- crates/servicepoint_binding_cs/build.rs | 15 +- 18 files changed, 577 insertions(+), 480 deletions(-) create mode 100644 crates/servicepoint_binding_c/src/constants.rs diff --git a/crates/servicepoint/src/connection.rs b/crates/servicepoint/src/connection.rs index 76945c3..9237006 100644 --- a/crates/servicepoint/src/connection.rs +++ b/crates/servicepoint/src/connection.rs @@ -9,38 +9,24 @@ use crate::Packet; /// /// # Examples /// ```rust -/// # use servicepoint::{Command, Connection}; -/// let connection = servicepoint::UdpConnection::open("172.23.42.29:2342") +/// let connection = servicepoint::Connection::open("172.23.42.29:2342") /// .expect("connection failed"); -/// connection.send(Command::Clear); +/// connection.send(servicepoint::Command::Clear) +/// .expect("send failed"); /// ``` -pub trait Connection { - /// Send something packet-like to the display. Usually this is in the form of a Command. - /// - /// # Arguments - /// - /// - `packet`: the packet-like to send - /// - /// returns: true if packet was sent, otherwise false - /// - /// # Examples - /// - /// ```rust - /// # use servicepoint::{Command, Connection }; - /// # let connection = servicepoint::UdpConnection::open("172.23.42.29:2342") - /// # .expect("connection failed"); - /// // turn off all pixels on display - /// connection.send(Command::Clear); - /// ``` - fn send(&self, packet: impl Into) -> bool; +pub enum Connection { + /// A real connection using the UDP protocol + Udp(UdpSocket), + /// A fake connection for testing that does not actually send anything + Fake, } -/// A real connection using the UDP protocol -pub struct UdpConnection { - socket: UdpSocket, +#[derive(Debug)] +pub enum SendError { + IoError(std::io::Error), } -impl UdpConnection { +impl Connection { /// Open a new UDP socket and connect to the provided host. /// /// Note that this is UDP, which means that the open call can succeed even if the display is unreachable. @@ -58,24 +44,37 @@ impl UdpConnection { info!("connecting to {addr:?}"); let socket = UdpSocket::bind("0.0.0.0:0")?; socket.connect(addr)?; - Ok(Self { socket }) + Ok(Self::Udp(socket)) } -} -impl Connection for UdpConnection { - fn send(&self, packet: impl Into) -> bool { + /// Send something packet-like to the display. Usually this is in the form of a Command. + /// + /// # Arguments + /// + /// - `packet`: the packet-like to send + /// + /// returns: true if packet was sent, otherwise false + /// + /// # Examples + /// + /// ```rust + /// # let connection = servicepoint::Connection::Fake; + /// // turn off all pixels on display + /// connection.send(servicepoint::Command::Clear) + /// .expect("send failed"); + /// ``` + pub fn send(&self, packet: impl Into) -> Result<(), SendError> { let packet = packet.into(); debug!("sending {packet:?}"); let data: Vec = packet.into(); - self.socket.send(&data).is_err() - } -} - -/// A fake connection for testing that does not actually send anything -pub struct NoopConnection; - -impl Connection for NoopConnection { - fn send(&self, packet: impl Into) -> bool { - true + match self { + Connection::Udp(socket) => { + socket + .send(&data) + .map_err(move |io_err| SendError::IoError(io_err)) + .map(move |_| ()) // ignore Ok value + } + Connection::Fake => Ok(()), + } } } diff --git a/crates/servicepoint/src/lib.rs b/crates/servicepoint/src/lib.rs index a8956bb..d71e1fa 100644 --- a/crates/servicepoint/src/lib.rs +++ b/crates/servicepoint/src/lib.rs @@ -39,7 +39,7 @@ use bitvec::prelude::{BitVec, Msb0}; pub use crate::brightness::{Brightness, BrightnessGrid}; pub use crate::command::{Command, Cp437Grid, Offset}; pub use crate::compression_code::CompressionCode; -pub use crate::connection::{Connection, UdpConnection}; +pub use crate::connection::Connection; pub use crate::data_ref::DataRef; pub use crate::grid::Grid; pub use crate::origin::{Origin, Pixels, Tiles}; diff --git a/crates/servicepoint_binding_c/cbindgen.toml b/crates/servicepoint_binding_c/cbindgen.toml index c65f551..1c363cf 100644 --- a/crates/servicepoint_binding_c/cbindgen.toml +++ b/crates/servicepoint_binding_c/cbindgen.toml @@ -18,19 +18,8 @@ style = "both" sort_by = "Name" usize_is_size_t = true -[defines] -#"feature = compression_zlib" = "SP_FEATURE_compression_zlib" -#"feature = compression_bzip2" = "SP_FEATURE_compression_bzip2" -#"feature = compression_lzma" = "SP_FEATURE_compression_lzma" -#"feature = compression_zstd" = "SP_FEATURE_compression_zstd" - -[export] -prefix = "sp_" - [parse] -parse_deps = true -include = ["servicepoint"] -extra_bindings = ["servicepoint"] +parse_deps = false [parse.expand] all_features = true diff --git a/crates/servicepoint_binding_c/examples/lang_c/Makefile b/crates/servicepoint_binding_c/examples/lang_c/Makefile index 86cf49c..6b15722 100644 --- a/crates/servicepoint_binding_c/examples/lang_c/Makefile +++ b/crates/servicepoint_binding_c/examples/lang_c/Makefile @@ -6,8 +6,9 @@ REPO_ROOT := $(THIS_DIR)/../../../.. build: out/lang_c clean: - rm -r out - rm include/servicepoint.h + rm -r out || true + rm include/servicepoint.h || true + cargo clean run: out/lang_c 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 eaf2e40..960353e 100644 --- a/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h +++ b/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h @@ -9,78 +9,37 @@ /** * pixel count on whole screen */ -#define sp_PIXEL_COUNT (sp_PIXEL_WIDTH * sp_PIXEL_HEIGHT) +#define SP_PIXEL_COUNT (SP_PIXEL_WIDTH * SP_PIXEL_HEIGHT) /** * Display height in pixels - * - * # Examples - * - * ```rust - * # use servicepoint::{PIXEL_HEIGHT, PIXEL_WIDTH, PixelGrid}; - * let grid = PixelGrid::new(PIXEL_WIDTH, PIXEL_HEIGHT); - * ``` */ -#define sp_PIXEL_HEIGHT (sp_TILE_HEIGHT * sp_TILE_SIZE) +#define SP_PIXEL_HEIGHT (SP_TILE_HEIGHT * SP_TILE_SIZE) /** * Display width in pixels - * - * # Examples - * - * ```rust - * # use servicepoint::{PIXEL_HEIGHT, PIXEL_WIDTH, PixelGrid}; - * let grid = PixelGrid::new(PIXEL_WIDTH, PIXEL_HEIGHT); - * ``` */ -#define sp_PIXEL_WIDTH (sp_TILE_WIDTH * sp_TILE_SIZE) +#define SP_PIXEL_WIDTH (SP_TILE_WIDTH * SP_TILE_SIZE) /** * Display tile count in the y-direction - * - * # Examples - * - * ```rust - * # use servicepoint::{Cp437Grid, TILE_HEIGHT, TILE_WIDTH}; - * let grid = Cp437Grid::new(TILE_WIDTH, TILE_HEIGHT); - * ``` */ -#define sp_TILE_HEIGHT 20 +#define SP_TILE_HEIGHT 20 /** * size of a single tile in one dimension */ -#define sp_TILE_SIZE 8 +#define SP_TILE_SIZE 8 /** * Display tile count in the x-direction - * - * # Examples - * - * ```rust - * # use servicepoint::{Cp437Grid, TILE_HEIGHT, TILE_WIDTH}; - * let grid = Cp437Grid::new(TILE_WIDTH, TILE_HEIGHT); - * ``` */ -#define sp_TILE_WIDTH 56 +#define SP_TILE_WIDTH 56 /** - * Specifies the kind of compression to use. Availability depends on features. - * - * # Examples - * - * ```rust - * # use servicepoint::{Command, CompressionCode, Origin, PixelGrid}; - * // create command without payload compression - * # let pixels = PixelGrid::max_sized(); - * _ = Command::BitmapLinearWin(Origin::new(0, 0), pixels, CompressionCode::Uncompressed); - * - * // create command with payload compressed with lzma and appropriate header flags - * # let pixels = PixelGrid::max_sized(); - * _ = Command::BitmapLinearWin(Origin::new(0, 0), pixels, CompressionCode::Lzma); - * ``` + * Specifies the kind of compression to use. */ -enum sp_CompressionCode +enum SPCompressionCode #ifdef __cplusplus : uint16_t #endif // __cplusplus @@ -107,75 +66,103 @@ enum sp_CompressionCode Zstd = 31347, }; #ifndef __cplusplus -typedef uint16_t sp_CompressionCode; +typedef uint16_t SPCompressionCode; #endif // __cplusplus /** - * A display brightness value, checked for correct value range + * A vector of bits * * # Examples - * - * ``` - * # use servicepoint::{Brightness, Command, Connection}; - * let b = Brightness::MAX; - * let val: u8 = b.into(); - * - * let b = Brightness::try_from(7).unwrap(); - * # let connection = Connection::open("127.0.0.1:2342").unwrap(); - * let result = connection.send(Command::Brightness(b)); + * ```C + * SPBitVec vec = sp_bit_vec_new(8); + * sp_bit_vec_set(vec, 5, true); + * sp_bit_vec_dealloc(vec); * ``` */ -typedef struct sp_Brightness sp_Brightness; +typedef struct SPBitVec SPBitVec; /** - * A vector of bits + * A grid containing brightness values. + * + * # Examples + * ```C + * SPConnection connection = sp_connection_open("127.0.0.1:2342"); + * if (connection == NULL) + * return 1; + * + * SPBrightnessGrid grid = sp_brightness_grid_new(2, 2); + * sp_brightness_grid_set(grid, 0, 0, 0); + * sp_brightness_grid_set(grid, 1, 1, 10); + * + * SPCommand command = sp_command_char_brightness(grid); + * sp_connection_dealloc(connection); + * ``` */ -typedef struct sp_CBitVec sp_CBitVec; - -/** - * C-wrapper for grid containing brightness values. - */ -typedef struct sp_CBrightnessGrid sp_CBrightnessGrid; +typedef struct SPBrightnessGrid SPBrightnessGrid; /** * A low-level display command. * * This struct and associated functions implement the UDP protocol for the display. * - * To send a `CCommand`, use a `Connection`. - */ -typedef struct sp_CCommand sp_CCommand; - -/** - * A C-wrapper for grid containing codepage 437 characters. + * To send a `CCommand`, use a `CConnection`. * - * The encoding is currently not enforced. + * # Examples + * + * ```C + * sp_connection_send(connection, sp_command_clear()); + * sp_connection_send(connection, sp_command_brightness(5)); + * ``` */ -typedef struct sp_CCp437Grid sp_CCp437Grid; +typedef struct SPCommand SPCommand; /** * A connection to the display. * * # Examples - * ```rust - * # use servicepoint::Command; - * let connection = servicepoint::Connection::open("172.23.42.29:2342") - * .expect("connection failed"); - * connection.send(Command::Clear) - * .expect("send failed"); + * + * ```C + * CConnection connection = sp_connection_open("172.23.42.29:2342"); + * if (connection != NULL) + * sp_connection_send(connection, sp_command_clear()); * ``` */ -typedef struct sp_Connection sp_Connection; +typedef struct SPConnection SPConnection; /** - * The raw packet. Should probably not be used directly. + * A C-wrapper for grid containing codepage 437 characters. + * + * The encoding is currently not enforced. + * + * # Examples + * + * ```C + * Cp437Grid grid = sp_cp437_grid_new(4, 3); + * sp_cp437_grid_fill(grid, '?'); + * sp_cp437_grid_set(grid, 0, 0, '!'); + * sp_cp437_grid_dealloc(grid); + * ``` */ -typedef struct sp_Packet sp_Packet; +typedef struct SPCp437Grid SPCp437Grid; /** - * A grid of pixels stored in packed bytes. + * The raw packet */ -typedef struct sp_PixelGrid sp_PixelGrid; +typedef struct SPPacket SPPacket; + +/** + * A grid of pixels. + * + * # Examples + * + * ```C + * Cp437Grid grid = sp_pixel_grid_new(8, 3); + * sp_pixel_grid_fill(grid, true); + * sp_pixel_grid_set(grid, 0, 0, false); + * sp_pixel_grid_dealloc(grid); + * ``` + */ +typedef struct SPPixelGrid SPPixelGrid; /** * Represents a span of memory (`&mut [u8]` ) as a struct usable by C code. @@ -188,7 +175,7 @@ typedef struct sp_PixelGrid sp_PixelGrid; * - 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 { +typedef struct SPByteSlice { /** * The start address of the memory */ @@ -197,16 +184,12 @@ typedef struct sp_CByteSlice { * The amount of memory in bytes */ size_t length; -} sp_CByteSlice; +} SPByteSlice; /** - * Type alias for documenting the meaning of the u16 in enum values + * Type alias for documenting the meaning of the variable in enum values */ -typedef size_t sp_Offset; - - - - +typedef size_t SPOffset; #ifdef __cplusplus extern "C" { @@ -224,7 +207,7 @@ extern "C" { * - the returned instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_bit_vec_dealloc`. */ -struct sp_CBitVec *sp_bit_vec_clone(const struct sp_CBitVec *this_); +struct SPBitVec *sp_bit_vec_clone(const struct SPBitVec *this_); /** * Deallocates a `BitVec`. @@ -237,7 +220,7 @@ struct sp_CBitVec *sp_bit_vec_clone(const struct sp_CBitVec *this_); * - `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_CBitVec *this_); +void sp_bit_vec_dealloc(struct SPBitVec *this_); /** * Sets the value of all bits in the `BitVec`. @@ -253,7 +236,7 @@ void sp_bit_vec_dealloc(struct sp_CBitVec *this_); * - `this` points to a valid `BitVec` * - `this` is not written to or read from concurrently */ -void sp_bit_vec_fill(struct sp_CBitVec *this_, bool value); +void sp_bit_vec_fill(struct SPBitVec *this_, bool value); /** * Gets the value of a bit from the `BitVec`. @@ -276,7 +259,7 @@ void sp_bit_vec_fill(struct sp_CBitVec *this_, bool value); * - `this` points to a valid `BitVec` * - `this` is not written to concurrently */ -bool sp_bit_vec_get(const struct sp_CBitVec *this_, size_t index); +bool sp_bit_vec_get(const struct SPBitVec *this_, size_t index); /** * Returns true if length is 0. @@ -287,7 +270,7 @@ bool sp_bit_vec_get(const struct sp_CBitVec *this_, size_t index); * * - `this` points to a valid `BitVec` */ -bool sp_bit_vec_is_empty(const struct sp_CBitVec *this_); +bool sp_bit_vec_is_empty(const struct SPBitVec *this_); /** * Gets the length of the `BitVec` in bits. @@ -298,7 +281,7 @@ bool sp_bit_vec_is_empty(const struct sp_CBitVec *this_); * * - `this` points to a valid `BitVec` */ -size_t sp_bit_vec_len(const struct sp_CBitVec *this_); +size_t sp_bit_vec_len(const struct SPBitVec *this_); /** * Interpret the data as a series of bits and load then into a new `BitVec` instance. @@ -312,8 +295,8 @@ size_t sp_bit_vec_len(const struct sp_CBitVec *this_); * - the returned instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_bit_vec_dealloc`. */ -struct sp_CBitVec *sp_bit_vec_load(const uint8_t *data, - size_t data_length); +struct SPBitVec *sp_bit_vec_load(const uint8_t *data, + size_t data_length); /** * Creates a new `BitVec` instance. @@ -335,7 +318,7 @@ struct sp_CBitVec *sp_bit_vec_load(const uint8_t *data, * - the returned instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_bit_vec_dealloc`. */ -struct sp_CBitVec *sp_bit_vec_new(size_t size); +struct SPBitVec *sp_bit_vec_new(size_t size); /** * Sets the value of a bit in the `BitVec`. @@ -359,7 +342,7 @@ struct sp_CBitVec *sp_bit_vec_new(size_t size); * - `this` points to a valid `BitVec` * - `this` is not written to or read from concurrently */ -void sp_bit_vec_set(struct sp_CBitVec *this_, size_t index, bool value); +void sp_bit_vec_set(struct SPBitVec *this_, size_t index, bool value); /** * Gets an unsafe reference to the data of the `BitVec` instance. @@ -372,7 +355,7 @@ void sp_bit_vec_set(struct sp_CBitVec *this_, size_t index, bool value); * - 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_CBitVec *this_); +struct SPByteSlice sp_bit_vec_unsafe_data_ref(struct SPBitVec *this_); /** * Clones a `BrightnessGrid`. @@ -386,7 +369,7 @@ struct sp_CByteSlice sp_bit_vec_unsafe_data_ref(struct sp_CBitVec *this_); * - the returned instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_brightness_grid_dealloc`. */ -struct sp_CBrightnessGrid *sp_brightness_grid_clone(const struct sp_CBrightnessGrid *this_); +struct SPBrightnessGrid *sp_brightness_grid_clone(const struct SPBrightnessGrid *this_); /** * Deallocates a `BrightnessGrid`. @@ -399,7 +382,7 @@ struct sp_CBrightnessGrid *sp_brightness_grid_clone(const struct sp_CBrightnessG * - `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_brightness_grid_dealloc(struct sp_CBrightnessGrid *this_); +void sp_brightness_grid_dealloc(struct SPBrightnessGrid *this_); /** * Sets the value of all cells in the `BrightnessGrid`. @@ -420,7 +403,7 @@ void sp_brightness_grid_dealloc(struct sp_CBrightnessGrid *this_); * - `this` points to a valid `BrightnessGrid` * - `this` is not written to or read from concurrently */ -void sp_brightness_grid_fill(struct sp_CBrightnessGrid *this_, uint8_t value); +void sp_brightness_grid_fill(struct SPBrightnessGrid *this_, uint8_t value); /** * Gets the current value at the specified position. @@ -441,7 +424,7 @@ void sp_brightness_grid_fill(struct sp_CBrightnessGrid *this_, uint8_t value); * - `this` points to a valid `BrightnessGrid` * - `this` is not written to concurrently */ -uint8_t sp_brightness_grid_get(const struct sp_CBrightnessGrid *this_, +uint8_t sp_brightness_grid_get(const struct SPBrightnessGrid *this_, size_t x, size_t y); @@ -458,7 +441,7 @@ uint8_t sp_brightness_grid_get(const struct sp_CBrightnessGrid *this_, * * - `this` points to a valid `BrightnessGrid` */ -size_t sp_brightness_grid_height(const struct sp_CBrightnessGrid *this_); +size_t sp_brightness_grid_height(const struct SPBrightnessGrid *this_); /** * Loads a `BrightnessGrid` with the specified dimensions from the provided data. @@ -476,10 +459,10 @@ size_t sp_brightness_grid_height(const struct sp_CBrightnessGrid *this_); * - the returned instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_brightness_grid_dealloc`. */ -struct sp_CBrightnessGrid *sp_brightness_grid_load(size_t width, - size_t height, - const uint8_t *data, - size_t data_length); +struct SPBrightnessGrid *sp_brightness_grid_load(size_t width, + size_t height, + const uint8_t *data, + size_t data_length); /** * Creates a new `BrightnessGrid` with the specified dimensions. @@ -493,8 +476,8 @@ struct sp_CBrightnessGrid *sp_brightness_grid_load(size_t width, * - the returned instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_brightness_grid_dealloc`. */ -struct sp_CBrightnessGrid *sp_brightness_grid_new(size_t width, - size_t height); +struct SPBrightnessGrid *sp_brightness_grid_new(size_t width, + size_t height); /** * Sets the value of the specified position in the `BrightnessGrid`. @@ -519,7 +502,7 @@ struct sp_CBrightnessGrid *sp_brightness_grid_new(size_t width, * - `this` points to a valid `BitVec` * - `this` is not written to or read from concurrently */ -void sp_brightness_grid_set(struct sp_CBrightnessGrid *this_, +void sp_brightness_grid_set(struct SPBrightnessGrid *this_, size_t x, size_t y, uint8_t value); @@ -535,7 +518,7 @@ void sp_brightness_grid_set(struct sp_CBrightnessGrid *this_, * - the returned memory range is never accessed after the passed `BrightnessGrid` has been freed * - the returned memory range is never accessed concurrently, either via the `BrightnessGrid` or directly */ -struct sp_CByteSlice sp_brightness_grid_unsafe_data_ref(struct sp_CBrightnessGrid *this_); +struct SPByteSlice sp_brightness_grid_unsafe_data_ref(struct SPBrightnessGrid *this_); /** * Gets the width of the `BrightnessGrid` instance. @@ -550,7 +533,7 @@ struct sp_CByteSlice sp_brightness_grid_unsafe_data_ref(struct sp_CBrightnessGri * * - `this` points to a valid `BrightnessGrid` */ -size_t sp_brightness_grid_width(const struct sp_CBrightnessGrid *this_); +size_t sp_brightness_grid_width(const struct SPBrightnessGrid *this_); /** * Allocates a new `Command::BitmapLinear` instance. @@ -566,9 +549,9 @@ size_t sp_brightness_grid_width(const struct sp_CBrightnessGrid *this_); * - the returned `Command` instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_dealloc`. */ -struct sp_CCommand *sp_command_bitmap_linear(sp_Offset offset, - struct sp_CBitVec *bit_vec, - sp_CompressionCode compression); +struct SPCommand *sp_command_bitmap_linear(SPOffset offset, + struct SPBitVec *bit_vec, + SPCompressionCode compression); /** * Allocates a new `Command::BitmapLinearAnd` instance. @@ -584,9 +567,9 @@ struct sp_CCommand *sp_command_bitmap_linear(sp_Offset offset, * - the returned `Command` instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_dealloc`. */ -struct sp_CCommand *sp_command_bitmap_linear_and(sp_Offset offset, - struct sp_CBitVec *bit_vec, - sp_CompressionCode compression); +struct SPCommand *sp_command_bitmap_linear_and(SPOffset offset, + struct SPBitVec *bit_vec, + SPCompressionCode compression); /** * Allocates a new `Command::BitmapLinearOr` instance. @@ -602,9 +585,9 @@ struct sp_CCommand *sp_command_bitmap_linear_and(sp_Offset offset, * - the returned `Command` instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_dealloc`. */ -struct sp_CCommand *sp_command_bitmap_linear_or(sp_Offset offset, - struct sp_CBitVec *bit_vec, - sp_CompressionCode compression); +struct SPCommand *sp_command_bitmap_linear_or(SPOffset offset, + struct SPBitVec *bit_vec, + SPCompressionCode compression); /** * Allocates a new `Command::BitmapLinearWin` instance. @@ -620,10 +603,10 @@ struct sp_CCommand *sp_command_bitmap_linear_or(sp_Offset offset, * - the returned `Command` instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_dealloc`. */ -struct sp_CCommand *sp_command_bitmap_linear_win(size_t x, - size_t y, - struct sp_PixelGrid *pixel_grid, - sp_CompressionCode compression_code); +struct SPCommand *sp_command_bitmap_linear_win(size_t x, + size_t y, + struct SPPixelGrid *pixel_grid, + SPCompressionCode compression_code); /** * Allocates a new `Command::BitmapLinearXor` instance. @@ -639,9 +622,9 @@ struct sp_CCommand *sp_command_bitmap_linear_win(size_t x, * - the returned `Command` instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_dealloc`. */ -struct sp_CCommand *sp_command_bitmap_linear_xor(sp_Offset offset, - struct sp_CBitVec *bit_vec, - sp_CompressionCode compression); +struct SPCommand *sp_command_bitmap_linear_xor(SPOffset offset, + struct SPBitVec *bit_vec, + SPCompressionCode compression); /** * Allocates a new `Command::Brightness` instance for setting the brightness of all tiles to the @@ -655,27 +638,27 @@ struct sp_CCommand *sp_command_bitmap_linear_xor(sp_Offset offset, * * The caller has to make sure that: * - * - the returned `Command` instance is freed in some way, either by using a consuming function or + * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_dealloc`. */ -struct sp_CCommand *sp_command_brightness(uint8_t brightness); +struct SPCommand *sp_command_brightness(uint8_t brightness); /** * Allocates a new `Command::CharBrightness` instance. - * The passed `ByteGrid` gets consumed. + * The passed `SPBrightnessGrid` 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 + * - `grid` points to a valid instance of `SPBrightnessGrid` + * - `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_CCommand *sp_command_char_brightness(size_t x, - size_t y, - struct sp_CBrightnessGrid *byte_grid); +struct SPCommand *sp_command_char_brightness(size_t x, + size_t y, + struct SPBrightnessGrid *grid); /** * Allocates a new `Command::Clear` instance. @@ -687,7 +670,7 @@ struct sp_CCommand *sp_command_char_brightness(size_t x, * - the returned `Command` instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_dealloc`. */ -struct sp_CCommand *sp_command_clear(void); +struct SPCommand *sp_command_clear(void); /** * Clones a `Command` instance. @@ -701,7 +684,7 @@ struct sp_CCommand *sp_command_clear(void); * - the returned `Command` instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_dealloc`. */ -struct sp_CCommand *sp_command_clone(const struct sp_CCommand *original); +struct SPCommand *sp_command_clone(const struct SPCommand *original); /** * Allocates a new `Command::Cp437Data` instance. @@ -716,9 +699,9 @@ struct sp_CCommand *sp_command_clone(const struct sp_CCommand *original); * - the returned `Command` instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_dealloc`. */ -struct sp_CCommand *sp_command_cp437_data(size_t x, - size_t y, - struct sp_CCp437Grid *byte_grid); +struct SPCommand *sp_command_cp437_data(size_t x, + size_t y, + struct SPCp437Grid *byte_grid); /** * Deallocates a `Command`. @@ -731,7 +714,7 @@ struct sp_CCommand *sp_command_cp437_data(size_t x, * - `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_CCommand *ptr); +void sp_command_dealloc(struct SPCommand *ptr); /** * Allocates a new `Command::FadeOut` instance. @@ -743,7 +726,7 @@ void sp_command_dealloc(struct sp_CCommand *ptr); * - the returned `Command` instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_dealloc`. */ -struct sp_CCommand *sp_command_fade_out(void); +struct SPCommand *sp_command_fade_out(void); /** * Allocates a new `Command::HardReset` instance. @@ -755,7 +738,7 @@ struct sp_CCommand *sp_command_fade_out(void); * - the returned `Command` instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_dealloc`. */ -struct sp_CCommand *sp_command_hard_reset(void); +struct SPCommand *sp_command_hard_reset(void); /** * Tries to turn a `Packet` into a `Command`. The packet is deallocated in the process. @@ -772,7 +755,7 @@ struct sp_CCommand *sp_command_hard_reset(void); * - the returned `Command` instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_dealloc`. */ -struct sp_CCommand *sp_command_try_from_packet(struct sp_Packet *packet); +struct SPCommand *sp_command_try_from_packet(struct SPPacket *packet); /** * Closes and deallocates a `Connection`. @@ -784,7 +767,7 @@ struct sp_CCommand *sp_command_try_from_packet(struct sp_Packet *packet); * - `this` points to a valid `Connection` * - `this` is not used concurrently or after this call */ -void sp_connection_dealloc(struct sp_Connection *ptr); +void sp_connection_dealloc(struct SPConnection *ptr); /** * Creates a new instance of `Connection`. @@ -802,7 +785,7 @@ void sp_connection_dealloc(struct sp_Connection *ptr); * - 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); +struct SPConnection *sp_connection_open(const char *host); /** * Sends a `Packet` to the display using the `Connection`. @@ -818,8 +801,8 @@ struct sp_Connection *sp_connection_open(const char *host); * - `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 *packet); +bool sp_connection_send(const struct SPConnection *connection, + struct SPPacket *packet); /** * Clones a `Cp437Grid`. @@ -833,7 +816,7 @@ bool sp_connection_send(const struct sp_Connection *connection, * - the returned instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_cp437_grid_dealloc`. */ -struct sp_CCp437Grid *sp_cp437_grid_clone(const struct sp_CCp437Grid *this_); +struct SPCp437Grid *sp_cp437_grid_clone(const struct SPCp437Grid *this_); /** * Deallocates a `Cp437Grid`. @@ -846,7 +829,7 @@ struct sp_CCp437Grid *sp_cp437_grid_clone(const struct sp_CCp437Grid *this_); * - `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_cp437_grid_dealloc(struct sp_CCp437Grid *this_); +void sp_cp437_grid_dealloc(struct SPCp437Grid *this_); /** * Sets the value of all cells in the `Cp437Grid`. @@ -863,7 +846,7 @@ void sp_cp437_grid_dealloc(struct sp_CCp437Grid *this_); * - `this` points to a valid `Cp437Grid` * - `this` is not written to or read from concurrently */ -void sp_cp437_grid_fill(struct sp_CCp437Grid *this_, uint8_t value); +void sp_cp437_grid_fill(struct SPCp437Grid *this_, uint8_t value); /** * Gets the current value at the specified position. @@ -884,9 +867,7 @@ void sp_cp437_grid_fill(struct sp_CCp437Grid *this_, uint8_t value); * - `this` points to a valid `Cp437Grid` * - `this` is not written to concurrently */ -uint8_t sp_cp437_grid_get(const struct sp_CCp437Grid *this_, - size_t x, - size_t y); +uint8_t sp_cp437_grid_get(const struct SPCp437Grid *this_, size_t x, size_t y); /** * Gets the height of the `Cp437Grid` instance. @@ -901,7 +882,7 @@ uint8_t sp_cp437_grid_get(const struct sp_CCp437Grid *this_, * * - `this` points to a valid `Cp437Grid` */ -size_t sp_cp437_grid_height(const struct sp_CCp437Grid *this_); +size_t sp_cp437_grid_height(const struct SPCp437Grid *this_); /** * Loads a `Cp437Grid` with the specified dimensions from the provided data. @@ -919,10 +900,10 @@ size_t sp_cp437_grid_height(const struct sp_CCp437Grid *this_); * - the returned instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_cp437_grid_dealloc`. */ -struct sp_CCp437Grid *sp_cp437_grid_load(size_t width, - size_t height, - const uint8_t *data, - size_t data_length); +struct SPCp437Grid *sp_cp437_grid_load(size_t width, + size_t height, + const uint8_t *data, + size_t data_length); /** * Creates a new `Cp437Grid` with the specified dimensions. @@ -936,8 +917,8 @@ struct sp_CCp437Grid *sp_cp437_grid_load(size_t width, * - the returned instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_cp437_grid_dealloc`. */ -struct sp_CCp437Grid *sp_cp437_grid_new(size_t width, - size_t height); +struct SPCp437Grid *sp_cp437_grid_new(size_t width, + size_t height); /** * Sets the value of the specified position in the `Cp437Grid`. @@ -961,7 +942,7 @@ struct sp_CCp437Grid *sp_cp437_grid_new(size_t width, * - `this` points to a valid `BitVec` * - `this` is not written to or read from concurrently */ -void sp_cp437_grid_set(struct sp_CCp437Grid *this_, +void sp_cp437_grid_set(struct SPCp437Grid *this_, size_t x, size_t y, uint8_t value); @@ -977,7 +958,7 @@ void sp_cp437_grid_set(struct sp_CCp437Grid *this_, * - the returned memory range is never accessed after the passed `Cp437Grid` has been freed * - the returned memory range is never accessed concurrently, either via the `Cp437Grid` or directly */ -struct sp_CByteSlice sp_cp437_grid_unsafe_data_ref(struct sp_CCp437Grid *this_); +struct SPByteSlice sp_cp437_grid_unsafe_data_ref(struct SPCp437Grid *this_); /** * Gets the width of the `Cp437Grid` instance. @@ -992,7 +973,7 @@ struct sp_CByteSlice sp_cp437_grid_unsafe_data_ref(struct sp_CCp437Grid *this_); * * - `this` points to a valid `Cp437Grid` */ -size_t sp_cp437_grid_width(const struct sp_CCp437Grid *this_); +size_t sp_cp437_grid_width(const struct SPCp437Grid *this_); /** * Clones a `Packet`. @@ -1006,7 +987,7 @@ size_t sp_cp437_grid_width(const struct sp_CCp437Grid *this_); * - the returned instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_packet_dealloc`. */ -struct sp_Packet *sp_packet_clone(const struct sp_Packet *this_); +struct SPPacket *sp_packet_clone(const struct SPPacket *this_); /** * Deallocates a `Packet`. @@ -1018,7 +999,7 @@ struct sp_Packet *sp_packet_clone(const struct sp_Packet *this_); * - `this` points to a valid `Packet` * - `this` is not used concurrently or after this call */ -void sp_packet_dealloc(struct sp_Packet *this_); +void sp_packet_dealloc(struct SPPacket *this_); /** * Turns a `Command` into a `Packet`. @@ -1033,7 +1014,7 @@ void sp_packet_dealloc(struct sp_Packet *this_); * - 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_CCommand *command); +struct SPPacket *sp_packet_from_command(struct SPCommand *command); /** * Tries to load a `Packet` from the passed array with the specified length. @@ -1049,8 +1030,8 @@ struct sp_Packet *sp_packet_from_command(struct sp_CCommand *command); * - 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 SPPacket *sp_packet_try_load(const uint8_t *data, + size_t length); /** * Clones a `PixelGrid`. @@ -1064,7 +1045,7 @@ struct sp_Packet *sp_packet_try_load(const uint8_t *data, * - 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_); +struct SPPixelGrid *sp_pixel_grid_clone(const struct SPPixelGrid *this_); /** * Deallocates a `PixelGrid`. @@ -1077,7 +1058,7 @@ struct sp_PixelGrid *sp_pixel_grid_clone(const struct sp_PixelGrid *this_); * - `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_); +void sp_pixel_grid_dealloc(struct SPPixelGrid *this_); /** * Sets the state of all pixels in the `PixelGrid`. @@ -1094,7 +1075,7 @@ void sp_pixel_grid_dealloc(struct sp_PixelGrid *this_); * - `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); +void sp_pixel_grid_fill(struct SPPixelGrid *this_, bool value); /** * Gets the current value at the specified position in the `PixelGrid`. @@ -1115,7 +1096,7 @@ void sp_pixel_grid_fill(struct sp_PixelGrid *this_, bool value); * - `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); +bool sp_pixel_grid_get(const struct SPPixelGrid *this_, size_t x, size_t y); /** * Gets the height in pixels of the `PixelGrid` instance. @@ -1130,7 +1111,7 @@ bool sp_pixel_grid_get(const struct sp_PixelGrid *this_, size_t x, size_t y); * * - `this` points to a valid `PixelGrid` */ -size_t sp_pixel_grid_height(const struct sp_PixelGrid *this_); +size_t sp_pixel_grid_height(const struct SPPixelGrid *this_); /** * Loads a `PixelGrid` with the specified dimensions from the provided data. @@ -1155,10 +1136,10 @@ size_t sp_pixel_grid_height(const struct sp_PixelGrid *this_); * - 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, - const uint8_t *data, - size_t data_length); +struct SPPixelGrid *sp_pixel_grid_load(size_t width, + size_t height, + const uint8_t *data, + size_t data_length); /** * Creates a new `PixelGrid` with the specified dimensions. @@ -1181,8 +1162,8 @@ struct sp_PixelGrid *sp_pixel_grid_load(size_t width, * - 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 SPPixelGrid *sp_pixel_grid_new(size_t width, + size_t height); /** * Sets the value of the specified position in the `PixelGrid`. @@ -1206,7 +1187,7 @@ struct sp_PixelGrid *sp_pixel_grid_new(size_t width, * - `this` points to a valid `PixelGrid` * - `this` is not written to or read from concurrently */ -void sp_pixel_grid_set(struct sp_PixelGrid *this_, +void sp_pixel_grid_set(struct SPPixelGrid *this_, size_t x, size_t y, bool value); @@ -1222,7 +1203,7 @@ void sp_pixel_grid_set(struct sp_PixelGrid *this_, * - 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_); +struct SPByteSlice sp_pixel_grid_unsafe_data_ref(struct SPPixelGrid *this_); /** * Gets the width in pixels of the `PixelGrid` instance. @@ -1237,7 +1218,7 @@ struct sp_CByteSlice sp_pixel_grid_unsafe_data_ref(struct sp_PixelGrid *this_); * * - `this` points to a valid `PixelGrid` */ -size_t sp_pixel_grid_width(const struct sp_PixelGrid *this_); +size_t sp_pixel_grid_width(const struct SPPixelGrid *this_); #ifdef __cplusplus } // extern "C" diff --git a/crates/servicepoint_binding_c/examples/lang_c/src/main.c b/crates/servicepoint_binding_c/examples/lang_c/src/main.c index 451abe7..738cdfe 100644 --- a/crates/servicepoint_binding_c/examples/lang_c/src/main.c +++ b/crates/servicepoint_binding_c/examples/lang_c/src/main.c @@ -2,15 +2,15 @@ #include "servicepoint.h" int main(void) { - sp_Connection *connection = sp_connection_open("172.23.42.29:2342"); + SPConnection *connection = sp_connection_open("172.23.42.29:2342"); if (connection == NULL) return 1; - sp_PixelGrid *pixels = sp_pixel_grid_new(sp_PIXEL_WIDTH, sp_PIXEL_HEIGHT); + SPPixelGrid *pixels = sp_pixel_grid_new(SP_PIXEL_WIDTH, SP_PIXEL_HEIGHT); sp_pixel_grid_fill(pixels, true); - sp_CCommand *command = sp_command_bitmap_linear_win(0, 0, pixels, Uncompressed); - sp_Packet *packet = sp_packet_from_command(command); + SPCommand *command = sp_command_bitmap_linear_win(0, 0, pixels, Uncompressed); + SPPacket *packet = sp_packet_from_command(command); while (sp_connection_send(connection, sp_packet_clone(packet))); sp_packet_dealloc(packet); diff --git a/crates/servicepoint_binding_c/src/bit_vec.rs b/crates/servicepoint_binding_c/src/bit_vec.rs index 6a52a63..d53792e 100644 --- a/crates/servicepoint_binding_c/src/bit_vec.rs +++ b/crates/servicepoint_binding_c/src/bit_vec.rs @@ -2,34 +2,34 @@ //! //! prefix `sp_bit_vec_` -use crate::c_slice::CByteSlice; +use crate::c_slice::SPByteSlice; use servicepoint::bitvec::prelude::{BitVec, Msb0}; -/// cbindgen:no-export -type SpBitVec = BitVec; - /// A vector of bits -pub struct CBitVec { - actual: SpBitVec, -} +/// +/// # Examples +/// ```C +/// SPBitVec vec = sp_bit_vec_new(8); +/// sp_bit_vec_set(vec, 5, true); +/// sp_bit_vec_dealloc(vec); +/// ``` +pub struct SPBitVec(BitVec); -impl From for CBitVec { - fn from(actual: SpBitVec) -> Self { - Self { actual } +impl From> for SPBitVec { + fn from(actual: BitVec) -> Self { + Self(actual) } } -impl From for SpBitVec { - fn from(value: CBitVec) -> Self { - value.actual +impl From for BitVec { + fn from(value: SPBitVec) -> Self { + value.0 } } -impl Clone for CBitVec { +impl Clone for SPBitVec { fn clone(&self) -> Self { - CBitVec { - actual: self.actual.clone(), - } + SPBitVec(self.0.clone()) } } @@ -52,10 +52,8 @@ impl Clone for CBitVec { /// - 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 CBitVec { - Box::into_raw(Box::new(CBitVec { - actual: SpBitVec::repeat(false, size), - })) +pub unsafe extern "C" fn sp_bit_vec_new(size: usize) -> *mut SPBitVec { + Box::into_raw(Box::new(SPBitVec(BitVec::repeat(false, size)))) } /// Interpret the data as a series of bits and load then into a new `BitVec` instance. @@ -72,11 +70,9 @@ pub unsafe extern "C" fn sp_bit_vec_new(size: usize) -> *mut CBitVec { pub unsafe extern "C" fn sp_bit_vec_load( data: *const u8, data_length: usize, -) -> *mut CBitVec { +) -> *mut SPBitVec { let data = std::slice::from_raw_parts(data, data_length); - Box::into_raw(Box::new(CBitVec { - actual: SpBitVec::from_slice(data), - })) + Box::into_raw(Box::new(SPBitVec(BitVec::from_slice(data)))) } /// Clones a `BitVec`. @@ -91,8 +87,8 @@ pub unsafe extern "C" fn sp_bit_vec_load( /// by explicitly calling `sp_bit_vec_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_bit_vec_clone( - this: *const CBitVec, -) -> *mut CBitVec { + this: *const SPBitVec, +) -> *mut SPBitVec { Box::into_raw(Box::new((*this).clone())) } @@ -106,7 +102,7 @@ pub unsafe extern "C" fn sp_bit_vec_clone( /// - `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 CBitVec) { +pub unsafe extern "C" fn sp_bit_vec_dealloc(this: *mut SPBitVec) { _ = Box::from_raw(this); } @@ -131,10 +127,10 @@ pub unsafe extern "C" fn sp_bit_vec_dealloc(this: *mut CBitVec) { /// - `this` is not written to concurrently #[no_mangle] pub unsafe extern "C" fn sp_bit_vec_get( - this: *const CBitVec, + this: *const SPBitVec, index: usize, ) -> bool { - *(*this).actual.get(index).unwrap() + *(*this).0.get(index).unwrap() } /// Sets the value of a bit in the `BitVec`. @@ -159,11 +155,11 @@ pub unsafe extern "C" fn sp_bit_vec_get( /// - `this` is not written to or read from concurrently #[no_mangle] pub unsafe extern "C" fn sp_bit_vec_set( - this: *mut CBitVec, + this: *mut SPBitVec, index: usize, value: bool, ) { - (*this).actual.set(index, value) + (*this).0.set(index, value) } /// Sets the value of all bits in the `BitVec`. @@ -179,8 +175,8 @@ pub unsafe extern "C" fn sp_bit_vec_set( /// - `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 CBitVec, value: bool) { - (*this).actual.fill(value) +pub unsafe extern "C" fn sp_bit_vec_fill(this: *mut SPBitVec, value: bool) { + (*this).0.fill(value) } /// Gets the length of the `BitVec` in bits. @@ -191,8 +187,8 @@ pub unsafe extern "C" fn sp_bit_vec_fill(this: *mut CBitVec, value: bool) { /// /// - `this` points to a valid `BitVec` #[no_mangle] -pub unsafe extern "C" fn sp_bit_vec_len(this: *const CBitVec) -> usize { - (*this).actual.len() +pub unsafe extern "C" fn sp_bit_vec_len(this: *const SPBitVec) -> usize { + (*this).0.len() } /// Returns true if length is 0. @@ -203,8 +199,8 @@ pub unsafe extern "C" fn sp_bit_vec_len(this: *const CBitVec) -> usize { /// /// - `this` points to a valid `BitVec` #[no_mangle] -pub unsafe extern "C" fn sp_bit_vec_is_empty(this: *const CBitVec) -> bool { - (*this).actual.is_empty() +pub unsafe extern "C" fn sp_bit_vec_is_empty(this: *const SPBitVec) -> bool { + (*this).0.is_empty() } /// Gets an unsafe reference to the data of the `BitVec` instance. @@ -218,10 +214,10 @@ pub unsafe extern "C" fn sp_bit_vec_is_empty(this: *const CBitVec) -> bool { /// - 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 CBitVec, -) -> CByteSlice { - let data = (*this).actual.as_raw_mut_slice(); - CByteSlice { + this: *mut SPBitVec, +) -> SPByteSlice { + let data = (*this).0.as_raw_mut_slice(); + SPByteSlice { start: data.as_mut_ptr_range().start, length: data.len(), } diff --git a/crates/servicepoint_binding_c/src/brightness_grid.rs b/crates/servicepoint_binding_c/src/brightness_grid.rs index 0ca0ec6..e4af777 100644 --- a/crates/servicepoint_binding_c/src/brightness_grid.rs +++ b/crates/servicepoint_binding_c/src/brightness_grid.rs @@ -2,18 +2,32 @@ //! //! prefix `sp_brightness_grid_` -use crate::c_slice::CByteSlice; -use servicepoint::{Brightness, BrightnessGrid, DataRef, Grid, PrimitiveGrid}; +use crate::c_slice::SPByteSlice; +use servicepoint::{Brightness, DataRef, Grid, PrimitiveGrid}; use std::intrinsics::transmute; -/// C-wrapper for grid containing brightness values. -pub struct CBrightnessGrid { - pub(crate) actual: BrightnessGrid, +/// A grid containing brightness values. +/// +/// # Examples +/// ```C +/// SPConnection connection = sp_connection_open("127.0.0.1:2342"); +/// if (connection == NULL) +/// return 1; +/// +/// SPBrightnessGrid grid = sp_brightness_grid_new(2, 2); +/// sp_brightness_grid_set(grid, 0, 0, 0); +/// sp_brightness_grid_set(grid, 1, 1, 10); +/// +/// SPCommand command = sp_command_char_brightness(grid); +/// sp_connection_dealloc(connection); +/// ``` +pub struct SPBrightnessGrid { + pub(crate) actual: servicepoint::BrightnessGrid, } -impl Clone for CBrightnessGrid { +impl Clone for SPBrightnessGrid { fn clone(&self) -> Self { - CBrightnessGrid { + SPBrightnessGrid { actual: self.actual.clone(), } } @@ -33,9 +47,9 @@ impl Clone for CBrightnessGrid { pub unsafe extern "C" fn sp_brightness_grid_new( width: usize, height: usize, -) -> *mut CBrightnessGrid { - Box::into_raw(Box::new(CBrightnessGrid { - actual: BrightnessGrid::new(width, height), +) -> *mut SPBrightnessGrid { + Box::into_raw(Box::new(SPBrightnessGrid { + actual: servicepoint::BrightnessGrid::new(width, height), })) } @@ -59,12 +73,12 @@ pub unsafe extern "C" fn sp_brightness_grid_load( height: usize, data: *const u8, data_length: usize, -) -> *mut CBrightnessGrid { +) -> *mut SPBrightnessGrid { let data = std::slice::from_raw_parts(data, data_length); let grid = PrimitiveGrid::load(width, height, data); - let grid = - BrightnessGrid::try_from(grid).expect("invalid brightness value"); - Box::into_raw(Box::new(CBrightnessGrid { actual: grid })) + let grid = servicepoint::BrightnessGrid::try_from(grid) + .expect("invalid brightness value"); + Box::into_raw(Box::new(SPBrightnessGrid { actual: grid })) } /// Clones a `BrightnessGrid`. @@ -79,8 +93,8 @@ pub unsafe extern "C" fn sp_brightness_grid_load( /// by explicitly calling `sp_brightness_grid_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_brightness_grid_clone( - this: *const CBrightnessGrid, -) -> *mut CBrightnessGrid { + this: *const SPBrightnessGrid, +) -> *mut SPBrightnessGrid { Box::into_raw(Box::new((*this).clone())) } @@ -95,7 +109,7 @@ pub unsafe extern "C" fn sp_brightness_grid_clone( /// - `this` was not passed to another consuming function, e.g. to create a `Command` #[no_mangle] pub unsafe extern "C" fn sp_brightness_grid_dealloc( - this: *mut CBrightnessGrid, + this: *mut SPBrightnessGrid, ) { _ = Box::from_raw(this); } @@ -119,7 +133,7 @@ pub unsafe extern "C" fn sp_brightness_grid_dealloc( /// - `this` is not written to concurrently #[no_mangle] pub unsafe extern "C" fn sp_brightness_grid_get( - this: *const CBrightnessGrid, + this: *const SPBrightnessGrid, x: usize, y: usize, ) -> u8 { @@ -149,7 +163,7 @@ pub unsafe extern "C" fn sp_brightness_grid_get( /// - `this` is not written to or read from concurrently #[no_mangle] pub unsafe extern "C" fn sp_brightness_grid_set( - this: *mut CBrightnessGrid, + this: *mut SPBrightnessGrid, x: usize, y: usize, value: u8, @@ -178,7 +192,7 @@ pub unsafe extern "C" fn sp_brightness_grid_set( /// - `this` is not written to or read from concurrently #[no_mangle] pub unsafe extern "C" fn sp_brightness_grid_fill( - this: *mut CBrightnessGrid, + this: *mut SPBrightnessGrid, value: u8, ) { let brightness = @@ -199,7 +213,7 @@ pub unsafe extern "C" fn sp_brightness_grid_fill( /// - `this` points to a valid `BrightnessGrid` #[no_mangle] pub unsafe extern "C" fn sp_brightness_grid_width( - this: *const CBrightnessGrid, + this: *const SPBrightnessGrid, ) -> usize { (*this).actual.width() } @@ -217,7 +231,7 @@ pub unsafe extern "C" fn sp_brightness_grid_width( /// - `this` points to a valid `BrightnessGrid` #[no_mangle] pub unsafe extern "C" fn sp_brightness_grid_height( - this: *const CBrightnessGrid, + this: *const SPBrightnessGrid, ) -> usize { (*this).actual.height() } @@ -233,13 +247,13 @@ pub unsafe extern "C" fn sp_brightness_grid_height( /// - the returned memory range is never accessed concurrently, either via the `BrightnessGrid` or directly #[no_mangle] pub unsafe extern "C" fn sp_brightness_grid_unsafe_data_ref( - this: *mut CBrightnessGrid, -) -> CByteSlice { + this: *mut SPBrightnessGrid, +) -> SPByteSlice { assert_eq!(std::mem::size_of::(), 1); let data = (*this).actual.data_ref_mut(); let data: &mut [u8] = transmute(data); - CByteSlice { + SPByteSlice { start: data.as_mut_ptr_range().start, length: data.len(), } diff --git a/crates/servicepoint_binding_c/src/c_slice.rs b/crates/servicepoint_binding_c/src/c_slice.rs index 566213d..9962511 100644 --- a/crates/servicepoint_binding_c/src/c_slice.rs +++ b/crates/servicepoint_binding_c/src/c_slice.rs @@ -10,7 +10,7 @@ /// - 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 { +pub struct SPByteSlice { /// The start address of the memory pub start: *mut u8, /// The amount of memory in bytes diff --git a/crates/servicepoint_binding_c/src/command.rs b/crates/servicepoint_binding_c/src/command.rs index 6126284..ec8a033 100644 --- a/crates/servicepoint_binding_c/src/command.rs +++ b/crates/servicepoint_binding_c/src/command.rs @@ -4,24 +4,33 @@ use std::ptr::null_mut; -use servicepoint::{ - Brightness, Command, CompressionCode, Offset, Origin, Packet, PixelGrid, -}; +use servicepoint::{Brightness, Origin}; -use crate::bit_vec::CBitVec; -use crate::brightness_grid::CBrightnessGrid; -use crate::cp437_grid::CCp437Grid; +use crate::bit_vec::SPBitVec; +use crate::brightness_grid::SPBrightnessGrid; +use crate::constants::SPCompressionCode; +use crate::cp437_grid::SPCp437Grid; +use crate::packet::SPPacket; +use crate::pixel_grid::SPPixelGrid; +use crate::SPOffset; /// A low-level display command. /// /// This struct and associated functions implement the UDP protocol for the display. /// -/// To send a `CCommand`, use a `Connection`. -pub struct CCommand(pub(crate) Command); +/// To send a `CCommand`, use a `CConnection`. +/// +/// # Examples +/// +/// ```C +/// sp_connection_send(connection, sp_command_clear()); +/// sp_connection_send(connection, sp_command_brightness(5)); +/// ``` +pub struct SPCommand(pub(crate) servicepoint::Command); -impl Clone for CCommand { +impl Clone for SPCommand { fn clone(&self) -> Self { - CCommand(self.0.clone()) + SPCommand(self.0.clone()) } } @@ -40,12 +49,12 @@ impl Clone for CCommand { /// by explicitly calling `sp_command_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_command_try_from_packet( - packet: *mut Packet, -) -> *mut CCommand { + packet: *mut SPPacket, +) -> *mut SPCommand { let packet = *Box::from_raw(packet); - match Command::try_from(packet) { + match servicepoint::Command::try_from(packet.0) { Err(_) => null_mut(), - Ok(command) => Box::into_raw(Box::new(CCommand(command))), + Ok(command) => Box::into_raw(Box::new(SPCommand(command))), } } @@ -61,8 +70,8 @@ pub unsafe extern "C" fn sp_command_try_from_packet( /// by explicitly calling `sp_command_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_command_clone( - original: *const CCommand, -) -> *mut CCommand { + original: *const SPCommand, +) -> *mut SPCommand { Box::into_raw(Box::new((*original).clone())) } @@ -75,8 +84,8 @@ pub unsafe extern "C" fn sp_command_clone( /// - 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 CCommand { - Box::into_raw(Box::new(CCommand(Command::Clear))) +pub unsafe extern "C" fn sp_command_clear() -> *mut SPCommand { + Box::into_raw(Box::new(SPCommand(servicepoint::Command::Clear))) } /// Allocates a new `Command::HardReset` instance. @@ -88,8 +97,8 @@ pub unsafe extern "C" fn sp_command_clear() -> *mut CCommand { /// - 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 CCommand { - Box::into_raw(Box::new(CCommand(Command::HardReset))) +pub unsafe extern "C" fn sp_command_hard_reset() -> *mut SPCommand { + Box::into_raw(Box::new(SPCommand(servicepoint::Command::HardReset))) } /// Allocates a new `Command::FadeOut` instance. @@ -101,8 +110,8 @@ pub unsafe extern "C" fn sp_command_hard_reset() -> *mut CCommand { /// - 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 CCommand { - Box::into_raw(Box::new(CCommand(Command::FadeOut))) +pub unsafe extern "C" fn sp_command_fade_out() -> *mut SPCommand { + Box::into_raw(Box::new(SPCommand(servicepoint::Command::FadeOut))) } /// Allocates a new `Command::Brightness` instance for setting the brightness of all tiles to the @@ -116,36 +125,38 @@ pub unsafe extern "C" fn sp_command_fade_out() -> *mut CCommand { /// /// The caller has to make sure that: /// -/// - the returned `Command` instance is freed in some way, either by using a consuming function or +/// - the returned `SPCommand` 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: u8, -) -> *mut CCommand { +) -> *mut SPCommand { let brightness = Brightness::try_from(brightness).expect("invalid brightness"); - Box::into_raw(Box::new(CCommand(Command::Brightness(brightness)))) + Box::into_raw(Box::new(SPCommand(servicepoint::Command::Brightness( + brightness, + )))) } /// Allocates a new `Command::CharBrightness` instance. -/// The passed `ByteGrid` gets consumed. +/// The passed `SPBrightnessGrid` 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 +/// - `grid` points to a valid instance of `SPBrightnessGrid` +/// - `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, y: usize, - byte_grid: *mut CBrightnessGrid, -) -> *mut CCommand { - let byte_grid = *Box::from_raw(byte_grid); - Box::into_raw(Box::new(CCommand(Command::CharBrightness( + grid: *mut SPBrightnessGrid, +) -> *mut SPCommand { + let byte_grid = *Box::from_raw(grid); + Box::into_raw(Box::new(SPCommand(servicepoint::Command::CharBrightness( Origin::new(x, y), byte_grid.actual, )))) @@ -165,15 +176,15 @@ pub unsafe extern "C" fn sp_command_char_brightness( /// by explicitly calling `sp_command_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_command_bitmap_linear( - offset: Offset, - bit_vec: *mut CBitVec, - compression: CompressionCode, -) -> *mut CCommand { + offset: SPOffset, + bit_vec: *mut SPBitVec, + compression: SPCompressionCode, +) -> *mut SPCommand { let bit_vec = *Box::from_raw(bit_vec); - Box::into_raw(Box::new(CCommand(Command::BitmapLinear( + Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinear( offset, bit_vec.into(), - compression, + compression.try_into().expect("invalid compression code"), )))) } @@ -191,15 +202,15 @@ pub unsafe extern "C" fn sp_command_bitmap_linear( /// by explicitly calling `sp_command_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_command_bitmap_linear_and( - offset: Offset, - bit_vec: *mut CBitVec, - compression: CompressionCode, -) -> *mut CCommand { + offset: SPOffset, + bit_vec: *mut SPBitVec, + compression: SPCompressionCode, +) -> *mut SPCommand { let bit_vec = *Box::from_raw(bit_vec); - Box::into_raw(Box::new(CCommand(Command::BitmapLinearAnd( + Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinearAnd( offset, bit_vec.into(), - compression, + compression.try_into().expect("invalid compression code"), )))) } @@ -217,15 +228,15 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_and( /// by explicitly calling `sp_command_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_command_bitmap_linear_or( - offset: Offset, - bit_vec: *mut CBitVec, - compression: CompressionCode, -) -> *mut CCommand { + offset: SPOffset, + bit_vec: *mut SPBitVec, + compression: SPCompressionCode, +) -> *mut SPCommand { let bit_vec = *Box::from_raw(bit_vec); - Box::into_raw(Box::new(CCommand(Command::BitmapLinearOr( + Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinearOr( offset, bit_vec.into(), - compression, + compression.try_into().expect("invalid compression code"), )))) } @@ -243,15 +254,15 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_or( /// by explicitly calling `sp_command_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_command_bitmap_linear_xor( - offset: Offset, - bit_vec: *mut CBitVec, - compression: CompressionCode, -) -> *mut CCommand { + offset: SPOffset, + bit_vec: *mut SPBitVec, + compression: SPCompressionCode, +) -> *mut SPCommand { let bit_vec = *Box::from_raw(bit_vec); - Box::into_raw(Box::new(CCommand(Command::BitmapLinearXor( + Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinearXor( offset, bit_vec.into(), - compression, + compression.try_into().expect("invalid compression code"), )))) } @@ -270,10 +281,10 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_xor( pub unsafe extern "C" fn sp_command_cp437_data( x: usize, y: usize, - byte_grid: *mut CCp437Grid, -) -> *mut CCommand { + byte_grid: *mut SPCp437Grid, +) -> *mut SPCommand { let byte_grid = *Box::from_raw(byte_grid); - Box::into_raw(Box::new(CCommand(Command::Cp437Data( + Box::into_raw(Box::new(SPCommand(servicepoint::Command::Cp437Data( Origin::new(x, y), byte_grid.actual, )))) @@ -295,14 +306,16 @@ pub unsafe extern "C" fn sp_command_cp437_data( pub unsafe extern "C" fn sp_command_bitmap_linear_win( x: usize, y: usize, - pixel_grid: *mut PixelGrid, - compression_code: CompressionCode, -) -> *mut CCommand { - let byte_grid = *Box::from_raw(pixel_grid); - Box::into_raw(Box::new(CCommand(Command::BitmapLinearWin( + pixel_grid: *mut SPPixelGrid, + compression_code: SPCompressionCode, +) -> *mut SPCommand { + let byte_grid = (*Box::from_raw(pixel_grid)).0; + Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinearWin( Origin::new(x, y), byte_grid, - compression_code, + compression_code + .try_into() + .expect("invalid compression code"), )))) } @@ -316,6 +329,6 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_win( /// - `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 CCommand) { +pub unsafe extern "C" fn sp_command_dealloc(ptr: *mut SPCommand) { _ = Box::from_raw(ptr); } diff --git a/crates/servicepoint_binding_c/src/connection.rs b/crates/servicepoint_binding_c/src/connection.rs index 25b9cf7..e0556e3 100644 --- a/crates/servicepoint_binding_c/src/connection.rs +++ b/crates/servicepoint_binding_c/src/connection.rs @@ -5,7 +5,18 @@ use std::ffi::{c_char, CStr}; use std::ptr::null_mut; -use servicepoint::{Connection, Packet}; +use crate::packet::SPPacket; + +/// A connection to the display. +/// +/// # Examples +/// +/// ```C +/// CConnection connection = sp_connection_open("172.23.42.29:2342"); +/// if (connection != NULL) +/// sp_connection_send(connection, sp_command_clear()); +/// ``` +pub struct SPConnection(pub(crate) servicepoint::Connection); /// Creates a new instance of `Connection`. /// @@ -24,14 +35,14 @@ use servicepoint::{Connection, Packet}; #[no_mangle] pub unsafe extern "C" fn sp_connection_open( host: *const c_char, -) -> *mut Connection { +) -> *mut SPConnection { let host = CStr::from_ptr(host).to_str().expect("Bad encoding"); - let connection = match Connection::open(host) { + let connection = match servicepoint::Connection::open(host) { Err(_) => return null_mut(), Ok(value) => value, }; - Box::into_raw(Box::new(connection)) + Box::into_raw(Box::new(SPConnection(connection))) } /// Sends a `Packet` to the display using the `Connection`. @@ -48,11 +59,11 @@ pub unsafe extern "C" fn sp_connection_open( /// - `packet` is not used concurrently or after this call #[no_mangle] pub unsafe extern "C" fn sp_connection_send( - connection: *const Connection, - packet: *mut Packet, + connection: *const SPConnection, + packet: *mut SPPacket, ) -> bool { let packet = Box::from_raw(packet); - (*connection).send(*packet).is_ok() + (*connection).0.send((*packet).0).is_ok() } /// Closes and deallocates a `Connection`. @@ -64,6 +75,6 @@ pub unsafe extern "C" fn sp_connection_send( /// - `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) { +pub unsafe extern "C" fn sp_connection_dealloc(ptr: *mut SPConnection) { _ = Box::from_raw(ptr); } diff --git a/crates/servicepoint_binding_c/src/constants.rs b/crates/servicepoint_binding_c/src/constants.rs new file mode 100644 index 0000000..1a268f4 --- /dev/null +++ b/crates/servicepoint_binding_c/src/constants.rs @@ -0,0 +1,48 @@ +//! re-exported constants for use in C + +use servicepoint::CompressionCode; +use std::time::Duration; + +/// size of a single tile in one dimension +pub const SP_TILE_SIZE: usize = 8; + +/// Display tile count in the x-direction +pub const SP_TILE_WIDTH: usize = 56; + +/// Display tile count in the y-direction +pub const SP_TILE_HEIGHT: usize = 20; + +/// Display width in pixels +pub const SP_PIXEL_WIDTH: usize = SP_TILE_WIDTH * SP_TILE_SIZE; + +/// Display height in pixels +pub const SP_PIXEL_HEIGHT: usize = SP_TILE_HEIGHT * SP_TILE_SIZE; + +/// pixel count on whole screen +pub const SP_PIXEL_COUNT: usize = SP_PIXEL_WIDTH * SP_PIXEL_HEIGHT; + +/// Actual hardware limit is around 28-29ms/frame. Rounded up for less dropped packets. +pub const SP_FRAME_PACING_MS: u128 = Duration::from_millis(30).as_millis(); + +/// Specifies the kind of compression to use. +#[repr(u16)] +pub enum SPCompressionCode { + /// no compression + Uncompressed = 0x0, + /// compress using flate2 with zlib header + Zlib = 0x677a, + /// compress using bzip2 + Bzip2 = 0x627a, + /// compress using lzma + Lzma = 0x6c7a, + /// compress using Zstandard + Zstd = 0x7a73, +} + +impl TryFrom for CompressionCode { + type Error = (); + + fn try_from(value: SPCompressionCode) -> Result { + CompressionCode::try_from(value as u16) + } +} diff --git a/crates/servicepoint_binding_c/src/cp437_grid.rs b/crates/servicepoint_binding_c/src/cp437_grid.rs index 79651bf..f181fdf 100644 --- a/crates/servicepoint_binding_c/src/cp437_grid.rs +++ b/crates/servicepoint_binding_c/src/cp437_grid.rs @@ -2,19 +2,28 @@ //! //! prefix `sp_cp437_grid_` -use crate::c_slice::CByteSlice; +use crate::c_slice::SPByteSlice; use servicepoint::{Cp437Grid, DataRef, Grid}; /// A C-wrapper for grid containing codepage 437 characters. /// /// The encoding is currently not enforced. -pub struct CCp437Grid { +/// +/// # Examples +/// +/// ```C +/// Cp437Grid grid = sp_cp437_grid_new(4, 3); +/// sp_cp437_grid_fill(grid, '?'); +/// sp_cp437_grid_set(grid, 0, 0, '!'); +/// sp_cp437_grid_dealloc(grid); +/// ``` +pub struct SPCp437Grid { pub(crate) actual: Cp437Grid, } -impl Clone for CCp437Grid { +impl Clone for SPCp437Grid { fn clone(&self) -> Self { - CCp437Grid { + SPCp437Grid { actual: self.actual.clone(), } } @@ -34,8 +43,8 @@ impl Clone for CCp437Grid { pub unsafe extern "C" fn sp_cp437_grid_new( width: usize, height: usize, -) -> *mut CCp437Grid { - Box::into_raw(Box::new(CCp437Grid { +) -> *mut SPCp437Grid { + Box::into_raw(Box::new(SPCp437Grid { actual: Cp437Grid::new(width, height), })) } @@ -60,9 +69,9 @@ pub unsafe extern "C" fn sp_cp437_grid_load( height: usize, data: *const u8, data_length: usize, -) -> *mut CCp437Grid { +) -> *mut SPCp437Grid { let data = std::slice::from_raw_parts(data, data_length); - Box::into_raw(Box::new(CCp437Grid { + Box::into_raw(Box::new(SPCp437Grid { actual: Cp437Grid::load(width, height, data), })) } @@ -79,8 +88,8 @@ pub unsafe extern "C" fn sp_cp437_grid_load( /// by explicitly calling `sp_cp437_grid_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_cp437_grid_clone( - this: *const CCp437Grid, -) -> *mut CCp437Grid { + this: *const SPCp437Grid, +) -> *mut SPCp437Grid { Box::into_raw(Box::new((*this).clone())) } @@ -94,7 +103,7 @@ pub unsafe extern "C" fn sp_cp437_grid_clone( /// - `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_cp437_grid_dealloc(this: *mut CCp437Grid) { +pub unsafe extern "C" fn sp_cp437_grid_dealloc(this: *mut SPCp437Grid) { _ = Box::from_raw(this); } @@ -117,7 +126,7 @@ pub unsafe extern "C" fn sp_cp437_grid_dealloc(this: *mut CCp437Grid) { /// - `this` is not written to concurrently #[no_mangle] pub unsafe extern "C" fn sp_cp437_grid_get( - this: *const CCp437Grid, + this: *const SPCp437Grid, x: usize, y: usize, ) -> u8 { @@ -146,7 +155,7 @@ pub unsafe extern "C" fn sp_cp437_grid_get( /// - `this` is not written to or read from concurrently #[no_mangle] pub unsafe extern "C" fn sp_cp437_grid_set( - this: *mut CCp437Grid, + this: *mut SPCp437Grid, x: usize, y: usize, value: u8, @@ -168,7 +177,7 @@ pub unsafe extern "C" fn sp_cp437_grid_set( /// - `this` points to a valid `Cp437Grid` /// - `this` is not written to or read from concurrently #[no_mangle] -pub unsafe extern "C" fn sp_cp437_grid_fill(this: *mut CCp437Grid, value: u8) { +pub unsafe extern "C" fn sp_cp437_grid_fill(this: *mut SPCp437Grid, value: u8) { (*this).actual.fill(value); } @@ -184,7 +193,9 @@ pub unsafe extern "C" fn sp_cp437_grid_fill(this: *mut CCp437Grid, value: u8) { /// /// - `this` points to a valid `Cp437Grid` #[no_mangle] -pub unsafe extern "C" fn sp_cp437_grid_width(this: *const CCp437Grid) -> usize { +pub unsafe extern "C" fn sp_cp437_grid_width( + this: *const SPCp437Grid, +) -> usize { (*this).actual.width() } @@ -201,7 +212,7 @@ pub unsafe extern "C" fn sp_cp437_grid_width(this: *const CCp437Grid) -> usize { /// - `this` points to a valid `Cp437Grid` #[no_mangle] pub unsafe extern "C" fn sp_cp437_grid_height( - this: *const CCp437Grid, + this: *const SPCp437Grid, ) -> usize { (*this).actual.height() } @@ -217,10 +228,10 @@ pub unsafe extern "C" fn sp_cp437_grid_height( /// - the returned memory range is never accessed concurrently, either via the `Cp437Grid` or directly #[no_mangle] pub unsafe extern "C" fn sp_cp437_grid_unsafe_data_ref( - this: *mut CCp437Grid, -) -> CByteSlice { + this: *mut SPCp437Grid, +) -> SPByteSlice { let data = (*this).actual.data_ref_mut(); - CByteSlice { + SPByteSlice { start: data.as_mut_ptr_range().start, length: data.len(), } diff --git a/crates/servicepoint_binding_c/src/lib.rs b/crates/servicepoint_binding_c/src/lib.rs index 0939b66..c2d2877 100644 --- a/crates/servicepoint_binding_c/src/lib.rs +++ b/crates/servicepoint_binding_c/src/lib.rs @@ -1,11 +1,6 @@ //! 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; +pub use crate::c_slice::SPByteSlice; pub mod bit_vec; @@ -23,5 +18,7 @@ pub mod c_slice; pub mod cp437_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; +pub mod constants; + +/// Type alias for documenting the meaning of the variable in enum values +pub type SPOffset = usize; diff --git a/crates/servicepoint_binding_c/src/packet.rs b/crates/servicepoint_binding_c/src/packet.rs index 8c69410..c3304b8 100644 --- a/crates/servicepoint_binding_c/src/packet.rs +++ b/crates/servicepoint_binding_c/src/packet.rs @@ -4,8 +4,10 @@ use std::ptr::null_mut; -use crate::command::CCommand; -use servicepoint::Packet; +use crate::command::SPCommand; + +/// The raw packet +pub struct SPPacket(pub(crate) servicepoint::Packet); /// Turns a `Command` into a `Packet`. /// The `Command` gets consumed. @@ -20,10 +22,10 @@ use servicepoint::Packet; /// by explicitly calling `sp_packet_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_packet_from_command( - command: *mut CCommand, -) -> *mut Packet { + command: *mut SPCommand, +) -> *mut SPPacket { let command = *Box::from_raw(command); - let packet = command.0.into(); + let packet = SPPacket(command.0.into()); Box::into_raw(Box::new(packet)) } @@ -43,11 +45,11 @@ pub unsafe extern "C" fn sp_packet_from_command( pub unsafe extern "C" fn sp_packet_try_load( data: *const u8, length: usize, -) -> *mut Packet { +) -> *mut SPPacket { let data = std::slice::from_raw_parts(data, length); - match Packet::try_from(data) { + match servicepoint::Packet::try_from(data) { Err(_) => null_mut(), - Ok(packet) => Box::into_raw(Box::new(packet)), + Ok(packet) => Box::into_raw(Box::new(SPPacket(packet))), } } @@ -62,8 +64,10 @@ pub unsafe extern "C" fn sp_packet_try_load( /// - the returned 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_clone(this: *const Packet) -> *mut Packet { - Box::into_raw(Box::new((*this).clone())) +pub unsafe extern "C" fn sp_packet_clone( + this: *const SPPacket, +) -> *mut SPPacket { + Box::into_raw(Box::new(SPPacket((*this).0.clone()))) } /// Deallocates a `Packet`. @@ -75,6 +79,6 @@ pub unsafe extern "C" fn sp_packet_clone(this: *const Packet) -> *mut Packet { /// - `this` points to a valid `Packet` /// - `this` is not used concurrently or after this call #[no_mangle] -pub unsafe extern "C" fn sp_packet_dealloc(this: *mut Packet) { +pub unsafe extern "C" fn sp_packet_dealloc(this: *mut SPPacket) { _ = Box::from_raw(this) } diff --git a/crates/servicepoint_binding_c/src/pixel_grid.rs b/crates/servicepoint_binding_c/src/pixel_grid.rs index 185017c..585fda3 100644 --- a/crates/servicepoint_binding_c/src/pixel_grid.rs +++ b/crates/servicepoint_binding_c/src/pixel_grid.rs @@ -2,9 +2,21 @@ //! //! prefix `sp_pixel_grid_` -use servicepoint::{DataRef, Grid, PixelGrid}; +use servicepoint::{DataRef, Grid}; -use crate::c_slice::CByteSlice; +use crate::c_slice::SPByteSlice; + +/// A grid of pixels. +/// +/// # Examples +/// +/// ```C +/// Cp437Grid grid = sp_pixel_grid_new(8, 3); +/// sp_pixel_grid_fill(grid, true); +/// sp_pixel_grid_set(grid, 0, 0, false); +/// sp_pixel_grid_dealloc(grid); +/// ``` +pub struct SPPixelGrid(pub(crate) servicepoint::PixelGrid); /// Creates a new `PixelGrid` with the specified dimensions. /// @@ -29,8 +41,10 @@ use crate::c_slice::CByteSlice; pub unsafe extern "C" fn sp_pixel_grid_new( width: usize, height: usize, -) -> *mut PixelGrid { - Box::into_raw(Box::new(PixelGrid::new(width, height))) +) -> *mut SPPixelGrid { + Box::into_raw(Box::new(SPPixelGrid(servicepoint::PixelGrid::new( + width, height, + )))) } /// Loads a `PixelGrid` with the specified dimensions from the provided data. @@ -60,9 +74,11 @@ pub unsafe extern "C" fn sp_pixel_grid_load( height: usize, data: *const u8, data_length: usize, -) -> *mut PixelGrid { +) -> *mut SPPixelGrid { let data = std::slice::from_raw_parts(data, data_length); - Box::into_raw(Box::new(PixelGrid::load(width, height, data))) + Box::into_raw(Box::new(SPPixelGrid(servicepoint::PixelGrid::load( + width, height, data, + )))) } /// Clones a `PixelGrid`. @@ -77,9 +93,9 @@ pub unsafe extern "C" fn sp_pixel_grid_load( /// by explicitly calling `sp_pixel_grid_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_pixel_grid_clone( - this: *const PixelGrid, -) -> *mut PixelGrid { - Box::into_raw(Box::new((*this).clone())) + this: *const SPPixelGrid, +) -> *mut SPPixelGrid { + Box::into_raw(Box::new(SPPixelGrid((*this).0.clone()))) } /// Deallocates a `PixelGrid`. @@ -92,7 +108,7 @@ pub unsafe extern "C" fn sp_pixel_grid_clone( /// - `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) { +pub unsafe extern "C" fn sp_pixel_grid_dealloc(this: *mut SPPixelGrid) { _ = Box::from_raw(this); } @@ -115,11 +131,11 @@ pub unsafe extern "C" fn sp_pixel_grid_dealloc(this: *mut PixelGrid) { /// - `this` is not written to concurrently #[no_mangle] pub unsafe extern "C" fn sp_pixel_grid_get( - this: *const PixelGrid, + this: *const SPPixelGrid, x: usize, y: usize, ) -> bool { - (*this).get(x, y) + (*this).0.get(x, y) } /// Sets the value of the specified position in the `PixelGrid`. @@ -144,12 +160,12 @@ pub unsafe extern "C" fn sp_pixel_grid_get( /// - `this` is not written to or read from concurrently #[no_mangle] pub unsafe extern "C" fn sp_pixel_grid_set( - this: *mut PixelGrid, + this: *mut SPPixelGrid, x: usize, y: usize, value: bool, ) { - (*this).set(x, y, value); + (*this).0.set(x, y, value); } /// Sets the state of all pixels in the `PixelGrid`. @@ -166,8 +182,11 @@ pub unsafe extern "C" fn sp_pixel_grid_set( /// - `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); +pub unsafe extern "C" fn sp_pixel_grid_fill( + this: *mut SPPixelGrid, + value: bool, +) { + (*this).0.fill(value); } /// Gets the width in pixels of the `PixelGrid` instance. @@ -182,8 +201,10 @@ pub unsafe extern "C" fn sp_pixel_grid_fill(this: *mut PixelGrid, value: bool) { /// /// - `this` points to a valid `PixelGrid` #[no_mangle] -pub unsafe extern "C" fn sp_pixel_grid_width(this: *const PixelGrid) -> usize { - (*this).width() +pub unsafe extern "C" fn sp_pixel_grid_width( + this: *const SPPixelGrid, +) -> usize { + (*this).0.width() } /// Gets the height in pixels of the `PixelGrid` instance. @@ -198,8 +219,10 @@ pub unsafe extern "C" fn sp_pixel_grid_width(this: *const PixelGrid) -> usize { /// /// - `this` points to a valid `PixelGrid` #[no_mangle] -pub unsafe extern "C" fn sp_pixel_grid_height(this: *const PixelGrid) -> usize { - (*this).height() +pub unsafe extern "C" fn sp_pixel_grid_height( + this: *const SPPixelGrid, +) -> usize { + (*this).0.height() } /// Gets an unsafe reference to the data of the `PixelGrid` instance. @@ -213,10 +236,10 @@ pub unsafe extern "C" fn sp_pixel_grid_height(this: *const PixelGrid) -> usize { /// - 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, -) -> CByteSlice { - let data = (*this).data_ref_mut(); - CByteSlice { + this: *mut SPPixelGrid, +) -> SPByteSlice { + let data = (*this).0.data_ref_mut(); + SPByteSlice { start: data.as_mut_ptr_range().start, length: data.len(), } diff --git a/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs b/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs index 6545319..49c4d25 100644 --- a/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs +++ b/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs @@ -14,9 +14,9 @@ namespace ServicePoint.BindGen { const string __DllName = "servicepoint_binding_c"; - public const nuint TILE_SIZE = 8; - public const nuint TILE_WIDTH = 56; - public const nuint TILE_HEIGHT = 20; + public const nuint SP_TILE_SIZE = 8; + public const nuint SP_TILE_WIDTH = 56; + public const nuint SP_TILE_HEIGHT = 20; /// @@ -629,7 +629,7 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - the returned `Command` instance is freed in some way, either by using a consuming function or + /// - the returned `SPCommand` 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)] @@ -637,19 +637,19 @@ namespace ServicePoint.BindGen /// /// Allocates a new `Command::CharBrightness` instance. - /// The passed `ByteGrid` gets consumed. + /// The passed `SPBrightnessGrid` 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 + /// - `grid` points to a valid instance of `SPBrightnessGrid` + /// - `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, BrightnessGrid* byte_grid); + public static extern Command* sp_command_char_brightness(nuint x, nuint y, BrightnessGrid* grid); /// /// Allocates a new `Command::BitmapLinear` instance. @@ -1040,6 +1040,21 @@ namespace ServicePoint.BindGen [DllImport(__DllName, EntryPoint = "sp_packet_try_load", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern Packet* sp_packet_try_load(byte* data, nuint length); + /// + /// Clones a `Packet`. + /// + /// # Safety + /// + /// The caller has to make sure that: + /// + /// - `this` points to a valid `Packet` + /// - `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_packet_dealloc`. + /// + [DllImport(__DllName, EntryPoint = "sp_packet_clone", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] + public static extern Packet* sp_packet_clone(Packet* @this); + /// /// Deallocates a `Packet`. /// @@ -1076,13 +1091,6 @@ namespace ServicePoint.BindGen { } - [StructLayout(LayoutKind.Sequential)] - public unsafe partial struct ByteSlice - { - public byte* start; - public nuint length; - } - [StructLayout(LayoutKind.Sequential)] public unsafe partial struct Connection { @@ -1093,6 +1101,13 @@ namespace ServicePoint.BindGen { } + [StructLayout(LayoutKind.Sequential)] + public unsafe partial struct ByteSlice + { + public byte* start; + public nuint length; + } + [StructLayout(LayoutKind.Sequential)] public unsafe partial struct Packet { diff --git a/crates/servicepoint_binding_cs/build.rs b/crates/servicepoint_binding_cs/build.rs index 648324d..a74e7ff 100644 --- a/crates/servicepoint_binding_cs/build.rs +++ b/crates/servicepoint_binding_cs/build.rs @@ -13,23 +13,18 @@ fn main() { .input_extern_file("../servicepoint_binding_c/src/lib.rs") .input_extern_file("../servicepoint_binding_c/src/c_slice.rs") .input_extern_file("../servicepoint_binding_c/src/packet.rs") - .input_extern_file("../servicepoint/src/command.rs") - .input_extern_file("../servicepoint/src/connection.rs") - .input_extern_file("../servicepoint/src/pixel_grid.rs") - .input_extern_file("../servicepoint/src/lib.rs") - .input_extern_file("../servicepoint/src/packet.rs") - .input_extern_file("../servicepoint/src/compression_code.rs") + .input_extern_file("../servicepoint_binding_c/src/constants.rs") .csharp_dll_name("servicepoint_binding_c") .csharp_namespace("ServicePoint.BindGen") .csharp_use_nint_types(true) .csharp_class_accessibility("public") .csharp_generate_const_filter(|_| true) .csharp_type_rename(move |name| { - if name.len() > 1 - && name.starts_with("C") - && name.chars().nth(1).unwrap().is_uppercase() + if name.len() > 2 + && name.starts_with("SP") + && name.chars().nth(2).unwrap().is_uppercase() { - name[1..].to_string() + name[2..].to_string() } else { name } From 34ca374e1416f30a02e57de96474670093000129 Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Thu, 5 Sep 2024 22:03:06 +0200 Subject: [PATCH 11/31] put the whole rust toolchain into one package so Rider can handle it --- shell.nix | 34 +++++++++++++++++++++------------- 1 file changed, 21 insertions(+), 13 deletions(-) diff --git a/shell.nix b/shell.nix index 4b4eeca..6da3bc6 100644 --- a/shell.nix +++ b/shell.nix @@ -1,16 +1,24 @@ -{pkgs ? import {}}: -pkgs.mkShell { - nativeBuildInputs = with pkgs.buildPackages; [ - rustc cargo gcc rustfmt clippy +{pkgs ? import {}}: let + rust-toolchain = pkgs.symlinkJoin { + name = "rust-toolchain"; + paths = with pkgs; [rustc cargo rustPlatform.rustcSrc rustfmt clippy]; + }; +in + pkgs.mkShell { + nativeBuildInputs = with pkgs.buildPackages; [ + rust-toolchain - pkg-config - xe - lzma - cargo-tarpaulin - gnumake + pkg-config + xe + lzma - # dotnet-sdk_8 - ]; + cargo-tarpaulin - RUST_SRC_PATH = "${pkgs.rust.packages.stable.rustPlatform.rustLibSrc}"; -} + gcc + gnumake + + # dotnet-sdk_8 + ]; + + RUST_SRC_PATH = "${pkgs.rust.packages.stable.rustPlatform.rustLibSrc}"; + } From 16e06dd78ad1fb2073b44f8fb49d3875bc826a08 Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Fri, 6 Sep 2024 20:10:14 +0200 Subject: [PATCH 12/31] copy paste command docs --- crates/servicepoint_binding_c/src/command.rs | 69 ++++++++++++++++++-- 1 file changed, 63 insertions(+), 6 deletions(-) diff --git a/crates/servicepoint_binding_c/src/command.rs b/crates/servicepoint_binding_c/src/command.rs index ec8a033..7c26536 100644 --- a/crates/servicepoint_binding_c/src/command.rs +++ b/crates/servicepoint_binding_c/src/command.rs @@ -18,7 +18,7 @@ use crate::SPOffset; /// /// This struct and associated functions implement the UDP protocol for the display. /// -/// To send a `CCommand`, use a `CConnection`. +/// To send a `SPCommand`, use a `SPConnection`. /// /// # Examples /// @@ -34,18 +34,18 @@ impl Clone for SPCommand { } } -/// Tries to turn a `Packet` into a `Command`. The packet is deallocated in the process. +/// Tries to turn a `SPPacket` into a `SPCommand`. The packet is deallocated in the process. /// -/// Returns: pointer to new `Command` instance or NULL +/// Returns: pointer to new `SPCommand` instance or NULL /// /// # Safety /// /// The caller has to make sure that: /// -/// - `packet` points to a valid instance of `Packet` +/// - `packet` points to a valid instance of `SPPacket` /// - `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 +/// - the returned `SPCommand` 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( @@ -58,7 +58,7 @@ pub unsafe extern "C" fn sp_command_try_from_packet( } } -/// Clones a `Command` instance. +/// Clones a `SPCommand` instance. /// /// # Safety /// @@ -77,6 +77,14 @@ pub unsafe extern "C" fn sp_command_clone( /// Allocates a new `Command::Clear` instance. /// +/// Set all pixels to the off state. Does not affect brightness. +/// +/// # Examples +/// +/// ```C +/// sp_connection_send(connection, sp_command_clear()); +/// ``` +/// /// # Safety /// /// The caller has to make sure that: @@ -90,6 +98,9 @@ pub unsafe extern "C" fn sp_command_clear() -> *mut SPCommand { /// Allocates a new `Command::HardReset` instance. /// +/// Kills the udp daemon on the display, which usually results in a restart. +/// Please do not send this in your normal program flow. +/// /// # Safety /// /// The caller has to make sure that: @@ -141,6 +152,8 @@ pub unsafe extern "C" fn sp_command_brightness( /// Allocates a new `Command::CharBrightness` instance. /// The passed `SPBrightnessGrid` gets consumed. /// +/// Set the brightness of individual tiles in a rectangular area of the display. +/// /// # Safety /// /// The caller has to make sure that: @@ -165,6 +178,13 @@ pub unsafe extern "C" fn sp_command_char_brightness( /// Allocates a new `Command::BitmapLinear` instance. /// The passed `BitVec` gets consumed. /// +/// Set pixel data starting at the pixel offset on screen. +/// +/// The screen will continuously overwrite more pixel data without regarding the offset, meaning +/// once the starting row is full, overwriting will continue on column 0. +/// +/// The contained `BitVec` is always uncompressed. +/// /// # Safety /// /// The caller has to make sure that: @@ -191,6 +211,13 @@ pub unsafe extern "C" fn sp_command_bitmap_linear( /// Allocates a new `Command::BitmapLinearAnd` instance. /// The passed `BitVec` gets consumed. /// +/// Set pixel data according to an and-mask starting at the offset. +/// +/// The screen will continuously overwrite more pixel data without regarding the offset, meaning +/// once the starting row is full, overwriting will continue on column 0. +/// +/// The contained `BitVec` is always uncompressed. +/// /// # Safety /// /// The caller has to make sure that: @@ -217,6 +244,13 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_and( /// Allocates a new `Command::BitmapLinearOr` instance. /// The passed `BitVec` gets consumed. /// +/// Set pixel data according to an or-mask starting at the offset. +/// +/// The screen will continuously overwrite more pixel data without regarding the offset, meaning +/// once the starting row is full, overwriting will continue on column 0. +/// +/// The contained `BitVec` is always uncompressed. +/// /// # Safety /// /// The caller has to make sure that: @@ -243,6 +277,13 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_or( /// Allocates a new `Command::BitmapLinearXor` instance. /// The passed `BitVec` gets consumed. /// +/// Set pixel data according to a xor-mask starting at the offset. +/// +/// The screen will continuously overwrite more pixel data without regarding the offset, meaning +/// once the starting row is full, overwriting will continue on column 0. +/// +/// The contained `BitVec` is always uncompressed. +/// /// # Safety /// /// The caller has to make sure that: @@ -269,6 +310,13 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_xor( /// Allocates a new `Command::Cp437Data` instance. /// The passed `ByteGrid` gets consumed. /// +/// Show text on the screen. +/// +///
+/// The library does not currently convert between UTF-8 and CP-437. +/// Because Rust expects UTF-8 strings, it might be necessary to only send ASCII for now. +///
+/// /// # Safety /// /// The caller has to make sure that: @@ -293,6 +341,8 @@ pub unsafe extern "C" fn sp_command_cp437_data( /// Allocates a new `Command::BitmapLinearWin` instance. /// The passed `PixelGrid` gets consumed. /// +/// Sets a window of pixels to the specified values +/// /// # Safety /// /// The caller has to make sure that: @@ -321,6 +371,13 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_win( /// Deallocates a `Command`. /// +/// # Examples +/// +/// ```C +/// SPCommand c = sp_command_clear(); +/// sp_command_dealloc(c); +/// ``` +/// /// # Safety /// /// The caller has to make sure that: From e54891e6621c8d2d889bba37229daa4dee0b513e Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Sat, 7 Sep 2024 10:35:31 +0200 Subject: [PATCH 13/31] envrc is environment, rename to default file --- .envrc => .envrc.default | 0 .gitignore | 1 + 2 files changed, 1 insertion(+) rename .envrc => .envrc.default (100%) diff --git a/.envrc b/.envrc.default similarity index 100% rename from .envrc rename to .envrc.default diff --git a/.gitignore b/.gitignore index 39156e2..b5806a2 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,4 @@ out bin obj .direnv +.envrc From e97418b51b4dcba5f8e8234681bf5b78c4d1414c Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Sat, 7 Sep 2024 11:44:42 +0200 Subject: [PATCH 14/31] named fields instead of tuple for Packet, doc adjustments --- crates/servicepoint/src/command.rs | 277 ++++++++++++++---- crates/servicepoint/src/connection.rs | 2 +- crates/servicepoint/src/packet.rs | 249 ++++++++++++---- .../examples/lang_c/include/servicepoint.h | 69 ++++- .../ServicePoint/BindGen/ServicePoint.g.cs | 67 ++++- 5 files changed, 529 insertions(+), 135 deletions(-) diff --git a/crates/servicepoint/src/command.rs b/crates/servicepoint/src/command.rs index 930b5b2..3a5ab1c 100644 --- a/crates/servicepoint/src/command.rs +++ b/crates/servicepoint/src/command.rs @@ -190,10 +190,17 @@ impl TryFrom for Command { /// Try to interpret the `Packet` as one containing a `Command` fn try_from(packet: Packet) -> Result { - let Packet(Header(command_u16, a, _, _, _), _) = packet; - let command_code = match CommandCode::try_from(command_u16) { + let Packet { + header: Header { + command_code, + a, + .. + }, + .. + } = packet; + let command_code = match CommandCode::try_from(command_code) { Err(()) => { - return Err(TryFromPacketError::InvalidCommand(command_u16)); + return Err(TryFromPacketError::InvalidCommand(command_code)); } Ok(value) => value, }; @@ -266,8 +273,16 @@ impl Command { packet: Packet, compression: CompressionCode, ) -> Result { - let Packet(Header(_, tiles_x, pixels_y, tile_w, pixel_h), payload) = - packet; + let Packet { + header: Header { + command_code: _, + a: tiles_x, + b: pixels_y, + c: tile_w, + d: pixel_h, + }, + payload, + } = packet; let payload = match into_decompressed(compression, payload) { None => return Err(TryFromPacketError::DecompressionFailed), @@ -290,7 +305,16 @@ impl Command { packet: Packet, command: Command, ) -> Result { - let Packet(Header(_, a, b, c, d), payload) = packet; + let Packet { + header: Header { + command_code: _, + a, + b, + c, + d, + }, + payload, + } = packet; if !payload.is_empty() { Err(TryFromPacketError::UnexpectedPayloadSize(0, payload.len())) } else if a != 0 || b != 0 || c != 0 || d != 0 { @@ -304,7 +328,15 @@ impl Command { fn packet_into_linear_bitmap( packet: Packet, ) -> Result<(SpBitVec, CompressionCode), TryFromPacketError> { - let Packet(Header(_, _, length, sub, reserved), payload) = packet; + let Packet { + header: Header { + b: length, + c: sub, + d: reserved, + .. + }, + payload, + } = packet; if reserved != 0 { return Err(TryFromPacketError::ExtraneousHeaderValues); } @@ -330,7 +362,16 @@ impl Command { fn packet_into_char_brightness( packet: &Packet, ) -> Result { - let Packet(Header(_, x, y, width, height), payload) = packet; + let Packet { + header: Header { + command_code: _, + a: x, + b: y, + c: width, + d: height, + }, + payload, + } = packet; let grid = PrimitiveGrid::load(*width as usize, *height as usize, payload); @@ -348,7 +389,16 @@ impl Command { fn packet_into_brightness( packet: &Packet, ) -> Result { - let Packet(Header(_, a, b, c, d), payload) = packet; + let Packet { + header: Header { + command_code: _, + a, + b, + c, + d, + }, + payload, + } = packet; if payload.len() != 1 { return Err(TryFromPacketError::UnexpectedPayloadSize( 1, @@ -369,7 +419,16 @@ impl Command { fn packet_into_cp437( packet: &Packet, ) -> Result { - let Packet(Header(_, a, b, c, d), payload) = packet; + let Packet { + header: Header { + command_code: _, + a, + b, + c, + d, + }, + payload, + } = packet; Ok(Command::Cp437Data( Origin::new(*a as usize, *b as usize), Cp437Grid::load(*c as usize, *d as usize, payload), @@ -483,7 +542,16 @@ mod tests { #[test] fn error_invalid_command() { - let p = Packet(Header(0xFF, 0x00, 0x00, 0x00, 0x00), vec![]); + let p = Packet { + header: Header { + command_code: 0xFF, + a: 0x00, + b: 0x00, + c: 0x00, + d: 0x00, + }, + payload: vec![], + }; let result = Command::try_from(p); assert!(matches!( result, @@ -493,10 +561,16 @@ mod tests { #[test] fn error_extraneous_header_values_clear() { - let p = Packet( - Header(CommandCode::Clear.into(), 0x05, 0x00, 0x00, 0x00), - vec![], - ); + let p = Packet { + header: Header { + command_code: CommandCode::Clear.into(), + a: 0x05, + b: 0x00, + c: 0x00, + d: 0x00, + }, + payload: vec![], + }; let result = Command::try_from(p); assert!(matches!( result, @@ -506,10 +580,16 @@ mod tests { #[test] fn error_extraneous_header_values_brightness() { - let p = Packet( - Header(CommandCode::Brightness.into(), 0x00, 0x13, 0x37, 0x00), - vec![5], - ); + let p = Packet { + header: Header { + command_code: CommandCode::Brightness.into(), + a: 0x00, + b: 0x13, + c: 0x37, + d: 0x00, + }, + payload: vec![5], + }; let result = Command::try_from(p); assert!(matches!( result, @@ -519,10 +599,16 @@ mod tests { #[test] fn error_extraneous_header_hard_reset() { - let p = Packet( - Header(CommandCode::HardReset.into(), 0x00, 0x00, 0x00, 0x01), - vec![], - ); + let p = Packet { + header: Header { + command_code: CommandCode::HardReset.into(), + a: 0x00, + b: 0x00, + c: 0x00, + d: 0x01, + }, + payload: vec![], + }; let result = Command::try_from(p); assert!(matches!( result, @@ -532,10 +618,16 @@ mod tests { #[test] fn error_extraneous_header_fade_out() { - let p = Packet( - Header(CommandCode::FadeOut.into(), 0x10, 0x00, 0x00, 0x01), - vec![], - ); + let p = Packet { + header: Header { + command_code: CommandCode::FadeOut.into(), + a: 0x10, + b: 0x00, + c: 0x00, + d: 0x01, + }, + payload: vec![], + }; let result = Command::try_from(p); assert!(matches!( result, @@ -545,10 +637,16 @@ mod tests { #[test] fn error_unexpected_payload() { - let p = Packet( - Header(CommandCode::FadeOut.into(), 0x00, 0x00, 0x00, 0x00), - vec![5, 7], - ); + let p = Packet { + header: Header { + command_code: CommandCode::FadeOut.into(), + a: 0x00, + b: 0x00, + c: 0x00, + d: 0x00, + }, + payload: vec![5, 7], + }; let result = Command::try_from(p); assert!(matches!( result, @@ -564,15 +662,19 @@ mod tests { PixelGrid::new(8, 8), compression, ) - .into(); - let Packet(header, mut payload) = p; + .into(); + + let Packet { + header, + mut payload, + } = p; // mangle it for byte in payload.iter_mut() { *byte -= *byte / 2; } - let p = Packet(header, payload); + let p = Packet { header, payload }; let result = Command::try_from(p); if compression != CompressionCode::Uncompressed { assert_eq!(result, Err(TryFromPacketError::DecompressionFailed)) @@ -590,15 +692,18 @@ mod tests { BitVec::repeat(false, 8), compression, ) - .into(); - let Packet(header, mut payload) = p; + .into(); + let Packet { + header, + mut payload, + } = p; // mangle it for byte in payload.iter_mut() { *byte -= *byte / 2; } - let p = Packet(header, payload); + let p = Packet { header, payload }; let result = Command::try_from(p); if compression != CompressionCode::Uncompressed { assert_eq!(result, Err(TryFromPacketError::DecompressionFailed)) @@ -612,32 +717,59 @@ mod tests { #[test] fn unexpected_payload_size_brightness() { assert_eq!( - Command::try_from(Packet( - Header(CommandCode::Brightness.into(), 0, 0, 0, 0), - vec!(), - )), + Command::try_from(Packet { + header: Header { + command_code: CommandCode::Brightness.into(), + a: 0, + b: 0, + c: 0, + d: 0, + }, + payload: vec!() + }), Err(TryFromPacketError::UnexpectedPayloadSize(1, 0)) ); assert_eq!( - Command::try_from(Packet( - Header(CommandCode::Brightness.into(), 0, 0, 0, 0), - vec!(0, 0), - )), + Command::try_from(Packet { + header: Header { + command_code: CommandCode::Brightness.into(), + a: 0, + b: 0, + c: 0, + d: 0, + }, + payload: vec!(0, 0) + }), Err(TryFromPacketError::UnexpectedPayloadSize(1, 2)) ); } #[test] fn error_reserved_used() { - let Packet(header, payload) = Command::BitmapLinear( + let Packet { header, payload } = Command::BitmapLinear( 0, BitVec::repeat(false, 8), CompressionCode::Uncompressed, ) - .into(); - let Header(command, offset, length, sub, _reserved) = header; - let p = Packet(Header(command, offset, length, sub, 69), payload); + .into(); + let Header { + command_code: command, + a: offset, + b: length, + c: sub, + d: _reserved, + } = header; + let p = Packet { + header: Header { + command_code: command, + a: offset, + b: length, + c: sub, + d: 69, + }, + payload, + }; assert_eq!( Command::try_from(p), Err(TryFromPacketError::ExtraneousHeaderValues) @@ -646,14 +778,29 @@ mod tests { #[test] fn error_invalid_compression() { - let Packet(header, payload) = Command::BitmapLinear( + let Packet { header, payload } = Command::BitmapLinear( 0, BitVec::repeat(false, 8), CompressionCode::Uncompressed, ) - .into(); - let Header(command, offset, length, _sub, reserved) = header; - let p = Packet(Header(command, offset, length, 42, reserved), payload); + .into(); + let Header { + command_code: command, + a: offset, + b: length, + c: _sub, + d: reserved, + } = header; + let p = Packet { + header: Header { + command_code: command, + a: offset, + b: length, + c: 42, + d: reserved, + }, + payload, + }; assert_eq!( Command::try_from(p), Err(TryFromPacketError::InvalidCompressionCode(42)) @@ -662,17 +809,29 @@ mod tests { #[test] fn error_unexpected_size() { - let Packet(header, payload) = Command::BitmapLinear( + let Packet { header, payload } = Command::BitmapLinear( 0, BitVec::repeat(false, 8), CompressionCode::Uncompressed, ) - .into(); - let Header(command, offset, length, compression, reserved) = header; - let p = Packet( - Header(command, offset, 420, compression, reserved), + .into(); + let Header { + command_code: command, + a: offset, + b: length, + c: compression, + d: reserved, + } = header; + let p = Packet { + header: Header { + command_code: command, + a: offset, + b: 420, + c: compression, + d: reserved, + }, payload, - ); + }; assert_eq!( Command::try_from(p), Err(TryFromPacketError::UnexpectedPayloadSize( diff --git a/crates/servicepoint/src/connection.rs b/crates/servicepoint/src/connection.rs index 9237006..032ffeb 100644 --- a/crates/servicepoint/src/connection.rs +++ b/crates/servicepoint/src/connection.rs @@ -71,7 +71,7 @@ impl Connection { Connection::Udp(socket) => { socket .send(&data) - .map_err(move |io_err| SendError::IoError(io_err)) + .map_err(SendError::IoError) .map(move |_| ()) // ignore Ok value } Connection::Fake => Ok(()), diff --git a/crates/servicepoint/src/packet.rs b/crates/servicepoint/src/packet.rs index 3718e34..67c96b4 100644 --- a/crates/servicepoint/src/packet.rs +++ b/crates/servicepoint/src/packet.rs @@ -3,25 +3,84 @@ use std::mem::size_of; use crate::command_code::CommandCode; use crate::compression::into_compressed; use crate::{ - Command, CompressionCode, Grid, Offset, Origin, PixelGrid, Pixels, + Command, CompressionCode, Grid, Offset, Origin, PixelGrid, Pixels, Tiles, TILE_SIZE, }; -/// A raw header. Should probably not be used directly. +/// A raw header. +/// +/// The header specifies the kind of command, the size of the payload and where to display the +/// payload, where applicable. +/// +/// Because the meaning of most fields depend on the command, there are no speaking names for them. +/// +/// Should probably only be used directly to use features not exposed by the library. #[derive(Copy, Clone, Debug, PartialEq)] -pub struct Header(pub u16, pub u16, pub u16, pub u16, pub u16); +pub struct Header { + /// The first two bytes specify which command this packet represents. + pub command_code: u16, + /// First command-specific value + pub a: u16, + /// Second command-specific value + pub b: u16, + /// Third command-specific value + pub c: u16, + /// Fourth command-specific value + pub d: u16, +} -/// The raw payload. Should probably not be used directly. +/// The raw payload. +/// +/// Should probably only be used directly to use features not exposed by the library. pub type Payload = Vec; -/// The raw packet. Should probably not be used directly. +/// The raw packet. +/// +/// Contents should probably only be used directly to use features not exposed by the library. +/// +/// # Examples +/// +/// Converting a packet to a command and back: +/// +/// ```rust +/// # use servicepoint::{Command, Packet}; +/// # let command = Command::Clear; +/// let packet: Packet = command.into(); +/// let command: Command = Command::try_from(packet).expect("could not read packet"); +/// ``` +/// +/// Converting a packet to bytes and back: +/// +/// ```rust +/// # use servicepoint::{Command, Packet}; +/// # let command = Command::Clear; +/// # let packet: Packet = command.into(); +/// let bytes: Vec = packet.into(); +/// let packet = Packet::try_from(bytes).expect("could not read packet from bytes"); +/// ``` +/// #[derive(Clone, Debug, PartialEq)] -pub struct Packet(pub Header, pub Payload); +pub struct Packet { + /// Meta-information for the packed command + pub header: Header, + /// The data for the packed command + pub payload: Payload, +} impl From for Vec { /// Turn the packet into raw bytes ready to send fn from(value: Packet) -> Self { - let Packet(Header(mode, a, b, c, d), payload) = value; + let Packet { + header: + Header { + command_code: mode, + a, + b, + c, + d, + }, + payload, + } = value; let mut packet = vec![0u8; 10 + payload.len()]; packet[0..=1].copy_from_slice(&u16::to_be_bytes(mode)); @@ -36,13 +95,6 @@ impl From for Vec { } } -fn u16_from_be_slice(slice: &[u8]) -> u16 { - let mut bytes = [0u8; 2]; - bytes[0] = slice[0]; - bytes[1] = slice[1]; - u16::from_be_bytes(bytes) -} - impl TryFrom<&[u8]> for Packet { type Error = (); @@ -54,14 +106,31 @@ impl TryFrom<&[u8]> for Packet { return Err(()); } - let mode = u16_from_be_slice(&value[0..=1]); - let a = u16_from_be_slice(&value[2..=3]); - let b = u16_from_be_slice(&value[4..=5]); - let c = u16_from_be_slice(&value[6..=7]); - let d = u16_from_be_slice(&value[8..=9]); + let header = { + let command_code = Self::u16_from_be_slice(&value[0..=1]); + let a = Self::u16_from_be_slice(&value[2..=3]); + let b = Self::u16_from_be_slice(&value[4..=5]); + let c = Self::u16_from_be_slice(&value[6..=7]); + let d = Self::u16_from_be_slice(&value[8..=9]); + Header { + command_code, + a, + b, + c, + d, + } + }; let payload = value[10..].to_vec(); - Ok(Packet(Header(mode, a, b, c, d), payload)) + Ok(Packet { header, payload }) + } +} + +impl TryFrom> for Packet { + type Error = (); + + fn try_from(value: Vec) -> Result { + Self::try_from(value.as_slice()) } } @@ -79,26 +148,23 @@ impl From for Packet { Command::BitmapLegacy => { Self::command_code_only(CommandCode::BitmapLegacy) } - Command::CharBrightness(origin, grid) => Packet( - Header( - CommandCode::CharBrightness.into(), - origin.x as u16, - origin.y as u16, - grid.width() as u16, - grid.height() as u16, - ), - grid.into(), - ), - Command::Brightness(brightness) => Packet( - Header( - CommandCode::Brightness.into(), - 0x00000, - 0x0000, - 0x0000, - 0x0000, - ), - vec![brightness.into()], - ), + Command::CharBrightness(origin, grid) => { + Self::origin_grid_to_packet( + origin, + grid, + CommandCode::CharBrightness, + ) + } + Command::Brightness(brightness) => Packet { + header: Header { + command_code: CommandCode::Brightness.into(), + a: 0x00000, + b: 0x0000, + c: 0x0000, + d: 0x0000, + }, + payload: vec![brightness.into()], + }, Command::BitmapLinearWin(origin, pixels, compression) => { Self::bitmap_win_into_packet(origin, pixels, compression) } @@ -134,15 +200,10 @@ impl From for Packet { bits.into(), ) } - Command::Cp437Data(origin, grid) => Packet( - Header( - CommandCode::Cp437Data.into(), - origin.x as u16, - origin.y as u16, - grid.width() as u16, - grid.height() as u16, - ), - grid.into(), + Command::Cp437Data(origin, grid) => Self::origin_grid_to_packet( + origin, + grid, + CommandCode::Cp437Data, ), } } @@ -159,16 +220,16 @@ impl Packet { ) -> Packet { let length = payload.len() as u16; let payload = into_compressed(compression, payload); - Packet( - Header( - command.into(), - offset as u16, - length, - compression.into(), - 0, - ), + Packet { + header: Header { + command_code: command.into(), + a: offset as u16, + b: length, + c: compression.into(), + d: 0, + }, payload, - ) + } } #[allow(clippy::cast_possible_truncation)] @@ -198,15 +259,54 @@ impl Packet { CompressionCode::Zstd => CommandCode::BitmapLinearWinZstd, }; - Packet( - Header(command.into(), tile_x, origin.y as u16, tile_w, pixel_h), + Packet { + header: Header { + command_code: command.into(), + a: tile_x, + b: origin.y as u16, + c: tile_w, + d: pixel_h, + }, payload, - ) + } } /// Helper method for creating empty packets only containing the command code fn command_code_only(code: CommandCode) -> Packet { - Packet(Header(code.into(), 0x0000, 0x0000, 0x0000, 0x0000), vec![]) + Packet { + header: Header { + command_code: code.into(), + a: 0x0000, + b: 0x0000, + c: 0x0000, + d: 0x0000, + }, + payload: vec![], + } + } + + fn u16_from_be_slice(slice: &[u8]) -> u16 { + let mut bytes = [0u8; 2]; + bytes[0] = slice[0]; + bytes[1] = slice[1]; + u16::from_be_bytes(bytes) + } + + fn origin_grid_to_packet( + origin: Origin, + grid: impl Grid + Into, + command_code: CommandCode, + ) -> Packet { + Packet { + header: Header { + command_code: command_code.into(), + a: origin.x as u16, + b: origin.y as u16, + c: grid.width() as u16, + d: grid.height() as u16, + }, + payload: grid.into(), + } } } @@ -216,10 +316,31 @@ mod tests { #[test] fn round_trip() { - let p = Packet(Header(0, 1, 2, 3, 4), vec![42u8; 23]); + let p = Packet { + header: Header { + command_code: 0, + a: 1, + b: 2, + c: 3, + d: 4, + }, + payload: vec![42u8; 23], + }; let data: Vec = p.into(); let p = Packet::try_from(&*data).unwrap(); - assert_eq!(p, Packet(Header(0, 1, 2, 3, 4), vec![42u8; 23])); + assert_eq!( + p, + Packet { + header: Header { + command_code: 0, + a: 1, + b: 2, + c: 3, + d: 4 + }, + payload: vec![42u8; 23] + } + ); } #[test] 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 960353e..0a6069f 100644 --- a/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h +++ b/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h @@ -105,7 +105,7 @@ typedef struct SPBrightnessGrid SPBrightnessGrid; * * This struct and associated functions implement the UDP protocol for the display. * - * To send a `CCommand`, use a `CConnection`. + * To send a `SPCommand`, use a `SPConnection`. * * # Examples * @@ -539,6 +539,13 @@ size_t sp_brightness_grid_width(const struct SPBrightnessGrid *this_); * Allocates a new `Command::BitmapLinear` instance. * The passed `BitVec` gets consumed. * + * Set pixel data starting at the pixel offset on screen. + * + * The screen will continuously overwrite more pixel data without regarding the offset, meaning + * once the starting row is full, overwriting will continue on column 0. + * + * The contained `BitVec` is always uncompressed. + * * # Safety * * The caller has to make sure that: @@ -557,6 +564,13 @@ struct SPCommand *sp_command_bitmap_linear(SPOffset offset, * Allocates a new `Command::BitmapLinearAnd` instance. * The passed `BitVec` gets consumed. * + * Set pixel data according to an and-mask starting at the offset. + * + * The screen will continuously overwrite more pixel data without regarding the offset, meaning + * once the starting row is full, overwriting will continue on column 0. + * + * The contained `BitVec` is always uncompressed. + * * # Safety * * The caller has to make sure that: @@ -575,6 +589,13 @@ struct SPCommand *sp_command_bitmap_linear_and(SPOffset offset, * Allocates a new `Command::BitmapLinearOr` instance. * The passed `BitVec` gets consumed. * + * Set pixel data according to an or-mask starting at the offset. + * + * The screen will continuously overwrite more pixel data without regarding the offset, meaning + * once the starting row is full, overwriting will continue on column 0. + * + * The contained `BitVec` is always uncompressed. + * * # Safety * * The caller has to make sure that: @@ -593,6 +614,8 @@ struct SPCommand *sp_command_bitmap_linear_or(SPOffset offset, * Allocates a new `Command::BitmapLinearWin` instance. * The passed `PixelGrid` gets consumed. * + * Sets a window of pixels to the specified values + * * # Safety * * The caller has to make sure that: @@ -612,6 +635,13 @@ struct SPCommand *sp_command_bitmap_linear_win(size_t x, * Allocates a new `Command::BitmapLinearXor` instance. * The passed `BitVec` gets consumed. * + * Set pixel data according to a xor-mask starting at the offset. + * + * The screen will continuously overwrite more pixel data without regarding the offset, meaning + * once the starting row is full, overwriting will continue on column 0. + * + * The contained `BitVec` is always uncompressed. + * * # Safety * * The caller has to make sure that: @@ -647,6 +677,8 @@ struct SPCommand *sp_command_brightness(uint8_t brightness); * Allocates a new `Command::CharBrightness` instance. * The passed `SPBrightnessGrid` gets consumed. * + * Set the brightness of individual tiles in a rectangular area of the display. + * * # Safety * * The caller has to make sure that: @@ -663,6 +695,14 @@ struct SPCommand *sp_command_char_brightness(size_t x, /** * Allocates a new `Command::Clear` instance. * + * Set all pixels to the off state. Does not affect brightness. + * + * # Examples + * + * ```C + * sp_connection_send(connection, sp_command_clear()); + * ``` + * * # Safety * * The caller has to make sure that: @@ -673,7 +713,7 @@ struct SPCommand *sp_command_char_brightness(size_t x, struct SPCommand *sp_command_clear(void); /** - * Clones a `Command` instance. + * Clones a `SPCommand` instance. * * # Safety * @@ -690,6 +730,13 @@ struct SPCommand *sp_command_clone(const struct SPCommand *original); * Allocates a new `Command::Cp437Data` instance. * The passed `ByteGrid` gets consumed. * + * Show text on the screen. + * + *
+ * The library does not currently convert between UTF-8 and CP-437. + * Because Rust expects UTF-8 strings, it might be necessary to only send ASCII for now. + *
+ * * # Safety * * The caller has to make sure that: @@ -706,6 +753,13 @@ struct SPCommand *sp_command_cp437_data(size_t x, /** * Deallocates a `Command`. * + * # Examples + * + * ```C + * SPCommand c = sp_command_clear(); + * sp_command_dealloc(c); + * ``` + * * # Safety * * The caller has to make sure that: @@ -731,6 +785,9 @@ struct SPCommand *sp_command_fade_out(void); /** * Allocates a new `Command::HardReset` instance. * + * Kills the udp daemon on the display, which usually results in a restart. + * Please do not send this in your normal program flow. + * * # Safety * * The caller has to make sure that: @@ -741,18 +798,18 @@ struct SPCommand *sp_command_fade_out(void); struct SPCommand *sp_command_hard_reset(void); /** - * Tries to turn a `Packet` into a `Command`. The packet is deallocated in the process. + * Tries to turn a `SPPacket` into a `SPCommand`. The packet is deallocated in the process. * - * Returns: pointer to new `Command` instance or NULL + * Returns: pointer to new `SPCommand` instance or NULL * * # Safety * * The caller has to make sure that: * - * - `packet` points to a valid instance of `Packet` + * - `packet` points to a valid instance of `SPPacket` * - `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 + * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_dealloc`. */ struct SPCommand *sp_command_try_from_packet(struct SPPacket *packet); diff --git a/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs b/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs index 49c4d25..cd73a1a 100644 --- a/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs +++ b/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs @@ -546,25 +546,25 @@ namespace ServicePoint.BindGen public static extern ByteSlice sp_cp437_grid_unsafe_data_ref(Cp437Grid* @this); /// - /// Tries to turn a `Packet` into a `Command`. The packet is deallocated in the process. + /// Tries to turn a `SPPacket` into a `SPCommand`. The packet is deallocated in the process. /// - /// Returns: pointer to new `Command` instance or NULL + /// Returns: pointer to new `SPCommand` instance or NULL /// /// # Safety /// /// The caller has to make sure that: /// - /// - `packet` points to a valid instance of `Packet` + /// - `packet` points to a valid instance of `SPPacket` /// - `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 + /// - the returned `SPCommand` 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 `SPCommand` instance. /// /// # Safety /// @@ -581,6 +581,14 @@ namespace ServicePoint.BindGen /// /// Allocates a new `Command::Clear` instance. /// + /// Set all pixels to the off state. Does not affect brightness. + /// + /// # Examples + /// + /// ```C + /// sp_connection_send(connection, sp_command_clear()); + /// ``` + /// /// # Safety /// /// The caller has to make sure that: @@ -594,6 +602,9 @@ namespace ServicePoint.BindGen /// /// Allocates a new `Command::HardReset` instance. /// + /// Kills the udp daemon on the display, which usually results in a restart. + /// Please do not send this in your normal program flow. + /// /// # Safety /// /// The caller has to make sure that: @@ -639,6 +650,8 @@ namespace ServicePoint.BindGen /// Allocates a new `Command::CharBrightness` instance. /// The passed `SPBrightnessGrid` gets consumed. /// + /// Set the brightness of individual tiles in a rectangular area of the display. + /// /// # Safety /// /// The caller has to make sure that: @@ -655,6 +668,13 @@ namespace ServicePoint.BindGen /// Allocates a new `Command::BitmapLinear` instance. /// The passed `BitVec` gets consumed. /// + /// Set pixel data starting at the pixel offset on screen. + /// + /// The screen will continuously overwrite more pixel data without regarding the offset, meaning + /// once the starting row is full, overwriting will continue on column 0. + /// + /// The contained `BitVec` is always uncompressed. + /// /// # Safety /// /// The caller has to make sure that: @@ -672,6 +692,13 @@ namespace ServicePoint.BindGen /// Allocates a new `Command::BitmapLinearAnd` instance. /// The passed `BitVec` gets consumed. /// + /// Set pixel data according to an and-mask starting at the offset. + /// + /// The screen will continuously overwrite more pixel data without regarding the offset, meaning + /// once the starting row is full, overwriting will continue on column 0. + /// + /// The contained `BitVec` is always uncompressed. + /// /// # Safety /// /// The caller has to make sure that: @@ -689,6 +716,13 @@ namespace ServicePoint.BindGen /// Allocates a new `Command::BitmapLinearOr` instance. /// The passed `BitVec` gets consumed. /// + /// Set pixel data according to an or-mask starting at the offset. + /// + /// The screen will continuously overwrite more pixel data without regarding the offset, meaning + /// once the starting row is full, overwriting will continue on column 0. + /// + /// The contained `BitVec` is always uncompressed. + /// /// # Safety /// /// The caller has to make sure that: @@ -706,6 +740,13 @@ namespace ServicePoint.BindGen /// Allocates a new `Command::BitmapLinearXor` instance. /// The passed `BitVec` gets consumed. /// + /// Set pixel data according to a xor-mask starting at the offset. + /// + /// The screen will continuously overwrite more pixel data without regarding the offset, meaning + /// once the starting row is full, overwriting will continue on column 0. + /// + /// The contained `BitVec` is always uncompressed. + /// /// # Safety /// /// The caller has to make sure that: @@ -723,6 +764,13 @@ namespace ServicePoint.BindGen /// Allocates a new `Command::Cp437Data` instance. /// The passed `ByteGrid` gets consumed. /// + /// Show text on the screen. + /// + /// <div class="warning"> + /// The library does not currently convert between UTF-8 and CP-437. + /// Because Rust expects UTF-8 strings, it might be necessary to only send ASCII for now. + /// </div> + /// /// # Safety /// /// The caller has to make sure that: @@ -739,6 +787,8 @@ namespace ServicePoint.BindGen /// Allocates a new `Command::BitmapLinearWin` instance. /// The passed `PixelGrid` gets consumed. /// + /// Sets a window of pixels to the specified values + /// /// # Safety /// /// The caller has to make sure that: @@ -755,6 +805,13 @@ namespace ServicePoint.BindGen /// /// Deallocates a `Command`. /// + /// # Examples + /// + /// ```C + /// SPCommand c = sp_command_clear(); + /// sp_command_dealloc(c); + /// ``` + /// /// # Safety /// /// The caller has to make sure that: From eddeb2ea2d43f33193f7cad2834dff75c5d3bc98 Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Sat, 7 Sep 2024 12:23:32 +0200 Subject: [PATCH 15/31] re-export everything from top-level for nicer docs --- crates/servicepoint_binding_c/README.md | 14 ++--- .../examples/lang_c/include/servicepoint.h | 17 +++--- crates/servicepoint_binding_c/src/bit_vec.rs | 2 +- .../src/brightness_grid.rs | 2 +- .../src/{c_slice.rs => byte_slice.rs} | 4 ++ crates/servicepoint_binding_c/src/command.rs | 19 +++--- .../servicepoint_binding_c/src/connection.rs | 2 +- .../servicepoint_binding_c/src/cp437_grid.rs | 10 ++-- crates/servicepoint_binding_c/src/lib.rs | 59 ++++++++++++++----- crates/servicepoint_binding_c/src/packet.rs | 2 +- .../servicepoint_binding_c/src/pixel_grid.rs | 2 +- crates/servicepoint_binding_cs/build.rs | 2 +- 12 files changed, 83 insertions(+), 52 deletions(-) rename crates/servicepoint_binding_c/src/{c_slice.rs => byte_slice.rs} (69%) diff --git a/crates/servicepoint_binding_c/README.md b/crates/servicepoint_binding_c/README.md index eacd65d..836af2e 100644 --- a/crates/servicepoint_binding_c/README.md +++ b/crates/servicepoint_binding_c/README.md @@ -17,18 +17,18 @@ This crate contains C bindings for the `servicepoint` library, enabling users to #include "servicepoint.h" int main(void) { - sp_Connection *connection = sp_connection_open("localhost:2342"); + SPConnection *connection = sp_connection_open("172.23.42.29:2342"); if (connection == NULL) return 1; - sp_PixelGrid *pixels = sp_pixel_grid_new(sp_PIXEL_WIDTH, sp_PIXEL_HEIGHT); + SPPixelGrid *pixels = sp_pixel_grid_new(SP_PIXEL_WIDTH, SP_PIXEL_HEIGHT); sp_pixel_grid_fill(pixels, true); - sp_Command *command = sp_command_bitmap_linear_win(0, 0, pixels, Uncompressed); - sp_Packet *packet = sp_packet_from_command(command); - if (!sp_connection_send(connection, packet)) - return 1; + SPCommand *command = sp_command_bitmap_linear_win(0, 0, pixels, Uncompressed); + SPPacket *packet = sp_packet_from_command(command); + while (sp_connection_send(connection, sp_packet_clone(packet))); + sp_packet_dealloc(packet); sp_connection_dealloc(connection); return 0; } @@ -53,7 +53,7 @@ You have the choice of linking statically (recommended) or dynamically. ## Notes on differences to rust library - function names are: `sp_` \ \. -- Instances get consumed in the same way they do when writing rust / C# code. Do not use an instance after an (implicit!) free. +- Instances get consumed in the same way they do when writing rust code. Do not use an instance after an (implicit!) free. - Option or Result turn into nullable return values - check for NULL! - There are no specifics for C++ here yet. You might get a nicer header when generating directly for C++, but it should be usable. - Reading and writing to instances concurrently is not safe. Only reading concurrently is safe. 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 0a6069f..4b1cfda 100644 --- a/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h +++ b/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h @@ -167,6 +167,8 @@ typedef struct SPPixelGrid SPPixelGrid; /** * Represents a span of memory (`&mut [u8]` ) as a struct usable by C code. * + * You should not create an instance of this type in your C code. + * * # Safety * * The caller has to make sure that: @@ -174,6 +176,8 @@ typedef struct SPPixelGrid SPPixelGrid; * - 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. + * - an instance of this created from C is never passed to a consuming function, as the rust code + * will try to free the memory of a potentially separate allocator. */ typedef struct SPByteSlice { /** @@ -186,11 +190,6 @@ typedef struct SPByteSlice { size_t length; } SPByteSlice; -/** - * Type alias for documenting the meaning of the variable in enum values - */ -typedef size_t SPOffset; - #ifdef __cplusplus extern "C" { #endif // __cplusplus @@ -556,7 +555,7 @@ size_t sp_brightness_grid_width(const struct SPBrightnessGrid *this_); * - the returned `Command` instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_dealloc`. */ -struct SPCommand *sp_command_bitmap_linear(SPOffset offset, +struct SPCommand *sp_command_bitmap_linear(size_t offset, struct SPBitVec *bit_vec, SPCompressionCode compression); @@ -581,7 +580,7 @@ struct SPCommand *sp_command_bitmap_linear(SPOffset offset, * - the returned `Command` instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_dealloc`. */ -struct SPCommand *sp_command_bitmap_linear_and(SPOffset offset, +struct SPCommand *sp_command_bitmap_linear_and(size_t offset, struct SPBitVec *bit_vec, SPCompressionCode compression); @@ -606,7 +605,7 @@ struct SPCommand *sp_command_bitmap_linear_and(SPOffset offset, * - the returned `Command` instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_dealloc`. */ -struct SPCommand *sp_command_bitmap_linear_or(SPOffset offset, +struct SPCommand *sp_command_bitmap_linear_or(size_t offset, struct SPBitVec *bit_vec, SPCompressionCode compression); @@ -652,7 +651,7 @@ struct SPCommand *sp_command_bitmap_linear_win(size_t x, * - the returned `Command` instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_dealloc`. */ -struct SPCommand *sp_command_bitmap_linear_xor(SPOffset offset, +struct SPCommand *sp_command_bitmap_linear_xor(size_t offset, struct SPBitVec *bit_vec, SPCompressionCode compression); diff --git a/crates/servicepoint_binding_c/src/bit_vec.rs b/crates/servicepoint_binding_c/src/bit_vec.rs index d53792e..4455cfa 100644 --- a/crates/servicepoint_binding_c/src/bit_vec.rs +++ b/crates/servicepoint_binding_c/src/bit_vec.rs @@ -2,7 +2,7 @@ //! //! prefix `sp_bit_vec_` -use crate::c_slice::SPByteSlice; +use crate::SPByteSlice; use servicepoint::bitvec::prelude::{BitVec, Msb0}; /// A vector of bits diff --git a/crates/servicepoint_binding_c/src/brightness_grid.rs b/crates/servicepoint_binding_c/src/brightness_grid.rs index e4af777..a7d45f2 100644 --- a/crates/servicepoint_binding_c/src/brightness_grid.rs +++ b/crates/servicepoint_binding_c/src/brightness_grid.rs @@ -2,7 +2,7 @@ //! //! prefix `sp_brightness_grid_` -use crate::c_slice::SPByteSlice; +use crate::SPByteSlice; use servicepoint::{Brightness, DataRef, Grid, PrimitiveGrid}; use std::intrinsics::transmute; diff --git a/crates/servicepoint_binding_c/src/c_slice.rs b/crates/servicepoint_binding_c/src/byte_slice.rs similarity index 69% rename from crates/servicepoint_binding_c/src/c_slice.rs rename to crates/servicepoint_binding_c/src/byte_slice.rs index 9962511..fbdda2a 100644 --- a/crates/servicepoint_binding_c/src/c_slice.rs +++ b/crates/servicepoint_binding_c/src/byte_slice.rs @@ -3,6 +3,8 @@ #[repr(C)] /// Represents a span of memory (`&mut [u8]` ) as a struct usable by C code. /// +/// You should not create an instance of this type in your C code. +/// /// # Safety /// /// The caller has to make sure that: @@ -10,6 +12,8 @@ /// - 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. +/// - an instance of this created from C is never passed to a consuming function, as the rust code +/// will try to free the memory of a potentially separate allocator. pub struct SPByteSlice { /// 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 7c26536..3ece0f1 100644 --- a/crates/servicepoint_binding_c/src/command.rs +++ b/crates/servicepoint_binding_c/src/command.rs @@ -6,13 +6,10 @@ use std::ptr::null_mut; use servicepoint::{Brightness, Origin}; -use crate::bit_vec::SPBitVec; -use crate::brightness_grid::SPBrightnessGrid; -use crate::constants::SPCompressionCode; -use crate::cp437_grid::SPCp437Grid; -use crate::packet::SPPacket; -use crate::pixel_grid::SPPixelGrid; -use crate::SPOffset; +use crate::{ + SPBitVec, SPBrightnessGrid, SPCompressionCode, SPCp437Grid, SPPacket, + SPPixelGrid, +}; /// A low-level display command. /// @@ -196,7 +193,7 @@ pub unsafe extern "C" fn sp_command_char_brightness( /// by explicitly calling `sp_command_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_command_bitmap_linear( - offset: SPOffset, + offset: usize, bit_vec: *mut SPBitVec, compression: SPCompressionCode, ) -> *mut SPCommand { @@ -229,7 +226,7 @@ pub unsafe extern "C" fn sp_command_bitmap_linear( /// by explicitly calling `sp_command_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_command_bitmap_linear_and( - offset: SPOffset, + offset: usize, bit_vec: *mut SPBitVec, compression: SPCompressionCode, ) -> *mut SPCommand { @@ -262,7 +259,7 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_and( /// by explicitly calling `sp_command_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_command_bitmap_linear_or( - offset: SPOffset, + offset: usize, bit_vec: *mut SPBitVec, compression: SPCompressionCode, ) -> *mut SPCommand { @@ -295,7 +292,7 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_or( /// by explicitly calling `sp_command_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_command_bitmap_linear_xor( - offset: SPOffset, + offset: usize, bit_vec: *mut SPBitVec, compression: SPCompressionCode, ) -> *mut SPCommand { diff --git a/crates/servicepoint_binding_c/src/connection.rs b/crates/servicepoint_binding_c/src/connection.rs index e0556e3..ae82831 100644 --- a/crates/servicepoint_binding_c/src/connection.rs +++ b/crates/servicepoint_binding_c/src/connection.rs @@ -5,7 +5,7 @@ use std::ffi::{c_char, CStr}; use std::ptr::null_mut; -use crate::packet::SPPacket; +use crate::SPPacket; /// A connection to the display. /// diff --git a/crates/servicepoint_binding_c/src/cp437_grid.rs b/crates/servicepoint_binding_c/src/cp437_grid.rs index f181fdf..963456d 100644 --- a/crates/servicepoint_binding_c/src/cp437_grid.rs +++ b/crates/servicepoint_binding_c/src/cp437_grid.rs @@ -2,8 +2,8 @@ //! //! prefix `sp_cp437_grid_` -use crate::c_slice::SPByteSlice; -use servicepoint::{Cp437Grid, DataRef, Grid}; +use crate::SPByteSlice; +use servicepoint::{DataRef, Grid}; /// A C-wrapper for grid containing codepage 437 characters. /// @@ -18,7 +18,7 @@ use servicepoint::{Cp437Grid, DataRef, Grid}; /// sp_cp437_grid_dealloc(grid); /// ``` pub struct SPCp437Grid { - pub(crate) actual: Cp437Grid, + pub(crate) actual: servicepoint::Cp437Grid, } impl Clone for SPCp437Grid { @@ -45,7 +45,7 @@ pub unsafe extern "C" fn sp_cp437_grid_new( height: usize, ) -> *mut SPCp437Grid { Box::into_raw(Box::new(SPCp437Grid { - actual: Cp437Grid::new(width, height), + actual: servicepoint::Cp437Grid::new(width, height), })) } @@ -72,7 +72,7 @@ pub unsafe extern "C" fn sp_cp437_grid_load( ) -> *mut SPCp437Grid { let data = std::slice::from_raw_parts(data, data_length); Box::into_raw(Box::new(SPCp437Grid { - actual: Cp437Grid::load(width, height, data), + actual: servicepoint::Cp437Grid::load(width, height, data), })) } diff --git a/crates/servicepoint_binding_c/src/lib.rs b/crates/servicepoint_binding_c/src/lib.rs index c2d2877..fc60693 100644 --- a/crates/servicepoint_binding_c/src/lib.rs +++ b/crates/servicepoint_binding_c/src/lib.rs @@ -1,24 +1,55 @@ -//! C API wrapper for the `servicepoint` crate. +//! C API wrapper for the [servicepoint](https://docs.rs/servicepoint/latest/servicepoint/) crate. +//! +//! # Examples +//! +//! Make sure to check out [this GitHub repo](https://github.com/arfst23/ServicePoint) as well! +//! +//! ```C +//! #include +//! #include "servicepoint.h" +//! +//! int main(void) { +//! SPConnection *connection = sp_connection_open("172.23.42.29:2342"); +//! if (connection == NULL) +//! return 1; +//! +//! SPPixelGrid *pixels = sp_pixel_grid_new(SP_PIXEL_WIDTH, SP_PIXEL_HEIGHT); +//! sp_pixel_grid_fill(pixels, true); +//! +//! SPCommand *command = sp_command_bitmap_linear_win(0, 0, pixels, Uncompressed); +//! SPPacket *packet = sp_packet_from_command(command); +//! while (sp_connection_send(connection, sp_packet_clone(packet))); +//! +//! sp_packet_dealloc(packet); +//! sp_connection_dealloc(connection); +//! return 0; +//! } +//! ``` -pub use crate::c_slice::SPByteSlice; +pub use bit_vec::*; +pub use brightness_grid::*; +pub use byte_slice::*; +pub use command::*; +pub use connection::*; +pub use constants::*; +pub use cp437_grid::*; +pub use packet::*; +pub use pixel_grid::*; -pub mod bit_vec; +mod bit_vec; -pub mod brightness_grid; +mod brightness_grid; -pub mod command; +mod command; -pub mod connection; +mod connection; -pub mod packet; +mod packet; -pub mod pixel_grid; +mod pixel_grid; -pub mod c_slice; +mod byte_slice; -pub mod cp437_grid; +mod cp437_grid; -pub mod constants; - -/// Type alias for documenting the meaning of the variable in enum values -pub type SPOffset = usize; +mod constants; diff --git a/crates/servicepoint_binding_c/src/packet.rs b/crates/servicepoint_binding_c/src/packet.rs index c3304b8..c575de7 100644 --- a/crates/servicepoint_binding_c/src/packet.rs +++ b/crates/servicepoint_binding_c/src/packet.rs @@ -4,7 +4,7 @@ use std::ptr::null_mut; -use crate::command::SPCommand; +use crate::SPCommand; /// The raw packet pub struct SPPacket(pub(crate) servicepoint::Packet); diff --git a/crates/servicepoint_binding_c/src/pixel_grid.rs b/crates/servicepoint_binding_c/src/pixel_grid.rs index 585fda3..d8b4a32 100644 --- a/crates/servicepoint_binding_c/src/pixel_grid.rs +++ b/crates/servicepoint_binding_c/src/pixel_grid.rs @@ -4,7 +4,7 @@ use servicepoint::{DataRef, Grid}; -use crate::c_slice::SPByteSlice; +use crate::byte_slice::SPByteSlice; /// A grid of pixels. /// diff --git a/crates/servicepoint_binding_cs/build.rs b/crates/servicepoint_binding_cs/build.rs index a74e7ff..e8fe1f5 100644 --- a/crates/servicepoint_binding_cs/build.rs +++ b/crates/servicepoint_binding_cs/build.rs @@ -11,7 +11,7 @@ fn main() { .input_extern_file("../servicepoint_binding_c/src/connection.rs") .input_extern_file("../servicepoint_binding_c/src/pixel_grid.rs") .input_extern_file("../servicepoint_binding_c/src/lib.rs") - .input_extern_file("../servicepoint_binding_c/src/c_slice.rs") + .input_extern_file("../servicepoint_binding_c/src/byte_slice.rs") .input_extern_file("../servicepoint_binding_c/src/packet.rs") .input_extern_file("../servicepoint_binding_c/src/constants.rs") .csharp_dll_name("servicepoint_binding_c") From 8a5f7ffa092832258d0c6c064e40d05cfa910223 Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Sat, 7 Sep 2024 12:27:07 +0200 Subject: [PATCH 16/31] link arfst23/ServicePoint --- README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/README.md b/README.md index c355df0..46b85dd 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,11 @@ Take a look at the contained crates for language specific information: ## Projects using the library - screen simulator (rust): [servicepoint-simulator](https://github.com/kaesaecracker/servicepoint-simulator) +- A bunch of projects (C): [arfst23/ServicePoint](https://github.com/arfst23/ServicePoint), including + - a CLI tool to display image files on the display or use the display as a TTY + - a BSD games robots clone + - a split-flap-display simulator + - animations that play on the display - tanks game (C#): [servicepoint-tanks](https://github.com/kaesaecracker/cccb-tanks-cs) - cellular automata slideshow (rust): [servicepoint-life](https://github.com/kaesaecracker/servicepoint-life) From 64fe0e299754cef851efab5f6fe4029f602f92a0 Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Sat, 7 Sep 2024 12:30:09 +0200 Subject: [PATCH 17/31] move about display section into own file --- README.md | 44 -------------------------------------------- about_display.md | 41 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 41 insertions(+), 44 deletions(-) create mode 100644 about_display.md diff --git a/README.md b/README.md index 46b85dd..f19c2b1 100644 --- a/README.md +++ b/README.md @@ -26,50 +26,6 @@ Take a look at the contained crates for language specific information: To add yourself to the list, open a pull request. -## About the display - -- Resolution: 352x160=56,320 pixels -- Pixels are grouped into 44x20=880 tiles (8x8=64 pixels each) -- Smallest addressable unit: row of pixels inside of a tile (8 pixels = 1 byte) -- The brightness can only be set per tile -- Screen content can be changed using a simple UDP protocol -- Between each row of tiles, there is a gap of around 4 pixels size. This gap changes the aspect ratio of the display. - -### Binary format - -A UDP package sent to the display has a header size of 10 bytes. -Each header value has a size of two bytes (unsigned 16 bit integer). -Depending on the command, there can be a payload following the header. - -The commands are implemented in DisplayCommands. - -To change screen contents, these commands are the most relevant: - -1. Clear screen - - command: `0x0002` - - (rest does not matter) -2. Send CP437 data: render specified text into rectangular region - - command: `0x0003` - - top left tile x - - top left tile y - - width in tiles - - height in tiles - - payload: (width in tiles * height in tiles) bytes - - 1 byte = 1 character - - each character is rendered into one tile (mono-spaced) - - characters are encoded using code page 437 -3. Send bitmap window: set pixel states for a rectangular region - - command: `0x0013` - - top left tile x - - top left _pixel_ y - - width in tiles - - height in _pixels_ - - payload: (width in tiles * height in pixels) bytes - - network byte order - - 1 bit = 1 pixel - -There are other commands implemented as well, e.g. for changing the brightness. - ## What happened to servicepoint2? After `servicepoint2` has been merged into `servicepoint`, `servicepoint2` will not continue to get any updates. diff --git a/about_display.md b/about_display.md new file mode 100644 index 0000000..4fe7911 --- /dev/null +++ b/about_display.md @@ -0,0 +1,41 @@ +# About the display + +- Resolution: 352x160=56,320 pixels +- Pixels are grouped into 44x20=880 tiles (8x8=64 pixels each) +- Smallest addressable unit: row of pixels inside of a tile (8 pixels = 1 byte) +- The brightness can only be set per tile +- Screen content can be changed using a simple UDP protocol +- Between each row of tiles, there is a gap of around 4 pixels size. This gap changes the aspect ratio of the display. + +### Binary format + +A UDP package sent to the display has a header size of 10 bytes. +Each header value has a size of two bytes (unsigned 16 bit integer). +Depending on the command, there can be a payload following the header. + +To change screen contents, these commands are the most relevant: + +1. Clear screen + - command: `0x0002` + - (rest does not matter) +2. Send CP437 data: render specified text into rectangular region + - command: `0x0003` + - top left tile x + - top left tile y + - width in tiles + - height in tiles + - payload: (width in tiles * height in tiles) bytes + - 1 byte = 1 character + - each character is rendered into one tile (mono-spaced) + - characters are encoded using code page 437 +3. Send bitmap window: set pixel states for a rectangular region + - command: `0x0013` + - top left tile x + - top left _pixel_ y + - width in tiles + - height in _pixels_ + - payload: (width in tiles * height in pixels) bytes + - network byte order + - 1 bit = 1 pixel + +There are other commands implemented as well, e.g. for changing the brightness. From 2b54b944b55086fac4e614d5fac0f462b80441cd Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Sat, 7 Sep 2024 12:59:02 +0200 Subject: [PATCH 18/31] add CONTRIBUTING.md --- CONTRIBUTING.md | 26 ++++++++++++++++++++++++++ README.md | 20 +++++++++----------- 2 files changed, 35 insertions(+), 11 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..06b144f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,26 @@ +# Contributing + +Contributions are accepted in any form (issues, documentation, feature requests, code, review, ...). + +All creatures welcome. + +## Pull requests + +Feel free to create a PR, even if your change is not done yet. + +Mark your PR as a draft as long as you do not want it to be merged. + +The main branch is supposed to be a working version, including language bindings, +which means sometimes your PR may be merged into a temporary development branch. + +## Language bindings + +Pull requests for your preferred language will be accepted. +If there is no code generator, it should call the C ABI methods provided by `servicepoint_binding_c`. +It should be able to send most of the basic commands in a way the simulator accepts, receiving is +not required for the merge. + +It is okay for the feature set of a language binding to lag behind the one of the rust crate. +This also means you do not have to expose a feature to all the language bindings when adding something to the core. + +If your change may break other language bindings, please note that in your PR description so someone can check them. diff --git a/README.md b/README.md index f19c2b1..a4e2836 100644 --- a/README.md +++ b/README.md @@ -7,11 +7,11 @@ programming languages. Take a look at the contained crates for language specific information: -| Language | Readme | -|----------|---------------------------------------------------------------------| -| Rust | [servicepoint](crates/servicepoint/README.md) | -| C / C++ | [servicepoint_binding_c](crates/servicepoint_binding_c/README.md) | -| C# / F# | [servicepoint_binding_cs](crates/servicepoint_binding_cs/README.md) | +| Language | Readme | +|-----------|---------------------------------------------------------------------| +| Rust | [servicepoint](crates/servicepoint/README.md) | +| C / C++ | [servicepoint_binding_c](crates/servicepoint_binding_c/README.md) | +| .NET (C#) | [servicepoint_binding_cs](crates/servicepoint_binding_cs/README.md) | ## Projects using the library @@ -26,12 +26,10 @@ Take a look at the contained crates for language specific information: To add yourself to the list, open a pull request. +## Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md). + ## What happened to servicepoint2? After `servicepoint2` has been merged into `servicepoint`, `servicepoint2` will not continue to get any updates. - -## Contributing - -Contributions are accepted in any form (issues, documentation, feature requests, code, review, ...). - -All creatures welcome. From 341c0ef2cdcde7c0cb0bab5aa2216f92f684f41d Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Sat, 7 Sep 2024 13:22:41 +0200 Subject: [PATCH 19/31] change cbindgen sorting to None --- crates/servicepoint/src/command.rs | 102 +- crates/servicepoint_binding_c/cbindgen.toml | 8 +- .../examples/lang_c/include/servicepoint.h | 1360 +++++++++-------- crates/servicepoint_binding_c/src/lib.rs | 36 +- 4 files changed, 755 insertions(+), 751 deletions(-) diff --git a/crates/servicepoint/src/command.rs b/crates/servicepoint/src/command.rs index 3a5ab1c..d799696 100644 --- a/crates/servicepoint/src/command.rs +++ b/crates/servicepoint/src/command.rs @@ -192,9 +192,7 @@ impl TryFrom for Command { fn try_from(packet: Packet) -> Result { let Packet { header: Header { - command_code, - a, - .. + command_code, a, .. }, .. } = packet; @@ -274,13 +272,14 @@ impl Command { compression: CompressionCode, ) -> Result { let Packet { - header: Header { - command_code: _, - a: tiles_x, - b: pixels_y, - c: tile_w, - d: pixel_h, - }, + header: + Header { + command_code: _, + a: tiles_x, + b: pixels_y, + c: tile_w, + d: pixel_h, + }, payload, } = packet; @@ -306,13 +305,14 @@ impl Command { command: Command, ) -> Result { let Packet { - header: Header { - command_code: _, - a, - b, - c, - d, - }, + header: + Header { + command_code: _, + a, + b, + c, + d, + }, payload, } = packet; if !payload.is_empty() { @@ -329,12 +329,13 @@ impl Command { packet: Packet, ) -> Result<(SpBitVec, CompressionCode), TryFromPacketError> { let Packet { - header: Header { - b: length, - c: sub, - d: reserved, - .. - }, + header: + Header { + b: length, + c: sub, + d: reserved, + .. + }, payload, } = packet; if reserved != 0 { @@ -363,13 +364,14 @@ impl Command { packet: &Packet, ) -> Result { let Packet { - header: Header { - command_code: _, - a: x, - b: y, - c: width, - d: height, - }, + header: + Header { + command_code: _, + a: x, + b: y, + c: width, + d: height, + }, payload, } = packet; @@ -390,13 +392,14 @@ impl Command { packet: &Packet, ) -> Result { let Packet { - header: Header { - command_code: _, - a, - b, - c, - d, - }, + header: + Header { + command_code: _, + a, + b, + c, + d, + }, payload, } = packet; if payload.len() != 1 { @@ -420,13 +423,14 @@ impl Command { packet: &Packet, ) -> Result { let Packet { - header: Header { - command_code: _, - a, - b, - c, - d, - }, + header: + Header { + command_code: _, + a, + b, + c, + d, + }, payload, } = packet; Ok(Command::Cp437Data( @@ -662,7 +666,7 @@ mod tests { PixelGrid::new(8, 8), compression, ) - .into(); + .into(); let Packet { header, @@ -692,7 +696,7 @@ mod tests { BitVec::repeat(false, 8), compression, ) - .into(); + .into(); let Packet { header, mut payload, @@ -752,7 +756,7 @@ mod tests { BitVec::repeat(false, 8), CompressionCode::Uncompressed, ) - .into(); + .into(); let Header { command_code: command, a: offset, @@ -783,7 +787,7 @@ mod tests { BitVec::repeat(false, 8), CompressionCode::Uncompressed, ) - .into(); + .into(); let Header { command_code: command, a: offset, @@ -814,7 +818,7 @@ mod tests { BitVec::repeat(false, 8), CompressionCode::Uncompressed, ) - .into(); + .into(); let Header { command_code: command, a: offset, diff --git a/crates/servicepoint_binding_c/cbindgen.toml b/crates/servicepoint_binding_c/cbindgen.toml index 1c363cf..5aa39c8 100644 --- a/crates/servicepoint_binding_c/cbindgen.toml +++ b/crates/servicepoint_binding_c/cbindgen.toml @@ -2,6 +2,8 @@ language = "C" include_version = true cpp_compat = true +autogen_warning = "/* Warning, this file is autogenerated by cbindgen. Don't modify this manually. */" + ############################ Code Style Options ################################ braces = "SameLine" @@ -15,7 +17,7 @@ line_endings = "LF" ############################# Codegen Options ################################## style = "both" -sort_by = "Name" +sort_by = "None" usize_is_size_t = true [parse] @@ -23,3 +25,7 @@ parse_deps = false [parse.expand] all_features = true + +[export] +include = [] +exclude = [] 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 4b1cfda..a132c7d 100644 --- a/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h +++ b/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h @@ -1,31 +1,13 @@ /* Generated with cbindgen:0.26.0 */ +/* Warning, this file is autogenerated by cbindgen. Don't modify this manually. */ + #include #include #include #include #include -/** - * pixel count on whole screen - */ -#define SP_PIXEL_COUNT (SP_PIXEL_WIDTH * SP_PIXEL_HEIGHT) - -/** - * Display height in pixels - */ -#define SP_PIXEL_HEIGHT (SP_TILE_HEIGHT * SP_TILE_SIZE) - -/** - * Display width in pixels - */ -#define SP_PIXEL_WIDTH (SP_TILE_WIDTH * SP_TILE_SIZE) - -/** - * Display tile count in the y-direction - */ -#define SP_TILE_HEIGHT 20 - /** * size of a single tile in one dimension */ @@ -36,6 +18,26 @@ */ #define SP_TILE_WIDTH 56 +/** + * Display tile count in the y-direction + */ +#define SP_TILE_HEIGHT 20 + +/** + * Display width in pixels + */ +#define SP_PIXEL_WIDTH (SP_TILE_WIDTH * SP_TILE_SIZE) + +/** + * Display height in pixels + */ +#define SP_PIXEL_HEIGHT (SP_TILE_HEIGHT * SP_TILE_SIZE) + +/** + * pixel count on whole screen + */ +#define SP_PIXEL_COUNT (SP_PIXEL_WIDTH * SP_PIXEL_HEIGHT) + /** * Specifies the kind of compression to use. */ @@ -195,344 +197,118 @@ extern "C" { #endif // __cplusplus /** - * Clones a `BitVec`. + * Tries to turn a `SPPacket` into a `SPCommand`. The packet is deallocated in the process. + * + * Returns: pointer to new `SPCommand` instance or NULL * * # Safety * * The caller has to make sure that: * - * - `this` points to a valid `BitVec` + * - `packet` points to a valid instance of `SPPacket` + * - `packet` is not used concurrently or after this call + * - the result is checked for NULL + * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_command_dealloc`. + */ +struct SPCommand *sp_command_try_from_packet(struct SPPacket *packet); + +/** + * Clones a `SPCommand` 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 instance is freed in some way, either by using a consuming function or - * by explicitly calling `sp_bit_vec_dealloc`. + * - the returned `Command` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_command_dealloc`. */ -struct SPBitVec *sp_bit_vec_clone(const struct SPBitVec *this_); +struct SPCommand *sp_command_clone(const struct SPCommand *original); /** - * Deallocates a `BitVec`. + * Allocates a new `Command::Clear` instance. + * + * Set all pixels to the off state. Does not affect brightness. + * + * # Examples + * + * ```C + * sp_connection_send(connection, sp_command_clear()); + * ``` * * # 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` + * - the returned `Command` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_command_dealloc`. */ -void sp_bit_vec_dealloc(struct SPBitVec *this_); +struct SPCommand *sp_command_clear(void); /** - * Sets the value of all bits in the `BitVec`. + * Allocates a new `Command::HardReset` instance. * - * # Arguments - * - * - `value`: the value to set all bits to + * Kills the udp daemon on the display, which usually results in a restart. + * Please do not send this in your normal program flow. * * # Safety * * The caller has to make sure that: * - * - `this` points to a valid `BitVec` - * - `this` is not written to or read from concurrently + * - the returned `Command` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_command_dealloc`. */ -void sp_bit_vec_fill(struct SPBitVec *this_, bool value); +struct SPCommand *sp_command_hard_reset(void); /** - * Gets the value of a bit from the `BitVec`. + * Allocates a new `Command::FadeOut` instance. * - * # Arguments + * # Safety * - * - `this`: instance to read from - * - `index`: the bit index to read + * The caller has to make sure that: * - * returns: value of the bit + * - the returned `Command` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_command_dealloc`. + */ +struct SPCommand *sp_command_fade_out(void); + +/** + * Allocates a new `Command::Brightness` instance for setting the brightness of all tiles to the + * same value. * * # Panics * - * When accessing `index` out of bounds. + * - When the provided brightness value is out of range (0-11). * * # Safety * * The caller has to make sure that: * - * - `this` points to a valid `BitVec` - * - `this` is not written to concurrently + * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_command_dealloc`. */ -bool sp_bit_vec_get(const struct SPBitVec *this_, size_t index); +struct SPCommand *sp_command_brightness(uint8_t brightness); /** - * Returns true if length is 0. + * Allocates a new `Command::CharBrightness` instance. + * The passed `SPBrightnessGrid` gets consumed. + * + * Set the brightness of individual tiles in a rectangular area of the display. * * # Safety * * The caller has to make sure that: * - * - `this` points to a valid `BitVec` + * - `grid` points to a valid instance of `SPBrightnessGrid` + * - `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`. */ -bool sp_bit_vec_is_empty(const struct SPBitVec *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 SPBitVec *this_); - -/** - * 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 SPBitVec *sp_bit_vec_load(const uint8_t *data, - size_t data_length); - -/** - * 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`. - */ -struct SPBitVec *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 - */ -void sp_bit_vec_set(struct SPBitVec *this_, size_t index, bool value); - -/** - * 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 - */ -struct SPByteSlice sp_bit_vec_unsafe_data_ref(struct SPBitVec *this_); - -/** - * Clones a `BrightnessGrid`. - * - * # Safety - * - * The caller has to make sure that: - * - * - `this` points to a valid `BrightnessGrid` - * - `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_brightness_grid_dealloc`. - */ -struct SPBrightnessGrid *sp_brightness_grid_clone(const struct SPBrightnessGrid *this_); - -/** - * Deallocates a `BrightnessGrid`. - * - * # Safety - * - * The caller has to make sure that: - * - * - `this` points to a valid `BrightnessGrid` - * - `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_brightness_grid_dealloc(struct SPBrightnessGrid *this_); - -/** - * Sets the value of all cells in the `BrightnessGrid`. - * - * # Arguments - * - * - `this`: instance to write to - * - `value`: the value to set all cells to - * - * # Panics - * - * - When providing an invalid brightness value - * - * # Safety - * - * The caller has to make sure that: - * - * - `this` points to a valid `BrightnessGrid` - * - `this` is not written to or read from concurrently - */ -void sp_brightness_grid_fill(struct SPBrightnessGrid *this_, uint8_t value); - -/** - * 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 `BrightnessGrid` - * - `this` is not written to concurrently - */ -uint8_t sp_brightness_grid_get(const struct SPBrightnessGrid *this_, - size_t x, - size_t y); - -/** - * Gets the height of the `BrightnessGrid` instance. - * - * # Arguments - * - * - `this`: instance to read from - * - * # Safety - * - * The caller has to make sure that: - * - * - `this` points to a valid `BrightnessGrid` - */ -size_t sp_brightness_grid_height(const struct SPBrightnessGrid *this_); - -/** - * Loads a `BrightnessGrid` 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_brightness_grid_dealloc`. - */ -struct SPBrightnessGrid *sp_brightness_grid_load(size_t width, - size_t height, - const uint8_t *data, - size_t data_length); - -/** - * Creates a new `BrightnessGrid` with the specified dimensions. - * - * returns: `BrightnessGrid` 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_brightness_grid_dealloc`. - */ -struct SPBrightnessGrid *sp_brightness_grid_new(size_t width, - size_t height); - -/** - * Sets the value of the specified position in the `BrightnessGrid`. - * - * # 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. - * - When providing an invalid brightness value - * - * # 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_brightness_grid_set(struct SPBrightnessGrid *this_, - size_t x, - size_t y, - uint8_t value); - -/** - * Gets an unsafe reference to the data of the `BrightnessGrid` instance. - * - * ## Safety - * - * The caller has to make sure that: - * - * - `this` points to a valid `BrightnessGrid` - * - the returned memory range is never accessed after the passed `BrightnessGrid` has been freed - * - the returned memory range is never accessed concurrently, either via the `BrightnessGrid` or directly - */ -struct SPByteSlice sp_brightness_grid_unsafe_data_ref(struct SPBrightnessGrid *this_); - -/** - * Gets the width of the `BrightnessGrid` instance. - * - * # Arguments - * - * - `this`: instance to read from - * - * # Safety - * - * The caller has to make sure that: - * - * - `this` points to a valid `BrightnessGrid` - */ -size_t sp_brightness_grid_width(const struct SPBrightnessGrid *this_); +struct SPCommand *sp_command_char_brightness(size_t x, + size_t y, + struct SPBrightnessGrid *grid); /** * Allocates a new `Command::BitmapLinear` instance. @@ -609,27 +385,6 @@ struct SPCommand *sp_command_bitmap_linear_or(size_t offset, struct SPBitVec *bit_vec, SPCompressionCode compression); -/** - * Allocates a new `Command::BitmapLinearWin` instance. - * The passed `PixelGrid` gets consumed. - * - * Sets a window of pixels to the specified values - * - * # 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 SPCommand *sp_command_bitmap_linear_win(size_t x, - size_t y, - struct SPPixelGrid *pixel_grid, - SPCompressionCode compression_code); - /** * Allocates a new `Command::BitmapLinearXor` instance. * The passed `BitVec` gets consumed. @@ -655,76 +410,6 @@ struct SPCommand *sp_command_bitmap_linear_xor(size_t offset, struct SPBitVec *bit_vec, SPCompressionCode compression); -/** - * Allocates a new `Command::Brightness` instance for setting the brightness of all tiles to the - * same value. - * - * # Panics - * - * - When the provided brightness value is out of range (0-11). - * - * # Safety - * - * The caller has to make sure that: - * - * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or - * by explicitly calling `sp_command_dealloc`. - */ -struct SPCommand *sp_command_brightness(uint8_t brightness); - -/** - * Allocates a new `Command::CharBrightness` instance. - * The passed `SPBrightnessGrid` gets consumed. - * - * Set the brightness of individual tiles in a rectangular area of the display. - * - * # Safety - * - * The caller has to make sure that: - * - * - `grid` points to a valid instance of `SPBrightnessGrid` - * - `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 SPCommand *sp_command_char_brightness(size_t x, - size_t y, - struct SPBrightnessGrid *grid); - -/** - * Allocates a new `Command::Clear` instance. - * - * Set all pixels to the off state. Does not affect brightness. - * - * # Examples - * - * ```C - * sp_connection_send(connection, sp_command_clear()); - * ``` - * - * # 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 SPCommand *sp_command_clear(void); - -/** - * Clones a `SPCommand` 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 SPCommand *sp_command_clone(const struct SPCommand *original); - /** * Allocates a new `Command::Cp437Data` instance. * The passed `ByteGrid` gets consumed. @@ -749,6 +434,27 @@ struct SPCommand *sp_command_cp437_data(size_t x, size_t y, struct SPCp437Grid *byte_grid); +/** + * Allocates a new `Command::BitmapLinearWin` instance. + * The passed `PixelGrid` gets consumed. + * + * Sets a window of pixels to the specified values + * + * # 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 SPCommand *sp_command_bitmap_linear_win(size_t x, + size_t y, + struct SPPixelGrid *pixel_grid, + SPCompressionCode compression_code); + /** * Deallocates a `Command`. * @@ -770,60 +476,344 @@ struct SPCommand *sp_command_cp437_data(size_t x, void sp_command_dealloc(struct SPCommand *ptr); /** - * Allocates a new `Command::FadeOut` instance. + * 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 `Command` instance is freed in some way, either by using a consuming function or - * by explicitly calling `sp_command_dealloc`. + * - the returned instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_bit_vec_dealloc`. */ -struct SPCommand *sp_command_fade_out(void); +struct SPBitVec *sp_bit_vec_new(size_t size); /** - * Allocates a new `Command::HardReset` instance. - * - * Kills the udp daemon on the display, which usually results in a restart. - * Please do not send this in your normal program flow. + * Interpret the data as a series of bits and load then into a new `BitVec` 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`. + * - `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 SPCommand *sp_command_hard_reset(void); +struct SPBitVec *sp_bit_vec_load(const uint8_t *data, + size_t data_length); /** - * Tries to turn a `SPPacket` into a `SPCommand`. The packet is deallocated in the process. - * - * Returns: pointer to new `SPCommand` instance or NULL + * Clones a `BitVec`. * * # Safety * * The caller has to make sure that: * - * - `packet` points to a valid instance of `SPPacket` - * - `packet` is not used concurrently or after this call - * - the result is checked for NULL - * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or - * by explicitly calling `sp_command_dealloc`. + * - `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 SPCommand *sp_command_try_from_packet(struct SPPacket *packet); +struct SPBitVec *sp_bit_vec_clone(const struct SPBitVec *this_); /** - * Closes and deallocates a `Connection`. + * Deallocates a `BitVec`. * * # Safety * * The caller has to make sure that: * - * - `this` points to a valid `Connection` + * - `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_connection_dealloc(struct SPConnection *ptr); +void sp_bit_vec_dealloc(struct SPBitVec *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 + */ +bool sp_bit_vec_get(const struct SPBitVec *this_, size_t index); + +/** + * 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 + */ +void sp_bit_vec_set(struct SPBitVec *this_, size_t index, bool value); + +/** + * 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 SPBitVec *this_, bool value); + +/** + * 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 SPBitVec *this_); + +/** + * 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 SPBitVec *this_); + +/** + * 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 + */ +struct SPByteSlice sp_bit_vec_unsafe_data_ref(struct SPBitVec *this_); + +/** + * Creates a new `BrightnessGrid` with the specified dimensions. + * + * returns: `BrightnessGrid` 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_brightness_grid_dealloc`. + */ +struct SPBrightnessGrid *sp_brightness_grid_new(size_t width, + size_t height); + +/** + * Loads a `BrightnessGrid` 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_brightness_grid_dealloc`. + */ +struct SPBrightnessGrid *sp_brightness_grid_load(size_t width, + size_t height, + const uint8_t *data, + size_t data_length); + +/** + * Clones a `BrightnessGrid`. + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `BrightnessGrid` + * - `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_brightness_grid_dealloc`. + */ +struct SPBrightnessGrid *sp_brightness_grid_clone(const struct SPBrightnessGrid *this_); + +/** + * Deallocates a `BrightnessGrid`. + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `BrightnessGrid` + * - `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_brightness_grid_dealloc(struct SPBrightnessGrid *this_); + +/** + * 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 `BrightnessGrid` + * - `this` is not written to concurrently + */ +uint8_t sp_brightness_grid_get(const struct SPBrightnessGrid *this_, + size_t x, + size_t y); + +/** + * Sets the value of the specified position in the `BrightnessGrid`. + * + * # 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. + * - When providing an invalid brightness value + * + * # 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_brightness_grid_set(struct SPBrightnessGrid *this_, + size_t x, + size_t y, + uint8_t value); + +/** + * Sets the value of all cells in the `BrightnessGrid`. + * + * # Arguments + * + * - `this`: instance to write to + * - `value`: the value to set all cells to + * + * # Panics + * + * - When providing an invalid brightness value + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `BrightnessGrid` + * - `this` is not written to or read from concurrently + */ +void sp_brightness_grid_fill(struct SPBrightnessGrid *this_, uint8_t value); + +/** + * Gets the width of the `BrightnessGrid` instance. + * + * # Arguments + * + * - `this`: instance to read from + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `BrightnessGrid` + */ +size_t sp_brightness_grid_width(const struct SPBrightnessGrid *this_); + +/** + * Gets the height of the `BrightnessGrid` instance. + * + * # Arguments + * + * - `this`: instance to read from + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `BrightnessGrid` + */ +size_t sp_brightness_grid_height(const struct SPBrightnessGrid *this_); + +/** + * Gets an unsafe reference to the data of the `BrightnessGrid` instance. + * + * ## Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `BrightnessGrid` + * - the returned memory range is never accessed after the passed `BrightnessGrid` has been freed + * - the returned memory range is never accessed concurrently, either via the `BrightnessGrid` or directly + */ +struct SPByteSlice sp_brightness_grid_unsafe_data_ref(struct SPBrightnessGrid *this_); /** * Creates a new instance of `Connection`. @@ -861,201 +851,16 @@ bool sp_connection_send(const struct SPConnection *connection, struct SPPacket *packet); /** - * Clones a `Cp437Grid`. + * Closes and deallocates a `Connection`. * * # Safety * * The caller has to make sure that: * - * - `this` points to a valid `Cp437Grid` - * - `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_cp437_grid_dealloc`. - */ -struct SPCp437Grid *sp_cp437_grid_clone(const struct SPCp437Grid *this_); - -/** - * Deallocates a `Cp437Grid`. - * - * # Safety - * - * The caller has to make sure that: - * - * - `this` points to a valid `Cp437Grid` - * - `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_cp437_grid_dealloc(struct SPCp437Grid *this_); - -/** - * Sets the value of all cells in the `Cp437Grid`. - * - * # 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 `Cp437Grid` - * - `this` is not written to or read from concurrently - */ -void sp_cp437_grid_fill(struct SPCp437Grid *this_, uint8_t value); - -/** - * 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 `Cp437Grid` - * - `this` is not written to concurrently - */ -uint8_t sp_cp437_grid_get(const struct SPCp437Grid *this_, size_t x, size_t y); - -/** - * Gets the height of the `Cp437Grid` instance. - * - * # Arguments - * - * - `this`: instance to read from - * - * # Safety - * - * The caller has to make sure that: - * - * - `this` points to a valid `Cp437Grid` - */ -size_t sp_cp437_grid_height(const struct SPCp437Grid *this_); - -/** - * Loads a `Cp437Grid` 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_cp437_grid_dealloc`. - */ -struct SPCp437Grid *sp_cp437_grid_load(size_t width, - size_t height, - const uint8_t *data, - size_t data_length); - -/** - * Creates a new `Cp437Grid` with the specified dimensions. - * - * returns: `Cp437Grid` 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_cp437_grid_dealloc`. - */ -struct SPCp437Grid *sp_cp437_grid_new(size_t width, - size_t height); - -/** - * Sets the value of the specified position in the `Cp437Grid`. - * - * # 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_cp437_grid_set(struct SPCp437Grid *this_, - size_t x, - size_t y, - uint8_t value); - -/** - * Gets an unsafe reference to the data of the `Cp437Grid` instance. - * - * ## Safety - * - * The caller has to make sure that: - * - * - `this` points to a valid `Cp437Grid` - * - the returned memory range is never accessed after the passed `Cp437Grid` has been freed - * - the returned memory range is never accessed concurrently, either via the `Cp437Grid` or directly - */ -struct SPByteSlice sp_cp437_grid_unsafe_data_ref(struct SPCp437Grid *this_); - -/** - * Gets the width of the `Cp437Grid` instance. - * - * # Arguments - * - * - `this`: instance to read from - * - * # Safety - * - * The caller has to make sure that: - * - * - `this` points to a valid `Cp437Grid` - */ -size_t sp_cp437_grid_width(const struct SPCp437Grid *this_); - -/** - * Clones a `Packet`. - * - * # Safety - * - * The caller has to make sure that: - * - * - `this` points to a valid `Packet` - * - `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_packet_dealloc`. - */ -struct SPPacket *sp_packet_clone(const struct SPPacket *this_); - -/** - * Deallocates a `Packet`. - * - * # Safety - * - * The caller has to make sure that: - * - * - `this` points to a valid `Packet` + * - `this` points to a valid `Connection` * - `this` is not used concurrently or after this call */ -void sp_packet_dealloc(struct SPPacket *this_); +void sp_connection_dealloc(struct SPConnection *ptr); /** * Turns a `Command` into a `Packet`. @@ -1090,84 +895,54 @@ struct SPPacket *sp_packet_try_load(const uint8_t *data, size_t length); /** - * Clones a `PixelGrid`. + * Clones a `Packet`. * * # Safety * * The caller has to make sure that: * - * - `this` points to a valid `PixelGrid` + * - `this` points to a valid `Packet` * - `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`. + * by explicitly calling `sp_packet_dealloc`. */ -struct SPPixelGrid *sp_pixel_grid_clone(const struct SPPixelGrid *this_); +struct SPPacket *sp_packet_clone(const struct SPPacket *this_); /** - * Deallocates a `PixelGrid`. + * Deallocates a `Packet`. * * # Safety * * The caller has to make sure that: * - * - `this` points to a valid `PixelGrid` + * - `this` points to a valid `Packet` * - `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 SPPixelGrid *this_); +void sp_packet_dealloc(struct SPPacket *this_); /** - * Sets the state of all pixels in the `PixelGrid`. + * Creates a new `PixelGrid` with the specified dimensions. * * # Arguments * - * - `this`: instance to write to - * - `value`: the value to set all pixels to + * - `width`: size in pixels in x-direction + * - `height`: size in pixels in y-direction * - * # 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 SPPixelGrid *this_, bool value); - -/** - * 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 + * returns: `PixelGrid` initialized to all pixels off * * # Panics * - * When accessing `x` or `y` out of bounds. + * - when the width is not dividable by 8 * * # 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`. */ -bool sp_pixel_grid_get(const struct SPPixelGrid *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 SPPixelGrid *this_); +struct SPPixelGrid *sp_pixel_grid_new(size_t width, + size_t height); /** * Loads a `PixelGrid` with the specified dimensions from the provided data. @@ -1198,28 +973,52 @@ struct SPPixelGrid *sp_pixel_grid_load(size_t width, size_t data_length); /** - * 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 + * 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`. */ -struct SPPixelGrid *sp_pixel_grid_new(size_t width, - size_t height); +struct SPPixelGrid *sp_pixel_grid_clone(const struct SPPixelGrid *this_); + +/** + * 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` + */ +void sp_pixel_grid_dealloc(struct SPPixelGrid *this_); + +/** + * 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 SPPixelGrid *this_, size_t x, size_t y); /** * Sets the value of the specified position in the `PixelGrid`. @@ -1249,17 +1048,21 @@ void sp_pixel_grid_set(struct SPPixelGrid *this_, bool value); /** - * Gets an unsafe reference to the data of the `PixelGrid` instance. + * Sets the state of all pixels in the `PixelGrid`. * - * ## Safety + * # 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` - * - 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 + * - `this` is not written to or read from concurrently */ -struct SPByteSlice sp_pixel_grid_unsafe_data_ref(struct SPPixelGrid *this_); +void sp_pixel_grid_fill(struct SPPixelGrid *this_, bool value); /** * Gets the width in pixels of the `PixelGrid` instance. @@ -1276,6 +1079,205 @@ struct SPByteSlice sp_pixel_grid_unsafe_data_ref(struct SPPixelGrid *this_); */ size_t sp_pixel_grid_width(const struct SPPixelGrid *this_); +/** + * 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 SPPixelGrid *this_); + +/** + * 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 + */ +struct SPByteSlice sp_pixel_grid_unsafe_data_ref(struct SPPixelGrid *this_); + +/** + * Creates a new `Cp437Grid` with the specified dimensions. + * + * returns: `Cp437Grid` 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_cp437_grid_dealloc`. + */ +struct SPCp437Grid *sp_cp437_grid_new(size_t width, + size_t height); + +/** + * Loads a `Cp437Grid` 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_cp437_grid_dealloc`. + */ +struct SPCp437Grid *sp_cp437_grid_load(size_t width, + size_t height, + const uint8_t *data, + size_t data_length); + +/** + * Clones a `Cp437Grid`. + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `Cp437Grid` + * - `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_cp437_grid_dealloc`. + */ +struct SPCp437Grid *sp_cp437_grid_clone(const struct SPCp437Grid *this_); + +/** + * Deallocates a `Cp437Grid`. + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `Cp437Grid` + * - `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_cp437_grid_dealloc(struct SPCp437Grid *this_); + +/** + * 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 `Cp437Grid` + * - `this` is not written to concurrently + */ +uint8_t sp_cp437_grid_get(const struct SPCp437Grid *this_, size_t x, size_t y); + +/** + * Sets the value of the specified position in the `Cp437Grid`. + * + * # 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_cp437_grid_set(struct SPCp437Grid *this_, + size_t x, + size_t y, + uint8_t value); + +/** + * Sets the value of all cells in the `Cp437Grid`. + * + * # 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 `Cp437Grid` + * - `this` is not written to or read from concurrently + */ +void sp_cp437_grid_fill(struct SPCp437Grid *this_, uint8_t value); + +/** + * Gets the width of the `Cp437Grid` instance. + * + * # Arguments + * + * - `this`: instance to read from + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `Cp437Grid` + */ +size_t sp_cp437_grid_width(const struct SPCp437Grid *this_); + +/** + * Gets the height of the `Cp437Grid` instance. + * + * # Arguments + * + * - `this`: instance to read from + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `Cp437Grid` + */ +size_t sp_cp437_grid_height(const struct SPCp437Grid *this_); + +/** + * Gets an unsafe reference to the data of the `Cp437Grid` instance. + * + * ## Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `Cp437Grid` + * - the returned memory range is never accessed after the passed `Cp437Grid` has been freed + * - the returned memory range is never accessed concurrently, either via the `Cp437Grid` or directly + */ +struct SPByteSlice sp_cp437_grid_unsafe_data_ref(struct SPCp437Grid *this_); + #ifdef __cplusplus } // extern "C" #endif // __cplusplus diff --git a/crates/servicepoint_binding_c/src/lib.rs b/crates/servicepoint_binding_c/src/lib.rs index fc60693..159b64d 100644 --- a/crates/servicepoint_binding_c/src/lib.rs +++ b/crates/servicepoint_binding_c/src/lib.rs @@ -26,30 +26,22 @@ //! } //! ``` -pub use bit_vec::*; -pub use brightness_grid::*; -pub use byte_slice::*; -pub use command::*; -pub use connection::*; -pub use constants::*; -pub use cp437_grid::*; -pub use packet::*; -pub use pixel_grid::*; +pub use crate::bit_vec::*; +pub use crate::brightness_grid::*; +pub use crate::byte_slice::*; +pub use crate::command::*; +pub use crate::connection::*; +pub use crate::constants::*; +pub use crate::cp437_grid::*; +pub use crate::packet::*; +pub use crate::pixel_grid::*; mod bit_vec; - mod brightness_grid; - -mod command; - -mod connection; - -mod packet; - -mod pixel_grid; - mod byte_slice; - -mod cp437_grid; - +mod command; +mod connection; mod constants; +mod cp437_grid; +mod packet; +mod pixel_grid; From cec31ad5b5392f9b24693a5b62ea66a494fe3e7d Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Sat, 7 Sep 2024 13:34:13 +0200 Subject: [PATCH 20/31] regenerate C# bindings, apparently Cp437Grid has been missing --- .../ServicePoint/BindGen/ServicePoint.g.cs | 488 +++++++++--------- crates/servicepoint_binding_cs/build.rs | 23 +- 2 files changed, 256 insertions(+), 255 deletions(-) diff --git a/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs b/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs index cd73a1a..fd7e1d3 100644 --- a/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs +++ b/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs @@ -371,180 +371,6 @@ namespace ServicePoint.BindGen [DllImport(__DllName, EntryPoint = "sp_brightness_grid_unsafe_data_ref", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern ByteSlice sp_brightness_grid_unsafe_data_ref(BrightnessGrid* @this); - /// - /// Creates a new `Cp437Grid` with the specified dimensions. - /// - /// returns: `Cp437Grid` 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_cp437_grid_dealloc`. - /// - [DllImport(__DllName, EntryPoint = "sp_cp437_grid_new", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern Cp437Grid* sp_cp437_grid_new(nuint width, nuint height); - - /// - /// Loads a `Cp437Grid` 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_cp437_grid_dealloc`. - /// - [DllImport(__DllName, EntryPoint = "sp_cp437_grid_load", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern Cp437Grid* sp_cp437_grid_load(nuint width, nuint height, byte* data, nuint data_length); - - /// - /// Clones a `Cp437Grid`. - /// - /// # Safety - /// - /// The caller has to make sure that: - /// - /// - `this` points to a valid `Cp437Grid` - /// - `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_cp437_grid_dealloc`. - /// - [DllImport(__DllName, EntryPoint = "sp_cp437_grid_clone", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern Cp437Grid* sp_cp437_grid_clone(Cp437Grid* @this); - - /// - /// Deallocates a `Cp437Grid`. - /// - /// # Safety - /// - /// The caller has to make sure that: - /// - /// - `this` points to a valid `Cp437Grid` - /// - `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_cp437_grid_dealloc", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern void sp_cp437_grid_dealloc(Cp437Grid* @this); - - /// - /// 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 `Cp437Grid` - /// - `this` is not written to concurrently - /// - [DllImport(__DllName, EntryPoint = "sp_cp437_grid_get", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern byte sp_cp437_grid_get(Cp437Grid* @this, nuint x, nuint y); - - /// - /// Sets the value of the specified position in the `Cp437Grid`. - /// - /// # 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_cp437_grid_set", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern void sp_cp437_grid_set(Cp437Grid* @this, nuint x, nuint y, byte value); - - /// - /// Sets the value of all cells in the `Cp437Grid`. - /// - /// # 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 `Cp437Grid` - /// - `this` is not written to or read from concurrently - /// - [DllImport(__DllName, EntryPoint = "sp_cp437_grid_fill", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern void sp_cp437_grid_fill(Cp437Grid* @this, byte value); - - /// - /// Gets the width of the `Cp437Grid` instance. - /// - /// # Arguments - /// - /// - `this`: instance to read from - /// - /// # Safety - /// - /// The caller has to make sure that: - /// - /// - `this` points to a valid `Cp437Grid` - /// - [DllImport(__DllName, EntryPoint = "sp_cp437_grid_width", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern nuint sp_cp437_grid_width(Cp437Grid* @this); - - /// - /// Gets the height of the `Cp437Grid` instance. - /// - /// # Arguments - /// - /// - `this`: instance to read from - /// - /// # Safety - /// - /// The caller has to make sure that: - /// - /// - `this` points to a valid `Cp437Grid` - /// - [DllImport(__DllName, EntryPoint = "sp_cp437_grid_height", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern nuint sp_cp437_grid_height(Cp437Grid* @this); - - /// - /// Gets an unsafe reference to the data of the `Cp437Grid` instance. - /// - /// ## Safety - /// - /// The caller has to make sure that: - /// - /// - `this` points to a valid `Cp437Grid` - /// - the returned memory range is never accessed after the passed `Cp437Grid` has been freed - /// - the returned memory range is never accessed concurrently, either via the `Cp437Grid` or directly - /// - [DllImport(__DllName, EntryPoint = "sp_cp437_grid_unsafe_data_ref", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern ByteSlice sp_cp437_grid_unsafe_data_ref(Cp437Grid* @this); - /// /// Tries to turn a `SPPacket` into a `SPCommand`. The packet is deallocated in the process. /// @@ -873,6 +699,241 @@ namespace ServicePoint.BindGen [DllImport(__DllName, EntryPoint = "sp_connection_dealloc", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_connection_dealloc(Connection* ptr); + /// + /// Creates a new `Cp437Grid` with the specified dimensions. + /// + /// returns: `Cp437Grid` 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_cp437_grid_dealloc`. + /// + [DllImport(__DllName, EntryPoint = "sp_cp437_grid_new", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] + public static extern Cp437Grid* sp_cp437_grid_new(nuint width, nuint height); + + /// + /// Loads a `Cp437Grid` 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_cp437_grid_dealloc`. + /// + [DllImport(__DllName, EntryPoint = "sp_cp437_grid_load", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] + public static extern Cp437Grid* sp_cp437_grid_load(nuint width, nuint height, byte* data, nuint data_length); + + /// + /// Clones a `Cp437Grid`. + /// + /// # Safety + /// + /// The caller has to make sure that: + /// + /// - `this` points to a valid `Cp437Grid` + /// - `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_cp437_grid_dealloc`. + /// + [DllImport(__DllName, EntryPoint = "sp_cp437_grid_clone", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] + public static extern Cp437Grid* sp_cp437_grid_clone(Cp437Grid* @this); + + /// + /// Deallocates a `Cp437Grid`. + /// + /// # Safety + /// + /// The caller has to make sure that: + /// + /// - `this` points to a valid `Cp437Grid` + /// - `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_cp437_grid_dealloc", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] + public static extern void sp_cp437_grid_dealloc(Cp437Grid* @this); + + /// + /// 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 `Cp437Grid` + /// - `this` is not written to concurrently + /// + [DllImport(__DllName, EntryPoint = "sp_cp437_grid_get", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] + public static extern byte sp_cp437_grid_get(Cp437Grid* @this, nuint x, nuint y); + + /// + /// Sets the value of the specified position in the `Cp437Grid`. + /// + /// # 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_cp437_grid_set", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] + public static extern void sp_cp437_grid_set(Cp437Grid* @this, nuint x, nuint y, byte value); + + /// + /// Sets the value of all cells in the `Cp437Grid`. + /// + /// # 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 `Cp437Grid` + /// - `this` is not written to or read from concurrently + /// + [DllImport(__DllName, EntryPoint = "sp_cp437_grid_fill", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] + public static extern void sp_cp437_grid_fill(Cp437Grid* @this, byte value); + + /// + /// Gets the width of the `Cp437Grid` instance. + /// + /// # Arguments + /// + /// - `this`: instance to read from + /// + /// # Safety + /// + /// The caller has to make sure that: + /// + /// - `this` points to a valid `Cp437Grid` + /// + [DllImport(__DllName, EntryPoint = "sp_cp437_grid_width", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] + public static extern nuint sp_cp437_grid_width(Cp437Grid* @this); + + /// + /// Gets the height of the `Cp437Grid` instance. + /// + /// # Arguments + /// + /// - `this`: instance to read from + /// + /// # Safety + /// + /// The caller has to make sure that: + /// + /// - `this` points to a valid `Cp437Grid` + /// + [DllImport(__DllName, EntryPoint = "sp_cp437_grid_height", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] + public static extern nuint sp_cp437_grid_height(Cp437Grid* @this); + + /// + /// Gets an unsafe reference to the data of the `Cp437Grid` instance. + /// + /// ## Safety + /// + /// The caller has to make sure that: + /// + /// - `this` points to a valid `Cp437Grid` + /// - the returned memory range is never accessed after the passed `Cp437Grid` has been freed + /// - the returned memory range is never accessed concurrently, either via the `Cp437Grid` or directly + /// + [DllImport(__DllName, EntryPoint = "sp_cp437_grid_unsafe_data_ref", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] + public static extern ByteSlice sp_cp437_grid_unsafe_data_ref(Cp437Grid* @this); + + /// + /// 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 + /// + /// # 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); + + /// + /// Clones a `Packet`. + /// + /// # Safety + /// + /// The caller has to make sure that: + /// + /// - `this` points to a valid `Packet` + /// - `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_packet_dealloc`. + /// + [DllImport(__DllName, EntryPoint = "sp_packet_clone", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] + public static extern Packet* sp_packet_clone(Packet* @this); + + /// + /// Deallocates a `Packet`. + /// + /// # Safety + /// + /// The caller has to make sure that: + /// + /// - `this` points to a valid `Packet` + /// - `this` is not used concurrently or after this call + /// + [DllImport(__DllName, EntryPoint = "sp_packet_dealloc", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] + public static extern void sp_packet_dealloc(Packet* @this); + /// /// Creates a new `PixelGrid` with the specified dimensions. /// @@ -1064,67 +1125,6 @@ namespace ServicePoint.BindGen [DllImport(__DllName, EntryPoint = "sp_pixel_grid_unsafe_data_ref", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern ByteSlice sp_pixel_grid_unsafe_data_ref(PixelGrid* @this); - /// - /// 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 - /// - /// # 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); - - /// - /// Clones a `Packet`. - /// - /// # Safety - /// - /// The caller has to make sure that: - /// - /// - `this` points to a valid `Packet` - /// - `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_packet_dealloc`. - /// - [DllImport(__DllName, EntryPoint = "sp_packet_clone", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern Packet* sp_packet_clone(Packet* @this); - - /// - /// Deallocates a `Packet`. - /// - /// # Safety - /// - /// The caller has to make sure that: - /// - /// - `this` points to a valid `Packet` - /// - `this` is not used concurrently or after this call - /// - [DllImport(__DllName, EntryPoint = "sp_packet_dealloc", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern void sp_packet_dealloc(Packet* @this); - } @@ -1139,8 +1139,10 @@ namespace ServicePoint.BindGen } [StructLayout(LayoutKind.Sequential)] - public unsafe partial struct Cp437Grid + public unsafe partial struct ByteSlice { + public byte* start; + public nuint length; } [StructLayout(LayoutKind.Sequential)] @@ -1154,22 +1156,20 @@ namespace ServicePoint.BindGen } [StructLayout(LayoutKind.Sequential)] - public unsafe partial struct PixelGrid + public unsafe partial struct Cp437Grid { } - [StructLayout(LayoutKind.Sequential)] - public unsafe partial struct ByteSlice - { - public byte* start; - public nuint length; - } - [StructLayout(LayoutKind.Sequential)] public unsafe partial struct Packet { } + [StructLayout(LayoutKind.Sequential)] + public unsafe partial struct PixelGrid + { + } + public enum CompressionCode : ushort { diff --git a/crates/servicepoint_binding_cs/build.rs b/crates/servicepoint_binding_cs/build.rs index e8fe1f5..5287698 100644 --- a/crates/servicepoint_binding_cs/build.rs +++ b/crates/servicepoint_binding_cs/build.rs @@ -1,19 +1,20 @@ //! Build script generating the C# code needed to call methods from the `servicepoint` C library. +use std::fs; + fn main() { println!("cargo::rerun-if-changed=../servicepoint_binding_c/src"); println!("cargo::rerun-if-changed=build.rs"); - csbindgen::Builder::default() - .input_extern_file("../servicepoint_binding_c/src/bit_vec.rs") - .input_extern_file("../servicepoint_binding_c/src/brightness_grid.rs") - .input_extern_file("../servicepoint_binding_c/src/cp437_grid.rs") - .input_extern_file("../servicepoint_binding_c/src/command.rs") - .input_extern_file("../servicepoint_binding_c/src/connection.rs") - .input_extern_file("../servicepoint_binding_c/src/pixel_grid.rs") - .input_extern_file("../servicepoint_binding_c/src/lib.rs") - .input_extern_file("../servicepoint_binding_c/src/byte_slice.rs") - .input_extern_file("../servicepoint_binding_c/src/packet.rs") - .input_extern_file("../servicepoint_binding_c/src/constants.rs") + + let mut builder = csbindgen::Builder::default(); + + for source in fs::read_dir("../servicepoint_binding_c/src").unwrap() { + let path = source.unwrap().path(); + println!("cargo:rerun-if-changed={}", path.display()); + builder = builder.input_extern_file(path); + } + + builder .csharp_dll_name("servicepoint_binding_c") .csharp_namespace("ServicePoint.BindGen") .csharp_use_nint_types(true) From 51b7b71cb7971844edd6df0b67609b64b1ddbba9 Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Sat, 7 Sep 2024 13:54:18 +0200 Subject: [PATCH 21/31] add test note --- CONTRIBUTING.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 06b144f..dfc1dcf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,6 +13,8 @@ Mark your PR as a draft as long as you do not want it to be merged. The main branch is supposed to be a working version, including language bindings, which means sometimes your PR may be merged into a temporary development branch. +Unit tests and documentation are required for the core library. + ## Language bindings Pull requests for your preferred language will be accepted. From f45c8090ecea9f37f3e540da8084e31b950ce3d6 Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Sat, 7 Sep 2024 13:55:27 +0200 Subject: [PATCH 22/31] fix URL --- crates/servicepoint_binding_cs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/servicepoint_binding_cs/README.md b/crates/servicepoint_binding_cs/README.md index 1248af7..0f5ee3d 100644 --- a/crates/servicepoint_binding_cs/README.md +++ b/crates/servicepoint_binding_cs/README.md @@ -39,7 +39,7 @@ Because of that, there is no NuGet package you can use directly. Including this repository as a submodule and building from source is the recommended way of using the library. ```bash -git submodule add https://github.com/kaesaecracker/servicepoint.git +git submodule add https://github.com/cccb/servicepoint.git git commit -m "add servicepoint submodule" ``` From aa359cc807962f2d1dacea8d8fade0f83ea0477c Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Sat, 7 Sep 2024 14:11:15 +0200 Subject: [PATCH 23/31] rename _dealloc to _free --- crates/servicepoint_binding_c/README.md | 4 +- .../examples/lang_c/src/main.c | 4 +- crates/servicepoint_binding_c/src/bit_vec.rs | 54 +-- .../src/brightness_grid.rs | 54 +-- crates/servicepoint_binding_c/src/command.rs | 106 ++--- .../servicepoint_binding_c/src/connection.rs | 22 +- .../servicepoint_binding_c/src/cp437_grid.rs | 54 +-- crates/servicepoint_binding_c/src/lib.rs | 4 +- crates/servicepoint_binding_c/src/packet.rs | 32 +- .../servicepoint_binding_c/src/pixel_grid.rs | 58 +-- .../ServicePoint/BindGen/ServicePoint.g.cs | 368 +++++++++--------- .../ServicePoint/BitVec.cs | 5 +- .../ServicePoint/BrightnessGrid.cs | 5 +- .../ServicePoint/Command.cs | 5 +- .../ServicePoint/Connection.cs | 5 +- .../ServicePoint/Cp437Grid.cs | 5 +- .../ServicePoint/Packet.cs | 5 +- .../ServicePoint/PixelGrid.cs | 5 +- .../ServicePoint/SpNativeInstance.cs | 4 +- 19 files changed, 389 insertions(+), 410 deletions(-) diff --git a/crates/servicepoint_binding_c/README.md b/crates/servicepoint_binding_c/README.md index 836af2e..8a8281c 100644 --- a/crates/servicepoint_binding_c/README.md +++ b/crates/servicepoint_binding_c/README.md @@ -28,8 +28,8 @@ int main(void) { SPPacket *packet = sp_packet_from_command(command); while (sp_connection_send(connection, sp_packet_clone(packet))); - sp_packet_dealloc(packet); - sp_connection_dealloc(connection); + sp_packet_free(packet); + sp_connection_free(connection); return 0; } ``` diff --git a/crates/servicepoint_binding_c/examples/lang_c/src/main.c b/crates/servicepoint_binding_c/examples/lang_c/src/main.c index 738cdfe..77ddf5a 100644 --- a/crates/servicepoint_binding_c/examples/lang_c/src/main.c +++ b/crates/servicepoint_binding_c/examples/lang_c/src/main.c @@ -13,7 +13,7 @@ int main(void) { SPPacket *packet = sp_packet_from_command(command); while (sp_connection_send(connection, sp_packet_clone(packet))); - sp_packet_dealloc(packet); - sp_connection_dealloc(connection); + sp_packet_free(packet); + sp_connection_free(connection); return 0; } diff --git a/crates/servicepoint_binding_c/src/bit_vec.rs b/crates/servicepoint_binding_c/src/bit_vec.rs index 4455cfa..f5024d1 100644 --- a/crates/servicepoint_binding_c/src/bit_vec.rs +++ b/crates/servicepoint_binding_c/src/bit_vec.rs @@ -1,4 +1,4 @@ -//! C functions for interacting with `BitVec`s +//! C functions for interacting with `SPBitVec`s //! //! prefix `sp_bit_vec_` @@ -11,7 +11,7 @@ use servicepoint::bitvec::prelude::{BitVec, Msb0}; /// ```C /// SPBitVec vec = sp_bit_vec_new(8); /// sp_bit_vec_set(vec, 5, true); -/// sp_bit_vec_dealloc(vec); +/// sp_bit_vec_free(vec); /// ``` pub struct SPBitVec(BitVec); @@ -33,13 +33,13 @@ impl Clone for SPBitVec { } } -/// Creates a new `BitVec` instance. +/// Creates a new `SPBitVec` instance. /// /// # Arguments /// /// - `size`: size in bits. /// -/// returns: `BitVec` with all bits set to false. +/// returns: `SPBitVec` with all bits set to false. /// /// # Panics /// @@ -50,13 +50,13 @@ impl Clone for SPBitVec { /// 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`. +/// by explicitly calling `sp_bit_vec_free`. #[no_mangle] pub unsafe extern "C" fn sp_bit_vec_new(size: usize) -> *mut SPBitVec { Box::into_raw(Box::new(SPBitVec(BitVec::repeat(false, size)))) } -/// Interpret the data as a series of bits and load then into a new `BitVec` instance. +/// Interpret the data as a series of bits and load then into a new `SPBitVec` instance. /// /// # Safety /// @@ -65,7 +65,7 @@ pub unsafe extern "C" fn sp_bit_vec_new(size: usize) -> *mut SPBitVec { /// - `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`. +/// by explicitly calling `sp_bit_vec_free`. #[no_mangle] pub unsafe extern "C" fn sp_bit_vec_load( data: *const u8, @@ -75,16 +75,16 @@ pub unsafe extern "C" fn sp_bit_vec_load( Box::into_raw(Box::new(SPBitVec(BitVec::from_slice(data)))) } -/// Clones a `BitVec`. +/// Clones a `SPBitVec`. /// /// # Safety /// /// The caller has to make sure that: /// -/// - `this` points to a valid `BitVec` +/// - `this` points to a valid `SPBitVec` /// - `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`. +/// by explicitly calling `sp_bit_vec_free`. #[no_mangle] pub unsafe extern "C" fn sp_bit_vec_clone( this: *const SPBitVec, @@ -92,21 +92,21 @@ pub unsafe extern "C" fn sp_bit_vec_clone( Box::into_raw(Box::new((*this).clone())) } -/// Deallocates a `BitVec`. +/// Deallocates a `SPBitVec`. /// /// # Safety /// /// The caller has to make sure that: /// -/// - `this` points to a valid `BitVec` +/// - `this` points to a valid `SPBitVec` /// - `this` is not used concurrently or after this call -/// - `this` was not passed to another consuming function, e.g. to create a `Command` +/// - `this` was not passed to another consuming function, e.g. to create a `SPCommand` #[no_mangle] -pub unsafe extern "C" fn sp_bit_vec_dealloc(this: *mut SPBitVec) { +pub unsafe extern "C" fn sp_bit_vec_free(this: *mut SPBitVec) { _ = Box::from_raw(this); } -/// Gets the value of a bit from the `BitVec`. +/// Gets the value of a bit from the `SPBitVec`. /// /// # Arguments /// @@ -123,7 +123,7 @@ pub unsafe extern "C" fn sp_bit_vec_dealloc(this: *mut SPBitVec) { /// /// The caller has to make sure that: /// -/// - `this` points to a valid `BitVec` +/// - `this` points to a valid `SPBitVec` /// - `this` is not written to concurrently #[no_mangle] pub unsafe extern "C" fn sp_bit_vec_get( @@ -133,7 +133,7 @@ pub unsafe extern "C" fn sp_bit_vec_get( *(*this).0.get(index).unwrap() } -/// Sets the value of a bit in the `BitVec`. +/// Sets the value of a bit in the `SPBitVec`. /// /// # Arguments /// @@ -151,7 +151,7 @@ pub unsafe extern "C" fn sp_bit_vec_get( /// /// The caller has to make sure that: /// -/// - `this` points to a valid `BitVec` +/// - `this` points to a valid `SPBitVec` /// - `this` is not written to or read from concurrently #[no_mangle] pub unsafe extern "C" fn sp_bit_vec_set( @@ -162,7 +162,7 @@ pub unsafe extern "C" fn sp_bit_vec_set( (*this).0.set(index, value) } -/// Sets the value of all bits in the `BitVec`. +/// Sets the value of all bits in the `SPBitVec`. /// /// # Arguments /// @@ -172,20 +172,20 @@ pub unsafe extern "C" fn sp_bit_vec_set( /// /// The caller has to make sure that: /// -/// - `this` points to a valid `BitVec` +/// - `this` points to a valid `SPBitVec` /// - `this` is not written to or read from concurrently #[no_mangle] pub unsafe extern "C" fn sp_bit_vec_fill(this: *mut SPBitVec, value: bool) { (*this).0.fill(value) } -/// Gets the length of the `BitVec` in bits. +/// Gets the length of the `SPBitVec` in bits. /// /// # Safety /// /// The caller has to make sure that: /// -/// - `this` points to a valid `BitVec` +/// - `this` points to a valid `SPBitVec` #[no_mangle] pub unsafe extern "C" fn sp_bit_vec_len(this: *const SPBitVec) -> usize { (*this).0.len() @@ -197,21 +197,21 @@ pub unsafe extern "C" fn sp_bit_vec_len(this: *const SPBitVec) -> usize { /// /// The caller has to make sure that: /// -/// - `this` points to a valid `BitVec` +/// - `this` points to a valid `SPBitVec` #[no_mangle] pub unsafe extern "C" fn sp_bit_vec_is_empty(this: *const SPBitVec) -> bool { (*this).0.is_empty() } -/// Gets an unsafe reference to the data of the `BitVec` instance. +/// Gets an unsafe reference to the data of the `SPBitVec` 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 +/// - `this` points to a valid `SPBitVec` +/// - the returned memory range is never accessed after the passed `SPBitVec` has been freed +/// - the returned memory range is never accessed concurrently, either via the `SPBitVec` or directly #[no_mangle] pub unsafe extern "C" fn sp_bit_vec_unsafe_data_ref( this: *mut SPBitVec, diff --git a/crates/servicepoint_binding_c/src/brightness_grid.rs b/crates/servicepoint_binding_c/src/brightness_grid.rs index a7d45f2..e129b94 100644 --- a/crates/servicepoint_binding_c/src/brightness_grid.rs +++ b/crates/servicepoint_binding_c/src/brightness_grid.rs @@ -1,4 +1,4 @@ -//! C functions for interacting with `BrightnessGrid`s +//! C functions for interacting with `SPBrightnessGrid`s //! //! prefix `sp_brightness_grid_` @@ -19,7 +19,7 @@ use std::intrinsics::transmute; /// sp_brightness_grid_set(grid, 1, 1, 10); /// /// SPCommand command = sp_command_char_brightness(grid); -/// sp_connection_dealloc(connection); +/// sp_connection_free(connection); /// ``` pub struct SPBrightnessGrid { pub(crate) actual: servicepoint::BrightnessGrid, @@ -33,16 +33,16 @@ impl Clone for SPBrightnessGrid { } } -/// Creates a new `BrightnessGrid` with the specified dimensions. +/// Creates a new `SPBrightnessGrid` with the specified dimensions. /// -/// returns: `BrightnessGrid` initialized to 0. +/// returns: `SPBrightnessGrid` 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_brightness_grid_dealloc`. +/// by explicitly calling `sp_brightness_grid_free`. #[no_mangle] pub unsafe extern "C" fn sp_brightness_grid_new( width: usize, @@ -53,7 +53,7 @@ pub unsafe extern "C" fn sp_brightness_grid_new( })) } -/// Loads a `BrightnessGrid` with the specified dimensions from the provided data. +/// Loads a `SPBrightnessGrid` with the specified dimensions from the provided data. /// /// # Panics /// @@ -66,7 +66,7 @@ pub unsafe extern "C" fn sp_brightness_grid_new( /// - `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_brightness_grid_dealloc`. +/// by explicitly calling `sp_brightness_grid_free`. #[no_mangle] pub unsafe extern "C" fn sp_brightness_grid_load( width: usize, @@ -81,16 +81,16 @@ pub unsafe extern "C" fn sp_brightness_grid_load( Box::into_raw(Box::new(SPBrightnessGrid { actual: grid })) } -/// Clones a `BrightnessGrid`. +/// Clones a `SPBrightnessGrid`. /// /// # Safety /// /// The caller has to make sure that: /// -/// - `this` points to a valid `BrightnessGrid` +/// - `this` points to a valid `SPBrightnessGrid` /// - `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_brightness_grid_dealloc`. +/// by explicitly calling `sp_brightness_grid_free`. #[no_mangle] pub unsafe extern "C" fn sp_brightness_grid_clone( this: *const SPBrightnessGrid, @@ -98,17 +98,17 @@ pub unsafe extern "C" fn sp_brightness_grid_clone( Box::into_raw(Box::new((*this).clone())) } -/// Deallocates a `BrightnessGrid`. +/// Deallocates a `SPBrightnessGrid`. /// /// # Safety /// /// The caller has to make sure that: /// -/// - `this` points to a valid `BrightnessGrid` +/// - `this` points to a valid `SPBrightnessGrid` /// - `this` is not used concurrently or after this call -/// - `this` was not passed to another consuming function, e.g. to create a `Command` +/// - `this` was not passed to another consuming function, e.g. to create a `SPCommand` #[no_mangle] -pub unsafe extern "C" fn sp_brightness_grid_dealloc( +pub unsafe extern "C" fn sp_brightness_grid_free( this: *mut SPBrightnessGrid, ) { _ = Box::from_raw(this); @@ -129,7 +129,7 @@ pub unsafe extern "C" fn sp_brightness_grid_dealloc( /// /// The caller has to make sure that: /// -/// - `this` points to a valid `BrightnessGrid` +/// - `this` points to a valid `SPBrightnessGrid` /// - `this` is not written to concurrently #[no_mangle] pub unsafe extern "C" fn sp_brightness_grid_get( @@ -140,7 +140,7 @@ pub unsafe extern "C" fn sp_brightness_grid_get( (*this).actual.get(x, y).into() } -/// Sets the value of the specified position in the `BrightnessGrid`. +/// Sets the value of the specified position in the `SPBrightnessGrid`. /// /// # Arguments /// @@ -159,7 +159,7 @@ pub unsafe extern "C" fn sp_brightness_grid_get( /// /// The caller has to make sure that: /// -/// - `this` points to a valid `BitVec` +/// - `this` points to a valid `SPBitVec` /// - `this` is not written to or read from concurrently #[no_mangle] pub unsafe extern "C" fn sp_brightness_grid_set( @@ -173,7 +173,7 @@ pub unsafe extern "C" fn sp_brightness_grid_set( (*this).actual.set(x, y, brightness); } -/// Sets the value of all cells in the `BrightnessGrid`. +/// Sets the value of all cells in the `SPBrightnessGrid`. /// /// # Arguments /// @@ -188,7 +188,7 @@ pub unsafe extern "C" fn sp_brightness_grid_set( /// /// The caller has to make sure that: /// -/// - `this` points to a valid `BrightnessGrid` +/// - `this` points to a valid `SPBrightnessGrid` /// - `this` is not written to or read from concurrently #[no_mangle] pub unsafe extern "C" fn sp_brightness_grid_fill( @@ -200,7 +200,7 @@ pub unsafe extern "C" fn sp_brightness_grid_fill( (*this).actual.fill(brightness); } -/// Gets the width of the `BrightnessGrid` instance. +/// Gets the width of the `SPBrightnessGrid` instance. /// /// # Arguments /// @@ -210,7 +210,7 @@ pub unsafe extern "C" fn sp_brightness_grid_fill( /// /// The caller has to make sure that: /// -/// - `this` points to a valid `BrightnessGrid` +/// - `this` points to a valid `SPBrightnessGrid` #[no_mangle] pub unsafe extern "C" fn sp_brightness_grid_width( this: *const SPBrightnessGrid, @@ -218,7 +218,7 @@ pub unsafe extern "C" fn sp_brightness_grid_width( (*this).actual.width() } -/// Gets the height of the `BrightnessGrid` instance. +/// Gets the height of the `SPBrightnessGrid` instance. /// /// # Arguments /// @@ -228,7 +228,7 @@ pub unsafe extern "C" fn sp_brightness_grid_width( /// /// The caller has to make sure that: /// -/// - `this` points to a valid `BrightnessGrid` +/// - `this` points to a valid `SPBrightnessGrid` #[no_mangle] pub unsafe extern "C" fn sp_brightness_grid_height( this: *const SPBrightnessGrid, @@ -236,15 +236,15 @@ pub unsafe extern "C" fn sp_brightness_grid_height( (*this).actual.height() } -/// Gets an unsafe reference to the data of the `BrightnessGrid` instance. +/// Gets an unsafe reference to the data of the `SPBrightnessGrid` instance. /// /// ## Safety /// /// The caller has to make sure that: /// -/// - `this` points to a valid `BrightnessGrid` -/// - the returned memory range is never accessed after the passed `BrightnessGrid` has been freed -/// - the returned memory range is never accessed concurrently, either via the `BrightnessGrid` or directly +/// - `this` points to a valid `SPBrightnessGrid` +/// - the returned memory range is never accessed after the passed `SPBrightnessGrid` has been freed +/// - the returned memory range is never accessed concurrently, either via the `SPBrightnessGrid` or directly #[no_mangle] pub unsafe extern "C" fn sp_brightness_grid_unsafe_data_ref( this: *mut SPBrightnessGrid, diff --git a/crates/servicepoint_binding_c/src/command.rs b/crates/servicepoint_binding_c/src/command.rs index 3ece0f1..7e92bf0 100644 --- a/crates/servicepoint_binding_c/src/command.rs +++ b/crates/servicepoint_binding_c/src/command.rs @@ -1,4 +1,4 @@ -//! C functions for interacting with `Command`s +//! C functions for interacting with `SPCommand`s //! //! prefix `sp_command_` @@ -39,11 +39,11 @@ impl Clone for SPCommand { /// /// The caller has to make sure that: /// -/// - `packet` points to a valid instance of `SPPacket` -/// - `packet` is not used concurrently or after this call +/// - `SPPacket` points to a valid instance of `SPPacket` +/// - `SPPacket` is not used concurrently or after this call /// - the result is checked for NULL /// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or -/// by explicitly calling `sp_command_dealloc`. +/// by explicitly calling `sp_command_free`. #[no_mangle] pub unsafe extern "C" fn sp_command_try_from_packet( packet: *mut SPPacket, @@ -61,10 +61,10 @@ pub unsafe extern "C" fn sp_command_try_from_packet( /// /// The caller has to make sure that: /// -/// - `this` points to a valid instance of `Command` +/// - `this` points to a valid instance of `SPCommand` /// - `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`. +/// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_command_free`. #[no_mangle] pub unsafe extern "C" fn sp_command_clone( original: *const SPCommand, @@ -86,8 +86,8 @@ pub unsafe extern "C" fn sp_command_clone( /// /// 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`. +/// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_command_free`. #[no_mangle] pub unsafe extern "C" fn sp_command_clear() -> *mut SPCommand { Box::into_raw(Box::new(SPCommand(servicepoint::Command::Clear))) @@ -102,8 +102,8 @@ pub unsafe extern "C" fn sp_command_clear() -> *mut SPCommand { /// /// 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`. +/// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_command_free`. #[no_mangle] pub unsafe extern "C" fn sp_command_hard_reset() -> *mut SPCommand { Box::into_raw(Box::new(SPCommand(servicepoint::Command::HardReset))) @@ -115,8 +115,8 @@ pub unsafe extern "C" fn sp_command_hard_reset() -> *mut SPCommand { /// /// 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`. +/// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_command_free`. #[no_mangle] pub unsafe extern "C" fn sp_command_fade_out() -> *mut SPCommand { Box::into_raw(Box::new(SPCommand(servicepoint::Command::FadeOut))) @@ -134,7 +134,7 @@ pub unsafe extern "C" fn sp_command_fade_out() -> *mut SPCommand { /// The caller has to make sure that: /// /// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or -/// by explicitly calling `sp_command_dealloc`. +/// by explicitly calling `sp_command_free`. #[no_mangle] pub unsafe extern "C" fn sp_command_brightness( brightness: u8, @@ -157,8 +157,8 @@ pub unsafe extern "C" fn sp_command_brightness( /// /// - `grid` points to a valid instance of `SPBrightnessGrid` /// - `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`. +/// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_command_free`. #[no_mangle] pub unsafe extern "C" fn sp_command_char_brightness( x: usize, @@ -173,24 +173,24 @@ pub unsafe extern "C" fn sp_command_char_brightness( } /// Allocates a new `Command::BitmapLinear` instance. -/// The passed `BitVec` gets consumed. +/// The passed `SPBitVec` gets consumed. /// /// Set pixel data starting at the pixel offset on screen. /// /// The screen will continuously overwrite more pixel data without regarding the offset, meaning /// once the starting row is full, overwriting will continue on column 0. /// -/// The contained `BitVec` is always uncompressed. +/// The contained `SPBitVec` is always uncompressed. /// /// # Safety /// /// The caller has to make sure that: /// -/// - `bit_vec` points to a valid instance of `BitVec` +/// - `bit_vec` points to a valid instance of `SPBitVec` /// - `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`. +/// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_command_free`. #[no_mangle] pub unsafe extern "C" fn sp_command_bitmap_linear( offset: usize, @@ -206,24 +206,24 @@ pub unsafe extern "C" fn sp_command_bitmap_linear( } /// Allocates a new `Command::BitmapLinearAnd` instance. -/// The passed `BitVec` gets consumed. +/// The passed `SPBitVec` gets consumed. /// /// Set pixel data according to an and-mask starting at the offset. /// /// The screen will continuously overwrite more pixel data without regarding the offset, meaning /// once the starting row is full, overwriting will continue on column 0. /// -/// The contained `BitVec` is always uncompressed. +/// The contained `SPBitVec` is always uncompressed. /// /// # Safety /// /// The caller has to make sure that: /// -/// - `bit_vec` points to a valid instance of `BitVec` +/// - `bit_vec` points to a valid instance of `SPBitVec` /// - `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`. +/// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_command_free`. #[no_mangle] pub unsafe extern "C" fn sp_command_bitmap_linear_and( offset: usize, @@ -239,24 +239,24 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_and( } /// Allocates a new `Command::BitmapLinearOr` instance. -/// The passed `BitVec` gets consumed. +/// The passed `SPBitVec` gets consumed. /// /// Set pixel data according to an or-mask starting at the offset. /// /// The screen will continuously overwrite more pixel data without regarding the offset, meaning /// once the starting row is full, overwriting will continue on column 0. /// -/// The contained `BitVec` is always uncompressed. +/// The contained `SPBitVec` is always uncompressed. /// /// # Safety /// /// The caller has to make sure that: /// -/// - `bit_vec` points to a valid instance of `BitVec` +/// - `bit_vec` points to a valid instance of `SPBitVec` /// - `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`. +/// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_command_free`. #[no_mangle] pub unsafe extern "C" fn sp_command_bitmap_linear_or( offset: usize, @@ -272,24 +272,24 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_or( } /// Allocates a new `Command::BitmapLinearXor` instance. -/// The passed `BitVec` gets consumed. +/// The passed `SPBitVec` gets consumed. /// /// Set pixel data according to a xor-mask starting at the offset. /// /// The screen will continuously overwrite more pixel data without regarding the offset, meaning /// once the starting row is full, overwriting will continue on column 0. /// -/// The contained `BitVec` is always uncompressed. +/// The contained `SPBitVec` is always uncompressed. /// /// # Safety /// /// The caller has to make sure that: /// -/// - `bit_vec` points to a valid instance of `BitVec` +/// - `bit_vec` points to a valid instance of `SPBitVec` /// - `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`. +/// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_command_free`. #[no_mangle] pub unsafe extern "C" fn sp_command_bitmap_linear_xor( offset: usize, @@ -305,7 +305,7 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_xor( } /// Allocates a new `Command::Cp437Data` instance. -/// The passed `ByteGrid` gets consumed. +/// The passed `SPCp437Grid` gets consumed. /// /// Show text on the screen. /// @@ -318,25 +318,25 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_xor( /// /// 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`. +/// - `grid` points to a valid instance of `SPCp437Grid` +/// - `grid` is not used concurrently or after this call +/// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_command_free`. #[no_mangle] pub unsafe extern "C" fn sp_command_cp437_data( x: usize, y: usize, - byte_grid: *mut SPCp437Grid, + grid: *mut SPCp437Grid, ) -> *mut SPCommand { - let byte_grid = *Box::from_raw(byte_grid); + let grid = *Box::from_raw(grid); Box::into_raw(Box::new(SPCommand(servicepoint::Command::Cp437Data( Origin::new(x, y), - byte_grid.actual, + grid.actual, )))) } /// Allocates a new `Command::BitmapLinearWin` instance. -/// The passed `PixelGrid` gets consumed. +/// The passed `SPPixelGrid` gets consumed. /// /// Sets a window of pixels to the specified values /// @@ -344,11 +344,11 @@ pub unsafe extern "C" fn sp_command_cp437_data( /// /// The caller has to make sure that: /// -/// - `pixel_grid` points to a valid instance of `PixelGrid` +/// - `pixel_grid` points to a valid instance of `SPPixelGrid` /// - `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`. +/// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_command_free`. #[no_mangle] pub unsafe extern "C" fn sp_command_bitmap_linear_win( x: usize, @@ -366,23 +366,23 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_win( )))) } -/// Deallocates a `Command`. +/// Deallocates a `SPCommand`. /// /// # Examples /// /// ```C /// SPCommand c = sp_command_clear(); -/// sp_command_dealloc(c); +/// sp_command_free(c); /// ``` /// /// # Safety /// /// The caller has to make sure that: /// -/// - `this` points to a valid `Command` +/// - `this` points to a valid `SPCommand` /// - `this` is not used concurrently or after this call -/// - `this` was not passed to another consuming function, e.g. to create a `Packet` +/// - `this` was not passed to another consuming function, e.g. to create a `SPPacket` #[no_mangle] -pub unsafe extern "C" fn sp_command_dealloc(ptr: *mut SPCommand) { +pub unsafe extern "C" fn sp_command_free(ptr: *mut SPCommand) { _ = Box::from_raw(ptr); } diff --git a/crates/servicepoint_binding_c/src/connection.rs b/crates/servicepoint_binding_c/src/connection.rs index ae82831..a6bd5a0 100644 --- a/crates/servicepoint_binding_c/src/connection.rs +++ b/crates/servicepoint_binding_c/src/connection.rs @@ -1,4 +1,4 @@ -//! C functions for interacting with `Connection`s +//! C functions for interacting with `SPConnection`s //! //! prefix `sp_connection_` @@ -18,7 +18,7 @@ use crate::SPPacket; /// ``` pub struct SPConnection(pub(crate) servicepoint::Connection); -/// Creates a new instance of `Connection`. +/// Creates a new instance of `SPConnection`. /// /// returns: NULL if connection fails, or connected instance /// @@ -31,7 +31,7 @@ pub struct SPConnection(pub(crate) servicepoint::Connection); /// 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`. +/// by explicitly calling `sp_connection_free`. #[no_mangle] pub unsafe extern "C" fn sp_connection_open( host: *const c_char, @@ -45,8 +45,8 @@ pub unsafe extern "C" fn sp_connection_open( Box::into_raw(Box::new(SPConnection(connection))) } -/// Sends a `Packet` to the display using the `Connection`. -/// The passed `Packet` gets consumed. +/// Sends a `SPPacket` to the display using the `SPConnection`. +/// The passed `SPPacket` gets consumed. /// /// returns: true in case of success /// @@ -54,9 +54,9 @@ pub unsafe extern "C" fn sp_connection_open( /// /// 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 +/// - `SPConnection` points to a valid instance of `SPConnection` +/// - `SPPacket` points to a valid instance of `SPPacket` +/// - `SPPacket` is not used concurrently or after this call #[no_mangle] pub unsafe extern "C" fn sp_connection_send( connection: *const SPConnection, @@ -66,15 +66,15 @@ pub unsafe extern "C" fn sp_connection_send( (*connection).0.send((*packet).0).is_ok() } -/// Closes and deallocates a `Connection`. +/// Closes and deallocates a `SPConnection`. /// /// # Safety /// /// The caller has to make sure that: /// -/// - `this` points to a valid `Connection` +/// - `this` points to a valid `SPConnection` /// - `this` is not used concurrently or after this call #[no_mangle] -pub unsafe extern "C" fn sp_connection_dealloc(ptr: *mut SPConnection) { +pub unsafe extern "C" fn sp_connection_free(ptr: *mut SPConnection) { _ = Box::from_raw(ptr); } diff --git a/crates/servicepoint_binding_c/src/cp437_grid.rs b/crates/servicepoint_binding_c/src/cp437_grid.rs index 963456d..7d24f0b 100644 --- a/crates/servicepoint_binding_c/src/cp437_grid.rs +++ b/crates/servicepoint_binding_c/src/cp437_grid.rs @@ -1,4 +1,4 @@ -//! C functions for interacting with `Cp437Grid`s +//! C functions for interacting with `SPCp437Grid`s //! //! prefix `sp_cp437_grid_` @@ -15,7 +15,7 @@ use servicepoint::{DataRef, Grid}; /// Cp437Grid grid = sp_cp437_grid_new(4, 3); /// sp_cp437_grid_fill(grid, '?'); /// sp_cp437_grid_set(grid, 0, 0, '!'); -/// sp_cp437_grid_dealloc(grid); +/// sp_cp437_grid_free(grid); /// ``` pub struct SPCp437Grid { pub(crate) actual: servicepoint::Cp437Grid, @@ -29,16 +29,16 @@ impl Clone for SPCp437Grid { } } -/// Creates a new `Cp437Grid` with the specified dimensions. +/// Creates a new `SPCp437Grid` with the specified dimensions. /// -/// returns: `Cp437Grid` initialized to 0. +/// returns: `SPCp437Grid` 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_cp437_grid_dealloc`. +/// by explicitly calling `sp_cp437_grid_free`. #[no_mangle] pub unsafe extern "C" fn sp_cp437_grid_new( width: usize, @@ -49,7 +49,7 @@ pub unsafe extern "C" fn sp_cp437_grid_new( })) } -/// Loads a `Cp437Grid` with the specified dimensions from the provided data. +/// Loads a `SPCp437Grid` with the specified dimensions from the provided data. /// /// # Panics /// @@ -62,7 +62,7 @@ pub unsafe extern "C" fn sp_cp437_grid_new( /// - `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_cp437_grid_dealloc`. +/// by explicitly calling `sp_cp437_grid_free`. #[no_mangle] pub unsafe extern "C" fn sp_cp437_grid_load( width: usize, @@ -76,16 +76,16 @@ pub unsafe extern "C" fn sp_cp437_grid_load( })) } -/// Clones a `Cp437Grid`. +/// Clones a `SPCp437Grid`. /// /// # Safety /// /// The caller has to make sure that: /// -/// - `this` points to a valid `Cp437Grid` +/// - `this` points to a valid `SPCp437Grid` /// - `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_cp437_grid_dealloc`. +/// by explicitly calling `sp_cp437_grid_free`. #[no_mangle] pub unsafe extern "C" fn sp_cp437_grid_clone( this: *const SPCp437Grid, @@ -93,17 +93,17 @@ pub unsafe extern "C" fn sp_cp437_grid_clone( Box::into_raw(Box::new((*this).clone())) } -/// Deallocates a `Cp437Grid`. +/// Deallocates a `SPCp437Grid`. /// /// # Safety /// /// The caller has to make sure that: /// -/// - `this` points to a valid `Cp437Grid` +/// - `this` points to a valid `SPCp437Grid` /// - `this` is not used concurrently or after this call -/// - `this` was not passed to another consuming function, e.g. to create a `Command` +/// - `this` was not passed to another consuming function, e.g. to create a `SPCommand` #[no_mangle] -pub unsafe extern "C" fn sp_cp437_grid_dealloc(this: *mut SPCp437Grid) { +pub unsafe extern "C" fn sp_cp437_grid_free(this: *mut SPCp437Grid) { _ = Box::from_raw(this); } @@ -122,7 +122,7 @@ pub unsafe extern "C" fn sp_cp437_grid_dealloc(this: *mut SPCp437Grid) { /// /// The caller has to make sure that: /// -/// - `this` points to a valid `Cp437Grid` +/// - `this` points to a valid `SPCp437Grid` /// - `this` is not written to concurrently #[no_mangle] pub unsafe extern "C" fn sp_cp437_grid_get( @@ -133,7 +133,7 @@ pub unsafe extern "C" fn sp_cp437_grid_get( (*this).actual.get(x, y) } -/// Sets the value of the specified position in the `Cp437Grid`. +/// Sets the value of the specified position in the `SPCp437Grid`. /// /// # Arguments /// @@ -151,7 +151,7 @@ pub unsafe extern "C" fn sp_cp437_grid_get( /// /// The caller has to make sure that: /// -/// - `this` points to a valid `BitVec` +/// - `this` points to a valid `SPBitVec` /// - `this` is not written to or read from concurrently #[no_mangle] pub unsafe extern "C" fn sp_cp437_grid_set( @@ -163,7 +163,7 @@ pub unsafe extern "C" fn sp_cp437_grid_set( (*this).actual.set(x, y, value); } -/// Sets the value of all cells in the `Cp437Grid`. +/// Sets the value of all cells in the `SPCp437Grid`. /// /// # Arguments /// @@ -174,14 +174,14 @@ pub unsafe extern "C" fn sp_cp437_grid_set( /// /// The caller has to make sure that: /// -/// - `this` points to a valid `Cp437Grid` +/// - `this` points to a valid `SPCp437Grid` /// - `this` is not written to or read from concurrently #[no_mangle] pub unsafe extern "C" fn sp_cp437_grid_fill(this: *mut SPCp437Grid, value: u8) { (*this).actual.fill(value); } -/// Gets the width of the `Cp437Grid` instance. +/// Gets the width of the `SPCp437Grid` instance. /// /// # Arguments /// @@ -191,7 +191,7 @@ pub unsafe extern "C" fn sp_cp437_grid_fill(this: *mut SPCp437Grid, value: u8) { /// /// The caller has to make sure that: /// -/// - `this` points to a valid `Cp437Grid` +/// - `this` points to a valid `SPCp437Grid` #[no_mangle] pub unsafe extern "C" fn sp_cp437_grid_width( this: *const SPCp437Grid, @@ -199,7 +199,7 @@ pub unsafe extern "C" fn sp_cp437_grid_width( (*this).actual.width() } -/// Gets the height of the `Cp437Grid` instance. +/// Gets the height of the `SPCp437Grid` instance. /// /// # Arguments /// @@ -209,7 +209,7 @@ pub unsafe extern "C" fn sp_cp437_grid_width( /// /// The caller has to make sure that: /// -/// - `this` points to a valid `Cp437Grid` +/// - `this` points to a valid `SPCp437Grid` #[no_mangle] pub unsafe extern "C" fn sp_cp437_grid_height( this: *const SPCp437Grid, @@ -217,15 +217,15 @@ pub unsafe extern "C" fn sp_cp437_grid_height( (*this).actual.height() } -/// Gets an unsafe reference to the data of the `Cp437Grid` instance. +/// Gets an unsafe reference to the data of the `SPCp437Grid` instance. /// /// ## Safety /// /// The caller has to make sure that: /// -/// - `this` points to a valid `Cp437Grid` -/// - the returned memory range is never accessed after the passed `Cp437Grid` has been freed -/// - the returned memory range is never accessed concurrently, either via the `Cp437Grid` or directly +/// - `this` points to a valid `SPCp437Grid` +/// - the returned memory range is never accessed after the passed `SPCp437Grid` has been freed +/// - the returned memory range is never accessed concurrently, either via the `SPCp437Grid` or directly #[no_mangle] pub unsafe extern "C" fn sp_cp437_grid_unsafe_data_ref( this: *mut SPCp437Grid, diff --git a/crates/servicepoint_binding_c/src/lib.rs b/crates/servicepoint_binding_c/src/lib.rs index 159b64d..6d38abc 100644 --- a/crates/servicepoint_binding_c/src/lib.rs +++ b/crates/servicepoint_binding_c/src/lib.rs @@ -20,8 +20,8 @@ //! SPPacket *packet = sp_packet_from_command(command); //! while (sp_connection_send(connection, sp_packet_clone(packet))); //! -//! sp_packet_dealloc(packet); -//! sp_connection_dealloc(connection); +//! sp_packet_free(packet); +//! sp_connection_free(connection); //! return 0; //! } //! ``` diff --git a/crates/servicepoint_binding_c/src/packet.rs b/crates/servicepoint_binding_c/src/packet.rs index c575de7..0a2bdef 100644 --- a/crates/servicepoint_binding_c/src/packet.rs +++ b/crates/servicepoint_binding_c/src/packet.rs @@ -1,4 +1,4 @@ -//! C functions for interacting with `Packet`s +//! C functions for interacting with `SPPacket`s //! //! prefix `sp_packet_` @@ -9,17 +9,17 @@ use crate::SPCommand; /// The raw packet pub struct SPPacket(pub(crate) servicepoint::Packet); -/// Turns a `Command` into a `Packet`. -/// The `Command` gets consumed. +/// Turns a `SPCommand` into a `SPPacket`. +/// The `SPCommand` 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`. +/// - `SPCommand` points to a valid instance of `SPCommand` +/// - `SPCommand` is not used concurrently or after this call +/// - the returned `SPPacket` instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_packet_free`. #[no_mangle] pub unsafe extern "C" fn sp_packet_from_command( command: *mut SPCommand, @@ -29,7 +29,7 @@ pub unsafe extern "C" fn sp_packet_from_command( Box::into_raw(Box::new(packet)) } -/// Tries to load a `Packet` from the passed array with the specified length. +/// Tries to load a `SPPacket` from the passed array with the specified length. /// /// returns: NULL in case of an error, pointer to the allocated packet otherwise /// @@ -39,8 +39,8 @@ pub unsafe extern "C" fn sp_packet_from_command( /// /// - `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`. +/// - the returned `SPPacket` instance is freed in some way, either by using a consuming function or +/// by explicitly calling `sp_packet_free`. #[no_mangle] pub unsafe extern "C" fn sp_packet_try_load( data: *const u8, @@ -53,16 +53,16 @@ pub unsafe extern "C" fn sp_packet_try_load( } } -/// Clones a `Packet`. +/// Clones a `SPPacket`. /// /// # Safety /// /// The caller has to make sure that: /// -/// - `this` points to a valid `Packet` +/// - `this` points to a valid `SPPacket` /// - `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_packet_dealloc`. +/// by explicitly calling `sp_packet_free`. #[no_mangle] pub unsafe extern "C" fn sp_packet_clone( this: *const SPPacket, @@ -70,15 +70,15 @@ pub unsafe extern "C" fn sp_packet_clone( Box::into_raw(Box::new(SPPacket((*this).0.clone()))) } -/// Deallocates a `Packet`. +/// Deallocates a `SPPacket`. /// /// # Safety /// /// The caller has to make sure that: /// -/// - `this` points to a valid `Packet` +/// - `this` points to a valid `SPPacket` /// - `this` is not used concurrently or after this call #[no_mangle] -pub unsafe extern "C" fn sp_packet_dealloc(this: *mut SPPacket) { +pub unsafe extern "C" fn sp_packet_free(this: *mut SPPacket) { _ = Box::from_raw(this) } diff --git a/crates/servicepoint_binding_c/src/pixel_grid.rs b/crates/servicepoint_binding_c/src/pixel_grid.rs index d8b4a32..2f6e00a 100644 --- a/crates/servicepoint_binding_c/src/pixel_grid.rs +++ b/crates/servicepoint_binding_c/src/pixel_grid.rs @@ -1,4 +1,4 @@ -//! C functions for interacting with `PixelGrid`s +//! C functions for interacting with `SPPixelGrid`s //! //! prefix `sp_pixel_grid_` @@ -14,18 +14,18 @@ use crate::byte_slice::SPByteSlice; /// Cp437Grid grid = sp_pixel_grid_new(8, 3); /// sp_pixel_grid_fill(grid, true); /// sp_pixel_grid_set(grid, 0, 0, false); -/// sp_pixel_grid_dealloc(grid); +/// sp_pixel_grid_free(grid); /// ``` pub struct SPPixelGrid(pub(crate) servicepoint::PixelGrid); -/// Creates a new `PixelGrid` with the specified dimensions. +/// Creates a new `SPPixelGrid` with the specified dimensions. /// /// # Arguments /// /// - `width`: size in pixels in x-direction /// - `height`: size in pixels in y-direction /// -/// returns: `PixelGrid` initialized to all pixels off +/// returns: `SPPixelGrid` initialized to all pixels off /// /// # Panics /// @@ -36,7 +36,7 @@ pub struct SPPixelGrid(pub(crate) servicepoint::PixelGrid); /// 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`. +/// by explicitly calling `sp_pixel_grid_free`. #[no_mangle] pub unsafe extern "C" fn sp_pixel_grid_new( width: usize, @@ -47,14 +47,14 @@ pub unsafe extern "C" fn sp_pixel_grid_new( )))) } -/// Loads a `PixelGrid` with the specified dimensions from the provided data. +/// Loads a `SPPixelGrid` with the specified dimensions from the provided data. /// /// # Arguments /// /// - `width`: size in pixels in x-direction /// - `height`: size in pixels in y-direction /// -/// returns: `PixelGrid` that contains a copy of the provided data +/// returns: `SPPixelGrid` that contains a copy of the provided data /// /// # Panics /// @@ -67,7 +67,7 @@ pub unsafe extern "C" fn sp_pixel_grid_new( /// /// - `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`. +/// by explicitly calling `sp_pixel_grid_free`. #[no_mangle] pub unsafe extern "C" fn sp_pixel_grid_load( width: usize, @@ -81,16 +81,16 @@ pub unsafe extern "C" fn sp_pixel_grid_load( )))) } -/// Clones a `PixelGrid`. +/// Clones a `SPPixelGrid`. /// /// # Safety /// /// The caller has to make sure that: /// -/// - `this` points to a valid `PixelGrid` +/// - `this` points to a valid `SPPixelGrid` /// - `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`. +/// by explicitly calling `sp_pixel_grid_free`. #[no_mangle] pub unsafe extern "C" fn sp_pixel_grid_clone( this: *const SPPixelGrid, @@ -98,21 +98,21 @@ pub unsafe extern "C" fn sp_pixel_grid_clone( Box::into_raw(Box::new(SPPixelGrid((*this).0.clone()))) } -/// Deallocates a `PixelGrid`. +/// Deallocates a `SPPixelGrid`. /// /// # Safety /// /// The caller has to make sure that: /// -/// - `this` points to a valid `PixelGrid` +/// - `this` points to a valid `SPPixelGrid` /// - `this` is not used concurrently or after this call -/// - `this` was not passed to another consuming function, e.g. to create a `Command` +/// - `this` was not passed to another consuming function, e.g. to create a `SPCommand` #[no_mangle] -pub unsafe extern "C" fn sp_pixel_grid_dealloc(this: *mut SPPixelGrid) { +pub unsafe extern "C" fn sp_pixel_grid_free(this: *mut SPPixelGrid) { _ = Box::from_raw(this); } -/// Gets the current value at the specified position in the `PixelGrid`. +/// Gets the current value at the specified position in the `SPPixelGrid`. /// /// # Arguments /// @@ -127,7 +127,7 @@ pub unsafe extern "C" fn sp_pixel_grid_dealloc(this: *mut SPPixelGrid) { /// /// The caller has to make sure that: /// -/// - `this` points to a valid `PixelGrid` +/// - `this` points to a valid `SPPixelGrid` /// - `this` is not written to concurrently #[no_mangle] pub unsafe extern "C" fn sp_pixel_grid_get( @@ -138,7 +138,7 @@ pub unsafe extern "C" fn sp_pixel_grid_get( (*this).0.get(x, y) } -/// Sets the value of the specified position in the `PixelGrid`. +/// Sets the value of the specified position in the `SPPixelGrid`. /// /// # Arguments /// @@ -156,7 +156,7 @@ pub unsafe extern "C" fn sp_pixel_grid_get( /// /// The caller has to make sure that: /// -/// - `this` points to a valid `PixelGrid` +/// - `this` points to a valid `SPPixelGrid` /// - `this` is not written to or read from concurrently #[no_mangle] pub unsafe extern "C" fn sp_pixel_grid_set( @@ -168,7 +168,7 @@ pub unsafe extern "C" fn sp_pixel_grid_set( (*this).0.set(x, y, value); } -/// Sets the state of all pixels in the `PixelGrid`. +/// Sets the state of all pixels in the `SPPixelGrid`. /// /// # Arguments /// @@ -179,7 +179,7 @@ pub unsafe extern "C" fn sp_pixel_grid_set( /// /// The caller has to make sure that: /// -/// - `this` points to a valid `PixelGrid` +/// - `this` points to a valid `SPPixelGrid` /// - `this` is not written to or read from concurrently #[no_mangle] pub unsafe extern "C" fn sp_pixel_grid_fill( @@ -189,7 +189,7 @@ pub unsafe extern "C" fn sp_pixel_grid_fill( (*this).0.fill(value); } -/// Gets the width in pixels of the `PixelGrid` instance. +/// Gets the width in pixels of the `SPPixelGrid` instance. /// /// # Arguments /// @@ -199,7 +199,7 @@ pub unsafe extern "C" fn sp_pixel_grid_fill( /// /// The caller has to make sure that: /// -/// - `this` points to a valid `PixelGrid` +/// - `this` points to a valid `SPPixelGrid` #[no_mangle] pub unsafe extern "C" fn sp_pixel_grid_width( this: *const SPPixelGrid, @@ -207,7 +207,7 @@ pub unsafe extern "C" fn sp_pixel_grid_width( (*this).0.width() } -/// Gets the height in pixels of the `PixelGrid` instance. +/// Gets the height in pixels of the `SPPixelGrid` instance. /// /// # Arguments /// @@ -217,7 +217,7 @@ pub unsafe extern "C" fn sp_pixel_grid_width( /// /// The caller has to make sure that: /// -/// - `this` points to a valid `PixelGrid` +/// - `this` points to a valid `SPPixelGrid` #[no_mangle] pub unsafe extern "C" fn sp_pixel_grid_height( this: *const SPPixelGrid, @@ -225,15 +225,15 @@ pub unsafe extern "C" fn sp_pixel_grid_height( (*this).0.height() } -/// Gets an unsafe reference to the data of the `PixelGrid` instance. +/// Gets an unsafe reference to the data of the `SPPixelGrid` 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 +/// - `this` points to a valid `SPPixelGrid` +/// - the returned memory range is never accessed after the passed `SPPixelGrid` has been freed +/// - the returned memory range is never accessed concurrently, either via the `SPPixelGrid` or directly #[no_mangle] pub unsafe extern "C" fn sp_pixel_grid_unsafe_data_ref( this: *mut SPPixelGrid, diff --git a/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs b/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs index fd7e1d3..8183a4d 100644 --- a/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs +++ b/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs @@ -20,13 +20,13 @@ namespace ServicePoint.BindGen /// - /// Creates a new `BitVec` instance. + /// Creates a new `SPBitVec` instance. /// /// # Arguments /// /// - `size`: size in bits. /// - /// returns: `BitVec` with all bits set to false. + /// returns: `SPBitVec` with all bits set to false. /// /// # Panics /// @@ -37,13 +37,13 @@ namespace ServicePoint.BindGen /// 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`. + /// by explicitly calling `sp_bit_vec_free`. /// [DllImport(__DllName, EntryPoint = "sp_bit_vec_new", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern BitVec* sp_bit_vec_new(nuint size); /// - /// Interpret the data as a series of bits and load then into a new `BitVec` instance. + /// Interpret the data as a series of bits and load then into a new `SPBitVec` instance. /// /// # Safety /// @@ -52,42 +52,42 @@ namespace ServicePoint.BindGen /// - `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`. + /// by explicitly calling `sp_bit_vec_free`. /// [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`. + /// Clones a `SPBitVec`. /// /// # Safety /// /// The caller has to make sure that: /// - /// - `this` points to a valid `BitVec` + /// - `this` points to a valid `SPBitVec` /// - `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`. + /// by explicitly calling `sp_bit_vec_free`. /// [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`. + /// Deallocates a `SPBitVec`. /// /// # Safety /// /// The caller has to make sure that: /// - /// - `this` points to a valid `BitVec` + /// - `this` points to a valid `SPBitVec` /// - `this` is not used concurrently or after this call - /// - `this` was not passed to another consuming function, e.g. to create a `Command` + /// - `this` was not passed to another consuming function, e.g. to create a `SPCommand` /// - [DllImport(__DllName, EntryPoint = "sp_bit_vec_dealloc", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern void sp_bit_vec_dealloc(BitVec* @this); + [DllImport(__DllName, EntryPoint = "sp_bit_vec_free", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] + public static extern void sp_bit_vec_free(BitVec* @this); /// - /// Gets the value of a bit from the `BitVec`. + /// Gets the value of a bit from the `SPBitVec`. /// /// # Arguments /// @@ -104,7 +104,7 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `BitVec` + /// - `this` points to a valid `SPBitVec` /// - `this` is not written to concurrently /// [DllImport(__DllName, EntryPoint = "sp_bit_vec_get", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] @@ -112,7 +112,7 @@ namespace ServicePoint.BindGen 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 `SPBitVec`. /// /// # Arguments /// @@ -130,14 +130,14 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `BitVec` + /// - `this` points to a valid `SPBitVec` /// - `this` is not written to or read from concurrently /// [DllImport(__DllName, EntryPoint = "sp_bit_vec_set", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void 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 `SPBitVec`. /// /// # Arguments /// @@ -147,20 +147,20 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `BitVec` + /// - `this` points to a valid `SPBitVec` /// - `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 `SPBitVec` in bits. /// /// # Safety /// /// The caller has to make sure that: /// - /// - `this` points to a valid `BitVec` + /// - `this` points to a valid `SPBitVec` /// [DllImport(__DllName, EntryPoint = "sp_bit_vec_len", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern nuint sp_bit_vec_len(BitVec* @this); @@ -172,43 +172,43 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `BitVec` + /// - `this` points to a valid `SPBitVec` /// [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. + /// Gets an unsafe reference to the data of the `SPBitVec` 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 + /// - `this` points to a valid `SPBitVec` + /// - the returned memory range is never accessed after the passed `SPBitVec` has been freed + /// - the returned memory range is never accessed concurrently, either via the `SPBitVec` or directly /// [DllImport(__DllName, EntryPoint = "sp_bit_vec_unsafe_data_ref", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern ByteSlice sp_bit_vec_unsafe_data_ref(BitVec* @this); /// - /// Creates a new `BrightnessGrid` with the specified dimensions. + /// Creates a new `SPBrightnessGrid` with the specified dimensions. /// - /// returns: `BrightnessGrid` initialized to 0. + /// returns: `SPBrightnessGrid` 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_brightness_grid_dealloc`. + /// by explicitly calling `sp_brightness_grid_free`. /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_new", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern BrightnessGrid* sp_brightness_grid_new(nuint width, nuint height); /// - /// Loads a `BrightnessGrid` with the specified dimensions from the provided data. + /// Loads a `SPBrightnessGrid` with the specified dimensions from the provided data. /// /// # Panics /// @@ -221,39 +221,39 @@ namespace ServicePoint.BindGen /// - `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_brightness_grid_dealloc`. + /// by explicitly calling `sp_brightness_grid_free`. /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_load", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern BrightnessGrid* sp_brightness_grid_load(nuint width, nuint height, byte* data, nuint data_length); /// - /// Clones a `BrightnessGrid`. + /// Clones a `SPBrightnessGrid`. /// /// # Safety /// /// The caller has to make sure that: /// - /// - `this` points to a valid `BrightnessGrid` + /// - `this` points to a valid `SPBrightnessGrid` /// - `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_brightness_grid_dealloc`. + /// by explicitly calling `sp_brightness_grid_free`. /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_clone", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern BrightnessGrid* sp_brightness_grid_clone(BrightnessGrid* @this); /// - /// Deallocates a `BrightnessGrid`. + /// Deallocates a `SPBrightnessGrid`. /// /// # Safety /// /// The caller has to make sure that: /// - /// - `this` points to a valid `BrightnessGrid` + /// - `this` points to a valid `SPBrightnessGrid` /// - `this` is not used concurrently or after this call - /// - `this` was not passed to another consuming function, e.g. to create a `Command` + /// - `this` was not passed to another consuming function, e.g. to create a `SPCommand` /// - [DllImport(__DllName, EntryPoint = "sp_brightness_grid_dealloc", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern void sp_brightness_grid_dealloc(BrightnessGrid* @this); + [DllImport(__DllName, EntryPoint = "sp_brightness_grid_free", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] + public static extern void sp_brightness_grid_free(BrightnessGrid* @this); /// /// Gets the current value at the specified position. @@ -271,14 +271,14 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `BrightnessGrid` + /// - `this` points to a valid `SPBrightnessGrid` /// - `this` is not written to concurrently /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_get", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern byte sp_brightness_grid_get(BrightnessGrid* @this, nuint x, nuint y); /// - /// Sets the value of the specified position in the `BrightnessGrid`. + /// Sets the value of the specified position in the `SPBrightnessGrid`. /// /// # Arguments /// @@ -297,14 +297,14 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `BitVec` + /// - `this` points to a valid `SPBitVec` /// - `this` is not written to or read from concurrently /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_set", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_brightness_grid_set(BrightnessGrid* @this, nuint x, nuint y, byte value); /// - /// Sets the value of all cells in the `BrightnessGrid`. + /// Sets the value of all cells in the `SPBrightnessGrid`. /// /// # Arguments /// @@ -319,14 +319,14 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `BrightnessGrid` + /// - `this` points to a valid `SPBrightnessGrid` /// - `this` is not written to or read from concurrently /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_fill", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_brightness_grid_fill(BrightnessGrid* @this, byte value); /// - /// Gets the width of the `BrightnessGrid` instance. + /// Gets the width of the `SPBrightnessGrid` instance. /// /// # Arguments /// @@ -336,13 +336,13 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `BrightnessGrid` + /// - `this` points to a valid `SPBrightnessGrid` /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_width", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern nuint sp_brightness_grid_width(BrightnessGrid* @this); /// - /// Gets the height of the `BrightnessGrid` instance. + /// Gets the height of the `SPBrightnessGrid` instance. /// /// # Arguments /// @@ -352,21 +352,21 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `BrightnessGrid` + /// - `this` points to a valid `SPBrightnessGrid` /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_height", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern nuint sp_brightness_grid_height(BrightnessGrid* @this); /// - /// Gets an unsafe reference to the data of the `BrightnessGrid` instance. + /// Gets an unsafe reference to the data of the `SPBrightnessGrid` instance. /// /// ## Safety /// /// The caller has to make sure that: /// - /// - `this` points to a valid `BrightnessGrid` - /// - the returned memory range is never accessed after the passed `BrightnessGrid` has been freed - /// - the returned memory range is never accessed concurrently, either via the `BrightnessGrid` or directly + /// - `this` points to a valid `SPBrightnessGrid` + /// - the returned memory range is never accessed after the passed `SPBrightnessGrid` has been freed + /// - the returned memory range is never accessed concurrently, either via the `SPBrightnessGrid` or directly /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_unsafe_data_ref", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern ByteSlice sp_brightness_grid_unsafe_data_ref(BrightnessGrid* @this); @@ -380,11 +380,11 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `packet` points to a valid instance of `SPPacket` - /// - `packet` is not used concurrently or after this call + /// - `SPPacket` points to a valid instance of `SPPacket` + /// - `SPPacket` is not used concurrently or after this call /// - the result is checked for NULL /// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or - /// by explicitly calling `sp_command_dealloc`. + /// by explicitly calling `sp_command_free`. /// [DllImport(__DllName, EntryPoint = "sp_command_try_from_packet", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern Command* sp_command_try_from_packet(Packet* packet); @@ -396,10 +396,10 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid instance of `Command` + /// - `this` points to a valid instance of `SPCommand` /// - `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`. + /// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + /// by explicitly calling `sp_command_free`. /// [DllImport(__DllName, EntryPoint = "sp_command_clone", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern Command* sp_command_clone(Command* original); @@ -419,8 +419,8 @@ namespace ServicePoint.BindGen /// /// 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`. + /// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + /// by explicitly calling `sp_command_free`. /// [DllImport(__DllName, EntryPoint = "sp_command_clear", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern Command* sp_command_clear(); @@ -435,8 +435,8 @@ namespace ServicePoint.BindGen /// /// 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`. + /// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + /// by explicitly calling `sp_command_free`. /// [DllImport(__DllName, EntryPoint = "sp_command_hard_reset", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern Command* sp_command_hard_reset(); @@ -448,8 +448,8 @@ namespace ServicePoint.BindGen /// /// 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`. + /// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + /// by explicitly calling `sp_command_free`. /// [DllImport(__DllName, EntryPoint = "sp_command_fade_out", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern Command* sp_command_fade_out(); @@ -467,7 +467,7 @@ namespace ServicePoint.BindGen /// The caller has to make sure that: /// /// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or - /// by explicitly calling `sp_command_dealloc`. + /// by explicitly calling `sp_command_free`. /// [DllImport(__DllName, EntryPoint = "sp_command_brightness", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern Command* sp_command_brightness(byte brightness); @@ -484,111 +484,111 @@ namespace ServicePoint.BindGen /// /// - `grid` points to a valid instance of `SPBrightnessGrid` /// - `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`. + /// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + /// by explicitly calling `sp_command_free`. /// [DllImport(__DllName, EntryPoint = "sp_command_char_brightness", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern Command* sp_command_char_brightness(nuint x, nuint y, BrightnessGrid* grid); /// /// Allocates a new `Command::BitmapLinear` instance. - /// The passed `BitVec` gets consumed. + /// The passed `SPBitVec` gets consumed. /// /// Set pixel data starting at the pixel offset on screen. /// /// The screen will continuously overwrite more pixel data without regarding the offset, meaning /// once the starting row is full, overwriting will continue on column 0. /// - /// The contained `BitVec` is always uncompressed. + /// The contained `SPBitVec` is always uncompressed. /// /// # Safety /// /// The caller has to make sure that: /// - /// - `bit_vec` points to a valid instance of `BitVec` + /// - `bit_vec` points to a valid instance of `SPBitVec` /// - `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`. + /// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + /// by explicitly calling `sp_command_free`. /// [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 consumed. + /// The passed `SPBitVec` gets consumed. /// /// Set pixel data according to an and-mask starting at the offset. /// /// The screen will continuously overwrite more pixel data without regarding the offset, meaning /// once the starting row is full, overwriting will continue on column 0. /// - /// The contained `BitVec` is always uncompressed. + /// The contained `SPBitVec` is always uncompressed. /// /// # Safety /// /// The caller has to make sure that: /// - /// - `bit_vec` points to a valid instance of `BitVec` + /// - `bit_vec` points to a valid instance of `SPBitVec` /// - `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`. + /// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + /// by explicitly calling `sp_command_free`. /// [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 consumed. + /// The passed `SPBitVec` gets consumed. /// /// Set pixel data according to an or-mask starting at the offset. /// /// The screen will continuously overwrite more pixel data without regarding the offset, meaning /// once the starting row is full, overwriting will continue on column 0. /// - /// The contained `BitVec` is always uncompressed. + /// The contained `SPBitVec` is always uncompressed. /// /// # Safety /// /// The caller has to make sure that: /// - /// - `bit_vec` points to a valid instance of `BitVec` + /// - `bit_vec` points to a valid instance of `SPBitVec` /// - `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`. + /// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + /// by explicitly calling `sp_command_free`. /// [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 consumed. + /// The passed `SPBitVec` gets consumed. /// /// Set pixel data according to a xor-mask starting at the offset. /// /// The screen will continuously overwrite more pixel data without regarding the offset, meaning /// once the starting row is full, overwriting will continue on column 0. /// - /// The contained `BitVec` is always uncompressed. + /// The contained `SPBitVec` is always uncompressed. /// /// # Safety /// /// The caller has to make sure that: /// - /// - `bit_vec` points to a valid instance of `BitVec` + /// - `bit_vec` points to a valid instance of `SPBitVec` /// - `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`. + /// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + /// by explicitly calling `sp_command_free`. /// [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 consumed. + /// The passed `SPCp437Grid` gets consumed. /// /// Show text on the screen. /// @@ -601,17 +601,17 @@ namespace ServicePoint.BindGen /// /// 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`. + /// - `grid` points to a valid instance of `SPCp437Grid` + /// - `grid` is not used concurrently or after this call + /// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + /// by explicitly calling `sp_command_free`. /// [DllImport(__DllName, EntryPoint = "sp_command_cp437_data", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern Command* sp_command_cp437_data(nuint x, nuint y, Cp437Grid* byte_grid); + public static extern Command* sp_command_cp437_data(nuint x, nuint y, Cp437Grid* grid); /// /// Allocates a new `Command::BitmapLinearWin` instance. - /// The passed `PixelGrid` gets consumed. + /// The passed `SPPixelGrid` gets consumed. /// /// Sets a window of pixels to the specified values /// @@ -619,38 +619,38 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `pixel_grid` points to a valid instance of `PixelGrid` + /// - `pixel_grid` points to a valid instance of `SPPixelGrid` /// - `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`. + /// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + /// by explicitly calling `sp_command_free`. /// [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* pixel_grid, CompressionCode compression_code); /// - /// Deallocates a `Command`. + /// Deallocates a `SPCommand`. /// /// # Examples /// /// ```C /// SPCommand c = sp_command_clear(); - /// sp_command_dealloc(c); + /// sp_command_free(c); /// ``` /// /// # Safety /// /// The caller has to make sure that: /// - /// - `this` points to a valid `Command` + /// - `this` points to a valid `SPCommand` /// - `this` is not used concurrently or after this call - /// - `this` was not passed to another consuming function, e.g. to create a `Packet` + /// - `this` was not passed to another consuming function, e.g. to create a `SPPacket` /// - [DllImport(__DllName, EntryPoint = "sp_command_dealloc", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern void sp_command_dealloc(Command* ptr); + [DllImport(__DllName, EntryPoint = "sp_command_free", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] + public static extern void sp_command_free(Command* ptr); /// - /// Creates a new instance of `Connection`. + /// Creates a new instance of `SPConnection`. /// /// returns: NULL if connection fails, or connected instance /// @@ -663,14 +663,14 @@ namespace ServicePoint.BindGen /// 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`. + /// by explicitly calling `sp_connection_free`. /// [DllImport(__DllName, EntryPoint = "sp_connection_open", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern Connection* sp_connection_open(byte* host); /// - /// Sends a `Packet` to the display using the `Connection`. - /// The passed `Packet` gets consumed. + /// Sends a `SPPacket` to the display using the `SPConnection`. + /// The passed `SPPacket` gets consumed. /// /// returns: true in case of success /// @@ -678,44 +678,44 @@ namespace ServicePoint.BindGen /// /// 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 + /// - `SPConnection` points to a valid instance of `SPConnection` + /// - `SPPacket` points to a valid instance of `SPPacket` + /// - `SPPacket` 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* packet); /// - /// Closes and deallocates a `Connection`. + /// Closes and deallocates a `SPConnection`. /// /// # Safety /// /// The caller has to make sure that: /// - /// - `this` points to a valid `Connection` + /// - `this` points to a valid `SPConnection` /// - `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); + [DllImport(__DllName, EntryPoint = "sp_connection_free", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] + public static extern void sp_connection_free(Connection* ptr); /// - /// Creates a new `Cp437Grid` with the specified dimensions. + /// Creates a new `SPCp437Grid` with the specified dimensions. /// - /// returns: `Cp437Grid` initialized to 0. + /// returns: `SPCp437Grid` 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_cp437_grid_dealloc`. + /// by explicitly calling `sp_cp437_grid_free`. /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_new", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern Cp437Grid* sp_cp437_grid_new(nuint width, nuint height); /// - /// Loads a `Cp437Grid` with the specified dimensions from the provided data. + /// Loads a `SPCp437Grid` with the specified dimensions from the provided data. /// /// # Panics /// @@ -728,39 +728,39 @@ namespace ServicePoint.BindGen /// - `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_cp437_grid_dealloc`. + /// by explicitly calling `sp_cp437_grid_free`. /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_load", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern Cp437Grid* sp_cp437_grid_load(nuint width, nuint height, byte* data, nuint data_length); /// - /// Clones a `Cp437Grid`. + /// Clones a `SPCp437Grid`. /// /// # Safety /// /// The caller has to make sure that: /// - /// - `this` points to a valid `Cp437Grid` + /// - `this` points to a valid `SPCp437Grid` /// - `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_cp437_grid_dealloc`. + /// by explicitly calling `sp_cp437_grid_free`. /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_clone", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern Cp437Grid* sp_cp437_grid_clone(Cp437Grid* @this); /// - /// Deallocates a `Cp437Grid`. + /// Deallocates a `SPCp437Grid`. /// /// # Safety /// /// The caller has to make sure that: /// - /// - `this` points to a valid `Cp437Grid` + /// - `this` points to a valid `SPCp437Grid` /// - `this` is not used concurrently or after this call - /// - `this` was not passed to another consuming function, e.g. to create a `Command` + /// - `this` was not passed to another consuming function, e.g. to create a `SPCommand` /// - [DllImport(__DllName, EntryPoint = "sp_cp437_grid_dealloc", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern void sp_cp437_grid_dealloc(Cp437Grid* @this); + [DllImport(__DllName, EntryPoint = "sp_cp437_grid_free", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] + public static extern void sp_cp437_grid_free(Cp437Grid* @this); /// /// Gets the current value at the specified position. @@ -778,14 +778,14 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `Cp437Grid` + /// - `this` points to a valid `SPCp437Grid` /// - `this` is not written to concurrently /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_get", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern byte sp_cp437_grid_get(Cp437Grid* @this, nuint x, nuint y); /// - /// Sets the value of the specified position in the `Cp437Grid`. + /// Sets the value of the specified position in the `SPCp437Grid`. /// /// # Arguments /// @@ -803,14 +803,14 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `BitVec` + /// - `this` points to a valid `SPBitVec` /// - `this` is not written to or read from concurrently /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_set", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_cp437_grid_set(Cp437Grid* @this, nuint x, nuint y, byte value); /// - /// Sets the value of all cells in the `Cp437Grid`. + /// Sets the value of all cells in the `SPCp437Grid`. /// /// # Arguments /// @@ -821,14 +821,14 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `Cp437Grid` + /// - `this` points to a valid `SPCp437Grid` /// - `this` is not written to or read from concurrently /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_fill", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_cp437_grid_fill(Cp437Grid* @this, byte value); /// - /// Gets the width of the `Cp437Grid` instance. + /// Gets the width of the `SPCp437Grid` instance. /// /// # Arguments /// @@ -838,13 +838,13 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `Cp437Grid` + /// - `this` points to a valid `SPCp437Grid` /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_width", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern nuint sp_cp437_grid_width(Cp437Grid* @this); /// - /// Gets the height of the `Cp437Grid` instance. + /// Gets the height of the `SPCp437Grid` instance. /// /// # Arguments /// @@ -854,43 +854,43 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `Cp437Grid` + /// - `this` points to a valid `SPCp437Grid` /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_height", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern nuint sp_cp437_grid_height(Cp437Grid* @this); /// - /// Gets an unsafe reference to the data of the `Cp437Grid` instance. + /// Gets an unsafe reference to the data of the `SPCp437Grid` instance. /// /// ## Safety /// /// The caller has to make sure that: /// - /// - `this` points to a valid `Cp437Grid` - /// - the returned memory range is never accessed after the passed `Cp437Grid` has been freed - /// - the returned memory range is never accessed concurrently, either via the `Cp437Grid` or directly + /// - `this` points to a valid `SPCp437Grid` + /// - the returned memory range is never accessed after the passed `SPCp437Grid` has been freed + /// - the returned memory range is never accessed concurrently, either via the `SPCp437Grid` or directly /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_unsafe_data_ref", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern ByteSlice sp_cp437_grid_unsafe_data_ref(Cp437Grid* @this); /// - /// Turns a `Command` into a `Packet`. - /// The `Command` gets consumed. + /// Turns a `SPCommand` into a `SPPacket`. + /// The `SPCommand` 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`. + /// - `SPCommand` points to a valid instance of `SPCommand` + /// - `SPCommand` is not used concurrently or after this call + /// - the returned `SPPacket` instance is freed in some way, either by using a consuming function or + /// by explicitly calling `sp_packet_free`. /// [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. + /// Tries to load a `SPPacket` from the passed array with the specified length. /// /// returns: NULL in case of an error, pointer to the allocated packet otherwise /// @@ -900,49 +900,49 @@ namespace ServicePoint.BindGen /// /// - `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`. + /// - the returned `SPPacket` instance is freed in some way, either by using a consuming function or + /// by explicitly calling `sp_packet_free`. /// [DllImport(__DllName, EntryPoint = "sp_packet_try_load", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern Packet* sp_packet_try_load(byte* data, nuint length); /// - /// Clones a `Packet`. + /// Clones a `SPPacket`. /// /// # Safety /// /// The caller has to make sure that: /// - /// - `this` points to a valid `Packet` + /// - `this` points to a valid `SPPacket` /// - `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_packet_dealloc`. + /// by explicitly calling `sp_packet_free`. /// [DllImport(__DllName, EntryPoint = "sp_packet_clone", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern Packet* sp_packet_clone(Packet* @this); /// - /// Deallocates a `Packet`. + /// Deallocates a `SPPacket`. /// /// # Safety /// /// The caller has to make sure that: /// - /// - `this` points to a valid `Packet` + /// - `this` points to a valid `SPPacket` /// - `this` is not used concurrently or after this call /// - [DllImport(__DllName, EntryPoint = "sp_packet_dealloc", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern void sp_packet_dealloc(Packet* @this); + [DllImport(__DllName, EntryPoint = "sp_packet_free", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] + public static extern void sp_packet_free(Packet* @this); /// - /// Creates a new `PixelGrid` with the specified dimensions. + /// Creates a new `SPPixelGrid` with the specified dimensions. /// /// # Arguments /// /// - `width`: size in pixels in x-direction /// - `height`: size in pixels in y-direction /// - /// returns: `PixelGrid` initialized to all pixels off + /// returns: `SPPixelGrid` initialized to all pixels off /// /// # Panics /// @@ -953,20 +953,20 @@ namespace ServicePoint.BindGen /// 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`. + /// by explicitly calling `sp_pixel_grid_free`. /// [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. + /// Loads a `SPPixelGrid` with the specified dimensions from the provided data. /// /// # Arguments /// /// - `width`: size in pixels in x-direction /// - `height`: size in pixels in y-direction /// - /// returns: `PixelGrid` that contains a copy of the provided data + /// returns: `SPPixelGrid` that contains a copy of the provided data /// /// # Panics /// @@ -979,42 +979,42 @@ namespace ServicePoint.BindGen /// /// - `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`. + /// by explicitly calling `sp_pixel_grid_free`. /// [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`. + /// Clones a `SPPixelGrid`. /// /// # Safety /// /// The caller has to make sure that: /// - /// - `this` points to a valid `PixelGrid` + /// - `this` points to a valid `SPPixelGrid` /// - `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`. + /// by explicitly calling `sp_pixel_grid_free`. /// [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`. + /// Deallocates a `SPPixelGrid`. /// /// # Safety /// /// The caller has to make sure that: /// - /// - `this` points to a valid `PixelGrid` + /// - `this` points to a valid `SPPixelGrid` /// - `this` is not used concurrently or after this call - /// - `this` was not passed to another consuming function, e.g. to create a `Command` + /// - `this` was not passed to another consuming function, e.g. to create a `SPCommand` /// - [DllImport(__DllName, EntryPoint = "sp_pixel_grid_dealloc", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern void sp_pixel_grid_dealloc(PixelGrid* @this); + [DllImport(__DllName, EntryPoint = "sp_pixel_grid_free", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] + public static extern void sp_pixel_grid_free(PixelGrid* @this); /// - /// Gets the current value at the specified position in the `PixelGrid`. + /// Gets the current value at the specified position in the `SPPixelGrid`. /// /// # Arguments /// @@ -1029,7 +1029,7 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `PixelGrid` + /// - `this` points to a valid `SPPixelGrid` /// - `this` is not written to concurrently /// [DllImport(__DllName, EntryPoint = "sp_pixel_grid_get", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] @@ -1037,7 +1037,7 @@ namespace ServicePoint.BindGen public static extern bool sp_pixel_grid_get(PixelGrid* @this, nuint x, nuint y); /// - /// Sets the value of the specified position in the `PixelGrid`. + /// Sets the value of the specified position in the `SPPixelGrid`. /// /// # Arguments /// @@ -1055,14 +1055,14 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `PixelGrid` + /// - `this` points to a valid `SPPixelGrid` /// - `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); /// - /// Sets the state of all pixels in the `PixelGrid`. + /// Sets the state of all pixels in the `SPPixelGrid`. /// /// # Arguments /// @@ -1073,14 +1073,14 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `PixelGrid` + /// - `this` points to a valid `SPPixelGrid` /// - `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 `SPPixelGrid` instance. /// /// # Arguments /// @@ -1090,13 +1090,13 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `PixelGrid` + /// - `this` points to a valid `SPPixelGrid` /// [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 `SPPixelGrid` instance. /// /// # Arguments /// @@ -1106,21 +1106,21 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `PixelGrid` + /// - `this` points to a valid `SPPixelGrid` /// [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. + /// Gets an unsafe reference to the data of the `SPPixelGrid` 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 + /// - `this` points to a valid `SPPixelGrid` + /// - the returned memory range is never accessed after the passed `SPPixelGrid` has been freed + /// - the returned memory range is never accessed concurrently, either via the `SPPixelGrid` or directly /// [DllImport(__DllName, EntryPoint = "sp_pixel_grid_unsafe_data_ref", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern ByteSlice sp_pixel_grid_unsafe_data_ref(PixelGrid* @this); diff --git a/crates/servicepoint_binding_cs/ServicePoint/BitVec.cs b/crates/servicepoint_binding_cs/ServicePoint/BitVec.cs index 13b2200..2abe78c 100644 --- a/crates/servicepoint_binding_cs/ServicePoint/BitVec.cs +++ b/crates/servicepoint_binding_cs/ServicePoint/BitVec.cs @@ -84,8 +84,5 @@ public sealed class BitVec : SpNativeInstance { } - private protected override unsafe void Dealloc() - { - NativeMethods.sp_bit_vec_dealloc(Instance); - } + private protected override unsafe void Free() => NativeMethods.sp_bit_vec_free(Instance); } diff --git a/crates/servicepoint_binding_cs/ServicePoint/BrightnessGrid.cs b/crates/servicepoint_binding_cs/ServicePoint/BrightnessGrid.cs index b80f64f..53970b5 100644 --- a/crates/servicepoint_binding_cs/ServicePoint/BrightnessGrid.cs +++ b/crates/servicepoint_binding_cs/ServicePoint/BrightnessGrid.cs @@ -96,8 +96,5 @@ public sealed class BrightnessGrid : SpNativeInstance { } - private protected override unsafe void Dealloc() - { - NativeMethods.sp_brightness_grid_dealloc(Instance); - } + private protected override unsafe void Free() => NativeMethods.sp_brightness_grid_free(Instance); } diff --git a/crates/servicepoint_binding_cs/ServicePoint/Command.cs b/crates/servicepoint_binding_cs/ServicePoint/Command.cs index a0349c8..e17c685 100644 --- a/crates/servicepoint_binding_cs/ServicePoint/Command.cs +++ b/crates/servicepoint_binding_cs/ServicePoint/Command.cs @@ -125,8 +125,5 @@ public sealed class Command : SpNativeInstance { } - private protected override unsafe void Dealloc() - { - NativeMethods.sp_command_dealloc(Instance); - } + private protected override unsafe void Free() => NativeMethods.sp_command_free(Instance); } diff --git a/crates/servicepoint_binding_cs/ServicePoint/Connection.cs b/crates/servicepoint_binding_cs/ServicePoint/Connection.cs index 3d1a480..302bc57 100644 --- a/crates/servicepoint_binding_cs/ServicePoint/Connection.cs +++ b/crates/servicepoint_binding_cs/ServicePoint/Connection.cs @@ -24,10 +24,7 @@ public sealed class Connection : SpNativeInstance } } - private protected override unsafe void Dealloc() - { - NativeMethods.sp_connection_dealloc(Instance); - } + private protected override unsafe void Free() => NativeMethods.sp_connection_free(Instance); private unsafe Connection(BindGen.Connection* instance) : base(instance) { diff --git a/crates/servicepoint_binding_cs/ServicePoint/Cp437Grid.cs b/crates/servicepoint_binding_cs/ServicePoint/Cp437Grid.cs index e795c85..905828b 100644 --- a/crates/servicepoint_binding_cs/ServicePoint/Cp437Grid.cs +++ b/crates/servicepoint_binding_cs/ServicePoint/Cp437Grid.cs @@ -127,8 +127,5 @@ public sealed class Cp437Grid : SpNativeInstance { } - private protected override unsafe void Dealloc() - { - NativeMethods.sp_cp437_grid_dealloc(Instance); - } + private protected override unsafe void Free() => NativeMethods.sp_cp437_grid_free(Instance); } diff --git a/crates/servicepoint_binding_cs/ServicePoint/Packet.cs b/crates/servicepoint_binding_cs/ServicePoint/Packet.cs index ab4b08a..24c2c18 100644 --- a/crates/servicepoint_binding_cs/ServicePoint/Packet.cs +++ b/crates/servicepoint_binding_cs/ServicePoint/Packet.cs @@ -32,8 +32,5 @@ public sealed class Packet : SpNativeInstance { } - private protected override unsafe void Dealloc() - { - NativeMethods.sp_packet_dealloc(Instance); - } + private protected override unsafe void Free() => NativeMethods.sp_packet_free(Instance); } diff --git a/crates/servicepoint_binding_cs/ServicePoint/PixelGrid.cs b/crates/servicepoint_binding_cs/ServicePoint/PixelGrid.cs index 1e6fb11..77e0cf3 100644 --- a/crates/servicepoint_binding_cs/ServicePoint/PixelGrid.cs +++ b/crates/servicepoint_binding_cs/ServicePoint/PixelGrid.cs @@ -96,8 +96,5 @@ public sealed class PixelGrid : SpNativeInstance { } - private protected override unsafe void Dealloc() - { - NativeMethods.sp_pixel_grid_dealloc(Instance); - } + private protected override unsafe void Free() => NativeMethods.sp_pixel_grid_free(Instance); } diff --git a/crates/servicepoint_binding_cs/ServicePoint/SpNativeInstance.cs b/crates/servicepoint_binding_cs/ServicePoint/SpNativeInstance.cs index 23013c8..b6c492e 100644 --- a/crates/servicepoint_binding_cs/ServicePoint/SpNativeInstance.cs +++ b/crates/servicepoint_binding_cs/ServicePoint/SpNativeInstance.cs @@ -22,7 +22,7 @@ public abstract class SpNativeInstance _instance = instance; } - private protected abstract void Dealloc(); + private protected abstract void Free(); internal unsafe T* Into() { @@ -34,7 +34,7 @@ public abstract class SpNativeInstance private unsafe void ReleaseUnmanagedResources() { if (_instance != null) - Dealloc(); + Free(); _instance = null; } From 53f05efb3d196deb4cdf6de66bb455872e5c0425 Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Sat, 7 Sep 2024 14:19:18 +0200 Subject: [PATCH 24/31] re-enable sorting because otherwise the order is different on my other machine --- crates/servicepoint_binding_c/cbindgen.toml | 4 +- .../examples/lang_c/include/servicepoint.h | 1716 ++++++++--------- 2 files changed, 861 insertions(+), 859 deletions(-) diff --git a/crates/servicepoint_binding_c/cbindgen.toml b/crates/servicepoint_binding_c/cbindgen.toml index 5aa39c8..1114264 100644 --- a/crates/servicepoint_binding_c/cbindgen.toml +++ b/crates/servicepoint_binding_c/cbindgen.toml @@ -17,9 +17,11 @@ line_endings = "LF" ############################# Codegen Options ################################## style = "both" -sort_by = "None" usize_is_size_t = true +# this is needed because otherwise the order in the C# bindings is different on different machines +sort_by = "Name" + [parse] parse_deps = false 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 a132c7d..29532d2 100644 --- a/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h +++ b/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h @@ -8,6 +8,26 @@ #include #include +/** + * pixel count on whole screen + */ +#define SP_PIXEL_COUNT (SP_PIXEL_WIDTH * SP_PIXEL_HEIGHT) + +/** + * Display height in pixels + */ +#define SP_PIXEL_HEIGHT (SP_TILE_HEIGHT * SP_TILE_SIZE) + +/** + * Display width in pixels + */ +#define SP_PIXEL_WIDTH (SP_TILE_WIDTH * SP_TILE_SIZE) + +/** + * Display tile count in the y-direction + */ +#define SP_TILE_HEIGHT 20 + /** * size of a single tile in one dimension */ @@ -18,26 +38,6 @@ */ #define SP_TILE_WIDTH 56 -/** - * Display tile count in the y-direction - */ -#define SP_TILE_HEIGHT 20 - -/** - * Display width in pixels - */ -#define SP_PIXEL_WIDTH (SP_TILE_WIDTH * SP_TILE_SIZE) - -/** - * Display height in pixels - */ -#define SP_PIXEL_HEIGHT (SP_TILE_HEIGHT * SP_TILE_SIZE) - -/** - * pixel count on whole screen - */ -#define SP_PIXEL_COUNT (SP_PIXEL_WIDTH * SP_PIXEL_HEIGHT) - /** * Specifies the kind of compression to use. */ @@ -78,7 +78,7 @@ typedef uint16_t SPCompressionCode; * ```C * SPBitVec vec = sp_bit_vec_new(8); * sp_bit_vec_set(vec, 5, true); - * sp_bit_vec_dealloc(vec); + * sp_bit_vec_free(vec); * ``` */ typedef struct SPBitVec SPBitVec; @@ -97,7 +97,7 @@ typedef struct SPBitVec SPBitVec; * sp_brightness_grid_set(grid, 1, 1, 10); * * SPCommand command = sp_command_char_brightness(grid); - * sp_connection_dealloc(connection); + * sp_connection_free(connection); * ``` */ typedef struct SPBrightnessGrid SPBrightnessGrid; @@ -142,7 +142,7 @@ typedef struct SPConnection SPConnection; * Cp437Grid grid = sp_cp437_grid_new(4, 3); * sp_cp437_grid_fill(grid, '?'); * sp_cp437_grid_set(grid, 0, 0, '!'); - * sp_cp437_grid_dealloc(grid); + * sp_cp437_grid_free(grid); * ``` */ typedef struct SPCp437Grid SPCp437Grid; @@ -161,7 +161,7 @@ typedef struct SPPacket SPPacket; * Cp437Grid grid = sp_pixel_grid_new(8, 3); * sp_pixel_grid_fill(grid, true); * sp_pixel_grid_set(grid, 0, 0, false); - * sp_pixel_grid_dealloc(grid); + * sp_pixel_grid_free(grid); * ``` */ typedef struct SPPixelGrid SPPixelGrid; @@ -197,350 +197,50 @@ extern "C" { #endif // __cplusplus /** - * Tries to turn a `SPPacket` into a `SPCommand`. The packet is deallocated in the process. - * - * Returns: pointer to new `SPCommand` instance or NULL + * Clones a `SPBitVec`. * * # Safety * * The caller has to make sure that: * - * - `packet` points to a valid instance of `SPPacket` - * - `packet` is not used concurrently or after this call - * - the result is checked for NULL - * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or - * by explicitly calling `sp_command_dealloc`. - */ -struct SPCommand *sp_command_try_from_packet(struct SPPacket *packet); - -/** - * Clones a `SPCommand` 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 SPCommand *sp_command_clone(const struct SPCommand *original); - -/** - * Allocates a new `Command::Clear` instance. - * - * Set all pixels to the off state. Does not affect brightness. - * - * # Examples - * - * ```C - * sp_connection_send(connection, sp_command_clear()); - * ``` - * - * # 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 SPCommand *sp_command_clear(void); - -/** - * Allocates a new `Command::HardReset` instance. - * - * Kills the udp daemon on the display, which usually results in a restart. - * Please do not send this in your normal program flow. - * - * # 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 SPCommand *sp_command_hard_reset(void); - -/** - * 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 SPCommand *sp_command_fade_out(void); - -/** - * Allocates a new `Command::Brightness` instance for setting the brightness of all tiles to the - * same value. - * - * # Panics - * - * - When the provided brightness value is out of range (0-11). - * - * # Safety - * - * The caller has to make sure that: - * - * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or - * by explicitly calling `sp_command_dealloc`. - */ -struct SPCommand *sp_command_brightness(uint8_t brightness); - -/** - * Allocates a new `Command::CharBrightness` instance. - * The passed `SPBrightnessGrid` gets consumed. - * - * Set the brightness of individual tiles in a rectangular area of the display. - * - * # Safety - * - * The caller has to make sure that: - * - * - `grid` points to a valid instance of `SPBrightnessGrid` - * - `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 SPCommand *sp_command_char_brightness(size_t x, - size_t y, - struct SPBrightnessGrid *grid); - -/** - * Allocates a new `Command::BitmapLinear` instance. - * The passed `BitVec` gets consumed. - * - * Set pixel data starting at the pixel offset on screen. - * - * The screen will continuously overwrite more pixel data without regarding the offset, meaning - * once the starting row is full, overwriting will continue on column 0. - * - * The contained `BitVec` is always uncompressed. - * - * # 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 SPCommand *sp_command_bitmap_linear(size_t offset, - struct SPBitVec *bit_vec, - SPCompressionCode compression); - -/** - * Allocates a new `Command::BitmapLinearAnd` instance. - * The passed `BitVec` gets consumed. - * - * Set pixel data according to an and-mask starting at the offset. - * - * The screen will continuously overwrite more pixel data without regarding the offset, meaning - * once the starting row is full, overwriting will continue on column 0. - * - * The contained `BitVec` is always uncompressed. - * - * # 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 SPCommand *sp_command_bitmap_linear_and(size_t offset, - struct SPBitVec *bit_vec, - SPCompressionCode compression); - -/** - * Allocates a new `Command::BitmapLinearOr` instance. - * The passed `BitVec` gets consumed. - * - * Set pixel data according to an or-mask starting at the offset. - * - * The screen will continuously overwrite more pixel data without regarding the offset, meaning - * once the starting row is full, overwriting will continue on column 0. - * - * The contained `BitVec` is always uncompressed. - * - * # 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 SPCommand *sp_command_bitmap_linear_or(size_t offset, - struct SPBitVec *bit_vec, - SPCompressionCode compression); - -/** - * Allocates a new `Command::BitmapLinearXor` instance. - * The passed `BitVec` gets consumed. - * - * Set pixel data according to a xor-mask starting at the offset. - * - * The screen will continuously overwrite more pixel data without regarding the offset, meaning - * once the starting row is full, overwriting will continue on column 0. - * - * The contained `BitVec` is always uncompressed. - * - * # 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 SPCommand *sp_command_bitmap_linear_xor(size_t offset, - struct SPBitVec *bit_vec, - SPCompressionCode compression); - -/** - * Allocates a new `Command::Cp437Data` instance. - * The passed `ByteGrid` gets consumed. - * - * Show text on the screen. - * - *
- * The library does not currently convert between UTF-8 and CP-437. - * Because Rust expects UTF-8 strings, it might be necessary to only send ASCII for now. - *
- * - * # 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 SPCommand *sp_command_cp437_data(size_t x, - size_t y, - struct SPCp437Grid *byte_grid); - -/** - * Allocates a new `Command::BitmapLinearWin` instance. - * The passed `PixelGrid` gets consumed. - * - * Sets a window of pixels to the specified values - * - * # 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 SPCommand *sp_command_bitmap_linear_win(size_t x, - size_t y, - struct SPPixelGrid *pixel_grid, - SPCompressionCode compression_code); - -/** - * Deallocates a `Command`. - * - * # Examples - * - * ```C - * SPCommand c = sp_command_clear(); - * sp_command_dealloc(c); - * ``` - * - * # 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 SPCommand *ptr); - -/** - * 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`. - */ -struct SPBitVec *sp_bit_vec_new(size_t size); - -/** - * 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 SPBitVec *sp_bit_vec_load(const uint8_t *data, - size_t data_length); - -/** - * Clones a `BitVec`. - * - * # Safety - * - * The caller has to make sure that: - * - * - `this` points to a valid `BitVec` + * - `this` points to a valid `SPBitVec` * - `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`. + * by explicitly calling `sp_bit_vec_free`. */ struct SPBitVec *sp_bit_vec_clone(const struct SPBitVec *this_); /** - * Deallocates a `BitVec`. + * Sets the value of all bits in the `SPBitVec`. + * + * # 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 used concurrently or after this call - * - `this` was not passed to another consuming function, e.g. to create a `Command` + * - `this` points to a valid `SPBitVec` + * - `this` is not written to or read from concurrently */ -void sp_bit_vec_dealloc(struct SPBitVec *this_); +void sp_bit_vec_fill(struct SPBitVec *this_, bool value); /** - * Gets the value of a bit from the `BitVec`. + * Deallocates a `SPBitVec`. + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `SPBitVec` + * - `this` is not used concurrently or after this call + * - `this` was not passed to another consuming function, e.g. to create a `SPCommand` + */ +void sp_bit_vec_free(struct SPBitVec *this_); + +/** + * Gets the value of a bit from the `SPBitVec`. * * # Arguments * @@ -557,13 +257,72 @@ void sp_bit_vec_dealloc(struct SPBitVec *this_); * * The caller has to make sure that: * - * - `this` points to a valid `BitVec` + * - `this` points to a valid `SPBitVec` * - `this` is not written to concurrently */ bool sp_bit_vec_get(const struct SPBitVec *this_, size_t index); /** - * Sets the value of a bit in the `BitVec`. + * Returns true if length is 0. + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `SPBitVec` + */ +bool sp_bit_vec_is_empty(const struct SPBitVec *this_); + +/** + * Gets the length of the `SPBitVec` in bits. + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `SPBitVec` + */ +size_t sp_bit_vec_len(const struct SPBitVec *this_); + +/** + * Interpret the data as a series of bits and load then into a new `SPBitVec` 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_free`. + */ +struct SPBitVec *sp_bit_vec_load(const uint8_t *data, + size_t data_length); + +/** + * Creates a new `SPBitVec` instance. + * + * # Arguments + * + * - `size`: size in bits. + * + * returns: `SPBitVec` 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_free`. + */ +struct SPBitVec *sp_bit_vec_new(size_t size); + +/** + * Sets the value of a bit in the `SPBitVec`. * * # Arguments * @@ -581,124 +340,71 @@ bool sp_bit_vec_get(const struct SPBitVec *this_, size_t index); * * The caller has to make sure that: * - * - `this` points to a valid `BitVec` + * - `this` points to a valid `SPBitVec` * - `this` is not written to or read from concurrently */ void sp_bit_vec_set(struct SPBitVec *this_, size_t index, bool value); /** - * 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 SPBitVec *this_, bool value); - -/** - * 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 SPBitVec *this_); - -/** - * 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 SPBitVec *this_); - -/** - * Gets an unsafe reference to the data of the `BitVec` instance. + * Gets an unsafe reference to the data of the `SPBitVec` 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 + * - `this` points to a valid `SPBitVec` + * - the returned memory range is never accessed after the passed `SPBitVec` has been freed + * - the returned memory range is never accessed concurrently, either via the `SPBitVec` or directly */ struct SPByteSlice sp_bit_vec_unsafe_data_ref(struct SPBitVec *this_); /** - * Creates a new `BrightnessGrid` with the specified dimensions. - * - * returns: `BrightnessGrid` initialized to 0. + * Clones a `SPBrightnessGrid`. * * # 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_brightness_grid_dealloc`. - */ -struct SPBrightnessGrid *sp_brightness_grid_new(size_t width, - size_t height); - -/** - * Loads a `BrightnessGrid` 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_brightness_grid_dealloc`. - */ -struct SPBrightnessGrid *sp_brightness_grid_load(size_t width, - size_t height, - const uint8_t *data, - size_t data_length); - -/** - * Clones a `BrightnessGrid`. - * - * # Safety - * - * The caller has to make sure that: - * - * - `this` points to a valid `BrightnessGrid` + * - `this` points to a valid `SPBrightnessGrid` * - `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_brightness_grid_dealloc`. + * by explicitly calling `sp_brightness_grid_free`. */ struct SPBrightnessGrid *sp_brightness_grid_clone(const struct SPBrightnessGrid *this_); /** - * Deallocates a `BrightnessGrid`. + * Sets the value of all cells in the `SPBrightnessGrid`. + * + * # Arguments + * + * - `this`: instance to write to + * - `value`: the value to set all cells to + * + * # Panics + * + * - When providing an invalid brightness value * * # Safety * * The caller has to make sure that: * - * - `this` points to a valid `BrightnessGrid` - * - `this` is not used concurrently or after this call - * - `this` was not passed to another consuming function, e.g. to create a `Command` + * - `this` points to a valid `SPBrightnessGrid` + * - `this` is not written to or read from concurrently */ -void sp_brightness_grid_dealloc(struct SPBrightnessGrid *this_); +void sp_brightness_grid_fill(struct SPBrightnessGrid *this_, uint8_t value); + +/** + * Deallocates a `SPBrightnessGrid`. + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `SPBrightnessGrid` + * - `this` is not used concurrently or after this call + * - `this` was not passed to another consuming function, e.g. to create a `SPCommand` + */ +void sp_brightness_grid_free(struct SPBrightnessGrid *this_); /** * Gets the current value at the specified position. @@ -716,7 +422,7 @@ void sp_brightness_grid_dealloc(struct SPBrightnessGrid *this_); * * The caller has to make sure that: * - * - `this` points to a valid `BrightnessGrid` + * - `this` points to a valid `SPBrightnessGrid` * - `this` is not written to concurrently */ uint8_t sp_brightness_grid_get(const struct SPBrightnessGrid *this_, @@ -724,7 +430,58 @@ uint8_t sp_brightness_grid_get(const struct SPBrightnessGrid *this_, size_t y); /** - * Sets the value of the specified position in the `BrightnessGrid`. + * Gets the height of the `SPBrightnessGrid` instance. + * + * # Arguments + * + * - `this`: instance to read from + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `SPBrightnessGrid` + */ +size_t sp_brightness_grid_height(const struct SPBrightnessGrid *this_); + +/** + * Loads a `SPBrightnessGrid` 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_brightness_grid_free`. + */ +struct SPBrightnessGrid *sp_brightness_grid_load(size_t width, + size_t height, + const uint8_t *data, + size_t data_length); + +/** + * Creates a new `SPBrightnessGrid` with the specified dimensions. + * + * returns: `SPBrightnessGrid` 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_brightness_grid_free`. + */ +struct SPBrightnessGrid *sp_brightness_grid_new(size_t width, + size_t height); + +/** + * Sets the value of the specified position in the `SPBrightnessGrid`. * * # Arguments * @@ -743,7 +500,7 @@ uint8_t sp_brightness_grid_get(const struct SPBrightnessGrid *this_, * * The caller has to make sure that: * - * - `this` points to a valid `BitVec` + * - `this` points to a valid `SPBitVec` * - `this` is not written to or read from concurrently */ void sp_brightness_grid_set(struct SPBrightnessGrid *this_, @@ -752,71 +509,326 @@ void sp_brightness_grid_set(struct SPBrightnessGrid *this_, uint8_t value); /** - * Sets the value of all cells in the `BrightnessGrid`. - * - * # Arguments - * - * - `this`: instance to write to - * - `value`: the value to set all cells to - * - * # Panics - * - * - When providing an invalid brightness value - * - * # Safety - * - * The caller has to make sure that: - * - * - `this` points to a valid `BrightnessGrid` - * - `this` is not written to or read from concurrently - */ -void sp_brightness_grid_fill(struct SPBrightnessGrid *this_, uint8_t value); - -/** - * Gets the width of the `BrightnessGrid` instance. - * - * # Arguments - * - * - `this`: instance to read from - * - * # Safety - * - * The caller has to make sure that: - * - * - `this` points to a valid `BrightnessGrid` - */ -size_t sp_brightness_grid_width(const struct SPBrightnessGrid *this_); - -/** - * Gets the height of the `BrightnessGrid` instance. - * - * # Arguments - * - * - `this`: instance to read from - * - * # Safety - * - * The caller has to make sure that: - * - * - `this` points to a valid `BrightnessGrid` - */ -size_t sp_brightness_grid_height(const struct SPBrightnessGrid *this_); - -/** - * Gets an unsafe reference to the data of the `BrightnessGrid` instance. + * Gets an unsafe reference to the data of the `SPBrightnessGrid` instance. * * ## Safety * * The caller has to make sure that: * - * - `this` points to a valid `BrightnessGrid` - * - the returned memory range is never accessed after the passed `BrightnessGrid` has been freed - * - the returned memory range is never accessed concurrently, either via the `BrightnessGrid` or directly + * - `this` points to a valid `SPBrightnessGrid` + * - the returned memory range is never accessed after the passed `SPBrightnessGrid` has been freed + * - the returned memory range is never accessed concurrently, either via the `SPBrightnessGrid` or directly */ struct SPByteSlice sp_brightness_grid_unsafe_data_ref(struct SPBrightnessGrid *this_); /** - * Creates a new instance of `Connection`. + * Gets the width of the `SPBrightnessGrid` instance. + * + * # Arguments + * + * - `this`: instance to read from + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `SPBrightnessGrid` + */ +size_t sp_brightness_grid_width(const struct SPBrightnessGrid *this_); + +/** + * Allocates a new `Command::BitmapLinear` instance. + * The passed `SPBitVec` gets consumed. + * + * Set pixel data starting at the pixel offset on screen. + * + * The screen will continuously overwrite more pixel data without regarding the offset, meaning + * once the starting row is full, overwriting will continue on column 0. + * + * The contained `SPBitVec` is always uncompressed. + * + * # Safety + * + * The caller has to make sure that: + * + * - `bit_vec` points to a valid instance of `SPBitVec` + * - `bit_vec` is not used concurrently or after this call + * - `compression` matches one of the allowed enum values + * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_command_free`. + */ +struct SPCommand *sp_command_bitmap_linear(size_t offset, + struct SPBitVec *bit_vec, + SPCompressionCode compression); + +/** + * Allocates a new `Command::BitmapLinearAnd` instance. + * The passed `SPBitVec` gets consumed. + * + * Set pixel data according to an and-mask starting at the offset. + * + * The screen will continuously overwrite more pixel data without regarding the offset, meaning + * once the starting row is full, overwriting will continue on column 0. + * + * The contained `SPBitVec` is always uncompressed. + * + * # Safety + * + * The caller has to make sure that: + * + * - `bit_vec` points to a valid instance of `SPBitVec` + * - `bit_vec` is not used concurrently or after this call + * - `compression` matches one of the allowed enum values + * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_command_free`. + */ +struct SPCommand *sp_command_bitmap_linear_and(size_t offset, + struct SPBitVec *bit_vec, + SPCompressionCode compression); + +/** + * Allocates a new `Command::BitmapLinearOr` instance. + * The passed `SPBitVec` gets consumed. + * + * Set pixel data according to an or-mask starting at the offset. + * + * The screen will continuously overwrite more pixel data without regarding the offset, meaning + * once the starting row is full, overwriting will continue on column 0. + * + * The contained `SPBitVec` is always uncompressed. + * + * # Safety + * + * The caller has to make sure that: + * + * - `bit_vec` points to a valid instance of `SPBitVec` + * - `bit_vec` is not used concurrently or after this call + * - `compression` matches one of the allowed enum values + * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_command_free`. + */ +struct SPCommand *sp_command_bitmap_linear_or(size_t offset, + struct SPBitVec *bit_vec, + SPCompressionCode compression); + +/** + * Allocates a new `Command::BitmapLinearWin` instance. + * The passed `SPPixelGrid` gets consumed. + * + * Sets a window of pixels to the specified values + * + * # Safety + * + * The caller has to make sure that: + * + * - `pixel_grid` points to a valid instance of `SPPixelGrid` + * - `pixel_grid` is not used concurrently or after this call + * - `compression` matches one of the allowed enum values + * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_command_free`. + */ +struct SPCommand *sp_command_bitmap_linear_win(size_t x, + size_t y, + struct SPPixelGrid *pixel_grid, + SPCompressionCode compression_code); + +/** + * Allocates a new `Command::BitmapLinearXor` instance. + * The passed `SPBitVec` gets consumed. + * + * Set pixel data according to a xor-mask starting at the offset. + * + * The screen will continuously overwrite more pixel data without regarding the offset, meaning + * once the starting row is full, overwriting will continue on column 0. + * + * The contained `SPBitVec` is always uncompressed. + * + * # Safety + * + * The caller has to make sure that: + * + * - `bit_vec` points to a valid instance of `SPBitVec` + * - `bit_vec` is not used concurrently or after this call + * - `compression` matches one of the allowed enum values + * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_command_free`. + */ +struct SPCommand *sp_command_bitmap_linear_xor(size_t offset, + struct SPBitVec *bit_vec, + SPCompressionCode compression); + +/** + * Allocates a new `Command::Brightness` instance for setting the brightness of all tiles to the + * same value. + * + * # Panics + * + * - When the provided brightness value is out of range (0-11). + * + * # Safety + * + * The caller has to make sure that: + * + * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_command_free`. + */ +struct SPCommand *sp_command_brightness(uint8_t brightness); + +/** + * Allocates a new `Command::CharBrightness` instance. + * The passed `SPBrightnessGrid` gets consumed. + * + * Set the brightness of individual tiles in a rectangular area of the display. + * + * # Safety + * + * The caller has to make sure that: + * + * - `grid` points to a valid instance of `SPBrightnessGrid` + * - `grid` is not used concurrently or after this call + * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_command_free`. + */ +struct SPCommand *sp_command_char_brightness(size_t x, + size_t y, + struct SPBrightnessGrid *grid); + +/** + * Allocates a new `Command::Clear` instance. + * + * Set all pixels to the off state. Does not affect brightness. + * + * # Examples + * + * ```C + * sp_connection_send(connection, sp_command_clear()); + * ``` + * + * # Safety + * + * The caller has to make sure that: + * + * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_command_free`. + */ +struct SPCommand *sp_command_clear(void); + +/** + * Clones a `SPCommand` instance. + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid instance of `SPCommand` + * - `this` is not written to concurrently + * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_command_free`. + */ +struct SPCommand *sp_command_clone(const struct SPCommand *original); + +/** + * Allocates a new `Command::Cp437Data` instance. + * The passed `SPCp437Grid` gets consumed. + * + * Show text on the screen. + * + *
+ * The library does not currently convert between UTF-8 and CP-437. + * Because Rust expects UTF-8 strings, it might be necessary to only send ASCII for now. + *
+ * + * # Safety + * + * The caller has to make sure that: + * + * - `grid` points to a valid instance of `SPCp437Grid` + * - `grid` is not used concurrently or after this call + * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_command_free`. + */ +struct SPCommand *sp_command_cp437_data(size_t x, + size_t y, + struct SPCp437Grid *grid); + +/** + * Allocates a new `Command::FadeOut` instance. + * + * # Safety + * + * The caller has to make sure that: + * + * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_command_free`. + */ +struct SPCommand *sp_command_fade_out(void); + +/** + * Deallocates a `SPCommand`. + * + * # Examples + * + * ```C + * SPCommand c = sp_command_clear(); + * sp_command_free(c); + * ``` + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `SPCommand` + * - `this` is not used concurrently or after this call + * - `this` was not passed to another consuming function, e.g. to create a `SPPacket` + */ +void sp_command_free(struct SPCommand *ptr); + +/** + * Allocates a new `Command::HardReset` instance. + * + * Kills the udp daemon on the display, which usually results in a restart. + * Please do not send this in your normal program flow. + * + * # Safety + * + * The caller has to make sure that: + * + * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_command_free`. + */ +struct SPCommand *sp_command_hard_reset(void); + +/** + * Tries to turn a `SPPacket` into a `SPCommand`. The packet is deallocated in the process. + * + * Returns: pointer to new `SPCommand` instance or NULL + * + * # Safety + * + * The caller has to make sure that: + * + * - `SPPacket` points to a valid instance of `SPPacket` + * - `SPPacket` is not used concurrently or after this call + * - the result is checked for NULL + * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_command_free`. + */ +struct SPCommand *sp_command_try_from_packet(struct SPPacket *packet); + +/** + * Closes and deallocates a `SPConnection`. + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `SPConnection` + * - `this` is not used concurrently or after this call + */ +void sp_connection_free(struct SPConnection *ptr); + +/** + * Creates a new instance of `SPConnection`. * * returns: NULL if connection fails, or connected instance * @@ -829,13 +841,13 @@ struct SPByteSlice sp_brightness_grid_unsafe_data_ref(struct SPBrightnessGrid *t * 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`. + * by explicitly calling `sp_connection_free`. */ struct SPConnection *sp_connection_open(const char *host); /** - * Sends a `Packet` to the display using the `Connection`. - * The passed `Packet` gets consumed. + * Sends a `SPPacket` to the display using the `SPConnection`. + * The passed `SPPacket` gets consumed. * * returns: true in case of success * @@ -843,332 +855,56 @@ struct SPConnection *sp_connection_open(const char *host); * * 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 + * - `SPConnection` points to a valid instance of `SPConnection` + * - `SPPacket` points to a valid instance of `SPPacket` + * - `SPPacket` is not used concurrently or after this call */ bool sp_connection_send(const struct SPConnection *connection, struct SPPacket *packet); /** - * Closes and deallocates a `Connection`. + * Clones a `SPCp437Grid`. * * # 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 SPConnection *ptr); - -/** - * 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 SPPacket *sp_packet_from_command(struct SPCommand *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 SPPacket *sp_packet_try_load(const uint8_t *data, - size_t length); - -/** - * Clones a `Packet`. - * - * # Safety - * - * The caller has to make sure that: - * - * - `this` points to a valid `Packet` + * - `this` points to a valid `SPCp437Grid` * - `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_packet_dealloc`. - */ -struct SPPacket *sp_packet_clone(const struct SPPacket *this_); - -/** - * Deallocates a `Packet`. - * - * # Safety - * - * The caller has to make sure that: - * - * - `this` points to a valid `Packet` - * - `this` is not used concurrently or after this call - */ -void sp_packet_dealloc(struct SPPacket *this_); - -/** - * 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 SPPixelGrid *sp_pixel_grid_new(size_t width, - size_t height); - -/** - * 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`. - */ -struct SPPixelGrid *sp_pixel_grid_load(size_t width, - size_t height, - const uint8_t *data, - size_t data_length); - -/** - * 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`. - */ -struct SPPixelGrid *sp_pixel_grid_clone(const struct SPPixelGrid *this_); - -/** - * 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` - */ -void sp_pixel_grid_dealloc(struct SPPixelGrid *this_); - -/** - * 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 SPPixelGrid *this_, size_t x, size_t y); - -/** - * 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 SPPixelGrid *this_, - size_t x, - size_t y, - bool 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 SPPixelGrid *this_, bool 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` - */ -size_t sp_pixel_grid_width(const struct SPPixelGrid *this_); - -/** - * 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 SPPixelGrid *this_); - -/** - * 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 - */ -struct SPByteSlice sp_pixel_grid_unsafe_data_ref(struct SPPixelGrid *this_); - -/** - * Creates a new `Cp437Grid` with the specified dimensions. - * - * returns: `Cp437Grid` 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_cp437_grid_dealloc`. - */ -struct SPCp437Grid *sp_cp437_grid_new(size_t width, - size_t height); - -/** - * Loads a `Cp437Grid` 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_cp437_grid_dealloc`. - */ -struct SPCp437Grid *sp_cp437_grid_load(size_t width, - size_t height, - const uint8_t *data, - size_t data_length); - -/** - * Clones a `Cp437Grid`. - * - * # Safety - * - * The caller has to make sure that: - * - * - `this` points to a valid `Cp437Grid` - * - `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_cp437_grid_dealloc`. + * by explicitly calling `sp_cp437_grid_free`. */ struct SPCp437Grid *sp_cp437_grid_clone(const struct SPCp437Grid *this_); /** - * Deallocates a `Cp437Grid`. + * Sets the value of all cells in the `SPCp437Grid`. + * + * # 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 `Cp437Grid` - * - `this` is not used concurrently or after this call - * - `this` was not passed to another consuming function, e.g. to create a `Command` + * - `this` points to a valid `SPCp437Grid` + * - `this` is not written to or read from concurrently */ -void sp_cp437_grid_dealloc(struct SPCp437Grid *this_); +void sp_cp437_grid_fill(struct SPCp437Grid *this_, uint8_t value); + +/** + * Deallocates a `SPCp437Grid`. + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `SPCp437Grid` + * - `this` is not used concurrently or after this call + * - `this` was not passed to another consuming function, e.g. to create a `SPCommand` + */ +void sp_cp437_grid_free(struct SPCp437Grid *this_); /** * Gets the current value at the specified position. @@ -1186,13 +922,64 @@ void sp_cp437_grid_dealloc(struct SPCp437Grid *this_); * * The caller has to make sure that: * - * - `this` points to a valid `Cp437Grid` + * - `this` points to a valid `SPCp437Grid` * - `this` is not written to concurrently */ uint8_t sp_cp437_grid_get(const struct SPCp437Grid *this_, size_t x, size_t y); /** - * Sets the value of the specified position in the `Cp437Grid`. + * Gets the height of the `SPCp437Grid` instance. + * + * # Arguments + * + * - `this`: instance to read from + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `SPCp437Grid` + */ +size_t sp_cp437_grid_height(const struct SPCp437Grid *this_); + +/** + * Loads a `SPCp437Grid` 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_cp437_grid_free`. + */ +struct SPCp437Grid *sp_cp437_grid_load(size_t width, + size_t height, + const uint8_t *data, + size_t data_length); + +/** + * Creates a new `SPCp437Grid` with the specified dimensions. + * + * returns: `SPCp437Grid` 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_cp437_grid_free`. + */ +struct SPCp437Grid *sp_cp437_grid_new(size_t width, + size_t height); + +/** + * Sets the value of the specified position in the `SPCp437Grid`. * * # Arguments * @@ -1210,7 +997,7 @@ uint8_t sp_cp437_grid_get(const struct SPCp437Grid *this_, size_t x, size_t y); * * The caller has to make sure that: * - * - `this` points to a valid `BitVec` + * - `this` points to a valid `SPBitVec` * - `this` is not written to or read from concurrently */ void sp_cp437_grid_set(struct SPCp437Grid *this_, @@ -1219,65 +1006,278 @@ void sp_cp437_grid_set(struct SPCp437Grid *this_, uint8_t value); /** - * Sets the value of all cells in the `Cp437Grid`. - * - * # 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 `Cp437Grid` - * - `this` is not written to or read from concurrently - */ -void sp_cp437_grid_fill(struct SPCp437Grid *this_, uint8_t value); - -/** - * Gets the width of the `Cp437Grid` instance. - * - * # Arguments - * - * - `this`: instance to read from - * - * # Safety - * - * The caller has to make sure that: - * - * - `this` points to a valid `Cp437Grid` - */ -size_t sp_cp437_grid_width(const struct SPCp437Grid *this_); - -/** - * Gets the height of the `Cp437Grid` instance. - * - * # Arguments - * - * - `this`: instance to read from - * - * # Safety - * - * The caller has to make sure that: - * - * - `this` points to a valid `Cp437Grid` - */ -size_t sp_cp437_grid_height(const struct SPCp437Grid *this_); - -/** - * Gets an unsafe reference to the data of the `Cp437Grid` instance. + * Gets an unsafe reference to the data of the `SPCp437Grid` instance. * * ## Safety * * The caller has to make sure that: * - * - `this` points to a valid `Cp437Grid` - * - the returned memory range is never accessed after the passed `Cp437Grid` has been freed - * - the returned memory range is never accessed concurrently, either via the `Cp437Grid` or directly + * - `this` points to a valid `SPCp437Grid` + * - the returned memory range is never accessed after the passed `SPCp437Grid` has been freed + * - the returned memory range is never accessed concurrently, either via the `SPCp437Grid` or directly */ struct SPByteSlice sp_cp437_grid_unsafe_data_ref(struct SPCp437Grid *this_); +/** + * Gets the width of the `SPCp437Grid` instance. + * + * # Arguments + * + * - `this`: instance to read from + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `SPCp437Grid` + */ +size_t sp_cp437_grid_width(const struct SPCp437Grid *this_); + +/** + * Clones a `SPPacket`. + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `SPPacket` + * - `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_packet_free`. + */ +struct SPPacket *sp_packet_clone(const struct SPPacket *this_); + +/** + * Deallocates a `SPPacket`. + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `SPPacket` + * - `this` is not used concurrently or after this call + */ +void sp_packet_free(struct SPPacket *this_); + +/** + * Turns a `SPCommand` into a `SPPacket`. + * The `SPCommand` gets consumed. + * + * # Safety + * + * The caller has to make sure that: + * + * - `SPCommand` points to a valid instance of `SPCommand` + * - `SPCommand` is not used concurrently or after this call + * - the returned `SPPacket` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_packet_free`. + */ +struct SPPacket *sp_packet_from_command(struct SPCommand *command); + +/** + * Tries to load a `SPPacket` 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 `SPPacket` instance is freed in some way, either by using a consuming function or + * by explicitly calling `sp_packet_free`. + */ +struct SPPacket *sp_packet_try_load(const uint8_t *data, + size_t length); + +/** + * Clones a `SPPixelGrid`. + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `SPPixelGrid` + * - `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_free`. + */ +struct SPPixelGrid *sp_pixel_grid_clone(const struct SPPixelGrid *this_); + +/** + * Sets the state of all pixels in the `SPPixelGrid`. + * + * # 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 `SPPixelGrid` + * - `this` is not written to or read from concurrently + */ +void sp_pixel_grid_fill(struct SPPixelGrid *this_, bool value); + +/** + * Deallocates a `SPPixelGrid`. + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `SPPixelGrid` + * - `this` is not used concurrently or after this call + * - `this` was not passed to another consuming function, e.g. to create a `SPCommand` + */ +void sp_pixel_grid_free(struct SPPixelGrid *this_); + +/** + * Gets the current value at the specified position in the `SPPixelGrid`. + * + * # 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 `SPPixelGrid` + * - `this` is not written to concurrently + */ +bool sp_pixel_grid_get(const struct SPPixelGrid *this_, size_t x, size_t y); + +/** + * Gets the height in pixels of the `SPPixelGrid` instance. + * + * # Arguments + * + * - `this`: instance to read from + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `SPPixelGrid` + */ +size_t sp_pixel_grid_height(const struct SPPixelGrid *this_); + +/** + * Loads a `SPPixelGrid` with the specified dimensions from the provided data. + * + * # Arguments + * + * - `width`: size in pixels in x-direction + * - `height`: size in pixels in y-direction + * + * returns: `SPPixelGrid` 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_free`. + */ +struct SPPixelGrid *sp_pixel_grid_load(size_t width, + size_t height, + const uint8_t *data, + size_t data_length); + +/** + * Creates a new `SPPixelGrid` with the specified dimensions. + * + * # Arguments + * + * - `width`: size in pixels in x-direction + * - `height`: size in pixels in y-direction + * + * returns: `SPPixelGrid` 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_free`. + */ +struct SPPixelGrid *sp_pixel_grid_new(size_t width, + size_t height); + +/** + * Sets the value of the specified position in the `SPPixelGrid`. + * + * # 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 `SPPixelGrid` + * - `this` is not written to or read from concurrently + */ +void sp_pixel_grid_set(struct SPPixelGrid *this_, + size_t x, + size_t y, + bool value); + +/** + * Gets an unsafe reference to the data of the `SPPixelGrid` instance. + * + * ## Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `SPPixelGrid` + * - the returned memory range is never accessed after the passed `SPPixelGrid` has been freed + * - the returned memory range is never accessed concurrently, either via the `SPPixelGrid` or directly + */ +struct SPByteSlice sp_pixel_grid_unsafe_data_ref(struct SPPixelGrid *this_); + +/** + * Gets the width in pixels of the `SPPixelGrid` instance. + * + * # Arguments + * + * - `this`: instance to read from + * + * # Safety + * + * The caller has to make sure that: + * + * - `this` points to a valid `SPPixelGrid` + */ +size_t sp_pixel_grid_width(const struct SPPixelGrid *this_); + #ifdef __cplusplus } // extern "C" #endif // __cplusplus From acc35b672740ce920b701c82991e8bc9be4da805 Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Sat, 7 Sep 2024 14:35:16 +0200 Subject: [PATCH 25/31] add ability to send commands directly in C code, annotate which functions may return null --- crates/servicepoint_binding_c/README.md | 3 +- .../examples/lang_c/include/servicepoint.h | 47 +++++++++++++++--- .../examples/lang_c/src/main.c | 5 +- crates/servicepoint_binding_c/src/bit_vec.rs | 2 +- .../src/brightness_grid.rs | 2 +- crates/servicepoint_binding_c/src/command.rs | 6 ++- .../servicepoint_binding_c/src/connection.rs | 25 +++++++++- .../servicepoint_binding_c/src/cp437_grid.rs | 6 +++ crates/servicepoint_binding_c/src/lib.rs | 3 +- crates/servicepoint_binding_c/src/packet.rs | 4 ++ .../servicepoint_binding_c/src/pixel_grid.rs | 6 ++- .../ServicePoint/BindGen/ServicePoint.g.cs | 48 ++++++++++++++++--- .../ServicePoint/Connection.cs | 10 +++- 13 files changed, 138 insertions(+), 29 deletions(-) diff --git a/crates/servicepoint_binding_c/README.md b/crates/servicepoint_binding_c/README.md index 8a8281c..79c4e0e 100644 --- a/crates/servicepoint_binding_c/README.md +++ b/crates/servicepoint_binding_c/README.md @@ -25,8 +25,7 @@ int main(void) { sp_pixel_grid_fill(pixels, true); SPCommand *command = sp_command_bitmap_linear_win(0, 0, pixels, Uncompressed); - SPPacket *packet = sp_packet_from_command(command); - while (sp_connection_send(connection, sp_packet_clone(packet))); + while (sp_connection_send(connection, sp_command_clone(command))); sp_packet_free(packet); sp_connection_free(connection); 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 29532d2..c9e3ad0 100644 --- a/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h +++ b/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h @@ -306,7 +306,7 @@ struct SPBitVec *sp_bit_vec_load(const uint8_t *data, * * - `size`: size in bits. * - * returns: `SPBitVec` with all bits set to false. + * returns: `SPBitVec` with all bits set to false. Will never return NULL. * * # Panics * @@ -468,7 +468,7 @@ struct SPBrightnessGrid *sp_brightness_grid_load(size_t width, /** * Creates a new `SPBrightnessGrid` with the specified dimensions. * - * returns: `SPBrightnessGrid` initialized to 0. + * returns: `SPBrightnessGrid` initialized to 0. Will never return NULL. * * # Safety * @@ -615,7 +615,9 @@ struct SPCommand *sp_command_bitmap_linear_or(size_t offset, * Allocates a new `Command::BitmapLinearWin` instance. * The passed `SPPixelGrid` gets consumed. * - * Sets a window of pixels to the specified values + * Sets a window of pixels to the specified values. + * + * Will never return NULL. * * # Safety * @@ -738,6 +740,8 @@ struct SPCommand *sp_command_clone(const struct SPCommand *original); * Because Rust expects UTF-8 strings, it might be necessary to only send ASCII for now. * * + * Will never return NULL. + * * # Safety * * The caller has to make sure that: @@ -845,6 +849,23 @@ void sp_connection_free(struct SPConnection *ptr); */ struct SPConnection *sp_connection_open(const char *host); +/** + * Sends a `SPCommand` to the display using the `SPConnection`. + * The passed `SPCommand` gets consumed. + * + * returns: true in case of success + * + * # Safety + * + * The caller has to make sure that: + * + * - `connection` points to a valid instance of `SPConnection` + * - `command` points to a valid instance of `SPPacket` + * - `command` is not used concurrently or after this call + */ +bool sp_connection_send_command(const struct SPConnection *connection, + struct SPCommand *command); + /** * Sends a `SPPacket` to the display using the `SPConnection`. * The passed `SPPacket` gets consumed. @@ -859,12 +880,14 @@ struct SPConnection *sp_connection_open(const char *host); * - `SPPacket` points to a valid instance of `SPPacket` * - `SPPacket` is not used concurrently or after this call */ -bool sp_connection_send(const struct SPConnection *connection, - struct SPPacket *packet); +bool sp_connection_send_packet(const struct SPConnection *connection, + struct SPPacket *packet); /** * Clones a `SPCp437Grid`. * + * Will never return NULL. + * * # Safety * * The caller has to make sure that: @@ -945,6 +968,8 @@ size_t sp_cp437_grid_height(const struct SPCp437Grid *this_); /** * Loads a `SPCp437Grid` with the specified dimensions from the provided data. * + * Will never return NULL. + * * # Panics * * When the provided `data_length` is not sufficient for the `height` and `width` @@ -1008,6 +1033,8 @@ void sp_cp437_grid_set(struct SPCp437Grid *this_, /** * Gets an unsafe reference to the data of the `SPCp437Grid` instance. * + * Will never return NULL. + * * ## Safety * * The caller has to make sure that: @@ -1036,6 +1063,8 @@ size_t sp_cp437_grid_width(const struct SPCp437Grid *this_); /** * Clones a `SPPacket`. * + * Will never return NULL. + * * # Safety * * The caller has to make sure that: @@ -1063,6 +1092,8 @@ void sp_packet_free(struct SPPacket *this_); * Turns a `SPCommand` into a `SPPacket`. * The `SPCommand` gets consumed. * + * Will never return NULL. + * * # Safety * * The caller has to make sure that: @@ -1094,6 +1125,8 @@ struct SPPacket *sp_packet_try_load(const uint8_t *data, /** * Clones a `SPPixelGrid`. * + * Will never return NULL. + * * # Safety * * The caller has to make sure that: @@ -1179,7 +1212,7 @@ size_t sp_pixel_grid_height(const struct SPPixelGrid *this_); * - `width`: size in pixels in x-direction * - `height`: size in pixels in y-direction * - * returns: `SPPixelGrid` that contains a copy of the provided data + * returns: `SPPixelGrid` that contains a copy of the provided data. Will never return NULL. * * # Panics * @@ -1207,7 +1240,7 @@ struct SPPixelGrid *sp_pixel_grid_load(size_t width, * - `width`: size in pixels in x-direction * - `height`: size in pixels in y-direction * - * returns: `SPPixelGrid` initialized to all pixels off + * returns: `SPPixelGrid` initialized to all pixels off. Will never return NULL. * * # Panics * diff --git a/crates/servicepoint_binding_c/examples/lang_c/src/main.c b/crates/servicepoint_binding_c/examples/lang_c/src/main.c index 77ddf5a..5054286 100644 --- a/crates/servicepoint_binding_c/examples/lang_c/src/main.c +++ b/crates/servicepoint_binding_c/examples/lang_c/src/main.c @@ -10,10 +10,9 @@ int main(void) { sp_pixel_grid_fill(pixels, true); SPCommand *command = sp_command_bitmap_linear_win(0, 0, pixels, Uncompressed); - SPPacket *packet = sp_packet_from_command(command); - while (sp_connection_send(connection, sp_packet_clone(packet))); + while (sp_connection_send_command(connection, sp_command_clone(command))); - sp_packet_free(packet); + sp_command_free(command); sp_connection_free(connection); return 0; } diff --git a/crates/servicepoint_binding_c/src/bit_vec.rs b/crates/servicepoint_binding_c/src/bit_vec.rs index f5024d1..6fa5795 100644 --- a/crates/servicepoint_binding_c/src/bit_vec.rs +++ b/crates/servicepoint_binding_c/src/bit_vec.rs @@ -39,7 +39,7 @@ impl Clone for SPBitVec { /// /// - `size`: size in bits. /// -/// returns: `SPBitVec` with all bits set to false. +/// returns: `SPBitVec` with all bits set to false. Will never return NULL. /// /// # Panics /// diff --git a/crates/servicepoint_binding_c/src/brightness_grid.rs b/crates/servicepoint_binding_c/src/brightness_grid.rs index e129b94..d205c4c 100644 --- a/crates/servicepoint_binding_c/src/brightness_grid.rs +++ b/crates/servicepoint_binding_c/src/brightness_grid.rs @@ -35,7 +35,7 @@ impl Clone for SPBrightnessGrid { /// Creates a new `SPBrightnessGrid` with the specified dimensions. /// -/// returns: `SPBrightnessGrid` initialized to 0. +/// returns: `SPBrightnessGrid` initialized to 0. Will never return NULL. /// /// # Safety /// diff --git a/crates/servicepoint_binding_c/src/command.rs b/crates/servicepoint_binding_c/src/command.rs index 7e92bf0..60d97fe 100644 --- a/crates/servicepoint_binding_c/src/command.rs +++ b/crates/servicepoint_binding_c/src/command.rs @@ -314,6 +314,8 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_xor( /// Because Rust expects UTF-8 strings, it might be necessary to only send ASCII for now. /// /// +/// Will never return NULL. +/// /// # Safety /// /// The caller has to make sure that: @@ -338,7 +340,9 @@ pub unsafe extern "C" fn sp_command_cp437_data( /// Allocates a new `Command::BitmapLinearWin` instance. /// The passed `SPPixelGrid` gets consumed. /// -/// Sets a window of pixels to the specified values +/// Sets a window of pixels to the specified values. +/// +/// Will never return NULL. /// /// # Safety /// diff --git a/crates/servicepoint_binding_c/src/connection.rs b/crates/servicepoint_binding_c/src/connection.rs index a6bd5a0..d993241 100644 --- a/crates/servicepoint_binding_c/src/connection.rs +++ b/crates/servicepoint_binding_c/src/connection.rs @@ -5,7 +5,7 @@ use std::ffi::{c_char, CStr}; use std::ptr::null_mut; -use crate::SPPacket; +use crate::{SPCommand, SPPacket}; /// A connection to the display. /// @@ -58,7 +58,7 @@ pub unsafe extern "C" fn sp_connection_open( /// - `SPPacket` points to a valid instance of `SPPacket` /// - `SPPacket` is not used concurrently or after this call #[no_mangle] -pub unsafe extern "C" fn sp_connection_send( +pub unsafe extern "C" fn sp_connection_send_packet( connection: *const SPConnection, packet: *mut SPPacket, ) -> bool { @@ -66,6 +66,27 @@ pub unsafe extern "C" fn sp_connection_send( (*connection).0.send((*packet).0).is_ok() } +/// Sends a `SPCommand` to the display using the `SPConnection`. +/// The passed `SPCommand` gets consumed. +/// +/// returns: true in case of success +/// +/// # Safety +/// +/// The caller has to make sure that: +/// +/// - `connection` points to a valid instance of `SPConnection` +/// - `command` points to a valid instance of `SPPacket` +/// - `command` is not used concurrently or after this call +#[no_mangle] +pub unsafe extern "C" fn sp_connection_send_command( + connection: *const SPConnection, + command: *mut SPCommand, +) -> bool { + let command = (*Box::from_raw(command)).0; + (*connection).0.send(command).is_ok() +} + /// Closes and deallocates a `SPConnection`. /// /// # Safety diff --git a/crates/servicepoint_binding_c/src/cp437_grid.rs b/crates/servicepoint_binding_c/src/cp437_grid.rs index 7d24f0b..88919fd 100644 --- a/crates/servicepoint_binding_c/src/cp437_grid.rs +++ b/crates/servicepoint_binding_c/src/cp437_grid.rs @@ -51,6 +51,8 @@ pub unsafe extern "C" fn sp_cp437_grid_new( /// Loads a `SPCp437Grid` with the specified dimensions from the provided data. /// +/// Will never return NULL. +/// /// # Panics /// /// When the provided `data_length` is not sufficient for the `height` and `width` @@ -78,6 +80,8 @@ pub unsafe extern "C" fn sp_cp437_grid_load( /// Clones a `SPCp437Grid`. /// +/// Will never return NULL. +/// /// # Safety /// /// The caller has to make sure that: @@ -219,6 +223,8 @@ pub unsafe extern "C" fn sp_cp437_grid_height( /// Gets an unsafe reference to the data of the `SPCp437Grid` instance. /// +/// Will never return NULL. +/// /// ## Safety /// /// The caller has to make sure that: diff --git a/crates/servicepoint_binding_c/src/lib.rs b/crates/servicepoint_binding_c/src/lib.rs index 6d38abc..698ae92 100644 --- a/crates/servicepoint_binding_c/src/lib.rs +++ b/crates/servicepoint_binding_c/src/lib.rs @@ -17,8 +17,7 @@ //! sp_pixel_grid_fill(pixels, true); //! //! SPCommand *command = sp_command_bitmap_linear_win(0, 0, pixels, Uncompressed); -//! SPPacket *packet = sp_packet_from_command(command); -//! while (sp_connection_send(connection, sp_packet_clone(packet))); +//! while (sp_connection_send(connection, sp_command_clone(command))); //! //! sp_packet_free(packet); //! sp_connection_free(connection); diff --git a/crates/servicepoint_binding_c/src/packet.rs b/crates/servicepoint_binding_c/src/packet.rs index 0a2bdef..2d6db47 100644 --- a/crates/servicepoint_binding_c/src/packet.rs +++ b/crates/servicepoint_binding_c/src/packet.rs @@ -12,6 +12,8 @@ pub struct SPPacket(pub(crate) servicepoint::Packet); /// Turns a `SPCommand` into a `SPPacket`. /// The `SPCommand` gets consumed. /// +/// Will never return NULL. +/// /// # Safety /// /// The caller has to make sure that: @@ -55,6 +57,8 @@ pub unsafe extern "C" fn sp_packet_try_load( /// Clones a `SPPacket`. /// +/// Will never return NULL. +/// /// # Safety /// /// The caller has to make sure that: diff --git a/crates/servicepoint_binding_c/src/pixel_grid.rs b/crates/servicepoint_binding_c/src/pixel_grid.rs index 2f6e00a..c5da1c0 100644 --- a/crates/servicepoint_binding_c/src/pixel_grid.rs +++ b/crates/servicepoint_binding_c/src/pixel_grid.rs @@ -25,7 +25,7 @@ pub struct SPPixelGrid(pub(crate) servicepoint::PixelGrid); /// - `width`: size in pixels in x-direction /// - `height`: size in pixels in y-direction /// -/// returns: `SPPixelGrid` initialized to all pixels off +/// returns: `SPPixelGrid` initialized to all pixels off. Will never return NULL. /// /// # Panics /// @@ -54,7 +54,7 @@ pub unsafe extern "C" fn sp_pixel_grid_new( /// - `width`: size in pixels in x-direction /// - `height`: size in pixels in y-direction /// -/// returns: `SPPixelGrid` that contains a copy of the provided data +/// returns: `SPPixelGrid` that contains a copy of the provided data. Will never return NULL. /// /// # Panics /// @@ -83,6 +83,8 @@ pub unsafe extern "C" fn sp_pixel_grid_load( /// Clones a `SPPixelGrid`. /// +/// Will never return NULL. +/// /// # Safety /// /// The caller has to make sure that: diff --git a/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs b/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs index 8183a4d..c234069 100644 --- a/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs +++ b/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs @@ -26,7 +26,7 @@ namespace ServicePoint.BindGen /// /// - `size`: size in bits. /// - /// returns: `SPBitVec` with all bits set to false. + /// returns: `SPBitVec` with all bits set to false. Will never return NULL. /// /// # Panics /// @@ -195,7 +195,7 @@ namespace ServicePoint.BindGen /// /// Creates a new `SPBrightnessGrid` with the specified dimensions. /// - /// returns: `SPBrightnessGrid` initialized to 0. + /// returns: `SPBrightnessGrid` initialized to 0. Will never return NULL. /// /// # Safety /// @@ -597,6 +597,8 @@ namespace ServicePoint.BindGen /// Because Rust expects UTF-8 strings, it might be necessary to only send ASCII for now. /// </div> /// + /// Will never return NULL. + /// /// # Safety /// /// The caller has to make sure that: @@ -613,7 +615,9 @@ namespace ServicePoint.BindGen /// Allocates a new `Command::BitmapLinearWin` instance. /// The passed `SPPixelGrid` gets consumed. /// - /// Sets a window of pixels to the specified values + /// Sets a window of pixels to the specified values. + /// + /// Will never return NULL. /// /// # Safety /// @@ -682,9 +686,27 @@ namespace ServicePoint.BindGen /// - `SPPacket` points to a valid instance of `SPPacket` /// - `SPPacket` is not used concurrently or after this call /// - [DllImport(__DllName, EntryPoint = "sp_connection_send", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] + [DllImport(__DllName, EntryPoint = "sp_connection_send_packet", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] [return: MarshalAs(UnmanagedType.U1)] - public static extern bool sp_connection_send(Connection* connection, Packet* packet); + public static extern bool sp_connection_send_packet(Connection* connection, Packet* packet); + + /// + /// Sends a `SPCommand` to the display using the `SPConnection`. + /// The passed `SPCommand` gets consumed. + /// + /// returns: true in case of success + /// + /// # Safety + /// + /// The caller has to make sure that: + /// + /// - `connection` points to a valid instance of `SPConnection` + /// - `command` points to a valid instance of `SPPacket` + /// - `command` is not used concurrently or after this call + /// + [DllImport(__DllName, EntryPoint = "sp_connection_send_command", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] + [return: MarshalAs(UnmanagedType.U1)] + public static extern bool sp_connection_send_command(Connection* connection, Command* command); /// /// Closes and deallocates a `SPConnection`. @@ -717,6 +739,8 @@ namespace ServicePoint.BindGen /// /// Loads a `SPCp437Grid` with the specified dimensions from the provided data. /// + /// Will never return NULL. + /// /// # Panics /// /// When the provided `data_length` is not sufficient for the `height` and `width` @@ -736,6 +760,8 @@ namespace ServicePoint.BindGen /// /// Clones a `SPCp437Grid`. /// + /// Will never return NULL. + /// /// # Safety /// /// The caller has to make sure that: @@ -862,6 +888,8 @@ namespace ServicePoint.BindGen /// /// Gets an unsafe reference to the data of the `SPCp437Grid` instance. /// + /// Will never return NULL. + /// /// ## Safety /// /// The caller has to make sure that: @@ -877,6 +905,8 @@ namespace ServicePoint.BindGen /// Turns a `SPCommand` into a `SPPacket`. /// The `SPCommand` gets consumed. /// + /// Will never return NULL. + /// /// # Safety /// /// The caller has to make sure that: @@ -909,6 +939,8 @@ namespace ServicePoint.BindGen /// /// Clones a `SPPacket`. /// + /// Will never return NULL. + /// /// # Safety /// /// The caller has to make sure that: @@ -942,7 +974,7 @@ namespace ServicePoint.BindGen /// - `width`: size in pixels in x-direction /// - `height`: size in pixels in y-direction /// - /// returns: `SPPixelGrid` initialized to all pixels off + /// returns: `SPPixelGrid` initialized to all pixels off. Will never return NULL. /// /// # Panics /// @@ -966,7 +998,7 @@ namespace ServicePoint.BindGen /// - `width`: size in pixels in x-direction /// - `height`: size in pixels in y-direction /// - /// returns: `SPPixelGrid` that contains a copy of the provided data + /// returns: `SPPixelGrid` that contains a copy of the provided data. Will never return NULL. /// /// # Panics /// @@ -987,6 +1019,8 @@ namespace ServicePoint.BindGen /// /// Clones a `SPPixelGrid`. /// + /// Will never return NULL. + /// /// # Safety /// /// The caller has to make sure that: diff --git a/crates/servicepoint_binding_cs/ServicePoint/Connection.cs b/crates/servicepoint_binding_cs/ServicePoint/Connection.cs index 302bc57..eff3b32 100644 --- a/crates/servicepoint_binding_cs/ServicePoint/Connection.cs +++ b/crates/servicepoint_binding_cs/ServicePoint/Connection.cs @@ -20,7 +20,15 @@ public sealed class Connection : SpNativeInstance { unsafe { - return NativeMethods.sp_connection_send(Instance, packet.Into()); + return NativeMethods.sp_connection_send_packet(Instance, packet.Into()); + } + } + + public bool Send(Command command) + { + unsafe + { + return NativeMethods.sp_connection_send_command(Instance, command.Into()); } } From c712b037d0400656402c9af2a3526b9e3209fbf3 Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Sat, 7 Sep 2024 14:44:25 +0200 Subject: [PATCH 26/31] improve which doc line is the first because this one is displayed in docs in the overview --- crates/servicepoint_binding_c/README.md | 2 +- .../examples/lang_c/include/servicepoint.h | 81 +++++++++++-------- crates/servicepoint_binding_c/src/command.rs | 77 ++++++++++-------- .../servicepoint_binding_c/src/connection.rs | 4 +- crates/servicepoint_binding_c/src/lib.rs | 2 +- .../ServicePoint/BindGen/ServicePoint.g.cs | 75 ++++++++++------- 6 files changed, 140 insertions(+), 101 deletions(-) diff --git a/crates/servicepoint_binding_c/README.md b/crates/servicepoint_binding_c/README.md index 79c4e0e..ba03216 100644 --- a/crates/servicepoint_binding_c/README.md +++ b/crates/servicepoint_binding_c/README.md @@ -25,7 +25,7 @@ int main(void) { sp_pixel_grid_fill(pixels, true); SPCommand *command = sp_command_bitmap_linear_win(0, 0, pixels, Uncompressed); - while (sp_connection_send(connection, sp_command_clone(command))); + while (sp_connection_send_command(connection, sp_command_clone(command))); sp_packet_free(packet); sp_connection_free(connection); 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 c9e3ad0..5039509 100644 --- a/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h +++ b/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h @@ -112,8 +112,8 @@ typedef struct SPBrightnessGrid SPBrightnessGrid; * # Examples * * ```C - * sp_connection_send(connection, sp_command_clear()); - * sp_connection_send(connection, sp_command_brightness(5)); + * sp_connection_send_command(connection, sp_command_clear()); + * sp_connection_send_command(connection, sp_command_brightness(5)); * ``` */ typedef struct SPCommand SPCommand; @@ -126,7 +126,7 @@ typedef struct SPCommand SPCommand; * ```C * CConnection connection = sp_connection_open("172.23.42.29:2342"); * if (connection != NULL) - * sp_connection_send(connection, sp_command_clear()); + * sp_connection_send_command(connection, sp_command_clear()); * ``` */ typedef struct SPConnection SPConnection; @@ -537,9 +537,6 @@ struct SPByteSlice sp_brightness_grid_unsafe_data_ref(struct SPBrightnessGrid *t size_t sp_brightness_grid_width(const struct SPBrightnessGrid *this_); /** - * Allocates a new `Command::BitmapLinear` instance. - * The passed `SPBitVec` gets consumed. - * * Set pixel data starting at the pixel offset on screen. * * The screen will continuously overwrite more pixel data without regarding the offset, meaning @@ -547,6 +544,10 @@ size_t sp_brightness_grid_width(const struct SPBrightnessGrid *this_); * * The contained `SPBitVec` is always uncompressed. * + * The passed `SPBitVec` gets consumed. + * + * Returns: a new `Command::BitmapLinear` instance. Will never return NULL. + * * # Safety * * The caller has to make sure that: @@ -562,9 +563,6 @@ struct SPCommand *sp_command_bitmap_linear(size_t offset, SPCompressionCode compression); /** - * Allocates a new `Command::BitmapLinearAnd` instance. - * The passed `SPBitVec` gets consumed. - * * Set pixel data according to an and-mask starting at the offset. * * The screen will continuously overwrite more pixel data without regarding the offset, meaning @@ -572,6 +570,10 @@ struct SPCommand *sp_command_bitmap_linear(size_t offset, * * The contained `SPBitVec` is always uncompressed. * + * The passed `SPBitVec` gets consumed. + * + * Returns: a new `Command::BitmapLinearAnd` instance. Will never return NULL. + * * # Safety * * The caller has to make sure that: @@ -587,9 +589,6 @@ struct SPCommand *sp_command_bitmap_linear_and(size_t offset, SPCompressionCode compression); /** - * Allocates a new `Command::BitmapLinearOr` instance. - * The passed `SPBitVec` gets consumed. - * * Set pixel data according to an or-mask starting at the offset. * * The screen will continuously overwrite more pixel data without regarding the offset, meaning @@ -597,6 +596,10 @@ struct SPCommand *sp_command_bitmap_linear_and(size_t offset, * * The contained `SPBitVec` is always uncompressed. * + * The passed `SPBitVec` gets consumed. + * + * Returns: a new `Command::BitmapLinearOr` instance. Will never return NULL. + * * # Safety * * The caller has to make sure that: @@ -612,12 +615,11 @@ struct SPCommand *sp_command_bitmap_linear_or(size_t offset, SPCompressionCode compression); /** - * Allocates a new `Command::BitmapLinearWin` instance. - * The passed `SPPixelGrid` gets consumed. - * * Sets a window of pixels to the specified values. * - * Will never return NULL. + * The passed `SPPixelGrid` gets consumed. + * + * Returns: a new `Command::BitmapLinearWin` instance. Will never return NULL. * * # Safety * @@ -635,9 +637,6 @@ struct SPCommand *sp_command_bitmap_linear_win(size_t x, SPCompressionCode compression_code); /** - * Allocates a new `Command::BitmapLinearXor` instance. - * The passed `SPBitVec` gets consumed. - * * Set pixel data according to a xor-mask starting at the offset. * * The screen will continuously overwrite more pixel data without regarding the offset, meaning @@ -645,6 +644,10 @@ struct SPCommand *sp_command_bitmap_linear_win(size_t x, * * The contained `SPBitVec` is always uncompressed. * + * The passed `SPBitVec` gets consumed. + * + * Returns: a new `Command::BitmapLinearXor` instance. Will never return NULL. + * * # Safety * * The caller has to make sure that: @@ -660,8 +663,9 @@ struct SPCommand *sp_command_bitmap_linear_xor(size_t offset, SPCompressionCode compression); /** - * Allocates a new `Command::Brightness` instance for setting the brightness of all tiles to the - * same value. + * Set the brightness of all tiles to the same value. + * + * Returns: a new `Command::Brightness` instance. Will never return NULL. * * # Panics * @@ -677,10 +681,11 @@ struct SPCommand *sp_command_bitmap_linear_xor(size_t offset, struct SPCommand *sp_command_brightness(uint8_t brightness); /** - * Allocates a new `Command::CharBrightness` instance. + * Set the brightness of individual tiles in a rectangular area of the display. + * * The passed `SPBrightnessGrid` gets consumed. * - * Set the brightness of individual tiles in a rectangular area of the display. + * Returns: a new `Command::CharBrightness` instance. Will never return NULL. * * # Safety * @@ -696,14 +701,16 @@ struct SPCommand *sp_command_char_brightness(size_t x, struct SPBrightnessGrid *grid); /** - * Allocates a new `Command::Clear` instance. + * Set all pixels to the off state. * - * Set all pixels to the off state. Does not affect brightness. + * Does not affect brightness. + * + * Returns: a new `Command::Clear` instance. Will never return NULL. * * # Examples * * ```C - * sp_connection_send(connection, sp_command_clear()); + * sp_connection_send_command(connection, sp_command_clear()); * ``` * * # Safety @@ -730,9 +737,6 @@ struct SPCommand *sp_command_clear(void); struct SPCommand *sp_command_clone(const struct SPCommand *original); /** - * Allocates a new `Command::Cp437Data` instance. - * The passed `SPCp437Grid` gets consumed. - * * Show text on the screen. * *
@@ -740,7 +744,9 @@ struct SPCommand *sp_command_clone(const struct SPCommand *original); * Because Rust expects UTF-8 strings, it might be necessary to only send ASCII for now. *
* - * Will never return NULL. + * The passed `SPCp437Grid` gets consumed./// + * + * Returns: a new `Command::Cp437Data` instance. Will never return NULL. * * # Safety * @@ -756,7 +762,9 @@ struct SPCommand *sp_command_cp437_data(size_t x, struct SPCp437Grid *grid); /** - * Allocates a new `Command::FadeOut` instance. + * A yet-to-be-tested command. + * + * Returns: a new `Command::FadeOut` instance. Will never return NULL. * * # Safety * @@ -788,11 +796,12 @@ struct SPCommand *sp_command_fade_out(void); void sp_command_free(struct SPCommand *ptr); /** - * Allocates a new `Command::HardReset` instance. - * * Kills the udp daemon on the display, which usually results in a restart. + * * Please do not send this in your normal program flow. * + * Returns: a new `Command::HardReset` instance. Will never return NULL. + * * # Safety * * The caller has to make sure that: @@ -803,7 +812,9 @@ void sp_command_free(struct SPCommand *ptr); struct SPCommand *sp_command_hard_reset(void); /** - * Tries to turn a `SPPacket` into a `SPCommand`. The packet is deallocated in the process. + * Tries to turn a `SPPacket` into a `SPCommand`. + * + * The packet is deallocated in the process. * * Returns: pointer to new `SPCommand` instance or NULL * @@ -851,6 +862,7 @@ struct SPConnection *sp_connection_open(const char *host); /** * Sends a `SPCommand` to the display using the `SPConnection`. + * * The passed `SPCommand` gets consumed. * * returns: true in case of success @@ -868,6 +880,7 @@ bool sp_connection_send_command(const struct SPConnection *connection, /** * Sends a `SPPacket` to the display using the `SPConnection`. + * * The passed `SPPacket` gets consumed. * * returns: true in case of success diff --git a/crates/servicepoint_binding_c/src/command.rs b/crates/servicepoint_binding_c/src/command.rs index 60d97fe..a67c541 100644 --- a/crates/servicepoint_binding_c/src/command.rs +++ b/crates/servicepoint_binding_c/src/command.rs @@ -20,8 +20,8 @@ use crate::{ /// # Examples /// /// ```C -/// sp_connection_send(connection, sp_command_clear()); -/// sp_connection_send(connection, sp_command_brightness(5)); +/// sp_connection_send_command(connection, sp_command_clear()); +/// sp_connection_send_command(connection, sp_command_brightness(5)); /// ``` pub struct SPCommand(pub(crate) servicepoint::Command); @@ -31,7 +31,9 @@ impl Clone for SPCommand { } } -/// Tries to turn a `SPPacket` into a `SPCommand`. The packet is deallocated in the process. +/// Tries to turn a `SPPacket` into a `SPCommand`. +/// +/// The packet is deallocated in the process. /// /// Returns: pointer to new `SPCommand` instance or NULL /// @@ -72,14 +74,16 @@ pub unsafe extern "C" fn sp_command_clone( Box::into_raw(Box::new((*original).clone())) } -/// Allocates a new `Command::Clear` instance. +/// Set all pixels to the off state. /// -/// Set all pixels to the off state. Does not affect brightness. +/// Does not affect brightness. +/// +/// Returns: a new `Command::Clear` instance. Will never return NULL. /// /// # Examples /// /// ```C -/// sp_connection_send(connection, sp_command_clear()); +/// sp_connection_send_command(connection, sp_command_clear()); /// ``` /// /// # Safety @@ -93,11 +97,12 @@ pub unsafe extern "C" fn sp_command_clear() -> *mut SPCommand { Box::into_raw(Box::new(SPCommand(servicepoint::Command::Clear))) } -/// Allocates a new `Command::HardReset` instance. -/// /// Kills the udp daemon on the display, which usually results in a restart. +/// /// Please do not send this in your normal program flow. /// +/// Returns: a new `Command::HardReset` instance. Will never return NULL. +/// /// # Safety /// /// The caller has to make sure that: @@ -109,7 +114,9 @@ pub unsafe extern "C" fn sp_command_hard_reset() -> *mut SPCommand { Box::into_raw(Box::new(SPCommand(servicepoint::Command::HardReset))) } -/// Allocates a new `Command::FadeOut` instance. +/// A yet-to-be-tested command. +/// +/// Returns: a new `Command::FadeOut` instance. Will never return NULL. /// /// # Safety /// @@ -122,8 +129,9 @@ pub unsafe extern "C" fn sp_command_fade_out() -> *mut SPCommand { Box::into_raw(Box::new(SPCommand(servicepoint::Command::FadeOut))) } -/// Allocates a new `Command::Brightness` instance for setting the brightness of all tiles to the -/// same value. +/// Set the brightness of all tiles to the same value. +/// +/// Returns: a new `Command::Brightness` instance. Will never return NULL. /// /// # Panics /// @@ -146,10 +154,11 @@ pub unsafe extern "C" fn sp_command_brightness( )))) } -/// Allocates a new `Command::CharBrightness` instance. +/// Set the brightness of individual tiles in a rectangular area of the display. +/// /// The passed `SPBrightnessGrid` gets consumed. /// -/// Set the brightness of individual tiles in a rectangular area of the display. +/// Returns: a new `Command::CharBrightness` instance. Will never return NULL. /// /// # Safety /// @@ -172,9 +181,6 @@ pub unsafe extern "C" fn sp_command_char_brightness( )))) } -/// Allocates a new `Command::BitmapLinear` instance. -/// The passed `SPBitVec` gets consumed. -/// /// Set pixel data starting at the pixel offset on screen. /// /// The screen will continuously overwrite more pixel data without regarding the offset, meaning @@ -182,6 +188,10 @@ pub unsafe extern "C" fn sp_command_char_brightness( /// /// The contained `SPBitVec` is always uncompressed. /// +/// The passed `SPBitVec` gets consumed. +/// +/// Returns: a new `Command::BitmapLinear` instance. Will never return NULL. +/// /// # Safety /// /// The caller has to make sure that: @@ -205,9 +215,6 @@ pub unsafe extern "C" fn sp_command_bitmap_linear( )))) } -/// Allocates a new `Command::BitmapLinearAnd` instance. -/// The passed `SPBitVec` gets consumed. -/// /// Set pixel data according to an and-mask starting at the offset. /// /// The screen will continuously overwrite more pixel data without regarding the offset, meaning @@ -215,6 +222,10 @@ pub unsafe extern "C" fn sp_command_bitmap_linear( /// /// The contained `SPBitVec` is always uncompressed. /// +/// The passed `SPBitVec` gets consumed. +/// +/// Returns: a new `Command::BitmapLinearAnd` instance. Will never return NULL. +/// /// # Safety /// /// The caller has to make sure that: @@ -238,9 +249,6 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_and( )))) } -/// Allocates a new `Command::BitmapLinearOr` instance. -/// The passed `SPBitVec` gets consumed. -/// /// Set pixel data according to an or-mask starting at the offset. /// /// The screen will continuously overwrite more pixel data without regarding the offset, meaning @@ -248,6 +256,10 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_and( /// /// The contained `SPBitVec` is always uncompressed. /// +/// The passed `SPBitVec` gets consumed. +/// +/// Returns: a new `Command::BitmapLinearOr` instance. Will never return NULL. +/// /// # Safety /// /// The caller has to make sure that: @@ -271,9 +283,6 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_or( )))) } -/// Allocates a new `Command::BitmapLinearXor` instance. -/// The passed `SPBitVec` gets consumed. -/// /// Set pixel data according to a xor-mask starting at the offset. /// /// The screen will continuously overwrite more pixel data without regarding the offset, meaning @@ -281,6 +290,10 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_or( /// /// The contained `SPBitVec` is always uncompressed. /// +/// The passed `SPBitVec` gets consumed. +/// +/// Returns: a new `Command::BitmapLinearXor` instance. Will never return NULL. +/// /// # Safety /// /// The caller has to make sure that: @@ -304,9 +317,6 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_xor( )))) } -/// Allocates a new `Command::Cp437Data` instance. -/// The passed `SPCp437Grid` gets consumed. -/// /// Show text on the screen. /// ///
@@ -314,7 +324,9 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_xor( /// Because Rust expects UTF-8 strings, it might be necessary to only send ASCII for now. ///
/// -/// Will never return NULL. +/// The passed `SPCp437Grid` gets consumed./// +/// +/// Returns: a new `Command::Cp437Data` instance. Will never return NULL. /// /// # Safety /// @@ -337,12 +349,11 @@ pub unsafe extern "C" fn sp_command_cp437_data( )))) } -/// Allocates a new `Command::BitmapLinearWin` instance. -/// The passed `SPPixelGrid` gets consumed. -/// /// Sets a window of pixels to the specified values. /// -/// Will never return NULL. +/// The passed `SPPixelGrid` gets consumed. +/// +/// Returns: a new `Command::BitmapLinearWin` instance. Will never return NULL. /// /// # Safety /// diff --git a/crates/servicepoint_binding_c/src/connection.rs b/crates/servicepoint_binding_c/src/connection.rs index d993241..6d69c99 100644 --- a/crates/servicepoint_binding_c/src/connection.rs +++ b/crates/servicepoint_binding_c/src/connection.rs @@ -14,7 +14,7 @@ use crate::{SPCommand, SPPacket}; /// ```C /// CConnection connection = sp_connection_open("172.23.42.29:2342"); /// if (connection != NULL) -/// sp_connection_send(connection, sp_command_clear()); +/// sp_connection_send_command(connection, sp_command_clear()); /// ``` pub struct SPConnection(pub(crate) servicepoint::Connection); @@ -46,6 +46,7 @@ pub unsafe extern "C" fn sp_connection_open( } /// Sends a `SPPacket` to the display using the `SPConnection`. +/// /// The passed `SPPacket` gets consumed. /// /// returns: true in case of success @@ -67,6 +68,7 @@ pub unsafe extern "C" fn sp_connection_send_packet( } /// Sends a `SPCommand` to the display using the `SPConnection`. +/// /// The passed `SPCommand` gets consumed. /// /// returns: true in case of success diff --git a/crates/servicepoint_binding_c/src/lib.rs b/crates/servicepoint_binding_c/src/lib.rs index 698ae92..54161de 100644 --- a/crates/servicepoint_binding_c/src/lib.rs +++ b/crates/servicepoint_binding_c/src/lib.rs @@ -17,7 +17,7 @@ //! sp_pixel_grid_fill(pixels, true); //! //! SPCommand *command = sp_command_bitmap_linear_win(0, 0, pixels, Uncompressed); -//! while (sp_connection_send(connection, sp_command_clone(command))); +//! while (sp_connection_send_command(connection, sp_command_clone(command))); //! //! sp_packet_free(packet); //! sp_connection_free(connection); diff --git a/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs b/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs index c234069..038d8e6 100644 --- a/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs +++ b/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs @@ -372,7 +372,9 @@ namespace ServicePoint.BindGen public static extern ByteSlice sp_brightness_grid_unsafe_data_ref(BrightnessGrid* @this); /// - /// Tries to turn a `SPPacket` into a `SPCommand`. The packet is deallocated in the process. + /// Tries to turn a `SPPacket` into a `SPCommand`. + /// + /// The packet is deallocated in the process. /// /// Returns: pointer to new `SPCommand` instance or NULL /// @@ -405,14 +407,16 @@ namespace ServicePoint.BindGen public static extern Command* sp_command_clone(Command* original); /// - /// Allocates a new `Command::Clear` instance. + /// Set all pixels to the off state. /// - /// Set all pixels to the off state. Does not affect brightness. + /// Does not affect brightness. + /// + /// Returns: a new `Command::Clear` instance. Will never return NULL. /// /// # Examples /// /// ```C - /// sp_connection_send(connection, sp_command_clear()); + /// sp_connection_send_command(connection, sp_command_clear()); /// ``` /// /// # Safety @@ -426,11 +430,12 @@ namespace ServicePoint.BindGen public static extern Command* sp_command_clear(); /// - /// Allocates a new `Command::HardReset` instance. - /// /// Kills the udp daemon on the display, which usually results in a restart. + /// /// Please do not send this in your normal program flow. /// + /// Returns: a new `Command::HardReset` instance. Will never return NULL. + /// /// # Safety /// /// The caller has to make sure that: @@ -442,7 +447,9 @@ namespace ServicePoint.BindGen public static extern Command* sp_command_hard_reset(); /// - /// Allocates a new `Command::FadeOut` instance. + /// A yet-to-be-tested command. + /// + /// Returns: a new `Command::FadeOut` instance. Will never return NULL. /// /// # Safety /// @@ -455,8 +462,9 @@ namespace ServicePoint.BindGen public static extern Command* sp_command_fade_out(); /// - /// Allocates a new `Command::Brightness` instance for setting the brightness of all tiles to the - /// same value. + /// Set the brightness of all tiles to the same value. + /// + /// Returns: a new `Command::Brightness` instance. Will never return NULL. /// /// # Panics /// @@ -473,10 +481,11 @@ namespace ServicePoint.BindGen public static extern Command* sp_command_brightness(byte brightness); /// - /// Allocates a new `Command::CharBrightness` instance. + /// Set the brightness of individual tiles in a rectangular area of the display. + /// /// The passed `SPBrightnessGrid` gets consumed. /// - /// Set the brightness of individual tiles in a rectangular area of the display. + /// Returns: a new `Command::CharBrightness` instance. Will never return NULL. /// /// # Safety /// @@ -491,9 +500,6 @@ namespace ServicePoint.BindGen public static extern Command* sp_command_char_brightness(nuint x, nuint y, BrightnessGrid* grid); /// - /// Allocates a new `Command::BitmapLinear` instance. - /// The passed `SPBitVec` gets consumed. - /// /// Set pixel data starting at the pixel offset on screen. /// /// The screen will continuously overwrite more pixel data without regarding the offset, meaning @@ -501,6 +507,10 @@ namespace ServicePoint.BindGen /// /// The contained `SPBitVec` is always uncompressed. /// + /// The passed `SPBitVec` gets consumed. + /// + /// Returns: a new `Command::BitmapLinear` instance. Will never return NULL. + /// /// # Safety /// /// The caller has to make sure that: @@ -515,9 +525,6 @@ namespace ServicePoint.BindGen public static extern Command* sp_command_bitmap_linear(nuint offset, BitVec* bit_vec, CompressionCode compression); /// - /// Allocates a new `Command::BitmapLinearAnd` instance. - /// The passed `SPBitVec` gets consumed. - /// /// Set pixel data according to an and-mask starting at the offset. /// /// The screen will continuously overwrite more pixel data without regarding the offset, meaning @@ -525,6 +532,10 @@ namespace ServicePoint.BindGen /// /// The contained `SPBitVec` is always uncompressed. /// + /// The passed `SPBitVec` gets consumed. + /// + /// Returns: a new `Command::BitmapLinearAnd` instance. Will never return NULL. + /// /// # Safety /// /// The caller has to make sure that: @@ -539,9 +550,6 @@ namespace ServicePoint.BindGen public static extern Command* sp_command_bitmap_linear_and(nuint offset, BitVec* bit_vec, CompressionCode compression); /// - /// Allocates a new `Command::BitmapLinearOr` instance. - /// The passed `SPBitVec` gets consumed. - /// /// Set pixel data according to an or-mask starting at the offset. /// /// The screen will continuously overwrite more pixel data without regarding the offset, meaning @@ -549,6 +557,10 @@ namespace ServicePoint.BindGen /// /// The contained `SPBitVec` is always uncompressed. /// + /// The passed `SPBitVec` gets consumed. + /// + /// Returns: a new `Command::BitmapLinearOr` instance. Will never return NULL. + /// /// # Safety /// /// The caller has to make sure that: @@ -563,9 +575,6 @@ namespace ServicePoint.BindGen public static extern Command* sp_command_bitmap_linear_or(nuint offset, BitVec* bit_vec, CompressionCode compression); /// - /// Allocates a new `Command::BitmapLinearXor` instance. - /// The passed `SPBitVec` gets consumed. - /// /// Set pixel data according to a xor-mask starting at the offset. /// /// The screen will continuously overwrite more pixel data without regarding the offset, meaning @@ -573,6 +582,10 @@ namespace ServicePoint.BindGen /// /// The contained `SPBitVec` is always uncompressed. /// + /// The passed `SPBitVec` gets consumed. + /// + /// Returns: a new `Command::BitmapLinearXor` instance. Will never return NULL. + /// /// # Safety /// /// The caller has to make sure that: @@ -587,9 +600,6 @@ namespace ServicePoint.BindGen public static extern Command* sp_command_bitmap_linear_xor(nuint offset, BitVec* bit_vec, CompressionCode compression); /// - /// Allocates a new `Command::Cp437Data` instance. - /// The passed `SPCp437Grid` gets consumed. - /// /// Show text on the screen. /// /// <div class="warning"> @@ -597,7 +607,9 @@ namespace ServicePoint.BindGen /// Because Rust expects UTF-8 strings, it might be necessary to only send ASCII for now. /// </div> /// - /// Will never return NULL. + /// The passed `SPCp437Grid` gets consumed./// + /// + /// Returns: a new `Command::Cp437Data` instance. Will never return NULL. /// /// # Safety /// @@ -612,12 +624,11 @@ namespace ServicePoint.BindGen public static extern Command* sp_command_cp437_data(nuint x, nuint y, Cp437Grid* grid); /// - /// Allocates a new `Command::BitmapLinearWin` instance. - /// The passed `SPPixelGrid` gets consumed. - /// /// Sets a window of pixels to the specified values. /// - /// Will never return NULL. + /// The passed `SPPixelGrid` gets consumed. + /// + /// Returns: a new `Command::BitmapLinearWin` instance. Will never return NULL. /// /// # Safety /// @@ -674,6 +685,7 @@ namespace ServicePoint.BindGen /// /// Sends a `SPPacket` to the display using the `SPConnection`. + /// /// The passed `SPPacket` gets consumed. /// /// returns: true in case of success @@ -692,6 +704,7 @@ namespace ServicePoint.BindGen /// /// Sends a `SPCommand` to the display using the `SPConnection`. + /// /// The passed `SPCommand` gets consumed. /// /// returns: true in case of success From 3e3a933ecb77dc4a62d861eeaf2d392bc34a3fcc Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Sat, 7 Sep 2024 14:53:16 +0200 Subject: [PATCH 27/31] fix example --- crates/servicepoint_binding_c/README.md | 2 +- crates/servicepoint_binding_c/src/lib.rs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/servicepoint_binding_c/README.md b/crates/servicepoint_binding_c/README.md index ba03216..16240a9 100644 --- a/crates/servicepoint_binding_c/README.md +++ b/crates/servicepoint_binding_c/README.md @@ -27,7 +27,7 @@ int main(void) { SPCommand *command = sp_command_bitmap_linear_win(0, 0, pixels, Uncompressed); while (sp_connection_send_command(connection, sp_command_clone(command))); - sp_packet_free(packet); + sp_command_free(command); sp_connection_free(connection); return 0; } diff --git a/crates/servicepoint_binding_c/src/lib.rs b/crates/servicepoint_binding_c/src/lib.rs index 54161de..d6f839b 100644 --- a/crates/servicepoint_binding_c/src/lib.rs +++ b/crates/servicepoint_binding_c/src/lib.rs @@ -19,7 +19,7 @@ //! SPCommand *command = sp_command_bitmap_linear_win(0, 0, pixels, Uncompressed); //! while (sp_connection_send_command(connection, sp_command_clone(command))); //! -//! sp_packet_free(packet); +//! sp_command_free(command); //! sp_connection_free(connection); //! return 0; //! } From e46391ca5f997e5b7d77d195595cca2c5a6174d7 Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Sat, 7 Sep 2024 15:06:11 +0200 Subject: [PATCH 28/31] replace usages of 'this' as parameter name --- .../examples/lang_c/include/servicepoint.h | 282 ++++++++++-------- crates/servicepoint_binding_c/src/bit_vec.rs | 77 +++-- .../src/brightness_grid.rs | 100 ++++--- crates/servicepoint_binding_c/src/command.rs | 20 +- .../servicepoint_binding_c/src/connection.rs | 18 +- .../servicepoint_binding_c/src/cp437_grid.rs | 73 ++--- crates/servicepoint_binding_c/src/packet.rs | 16 +- .../servicepoint_binding_c/src/pixel_grid.rs | 70 ++--- .../ServicePoint/BindGen/ServicePoint.g.cs | 277 +++++++++-------- 9 files changed, 506 insertions(+), 427 deletions(-) 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 5039509..ce780ff 100644 --- a/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h +++ b/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h @@ -203,28 +203,29 @@ extern "C" { * * The caller has to make sure that: * - * - `this` points to a valid `SPBitVec` - * - `this` is not written to concurrently + * - `bit_vec` points to a valid `SPBitVec` + * - `bit_vec` 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_free`. */ -struct SPBitVec *sp_bit_vec_clone(const struct SPBitVec *this_); +struct SPBitVec *sp_bit_vec_clone(const struct SPBitVec *bit_vec); /** * Sets the value of all bits in the `SPBitVec`. * * # Arguments * + * - `bit_vec`: instance to write to * - `value`: the value to set all bits to * * # Safety * * The caller has to make sure that: * - * - `this` points to a valid `SPBitVec` - * - `this` is not written to or read from concurrently + * - `bit_vec` points to a valid `SPBitVec` + * - `bit_vec` is not written to or read from concurrently */ -void sp_bit_vec_fill(struct SPBitVec *this_, bool value); +void sp_bit_vec_fill(struct SPBitVec *bit_vec, bool value); /** * Deallocates a `SPBitVec`. @@ -233,18 +234,18 @@ void sp_bit_vec_fill(struct SPBitVec *this_, bool value); * * The caller has to make sure that: * - * - `this` points to a valid `SPBitVec` - * - `this` is not used concurrently or after this call - * - `this` was not passed to another consuming function, e.g. to create a `SPCommand` + * - `bit_vec` points to a valid `SPBitVec` + * - `bit_vec` is not used concurrently or after this call + * - `bit_vec` was not passed to another consuming function, e.g. to create a `SPCommand` */ -void sp_bit_vec_free(struct SPBitVec *this_); +void sp_bit_vec_free(struct SPBitVec *bit_vec); /** * Gets the value of a bit from the `SPBitVec`. * * # Arguments * - * - `this`: instance to read from + * - `bit_vec`: instance to read from * - `index`: the bit index to read * * returns: value of the bit @@ -257,32 +258,40 @@ void sp_bit_vec_free(struct SPBitVec *this_); * * The caller has to make sure that: * - * - `this` points to a valid `SPBitVec` - * - `this` is not written to concurrently + * - `bit_vec` points to a valid `SPBitVec` + * - `bit_vec` is not written to concurrently */ -bool sp_bit_vec_get(const struct SPBitVec *this_, size_t index); +bool sp_bit_vec_get(const struct SPBitVec *bit_vec, size_t index); /** * Returns true if length is 0. * + * # Arguments + * + * - `bit_vec`: instance to write to + * * # Safety * * The caller has to make sure that: * - * - `this` points to a valid `SPBitVec` + * - `bit_vec` points to a valid `SPBitVec` */ -bool sp_bit_vec_is_empty(const struct SPBitVec *this_); +bool sp_bit_vec_is_empty(const struct SPBitVec *bit_vec); /** * Gets the length of the `SPBitVec` in bits. * + * # Arguments + * + * - `bit_vec`: instance to write to + * * # Safety * * The caller has to make sure that: * - * - `this` points to a valid `SPBitVec` + * - `bit_vec` points to a valid `SPBitVec` */ -size_t sp_bit_vec_len(const struct SPBitVec *this_); +size_t sp_bit_vec_len(const struct SPBitVec *bit_vec); /** * Interpret the data as a series of bits and load then into a new `SPBitVec` instance. @@ -326,7 +335,7 @@ struct SPBitVec *sp_bit_vec_new(size_t size); * * # Arguments * - * - `this`: instance to write to + * - `bit_vec`: instance to write to * - `index`: the bit index to edit * - `value`: the value to set the bit to * @@ -340,44 +349,52 @@ struct SPBitVec *sp_bit_vec_new(size_t size); * * The caller has to make sure that: * - * - `this` points to a valid `SPBitVec` - * - `this` is not written to or read from concurrently + * - `bit_vec` points to a valid `SPBitVec` + * - `bit_vec` is not written to or read from concurrently */ -void sp_bit_vec_set(struct SPBitVec *this_, size_t index, bool value); +void sp_bit_vec_set(struct SPBitVec *bit_vec, size_t index, bool value); /** * Gets an unsafe reference to the data of the `SPBitVec` instance. * + * # Arguments + * + * - `bit_vec`: instance to write to + * * ## Safety * * The caller has to make sure that: * - * - `this` points to a valid `SPBitVec` + * - `bit_vec` points to a valid `SPBitVec` * - the returned memory range is never accessed after the passed `SPBitVec` has been freed * - the returned memory range is never accessed concurrently, either via the `SPBitVec` or directly */ -struct SPByteSlice sp_bit_vec_unsafe_data_ref(struct SPBitVec *this_); +struct SPByteSlice sp_bit_vec_unsafe_data_ref(struct SPBitVec *bit_vec); /** * Clones a `SPBrightnessGrid`. * + * # Arguments + * + * - `brightness_grid`: instance to read from + * * # Safety * * The caller has to make sure that: * - * - `this` points to a valid `SPBrightnessGrid` - * - `this` is not written to concurrently + * - `brightness_grid` points to a valid `SPBrightnessGrid` + * - `brightness_grid` is not written to concurrently * - the returned instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_brightness_grid_free`. */ -struct SPBrightnessGrid *sp_brightness_grid_clone(const struct SPBrightnessGrid *this_); +struct SPBrightnessGrid *sp_brightness_grid_clone(const struct SPBrightnessGrid *brightness_grid); /** * Sets the value of all cells in the `SPBrightnessGrid`. * * # Arguments * - * - `this`: instance to write to + * - `brightness_grid`: instance to write to * - `value`: the value to set all cells to * * # Panics @@ -388,30 +405,35 @@ struct SPBrightnessGrid *sp_brightness_grid_clone(const struct SPBrightnessGrid * * The caller has to make sure that: * - * - `this` points to a valid `SPBrightnessGrid` - * - `this` is not written to or read from concurrently + * - `brightness_grid` points to a valid `SPBrightnessGrid` + * - `brightness_grid` is not written to or read from concurrently */ -void sp_brightness_grid_fill(struct SPBrightnessGrid *this_, uint8_t value); +void sp_brightness_grid_fill(struct SPBrightnessGrid *brightness_grid, + uint8_t value); /** * Deallocates a `SPBrightnessGrid`. * + * # Arguments + * + * - `brightness_grid`: instance to read from + * * # Safety * * The caller has to make sure that: * - * - `this` points to a valid `SPBrightnessGrid` - * - `this` is not used concurrently or after this call - * - `this` was not passed to another consuming function, e.g. to create a `SPCommand` + * - `brightness_grid` points to a valid `SPBrightnessGrid` + * - `brightness_grid` is not used concurrently or after this call + * - `brightness_grid` was not passed to another consuming function, e.g. to create a `SPCommand` */ -void sp_brightness_grid_free(struct SPBrightnessGrid *this_); +void sp_brightness_grid_free(struct SPBrightnessGrid *brightness_grid); /** * Gets the current value at the specified position. * * # Arguments * - * - `this`: instance to read from + * - `brightness_grid`: instance to read from * - `x` and `y`: position of the cell to read * * # Panics @@ -422,10 +444,10 @@ void sp_brightness_grid_free(struct SPBrightnessGrid *this_); * * The caller has to make sure that: * - * - `this` points to a valid `SPBrightnessGrid` - * - `this` is not written to concurrently + * - `brightness_grid` points to a valid `SPBrightnessGrid` + * - `brightness_grid` is not written to concurrently */ -uint8_t sp_brightness_grid_get(const struct SPBrightnessGrid *this_, +uint8_t sp_brightness_grid_get(const struct SPBrightnessGrid *brightness_grid, size_t x, size_t y); @@ -434,15 +456,15 @@ uint8_t sp_brightness_grid_get(const struct SPBrightnessGrid *this_, * * # Arguments * - * - `this`: instance to read from + * - `brightness_grid`: instance to read from * * # Safety * * The caller has to make sure that: * - * - `this` points to a valid `SPBrightnessGrid` + * - `brightness_grid` points to a valid `SPBrightnessGrid` */ -size_t sp_brightness_grid_height(const struct SPBrightnessGrid *this_); +size_t sp_brightness_grid_height(const struct SPBrightnessGrid *brightness_grid); /** * Loads a `SPBrightnessGrid` with the specified dimensions from the provided data. @@ -485,7 +507,7 @@ struct SPBrightnessGrid *sp_brightness_grid_new(size_t width, * * # Arguments * - * - `this`: instance to write to + * - `brightness_grid`: instance to write to * - `x` and `y`: position of the cell * - `value`: the value to write to the cell * @@ -500,10 +522,10 @@ struct SPBrightnessGrid *sp_brightness_grid_new(size_t width, * * The caller has to make sure that: * - * - `this` points to a valid `SPBitVec` - * - `this` is not written to or read from concurrently + * - `brightness_grid` points to a valid `SPBitVec` + * - `brightness_grid` is not written to or read from concurrently */ -void sp_brightness_grid_set(struct SPBrightnessGrid *this_, +void sp_brightness_grid_set(struct SPBrightnessGrid *brightness_grid, size_t x, size_t y, uint8_t value); @@ -511,30 +533,34 @@ void sp_brightness_grid_set(struct SPBrightnessGrid *this_, /** * Gets an unsafe reference to the data of the `SPBrightnessGrid` instance. * + * # Arguments + * + * - `brightness_grid`: instance to read from + * * ## Safety * * The caller has to make sure that: * - * - `this` points to a valid `SPBrightnessGrid` + * - `brightness_grid` points to a valid `SPBrightnessGrid` * - the returned memory range is never accessed after the passed `SPBrightnessGrid` has been freed * - the returned memory range is never accessed concurrently, either via the `SPBrightnessGrid` or directly */ -struct SPByteSlice sp_brightness_grid_unsafe_data_ref(struct SPBrightnessGrid *this_); +struct SPByteSlice sp_brightness_grid_unsafe_data_ref(struct SPBrightnessGrid *brightness_grid); /** * Gets the width of the `SPBrightnessGrid` instance. * * # Arguments * - * - `this`: instance to read from + * - `brightness_grid`: instance to read from * * # Safety * * The caller has to make sure that: * - * - `this` points to a valid `SPBrightnessGrid` + * - `brightness_grid` points to a valid `SPBrightnessGrid` */ -size_t sp_brightness_grid_width(const struct SPBrightnessGrid *this_); +size_t sp_brightness_grid_width(const struct SPBrightnessGrid *brightness_grid); /** * Set pixel data starting at the pixel offset on screen. @@ -729,12 +755,12 @@ struct SPCommand *sp_command_clear(void); * * The caller has to make sure that: * - * - `this` points to a valid instance of `SPCommand` - * - `this` is not written to concurrently + * - `command` points to a valid instance of `SPCommand` + * - `command` is not written to concurrently * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_free`. */ -struct SPCommand *sp_command_clone(const struct SPCommand *original); +struct SPCommand *sp_command_clone(const struct SPCommand *command); /** * Show text on the screen. @@ -789,11 +815,11 @@ struct SPCommand *sp_command_fade_out(void); * * The caller has to make sure that: * - * - `this` points to a valid `SPCommand` - * - `this` is not used concurrently or after this call - * - `this` was not passed to another consuming function, e.g. to create a `SPPacket` + * - `command` points to a valid `SPCommand` + * - `command` is not used concurrently or after this call + * - `command` was not passed to another consuming function, e.g. to create a `SPPacket` */ -void sp_command_free(struct SPCommand *ptr); +void sp_command_free(struct SPCommand *command); /** * Kills the udp daemon on the display, which usually results in a restart. @@ -837,10 +863,10 @@ struct SPCommand *sp_command_try_from_packet(struct SPPacket *packet); * * The caller has to make sure that: * - * - `this` points to a valid `SPConnection` - * - `this` is not used concurrently or after this call + * - `connection` points to a valid `SPConnection` + * - `connection` is not used concurrently or after this call */ -void sp_connection_free(struct SPConnection *ptr); +void sp_connection_free(struct SPConnection *connection); /** * Creates a new instance of `SPConnection`. @@ -863,7 +889,7 @@ struct SPConnection *sp_connection_open(const char *host); /** * Sends a `SPCommand` to the display using the `SPConnection`. * - * The passed `SPCommand` gets consumed. + * The passed `command` gets consumed. * * returns: true in case of success * @@ -881,7 +907,7 @@ bool sp_connection_send_command(const struct SPConnection *connection, /** * Sends a `SPPacket` to the display using the `SPConnection`. * - * The passed `SPPacket` gets consumed. + * The passed `packet` gets consumed. * * returns: true in case of success * @@ -889,9 +915,9 @@ bool sp_connection_send_command(const struct SPConnection *connection, * * The caller has to make sure that: * - * - `SPConnection` points to a valid instance of `SPConnection` - * - `SPPacket` points to a valid instance of `SPPacket` - * - `SPPacket` is not used concurrently or after this call + * - `connection` points to a valid instance of `SPConnection` + * - `packet` points to a valid instance of `SPPacket` + * - `packet` is not used concurrently or after this call */ bool sp_connection_send_packet(const struct SPConnection *connection, struct SPPacket *packet); @@ -905,29 +931,29 @@ bool sp_connection_send_packet(const struct SPConnection *connection, * * The caller has to make sure that: * - * - `this` points to a valid `SPCp437Grid` - * - `this` is not written to concurrently + * - `cp437_grid` points to a valid `SPCp437Grid` + * - `cp437_grid` is not written to concurrently * - the returned instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_cp437_grid_free`. */ -struct SPCp437Grid *sp_cp437_grid_clone(const struct SPCp437Grid *this_); +struct SPCp437Grid *sp_cp437_grid_clone(const struct SPCp437Grid *cp437_grid); /** * Sets the value of all cells in the `SPCp437Grid`. * * # Arguments * - * - `this`: instance to write to + * - `cp437_grid`: 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 `SPCp437Grid` - * - `this` is not written to or read from concurrently + * - `cp437_grid` points to a valid `SPCp437Grid` + * - `cp437_grid` is not written to or read from concurrently */ -void sp_cp437_grid_fill(struct SPCp437Grid *this_, uint8_t value); +void sp_cp437_grid_fill(struct SPCp437Grid *cp437_grid, uint8_t value); /** * Deallocates a `SPCp437Grid`. @@ -936,18 +962,18 @@ void sp_cp437_grid_fill(struct SPCp437Grid *this_, uint8_t value); * * The caller has to make sure that: * - * - `this` points to a valid `SPCp437Grid` - * - `this` is not used concurrently or after this call - * - `this` was not passed to another consuming function, e.g. to create a `SPCommand` + * - `cp437_grid` points to a valid `SPCp437Grid` + * - `cp437_grid` is not used concurrently or after cp437_grid call + * - `cp437_grid` was not passed to another consuming function, e.g. to create a `SPCommand` */ -void sp_cp437_grid_free(struct SPCp437Grid *this_); +void sp_cp437_grid_free(struct SPCp437Grid *cp437_grid); /** * Gets the current value at the specified position. * * # Arguments * - * - `this`: instance to read from + * - `cp437_grid`: instance to read from * - `x` and `y`: position of the cell to read * * # Panics @@ -958,25 +984,27 @@ void sp_cp437_grid_free(struct SPCp437Grid *this_); * * The caller has to make sure that: * - * - `this` points to a valid `SPCp437Grid` - * - `this` is not written to concurrently + * - `cp437_grid` points to a valid `SPCp437Grid` + * - `cp437_grid` is not written to concurrently */ -uint8_t sp_cp437_grid_get(const struct SPCp437Grid *this_, size_t x, size_t y); +uint8_t sp_cp437_grid_get(const struct SPCp437Grid *cp437_grid, + size_t x, + size_t y); /** * Gets the height of the `SPCp437Grid` instance. * * # Arguments * - * - `this`: instance to read from + * - `cp437_grid`: instance to read from * * # Safety * * The caller has to make sure that: * - * - `this` points to a valid `SPCp437Grid` + * - `cp437_grid` points to a valid `SPCp437Grid` */ -size_t sp_cp437_grid_height(const struct SPCp437Grid *this_); +size_t sp_cp437_grid_height(const struct SPCp437Grid *cp437_grid); /** * Loads a `SPCp437Grid` with the specified dimensions from the provided data. @@ -1021,7 +1049,7 @@ struct SPCp437Grid *sp_cp437_grid_new(size_t width, * * # Arguments * - * - `this`: instance to write to + * - `cp437_grid`: instance to write to * - `x` and `y`: position of the cell * - `value`: the value to write to the cell * @@ -1035,10 +1063,10 @@ struct SPCp437Grid *sp_cp437_grid_new(size_t width, * * The caller has to make sure that: * - * - `this` points to a valid `SPBitVec` - * - `this` is not written to or read from concurrently + * - `cp437_grid` points to a valid `SPBitVec` + * - `cp437_grid` is not written to or read from concurrently */ -void sp_cp437_grid_set(struct SPCp437Grid *this_, +void sp_cp437_grid_set(struct SPCp437Grid *cp437_grid, size_t x, size_t y, uint8_t value); @@ -1052,26 +1080,26 @@ void sp_cp437_grid_set(struct SPCp437Grid *this_, * * The caller has to make sure that: * - * - `this` points to a valid `SPCp437Grid` + * - `cp437_grid` points to a valid `SPCp437Grid` * - the returned memory range is never accessed after the passed `SPCp437Grid` has been freed * - the returned memory range is never accessed concurrently, either via the `SPCp437Grid` or directly */ -struct SPByteSlice sp_cp437_grid_unsafe_data_ref(struct SPCp437Grid *this_); +struct SPByteSlice sp_cp437_grid_unsafe_data_ref(struct SPCp437Grid *cp437_grid); /** * Gets the width of the `SPCp437Grid` instance. * * # Arguments * - * - `this`: instance to read from + * - `cp437_grid`: instance to read from * * # Safety * * The caller has to make sure that: * - * - `this` points to a valid `SPCp437Grid` + * - `cp437_grid` points to a valid `SPCp437Grid` */ -size_t sp_cp437_grid_width(const struct SPCp437Grid *this_); +size_t sp_cp437_grid_width(const struct SPCp437Grid *cp437_grid); /** * Clones a `SPPacket`. @@ -1082,12 +1110,12 @@ size_t sp_cp437_grid_width(const struct SPCp437Grid *this_); * * The caller has to make sure that: * - * - `this` points to a valid `SPPacket` - * - `this` is not written to concurrently + * - `packet` points to a valid `SPPacket` + * - `packet` is not written to concurrently * - the returned instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_packet_free`. */ -struct SPPacket *sp_packet_clone(const struct SPPacket *this_); +struct SPPacket *sp_packet_clone(const struct SPPacket *packet); /** * Deallocates a `SPPacket`. @@ -1096,10 +1124,10 @@ struct SPPacket *sp_packet_clone(const struct SPPacket *this_); * * The caller has to make sure that: * - * - `this` points to a valid `SPPacket` - * - `this` is not used concurrently or after this call + * - `packet` points to a valid `SPPacket` + * - `packet` is not used concurrently or after this call */ -void sp_packet_free(struct SPPacket *this_); +void sp_packet_free(struct SPPacket *packet); /** * Turns a `SPCommand` into a `SPPacket`. @@ -1144,29 +1172,29 @@ struct SPPacket *sp_packet_try_load(const uint8_t *data, * * The caller has to make sure that: * - * - `this` points to a valid `SPPixelGrid` - * - `this` is not written to concurrently + * - `pixel_grid` points to a valid `SPPixelGrid` + * - `pixel_grid` 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_free`. */ -struct SPPixelGrid *sp_pixel_grid_clone(const struct SPPixelGrid *this_); +struct SPPixelGrid *sp_pixel_grid_clone(const struct SPPixelGrid *pixel_grid); /** * Sets the state of all pixels in the `SPPixelGrid`. * * # Arguments * - * - `this`: instance to write to + * - `pixel_grid`: 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 `SPPixelGrid` - * - `this` is not written to or read from concurrently + * - `pixel_grid` points to a valid `SPPixelGrid` + * - `pixel_grid` is not written to or read from concurrently */ -void sp_pixel_grid_fill(struct SPPixelGrid *this_, bool value); +void sp_pixel_grid_fill(struct SPPixelGrid *pixel_grid, bool value); /** * Deallocates a `SPPixelGrid`. @@ -1175,18 +1203,18 @@ void sp_pixel_grid_fill(struct SPPixelGrid *this_, bool value); * * The caller has to make sure that: * - * - `this` points to a valid `SPPixelGrid` - * - `this` is not used concurrently or after this call - * - `this` was not passed to another consuming function, e.g. to create a `SPCommand` + * - `pixel_grid` points to a valid `SPPixelGrid` + * - `pixel_grid` is not used concurrently or after pixel_grid call + * - `pixel_grid` was not passed to another consuming function, e.g. to create a `SPCommand` */ -void sp_pixel_grid_free(struct SPPixelGrid *this_); +void sp_pixel_grid_free(struct SPPixelGrid *pixel_grid); /** * Gets the current value at the specified position in the `SPPixelGrid`. * * # Arguments * - * - `this`: instance to read from + * - `pixel_grid`: instance to read from * - `x` and `y`: position of the cell to read * * # Panics @@ -1197,25 +1225,27 @@ void sp_pixel_grid_free(struct SPPixelGrid *this_); * * The caller has to make sure that: * - * - `this` points to a valid `SPPixelGrid` - * - `this` is not written to concurrently + * - `pixel_grid` points to a valid `SPPixelGrid` + * - `pixel_grid` is not written to concurrently */ -bool sp_pixel_grid_get(const struct SPPixelGrid *this_, size_t x, size_t y); +bool sp_pixel_grid_get(const struct SPPixelGrid *pixel_grid, + size_t x, + size_t y); /** * Gets the height in pixels of the `SPPixelGrid` instance. * * # Arguments * - * - `this`: instance to read from + * - `pixel_grid`: instance to read from * * # Safety * * The caller has to make sure that: * - * - `this` points to a valid `SPPixelGrid` + * - `pixel_grid` points to a valid `SPPixelGrid` */ -size_t sp_pixel_grid_height(const struct SPPixelGrid *this_); +size_t sp_pixel_grid_height(const struct SPPixelGrid *pixel_grid); /** * Loads a `SPPixelGrid` with the specified dimensions from the provided data. @@ -1274,7 +1304,7 @@ struct SPPixelGrid *sp_pixel_grid_new(size_t width, * * # Arguments * - * - `this`: instance to write to + * - `pixel_grid`: instance to write to * - `x` and `y`: position of the cell * - `value`: the value to write to the cell * @@ -1288,10 +1318,10 @@ struct SPPixelGrid *sp_pixel_grid_new(size_t width, * * The caller has to make sure that: * - * - `this` points to a valid `SPPixelGrid` - * - `this` is not written to or read from concurrently + * - `pixel_grid` points to a valid `SPPixelGrid` + * - `pixel_grid` is not written to or read from concurrently */ -void sp_pixel_grid_set(struct SPPixelGrid *this_, +void sp_pixel_grid_set(struct SPPixelGrid *pixel_grid, size_t x, size_t y, bool value); @@ -1303,26 +1333,26 @@ void sp_pixel_grid_set(struct SPPixelGrid *this_, * * The caller has to make sure that: * - * - `this` points to a valid `SPPixelGrid` + * - `pixel_grid` points to a valid `SPPixelGrid` * - the returned memory range is never accessed after the passed `SPPixelGrid` has been freed * - the returned memory range is never accessed concurrently, either via the `SPPixelGrid` or directly */ -struct SPByteSlice sp_pixel_grid_unsafe_data_ref(struct SPPixelGrid *this_); +struct SPByteSlice sp_pixel_grid_unsafe_data_ref(struct SPPixelGrid *pixel_grid); /** * Gets the width in pixels of the `SPPixelGrid` instance. * * # Arguments * - * - `this`: instance to read from + * - `pixel_grid`: instance to read from * * # Safety * * The caller has to make sure that: * - * - `this` points to a valid `SPPixelGrid` + * - `pixel_grid` points to a valid `SPPixelGrid` */ -size_t sp_pixel_grid_width(const struct SPPixelGrid *this_); +size_t sp_pixel_grid_width(const struct SPPixelGrid *pixel_grid); #ifdef __cplusplus } // extern "C" diff --git a/crates/servicepoint_binding_c/src/bit_vec.rs b/crates/servicepoint_binding_c/src/bit_vec.rs index 6fa5795..d1b353c 100644 --- a/crates/servicepoint_binding_c/src/bit_vec.rs +++ b/crates/servicepoint_binding_c/src/bit_vec.rs @@ -81,15 +81,15 @@ pub unsafe extern "C" fn sp_bit_vec_load( /// /// The caller has to make sure that: /// -/// - `this` points to a valid `SPBitVec` -/// - `this` is not written to concurrently +/// - `bit_vec` points to a valid `SPBitVec` +/// - `bit_vec` 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_free`. #[no_mangle] pub unsafe extern "C" fn sp_bit_vec_clone( - this: *const SPBitVec, + bit_vec: *const SPBitVec, ) -> *mut SPBitVec { - Box::into_raw(Box::new((*this).clone())) + Box::into_raw(Box::new((*bit_vec).clone())) } /// Deallocates a `SPBitVec`. @@ -98,19 +98,19 @@ pub unsafe extern "C" fn sp_bit_vec_clone( /// /// The caller has to make sure that: /// -/// - `this` points to a valid `SPBitVec` -/// - `this` is not used concurrently or after this call -/// - `this` was not passed to another consuming function, e.g. to create a `SPCommand` +/// - `bit_vec` points to a valid `SPBitVec` +/// - `bit_vec` is not used concurrently or after this call +/// - `bit_vec` was not passed to another consuming function, e.g. to create a `SPCommand` #[no_mangle] -pub unsafe extern "C" fn sp_bit_vec_free(this: *mut SPBitVec) { - _ = Box::from_raw(this); +pub unsafe extern "C" fn sp_bit_vec_free(bit_vec: *mut SPBitVec) { + _ = Box::from_raw(bit_vec); } /// Gets the value of a bit from the `SPBitVec`. /// /// # Arguments /// -/// - `this`: instance to read from +/// - `bit_vec`: instance to read from /// - `index`: the bit index to read /// /// returns: value of the bit @@ -123,21 +123,21 @@ pub unsafe extern "C" fn sp_bit_vec_free(this: *mut SPBitVec) { /// /// The caller has to make sure that: /// -/// - `this` points to a valid `SPBitVec` -/// - `this` is not written to concurrently +/// - `bit_vec` points to a valid `SPBitVec` +/// - `bit_vec` is not written to concurrently #[no_mangle] pub unsafe extern "C" fn sp_bit_vec_get( - this: *const SPBitVec, + bit_vec: *const SPBitVec, index: usize, ) -> bool { - *(*this).0.get(index).unwrap() + *(*bit_vec).0.get(index).unwrap() } /// Sets the value of a bit in the `SPBitVec`. /// /// # Arguments /// -/// - `this`: instance to write to +/// - `bit_vec`: instance to write to /// - `index`: the bit index to edit /// - `value`: the value to set the bit to /// @@ -151,72 +151,85 @@ pub unsafe extern "C" fn sp_bit_vec_get( /// /// The caller has to make sure that: /// -/// - `this` points to a valid `SPBitVec` -/// - `this` is not written to or read from concurrently +/// - `bit_vec` points to a valid `SPBitVec` +/// - `bit_vec` is not written to or read from concurrently #[no_mangle] pub unsafe extern "C" fn sp_bit_vec_set( - this: *mut SPBitVec, + bit_vec: *mut SPBitVec, index: usize, value: bool, ) { - (*this).0.set(index, value) + (*bit_vec).0.set(index, value) } /// Sets the value of all bits in the `SPBitVec`. /// /// # Arguments /// +/// - `bit_vec`: instance to write to /// - `value`: the value to set all bits to /// /// # Safety /// /// The caller has to make sure that: /// -/// - `this` points to a valid `SPBitVec` -/// - `this` is not written to or read from concurrently +/// - `bit_vec` points to a valid `SPBitVec` +/// - `bit_vec` is not written to or read from concurrently #[no_mangle] -pub unsafe extern "C" fn sp_bit_vec_fill(this: *mut SPBitVec, value: bool) { - (*this).0.fill(value) +pub unsafe extern "C" fn sp_bit_vec_fill(bit_vec: *mut SPBitVec, value: bool) { + (*bit_vec).0.fill(value) } /// Gets the length of the `SPBitVec` in bits. /// +/// # Arguments +/// +/// - `bit_vec`: instance to write to +/// /// # Safety /// /// The caller has to make sure that: /// -/// - `this` points to a valid `SPBitVec` +/// - `bit_vec` points to a valid `SPBitVec` #[no_mangle] -pub unsafe extern "C" fn sp_bit_vec_len(this: *const SPBitVec) -> usize { - (*this).0.len() +pub unsafe extern "C" fn sp_bit_vec_len(bit_vec: *const SPBitVec) -> usize { + (*bit_vec).0.len() } /// Returns true if length is 0. /// +/// # Arguments +/// +/// - `bit_vec`: instance to write to +/// /// # Safety /// /// The caller has to make sure that: /// -/// - `this` points to a valid `SPBitVec` +/// - `bit_vec` points to a valid `SPBitVec` #[no_mangle] -pub unsafe extern "C" fn sp_bit_vec_is_empty(this: *const SPBitVec) -> bool { - (*this).0.is_empty() +pub unsafe extern "C" fn sp_bit_vec_is_empty(bit_vec: *const SPBitVec) -> bool { + (*bit_vec).0.is_empty() } /// Gets an unsafe reference to the data of the `SPBitVec` instance. /// +/// # Arguments +/// +/// - `bit_vec`: instance to write to +/// /// ## Safety /// /// The caller has to make sure that: /// -/// - `this` points to a valid `SPBitVec` +/// - `bit_vec` points to a valid `SPBitVec` /// - the returned memory range is never accessed after the passed `SPBitVec` has been freed /// - the returned memory range is never accessed concurrently, either via the `SPBitVec` or directly #[no_mangle] pub unsafe extern "C" fn sp_bit_vec_unsafe_data_ref( - this: *mut SPBitVec, + bit_vec: *mut SPBitVec, ) -> SPByteSlice { - let data = (*this).0.as_raw_mut_slice(); + let data = (*bit_vec).0.as_raw_mut_slice(); SPByteSlice { start: data.as_mut_ptr_range().start, length: data.len(), diff --git a/crates/servicepoint_binding_c/src/brightness_grid.rs b/crates/servicepoint_binding_c/src/brightness_grid.rs index d205c4c..a34ecf2 100644 --- a/crates/servicepoint_binding_c/src/brightness_grid.rs +++ b/crates/servicepoint_binding_c/src/brightness_grid.rs @@ -21,15 +21,11 @@ use std::intrinsics::transmute; /// SPCommand command = sp_command_char_brightness(grid); /// sp_connection_free(connection); /// ``` -pub struct SPBrightnessGrid { - pub(crate) actual: servicepoint::BrightnessGrid, -} +pub struct SPBrightnessGrid(pub(crate) servicepoint::BrightnessGrid); impl Clone for SPBrightnessGrid { fn clone(&self) -> Self { - SPBrightnessGrid { - actual: self.actual.clone(), - } + SPBrightnessGrid(self.0.clone()) } } @@ -48,9 +44,9 @@ pub unsafe extern "C" fn sp_brightness_grid_new( width: usize, height: usize, ) -> *mut SPBrightnessGrid { - Box::into_raw(Box::new(SPBrightnessGrid { - actual: servicepoint::BrightnessGrid::new(width, height), - })) + Box::into_raw(Box::new(SPBrightnessGrid( + servicepoint::BrightnessGrid::new(width, height), + ))) } /// Loads a `SPBrightnessGrid` with the specified dimensions from the provided data. @@ -78,47 +74,55 @@ pub unsafe extern "C" fn sp_brightness_grid_load( let grid = PrimitiveGrid::load(width, height, data); let grid = servicepoint::BrightnessGrid::try_from(grid) .expect("invalid brightness value"); - Box::into_raw(Box::new(SPBrightnessGrid { actual: grid })) + Box::into_raw(Box::new(SPBrightnessGrid(grid))) } /// Clones a `SPBrightnessGrid`. /// +/// # Arguments +/// +/// - `brightness_grid`: instance to read from +/// /// # Safety /// /// The caller has to make sure that: /// -/// - `this` points to a valid `SPBrightnessGrid` -/// - `this` is not written to concurrently +/// - `brightness_grid` points to a valid `SPBrightnessGrid` +/// - `brightness_grid` is not written to concurrently /// - the returned instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_brightness_grid_free`. #[no_mangle] pub unsafe extern "C" fn sp_brightness_grid_clone( - this: *const SPBrightnessGrid, + brightness_grid: *const SPBrightnessGrid, ) -> *mut SPBrightnessGrid { - Box::into_raw(Box::new((*this).clone())) + Box::into_raw(Box::new((*brightness_grid).clone())) } /// Deallocates a `SPBrightnessGrid`. /// +/// # Arguments +/// +/// - `brightness_grid`: instance to read from +/// /// # Safety /// /// The caller has to make sure that: /// -/// - `this` points to a valid `SPBrightnessGrid` -/// - `this` is not used concurrently or after this call -/// - `this` was not passed to another consuming function, e.g. to create a `SPCommand` +/// - `brightness_grid` points to a valid `SPBrightnessGrid` +/// - `brightness_grid` is not used concurrently or after this call +/// - `brightness_grid` was not passed to another consuming function, e.g. to create a `SPCommand` #[no_mangle] pub unsafe extern "C" fn sp_brightness_grid_free( - this: *mut SPBrightnessGrid, + brightness_grid: *mut SPBrightnessGrid, ) { - _ = Box::from_raw(this); + _ = Box::from_raw(brightness_grid); } /// Gets the current value at the specified position. /// /// # Arguments /// -/// - `this`: instance to read from +/// - `brightness_grid`: instance to read from /// - `x` and `y`: position of the cell to read /// /// # Panics @@ -129,22 +133,22 @@ pub unsafe extern "C" fn sp_brightness_grid_free( /// /// The caller has to make sure that: /// -/// - `this` points to a valid `SPBrightnessGrid` -/// - `this` is not written to concurrently +/// - `brightness_grid` points to a valid `SPBrightnessGrid` +/// - `brightness_grid` is not written to concurrently #[no_mangle] pub unsafe extern "C" fn sp_brightness_grid_get( - this: *const SPBrightnessGrid, + brightness_grid: *const SPBrightnessGrid, x: usize, y: usize, ) -> u8 { - (*this).actual.get(x, y).into() + (*brightness_grid).0.get(x, y).into() } /// Sets the value of the specified position in the `SPBrightnessGrid`. /// /// # Arguments /// -/// - `this`: instance to write to +/// - `brightness_grid`: instance to write to /// - `x` and `y`: position of the cell /// - `value`: the value to write to the cell /// @@ -159,25 +163,25 @@ pub unsafe extern "C" fn sp_brightness_grid_get( /// /// The caller has to make sure that: /// -/// - `this` points to a valid `SPBitVec` -/// - `this` is not written to or read from concurrently +/// - `brightness_grid` points to a valid `SPBitVec` +/// - `brightness_grid` is not written to or read from concurrently #[no_mangle] pub unsafe extern "C" fn sp_brightness_grid_set( - this: *mut SPBrightnessGrid, + brightness_grid: *mut SPBrightnessGrid, x: usize, y: usize, value: u8, ) { let brightness = Brightness::try_from(value).expect("invalid brightness value"); - (*this).actual.set(x, y, brightness); + (*brightness_grid).0.set(x, y, brightness); } /// Sets the value of all cells in the `SPBrightnessGrid`. /// /// # Arguments /// -/// - `this`: instance to write to +/// - `brightness_grid`: instance to write to /// - `value`: the value to set all cells to /// /// # Panics @@ -188,70 +192,74 @@ pub unsafe extern "C" fn sp_brightness_grid_set( /// /// The caller has to make sure that: /// -/// - `this` points to a valid `SPBrightnessGrid` -/// - `this` is not written to or read from concurrently +/// - `brightness_grid` points to a valid `SPBrightnessGrid` +/// - `brightness_grid` is not written to or read from concurrently #[no_mangle] pub unsafe extern "C" fn sp_brightness_grid_fill( - this: *mut SPBrightnessGrid, + brightness_grid: *mut SPBrightnessGrid, value: u8, ) { let brightness = Brightness::try_from(value).expect("invalid brightness value"); - (*this).actual.fill(brightness); + (*brightness_grid).0.fill(brightness); } /// Gets the width of the `SPBrightnessGrid` instance. /// /// # Arguments /// -/// - `this`: instance to read from +/// - `brightness_grid`: instance to read from /// /// # Safety /// /// The caller has to make sure that: /// -/// - `this` points to a valid `SPBrightnessGrid` +/// - `brightness_grid` points to a valid `SPBrightnessGrid` #[no_mangle] pub unsafe extern "C" fn sp_brightness_grid_width( - this: *const SPBrightnessGrid, + brightness_grid: *const SPBrightnessGrid, ) -> usize { - (*this).actual.width() + (*brightness_grid).0.width() } /// Gets the height of the `SPBrightnessGrid` instance. /// /// # Arguments /// -/// - `this`: instance to read from +/// - `brightness_grid`: instance to read from /// /// # Safety /// /// The caller has to make sure that: /// -/// - `this` points to a valid `SPBrightnessGrid` +/// - `brightness_grid` points to a valid `SPBrightnessGrid` #[no_mangle] pub unsafe extern "C" fn sp_brightness_grid_height( - this: *const SPBrightnessGrid, + brightness_grid: *const SPBrightnessGrid, ) -> usize { - (*this).actual.height() + (*brightness_grid).0.height() } /// Gets an unsafe reference to the data of the `SPBrightnessGrid` instance. /// +/// # Arguments +/// +/// - `brightness_grid`: instance to read from +/// /// ## Safety /// /// The caller has to make sure that: /// -/// - `this` points to a valid `SPBrightnessGrid` +/// - `brightness_grid` points to a valid `SPBrightnessGrid` /// - the returned memory range is never accessed after the passed `SPBrightnessGrid` has been freed /// - the returned memory range is never accessed concurrently, either via the `SPBrightnessGrid` or directly #[no_mangle] pub unsafe extern "C" fn sp_brightness_grid_unsafe_data_ref( - this: *mut SPBrightnessGrid, + brightness_grid: *mut SPBrightnessGrid, ) -> SPByteSlice { - assert_eq!(std::mem::size_of::(), 1); + assert_eq!(core::mem::size_of::(), 1); - let data = (*this).actual.data_ref_mut(); + let data = (*brightness_grid).0.data_ref_mut(); let data: &mut [u8] = transmute(data); SPByteSlice { start: data.as_mut_ptr_range().start, diff --git a/crates/servicepoint_binding_c/src/command.rs b/crates/servicepoint_binding_c/src/command.rs index a67c541..06eafc4 100644 --- a/crates/servicepoint_binding_c/src/command.rs +++ b/crates/servicepoint_binding_c/src/command.rs @@ -63,15 +63,15 @@ pub unsafe extern "C" fn sp_command_try_from_packet( /// /// The caller has to make sure that: /// -/// - `this` points to a valid instance of `SPCommand` -/// - `this` is not written to concurrently +/// - `command` points to a valid instance of `SPCommand` +/// - `command` is not written to concurrently /// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_command_free`. #[no_mangle] pub unsafe extern "C" fn sp_command_clone( - original: *const SPCommand, + command: *const SPCommand, ) -> *mut SPCommand { - Box::into_raw(Box::new((*original).clone())) + Box::into_raw(Box::new((*command).clone())) } /// Set all pixels to the off state. @@ -177,7 +177,7 @@ pub unsafe extern "C" fn sp_command_char_brightness( let byte_grid = *Box::from_raw(grid); Box::into_raw(Box::new(SPCommand(servicepoint::Command::CharBrightness( Origin::new(x, y), - byte_grid.actual, + byte_grid.0, )))) } @@ -394,10 +394,10 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_win( /// /// The caller has to make sure that: /// -/// - `this` points to a valid `SPCommand` -/// - `this` is not used concurrently or after this call -/// - `this` was not passed to another consuming function, e.g. to create a `SPPacket` +/// - `command` points to a valid `SPCommand` +/// - `command` is not used concurrently or after this call +/// - `command` was not passed to another consuming function, e.g. to create a `SPPacket` #[no_mangle] -pub unsafe extern "C" fn sp_command_free(ptr: *mut SPCommand) { - _ = Box::from_raw(ptr); +pub unsafe extern "C" fn sp_command_free(command: *mut SPCommand) { + _ = Box::from_raw(command); } diff --git a/crates/servicepoint_binding_c/src/connection.rs b/crates/servicepoint_binding_c/src/connection.rs index 6d69c99..846b607 100644 --- a/crates/servicepoint_binding_c/src/connection.rs +++ b/crates/servicepoint_binding_c/src/connection.rs @@ -47,7 +47,7 @@ pub unsafe extern "C" fn sp_connection_open( /// Sends a `SPPacket` to the display using the `SPConnection`. /// -/// The passed `SPPacket` gets consumed. +/// The passed `packet` gets consumed. /// /// returns: true in case of success /// @@ -55,9 +55,9 @@ pub unsafe extern "C" fn sp_connection_open( /// /// The caller has to make sure that: /// -/// - `SPConnection` points to a valid instance of `SPConnection` -/// - `SPPacket` points to a valid instance of `SPPacket` -/// - `SPPacket` is not used concurrently or after this call +/// - `connection` points to a valid instance of `SPConnection` +/// - `packet` points to a valid instance of `SPPacket` +/// - `packet` is not used concurrently or after this call #[no_mangle] pub unsafe extern "C" fn sp_connection_send_packet( connection: *const SPConnection, @@ -69,7 +69,7 @@ pub unsafe extern "C" fn sp_connection_send_packet( /// Sends a `SPCommand` to the display using the `SPConnection`. /// -/// The passed `SPCommand` gets consumed. +/// The passed `command` gets consumed. /// /// returns: true in case of success /// @@ -95,9 +95,9 @@ pub unsafe extern "C" fn sp_connection_send_command( /// /// The caller has to make sure that: /// -/// - `this` points to a valid `SPConnection` -/// - `this` is not used concurrently or after this call +/// - `connection` points to a valid `SPConnection` +/// - `connection` is not used concurrently or after this call #[no_mangle] -pub unsafe extern "C" fn sp_connection_free(ptr: *mut SPConnection) { - _ = Box::from_raw(ptr); +pub unsafe extern "C" fn sp_connection_free(connection: *mut SPConnection) { + _ = Box::from_raw(connection); } diff --git a/crates/servicepoint_binding_c/src/cp437_grid.rs b/crates/servicepoint_binding_c/src/cp437_grid.rs index 88919fd..c29f6da 100644 --- a/crates/servicepoint_binding_c/src/cp437_grid.rs +++ b/crates/servicepoint_binding_c/src/cp437_grid.rs @@ -86,15 +86,15 @@ pub unsafe extern "C" fn sp_cp437_grid_load( /// /// The caller has to make sure that: /// -/// - `this` points to a valid `SPCp437Grid` -/// - `this` is not written to concurrently +/// - `cp437_grid` points to a valid `SPCp437Grid` +/// - `cp437_grid` is not written to concurrently /// - the returned instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_cp437_grid_free`. #[no_mangle] pub unsafe extern "C" fn sp_cp437_grid_clone( - this: *const SPCp437Grid, + cp437_grid: *const SPCp437Grid, ) -> *mut SPCp437Grid { - Box::into_raw(Box::new((*this).clone())) + Box::into_raw(Box::new((*cp437_grid).clone())) } /// Deallocates a `SPCp437Grid`. @@ -103,19 +103,19 @@ pub unsafe extern "C" fn sp_cp437_grid_clone( /// /// The caller has to make sure that: /// -/// - `this` points to a valid `SPCp437Grid` -/// - `this` is not used concurrently or after this call -/// - `this` was not passed to another consuming function, e.g. to create a `SPCommand` +/// - `cp437_grid` points to a valid `SPCp437Grid` +/// - `cp437_grid` is not used concurrently or after cp437_grid call +/// - `cp437_grid` was not passed to another consuming function, e.g. to create a `SPCommand` #[no_mangle] -pub unsafe extern "C" fn sp_cp437_grid_free(this: *mut SPCp437Grid) { - _ = Box::from_raw(this); +pub unsafe extern "C" fn sp_cp437_grid_free(cp437_grid: *mut SPCp437Grid) { + _ = Box::from_raw(cp437_grid); } /// Gets the current value at the specified position. /// /// # Arguments /// -/// - `this`: instance to read from +/// - `cp437_grid`: instance to read from /// - `x` and `y`: position of the cell to read /// /// # Panics @@ -126,22 +126,22 @@ pub unsafe extern "C" fn sp_cp437_grid_free(this: *mut SPCp437Grid) { /// /// The caller has to make sure that: /// -/// - `this` points to a valid `SPCp437Grid` -/// - `this` is not written to concurrently +/// - `cp437_grid` points to a valid `SPCp437Grid` +/// - `cp437_grid` is not written to concurrently #[no_mangle] pub unsafe extern "C" fn sp_cp437_grid_get( - this: *const SPCp437Grid, + cp437_grid: *const SPCp437Grid, x: usize, y: usize, ) -> u8 { - (*this).actual.get(x, y) + (*cp437_grid).actual.get(x, y) } /// Sets the value of the specified position in the `SPCp437Grid`. /// /// # Arguments /// -/// - `this`: instance to write to +/// - `cp437_grid`: instance to write to /// - `x` and `y`: position of the cell /// - `value`: the value to write to the cell /// @@ -155,70 +155,73 @@ pub unsafe extern "C" fn sp_cp437_grid_get( /// /// The caller has to make sure that: /// -/// - `this` points to a valid `SPBitVec` -/// - `this` is not written to or read from concurrently +/// - `cp437_grid` points to a valid `SPBitVec` +/// - `cp437_grid` is not written to or read from concurrently #[no_mangle] pub unsafe extern "C" fn sp_cp437_grid_set( - this: *mut SPCp437Grid, + cp437_grid: *mut SPCp437Grid, x: usize, y: usize, value: u8, ) { - (*this).actual.set(x, y, value); + (*cp437_grid).actual.set(x, y, value); } /// Sets the value of all cells in the `SPCp437Grid`. /// /// # Arguments /// -/// - `this`: instance to write to +/// - `cp437_grid`: 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 `SPCp437Grid` -/// - `this` is not written to or read from concurrently +/// - `cp437_grid` points to a valid `SPCp437Grid` +/// - `cp437_grid` is not written to or read from concurrently #[no_mangle] -pub unsafe extern "C" fn sp_cp437_grid_fill(this: *mut SPCp437Grid, value: u8) { - (*this).actual.fill(value); +pub unsafe extern "C" fn sp_cp437_grid_fill( + cp437_grid: *mut SPCp437Grid, + value: u8, +) { + (*cp437_grid).actual.fill(value); } /// Gets the width of the `SPCp437Grid` instance. /// /// # Arguments /// -/// - `this`: instance to read from +/// - `cp437_grid`: instance to read from /// /// # Safety /// /// The caller has to make sure that: /// -/// - `this` points to a valid `SPCp437Grid` +/// - `cp437_grid` points to a valid `SPCp437Grid` #[no_mangle] pub unsafe extern "C" fn sp_cp437_grid_width( - this: *const SPCp437Grid, + cp437_grid: *const SPCp437Grid, ) -> usize { - (*this).actual.width() + (*cp437_grid).actual.width() } /// Gets the height of the `SPCp437Grid` instance. /// /// # Arguments /// -/// - `this`: instance to read from +/// - `cp437_grid`: instance to read from /// /// # Safety /// /// The caller has to make sure that: /// -/// - `this` points to a valid `SPCp437Grid` +/// - `cp437_grid` points to a valid `SPCp437Grid` #[no_mangle] pub unsafe extern "C" fn sp_cp437_grid_height( - this: *const SPCp437Grid, + cp437_grid: *const SPCp437Grid, ) -> usize { - (*this).actual.height() + (*cp437_grid).actual.height() } /// Gets an unsafe reference to the data of the `SPCp437Grid` instance. @@ -229,14 +232,14 @@ pub unsafe extern "C" fn sp_cp437_grid_height( /// /// The caller has to make sure that: /// -/// - `this` points to a valid `SPCp437Grid` +/// - `cp437_grid` points to a valid `SPCp437Grid` /// - the returned memory range is never accessed after the passed `SPCp437Grid` has been freed /// - the returned memory range is never accessed concurrently, either via the `SPCp437Grid` or directly #[no_mangle] pub unsafe extern "C" fn sp_cp437_grid_unsafe_data_ref( - this: *mut SPCp437Grid, + cp437_grid: *mut SPCp437Grid, ) -> SPByteSlice { - let data = (*this).actual.data_ref_mut(); + let data = (*cp437_grid).actual.data_ref_mut(); SPByteSlice { start: data.as_mut_ptr_range().start, length: data.len(), diff --git a/crates/servicepoint_binding_c/src/packet.rs b/crates/servicepoint_binding_c/src/packet.rs index 2d6db47..eac41b8 100644 --- a/crates/servicepoint_binding_c/src/packet.rs +++ b/crates/servicepoint_binding_c/src/packet.rs @@ -63,15 +63,15 @@ pub unsafe extern "C" fn sp_packet_try_load( /// /// The caller has to make sure that: /// -/// - `this` points to a valid `SPPacket` -/// - `this` is not written to concurrently +/// - `packet` points to a valid `SPPacket` +/// - `packet` is not written to concurrently /// - the returned instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_packet_free`. #[no_mangle] pub unsafe extern "C" fn sp_packet_clone( - this: *const SPPacket, + packet: *const SPPacket, ) -> *mut SPPacket { - Box::into_raw(Box::new(SPPacket((*this).0.clone()))) + Box::into_raw(Box::new(SPPacket((*packet).0.clone()))) } /// Deallocates a `SPPacket`. @@ -80,9 +80,9 @@ pub unsafe extern "C" fn sp_packet_clone( /// /// The caller has to make sure that: /// -/// - `this` points to a valid `SPPacket` -/// - `this` is not used concurrently or after this call +/// - `packet` points to a valid `SPPacket` +/// - `packet` is not used concurrently or after this call #[no_mangle] -pub unsafe extern "C" fn sp_packet_free(this: *mut SPPacket) { - _ = Box::from_raw(this) +pub unsafe extern "C" fn sp_packet_free(packet: *mut SPPacket) { + _ = Box::from_raw(packet) } diff --git a/crates/servicepoint_binding_c/src/pixel_grid.rs b/crates/servicepoint_binding_c/src/pixel_grid.rs index c5da1c0..780c305 100644 --- a/crates/servicepoint_binding_c/src/pixel_grid.rs +++ b/crates/servicepoint_binding_c/src/pixel_grid.rs @@ -89,15 +89,15 @@ pub unsafe extern "C" fn sp_pixel_grid_load( /// /// The caller has to make sure that: /// -/// - `this` points to a valid `SPPixelGrid` -/// - `this` is not written to concurrently +/// - `pixel_grid` points to a valid `SPPixelGrid` +/// - `pixel_grid` 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_free`. #[no_mangle] pub unsafe extern "C" fn sp_pixel_grid_clone( - this: *const SPPixelGrid, + pixel_grid: *const SPPixelGrid, ) -> *mut SPPixelGrid { - Box::into_raw(Box::new(SPPixelGrid((*this).0.clone()))) + Box::into_raw(Box::new(SPPixelGrid((*pixel_grid).0.clone()))) } /// Deallocates a `SPPixelGrid`. @@ -106,19 +106,19 @@ pub unsafe extern "C" fn sp_pixel_grid_clone( /// /// The caller has to make sure that: /// -/// - `this` points to a valid `SPPixelGrid` -/// - `this` is not used concurrently or after this call -/// - `this` was not passed to another consuming function, e.g. to create a `SPCommand` +/// - `pixel_grid` points to a valid `SPPixelGrid` +/// - `pixel_grid` is not used concurrently or after pixel_grid call +/// - `pixel_grid` was not passed to another consuming function, e.g. to create a `SPCommand` #[no_mangle] -pub unsafe extern "C" fn sp_pixel_grid_free(this: *mut SPPixelGrid) { - _ = Box::from_raw(this); +pub unsafe extern "C" fn sp_pixel_grid_free(pixel_grid: *mut SPPixelGrid) { + _ = Box::from_raw(pixel_grid); } /// Gets the current value at the specified position in the `SPPixelGrid`. /// /// # Arguments /// -/// - `this`: instance to read from +/// - `pixel_grid`: instance to read from /// - `x` and `y`: position of the cell to read /// /// # Panics @@ -129,22 +129,22 @@ pub unsafe extern "C" fn sp_pixel_grid_free(this: *mut SPPixelGrid) { /// /// The caller has to make sure that: /// -/// - `this` points to a valid `SPPixelGrid` -/// - `this` is not written to concurrently +/// - `pixel_grid` points to a valid `SPPixelGrid` +/// - `pixel_grid` is not written to concurrently #[no_mangle] pub unsafe extern "C" fn sp_pixel_grid_get( - this: *const SPPixelGrid, + pixel_grid: *const SPPixelGrid, x: usize, y: usize, ) -> bool { - (*this).0.get(x, y) + (*pixel_grid).0.get(x, y) } /// Sets the value of the specified position in the `SPPixelGrid`. /// /// # Arguments /// -/// - `this`: instance to write to +/// - `pixel_grid`: instance to write to /// - `x` and `y`: position of the cell /// - `value`: the value to write to the cell /// @@ -158,73 +158,73 @@ pub unsafe extern "C" fn sp_pixel_grid_get( /// /// The caller has to make sure that: /// -/// - `this` points to a valid `SPPixelGrid` -/// - `this` is not written to or read from concurrently +/// - `pixel_grid` points to a valid `SPPixelGrid` +/// - `pixel_grid` is not written to or read from concurrently #[no_mangle] pub unsafe extern "C" fn sp_pixel_grid_set( - this: *mut SPPixelGrid, + pixel_grid: *mut SPPixelGrid, x: usize, y: usize, value: bool, ) { - (*this).0.set(x, y, value); + (*pixel_grid).0.set(x, y, value); } /// Sets the state of all pixels in the `SPPixelGrid`. /// /// # Arguments /// -/// - `this`: instance to write to +/// - `pixel_grid`: 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 `SPPixelGrid` -/// - `this` is not written to or read from concurrently +/// - `pixel_grid` points to a valid `SPPixelGrid` +/// - `pixel_grid` is not written to or read from concurrently #[no_mangle] pub unsafe extern "C" fn sp_pixel_grid_fill( - this: *mut SPPixelGrid, + pixel_grid: *mut SPPixelGrid, value: bool, ) { - (*this).0.fill(value); + (*pixel_grid).0.fill(value); } /// Gets the width in pixels of the `SPPixelGrid` instance. /// /// # Arguments /// -/// - `this`: instance to read from +/// - `pixel_grid`: instance to read from /// /// # Safety /// /// The caller has to make sure that: /// -/// - `this` points to a valid `SPPixelGrid` +/// - `pixel_grid` points to a valid `SPPixelGrid` #[no_mangle] pub unsafe extern "C" fn sp_pixel_grid_width( - this: *const SPPixelGrid, + pixel_grid: *const SPPixelGrid, ) -> usize { - (*this).0.width() + (*pixel_grid).0.width() } /// Gets the height in pixels of the `SPPixelGrid` instance. /// /// # Arguments /// -/// - `this`: instance to read from +/// - `pixel_grid`: instance to read from /// /// # Safety /// /// The caller has to make sure that: /// -/// - `this` points to a valid `SPPixelGrid` +/// - `pixel_grid` points to a valid `SPPixelGrid` #[no_mangle] pub unsafe extern "C" fn sp_pixel_grid_height( - this: *const SPPixelGrid, + pixel_grid: *const SPPixelGrid, ) -> usize { - (*this).0.height() + (*pixel_grid).0.height() } /// Gets an unsafe reference to the data of the `SPPixelGrid` instance. @@ -233,14 +233,14 @@ pub unsafe extern "C" fn sp_pixel_grid_height( /// /// The caller has to make sure that: /// -/// - `this` points to a valid `SPPixelGrid` +/// - `pixel_grid` points to a valid `SPPixelGrid` /// - the returned memory range is never accessed after the passed `SPPixelGrid` has been freed /// - the returned memory range is never accessed concurrently, either via the `SPPixelGrid` or directly #[no_mangle] pub unsafe extern "C" fn sp_pixel_grid_unsafe_data_ref( - this: *mut SPPixelGrid, + pixel_grid: *mut SPPixelGrid, ) -> SPByteSlice { - let data = (*this).0.data_ref_mut(); + let data = (*pixel_grid).0.data_ref_mut(); SPByteSlice { start: data.as_mut_ptr_range().start, length: data.len(), diff --git a/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs b/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs index 038d8e6..d23b2b9 100644 --- a/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs +++ b/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs @@ -64,13 +64,13 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `SPBitVec` - /// - `this` is not written to concurrently + /// - `bit_vec` points to a valid `SPBitVec` + /// - `bit_vec` 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_free`. /// [DllImport(__DllName, EntryPoint = "sp_bit_vec_clone", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern BitVec* sp_bit_vec_clone(BitVec* @this); + public static extern BitVec* sp_bit_vec_clone(BitVec* bit_vec); /// /// Deallocates a `SPBitVec`. @@ -79,19 +79,19 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `SPBitVec` - /// - `this` is not used concurrently or after this call - /// - `this` was not passed to another consuming function, e.g. to create a `SPCommand` + /// - `bit_vec` points to a valid `SPBitVec` + /// - `bit_vec` is not used concurrently or after this call + /// - `bit_vec` was not passed to another consuming function, e.g. to create a `SPCommand` /// [DllImport(__DllName, EntryPoint = "sp_bit_vec_free", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern void sp_bit_vec_free(BitVec* @this); + public static extern void sp_bit_vec_free(BitVec* bit_vec); /// /// Gets the value of a bit from the `SPBitVec`. /// /// # Arguments /// - /// - `this`: instance to read from + /// - `bit_vec`: instance to read from /// - `index`: the bit index to read /// /// returns: value of the bit @@ -104,19 +104,19 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `SPBitVec` - /// - `this` is not written to concurrently + /// - `bit_vec` points to a valid `SPBitVec` + /// - `bit_vec` 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); + public static extern bool sp_bit_vec_get(BitVec* bit_vec, nuint index); /// /// Sets the value of a bit in the `SPBitVec`. /// /// # Arguments /// - /// - `this`: instance to write to + /// - `bit_vec`: instance to write to /// - `index`: the bit index to edit /// - `value`: the value to set the bit to /// @@ -130,67 +130,80 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `SPBitVec` - /// - `this` is not written to or read from concurrently + /// - `bit_vec` points to a valid `SPBitVec` + /// - `bit_vec` is not written to or read from concurrently /// [DllImport(__DllName, EntryPoint = "sp_bit_vec_set", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern void sp_bit_vec_set(BitVec* @this, nuint index, [MarshalAs(UnmanagedType.U1)] bool value); + public static extern void sp_bit_vec_set(BitVec* bit_vec, nuint index, [MarshalAs(UnmanagedType.U1)] bool value); /// /// Sets the value of all bits in the `SPBitVec`. /// /// # Arguments /// + /// - `bit_vec`: instance to write to /// - `value`: the value to set all bits to /// /// # Safety /// /// The caller has to make sure that: /// - /// - `this` points to a valid `SPBitVec` - /// - `this` is not written to or read from concurrently + /// - `bit_vec` points to a valid `SPBitVec` + /// - `bit_vec` 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); + public static extern void sp_bit_vec_fill(BitVec* bit_vec, [MarshalAs(UnmanagedType.U1)] bool value); /// /// Gets the length of the `SPBitVec` in bits. /// + /// # Arguments + /// + /// - `bit_vec`: instance to write to + /// /// # Safety /// /// The caller has to make sure that: /// - /// - `this` points to a valid `SPBitVec` + /// - `bit_vec` points to a valid `SPBitVec` /// [DllImport(__DllName, EntryPoint = "sp_bit_vec_len", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern nuint sp_bit_vec_len(BitVec* @this); + public static extern nuint sp_bit_vec_len(BitVec* bit_vec); /// /// Returns true if length is 0. /// + /// # Arguments + /// + /// - `bit_vec`: instance to write to + /// /// # Safety /// /// The caller has to make sure that: /// - /// - `this` points to a valid `SPBitVec` + /// - `bit_vec` points to a valid `SPBitVec` /// [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); + public static extern bool sp_bit_vec_is_empty(BitVec* bit_vec); /// /// Gets an unsafe reference to the data of the `SPBitVec` instance. /// + /// # Arguments + /// + /// - `bit_vec`: instance to write to + /// /// ## Safety /// /// The caller has to make sure that: /// - /// - `this` points to a valid `SPBitVec` + /// - `bit_vec` points to a valid `SPBitVec` /// - the returned memory range is never accessed after the passed `SPBitVec` has been freed /// - the returned memory range is never accessed concurrently, either via the `SPBitVec` or directly /// [DllImport(__DllName, EntryPoint = "sp_bit_vec_unsafe_data_ref", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern ByteSlice sp_bit_vec_unsafe_data_ref(BitVec* @this); + public static extern ByteSlice sp_bit_vec_unsafe_data_ref(BitVec* bit_vec); /// /// Creates a new `SPBrightnessGrid` with the specified dimensions. @@ -229,38 +242,46 @@ namespace ServicePoint.BindGen /// /// Clones a `SPBrightnessGrid`. /// + /// # Arguments + /// + /// - `brightness_grid`: instance to read from + /// /// # Safety /// /// The caller has to make sure that: /// - /// - `this` points to a valid `SPBrightnessGrid` - /// - `this` is not written to concurrently + /// - `brightness_grid` points to a valid `SPBrightnessGrid` + /// - `brightness_grid` is not written to concurrently /// - the returned instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_brightness_grid_free`. /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_clone", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern BrightnessGrid* sp_brightness_grid_clone(BrightnessGrid* @this); + public static extern BrightnessGrid* sp_brightness_grid_clone(BrightnessGrid* brightness_grid); /// /// Deallocates a `SPBrightnessGrid`. /// + /// # Arguments + /// + /// - `brightness_grid`: instance to read from + /// /// # Safety /// /// The caller has to make sure that: /// - /// - `this` points to a valid `SPBrightnessGrid` - /// - `this` is not used concurrently or after this call - /// - `this` was not passed to another consuming function, e.g. to create a `SPCommand` + /// - `brightness_grid` points to a valid `SPBrightnessGrid` + /// - `brightness_grid` is not used concurrently or after this call + /// - `brightness_grid` was not passed to another consuming function, e.g. to create a `SPCommand` /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_free", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern void sp_brightness_grid_free(BrightnessGrid* @this); + public static extern void sp_brightness_grid_free(BrightnessGrid* brightness_grid); /// /// Gets the current value at the specified position. /// /// # Arguments /// - /// - `this`: instance to read from + /// - `brightness_grid`: instance to read from /// - `x` and `y`: position of the cell to read /// /// # Panics @@ -271,18 +292,18 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `SPBrightnessGrid` - /// - `this` is not written to concurrently + /// - `brightness_grid` points to a valid `SPBrightnessGrid` + /// - `brightness_grid` is not written to concurrently /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_get", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern byte sp_brightness_grid_get(BrightnessGrid* @this, nuint x, nuint y); + public static extern byte sp_brightness_grid_get(BrightnessGrid* brightness_grid, nuint x, nuint y); /// /// Sets the value of the specified position in the `SPBrightnessGrid`. /// /// # Arguments /// - /// - `this`: instance to write to + /// - `brightness_grid`: instance to write to /// - `x` and `y`: position of the cell /// - `value`: the value to write to the cell /// @@ -297,18 +318,18 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `SPBitVec` - /// - `this` is not written to or read from concurrently + /// - `brightness_grid` points to a valid `SPBitVec` + /// - `brightness_grid` is not written to or read from concurrently /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_set", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern void sp_brightness_grid_set(BrightnessGrid* @this, nuint x, nuint y, byte value); + public static extern void sp_brightness_grid_set(BrightnessGrid* brightness_grid, nuint x, nuint y, byte value); /// /// Sets the value of all cells in the `SPBrightnessGrid`. /// /// # Arguments /// - /// - `this`: instance to write to + /// - `brightness_grid`: instance to write to /// - `value`: the value to set all cells to /// /// # Panics @@ -319,57 +340,61 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `SPBrightnessGrid` - /// - `this` is not written to or read from concurrently + /// - `brightness_grid` points to a valid `SPBrightnessGrid` + /// - `brightness_grid` is not written to or read from concurrently /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_fill", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern void sp_brightness_grid_fill(BrightnessGrid* @this, byte value); + public static extern void sp_brightness_grid_fill(BrightnessGrid* brightness_grid, byte value); /// /// Gets the width of the `SPBrightnessGrid` instance. /// /// # Arguments /// - /// - `this`: instance to read from + /// - `brightness_grid`: instance to read from /// /// # Safety /// /// The caller has to make sure that: /// - /// - `this` points to a valid `SPBrightnessGrid` + /// - `brightness_grid` points to a valid `SPBrightnessGrid` /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_width", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern nuint sp_brightness_grid_width(BrightnessGrid* @this); + public static extern nuint sp_brightness_grid_width(BrightnessGrid* brightness_grid); /// /// Gets the height of the `SPBrightnessGrid` instance. /// /// # Arguments /// - /// - `this`: instance to read from + /// - `brightness_grid`: instance to read from /// /// # Safety /// /// The caller has to make sure that: /// - /// - `this` points to a valid `SPBrightnessGrid` + /// - `brightness_grid` points to a valid `SPBrightnessGrid` /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_height", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern nuint sp_brightness_grid_height(BrightnessGrid* @this); + public static extern nuint sp_brightness_grid_height(BrightnessGrid* brightness_grid); /// /// Gets an unsafe reference to the data of the `SPBrightnessGrid` instance. /// + /// # Arguments + /// + /// - `brightness_grid`: instance to read from + /// /// ## Safety /// /// The caller has to make sure that: /// - /// - `this` points to a valid `SPBrightnessGrid` + /// - `brightness_grid` points to a valid `SPBrightnessGrid` /// - the returned memory range is never accessed after the passed `SPBrightnessGrid` has been freed /// - the returned memory range is never accessed concurrently, either via the `SPBrightnessGrid` or directly /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_unsafe_data_ref", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern ByteSlice sp_brightness_grid_unsafe_data_ref(BrightnessGrid* @this); + public static extern ByteSlice sp_brightness_grid_unsafe_data_ref(BrightnessGrid* brightness_grid); /// /// Tries to turn a `SPPacket` into a `SPCommand`. @@ -398,13 +423,13 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid instance of `SPCommand` - /// - `this` is not written to concurrently + /// - `command` points to a valid instance of `SPCommand` + /// - `command` is not written to concurrently /// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_command_free`. /// [DllImport(__DllName, EntryPoint = "sp_command_clone", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern Command* sp_command_clone(Command* original); + public static extern Command* sp_command_clone(Command* command); /// /// Set all pixels to the off state. @@ -657,12 +682,12 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `SPCommand` - /// - `this` is not used concurrently or after this call - /// - `this` was not passed to another consuming function, e.g. to create a `SPPacket` + /// - `command` points to a valid `SPCommand` + /// - `command` is not used concurrently or after this call + /// - `command` was not passed to another consuming function, e.g. to create a `SPPacket` /// [DllImport(__DllName, EntryPoint = "sp_command_free", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern void sp_command_free(Command* ptr); + public static extern void sp_command_free(Command* command); /// /// Creates a new instance of `SPConnection`. @@ -686,7 +711,7 @@ namespace ServicePoint.BindGen /// /// Sends a `SPPacket` to the display using the `SPConnection`. /// - /// The passed `SPPacket` gets consumed. + /// The passed `packet` gets consumed. /// /// returns: true in case of success /// @@ -694,9 +719,9 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `SPConnection` points to a valid instance of `SPConnection` - /// - `SPPacket` points to a valid instance of `SPPacket` - /// - `SPPacket` is not used concurrently or after this call + /// - `connection` points to a valid instance of `SPConnection` + /// - `packet` points to a valid instance of `SPPacket` + /// - `packet` is not used concurrently or after this call /// [DllImport(__DllName, EntryPoint = "sp_connection_send_packet", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] [return: MarshalAs(UnmanagedType.U1)] @@ -705,7 +730,7 @@ namespace ServicePoint.BindGen /// /// Sends a `SPCommand` to the display using the `SPConnection`. /// - /// The passed `SPCommand` gets consumed. + /// The passed `command` gets consumed. /// /// returns: true in case of success /// @@ -728,11 +753,11 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `SPConnection` - /// - `this` is not used concurrently or after this call + /// - `connection` points to a valid `SPConnection` + /// - `connection` is not used concurrently or after this call /// [DllImport(__DllName, EntryPoint = "sp_connection_free", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern void sp_connection_free(Connection* ptr); + public static extern void sp_connection_free(Connection* connection); /// /// Creates a new `SPCp437Grid` with the specified dimensions. @@ -779,13 +804,13 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `SPCp437Grid` - /// - `this` is not written to concurrently + /// - `cp437_grid` points to a valid `SPCp437Grid` + /// - `cp437_grid` is not written to concurrently /// - the returned instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_cp437_grid_free`. /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_clone", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern Cp437Grid* sp_cp437_grid_clone(Cp437Grid* @this); + public static extern Cp437Grid* sp_cp437_grid_clone(Cp437Grid* cp437_grid); /// /// Deallocates a `SPCp437Grid`. @@ -794,19 +819,19 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `SPCp437Grid` - /// - `this` is not used concurrently or after this call - /// - `this` was not passed to another consuming function, e.g. to create a `SPCommand` + /// - `cp437_grid` points to a valid `SPCp437Grid` + /// - `cp437_grid` is not used concurrently or after cp437_grid call + /// - `cp437_grid` was not passed to another consuming function, e.g. to create a `SPCommand` /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_free", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern void sp_cp437_grid_free(Cp437Grid* @this); + public static extern void sp_cp437_grid_free(Cp437Grid* cp437_grid); /// /// Gets the current value at the specified position. /// /// # Arguments /// - /// - `this`: instance to read from + /// - `cp437_grid`: instance to read from /// - `x` and `y`: position of the cell to read /// /// # Panics @@ -817,18 +842,18 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `SPCp437Grid` - /// - `this` is not written to concurrently + /// - `cp437_grid` points to a valid `SPCp437Grid` + /// - `cp437_grid` is not written to concurrently /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_get", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern byte sp_cp437_grid_get(Cp437Grid* @this, nuint x, nuint y); + public static extern byte sp_cp437_grid_get(Cp437Grid* cp437_grid, nuint x, nuint y); /// /// Sets the value of the specified position in the `SPCp437Grid`. /// /// # Arguments /// - /// - `this`: instance to write to + /// - `cp437_grid`: instance to write to /// - `x` and `y`: position of the cell /// - `value`: the value to write to the cell /// @@ -842,61 +867,61 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `SPBitVec` - /// - `this` is not written to or read from concurrently + /// - `cp437_grid` points to a valid `SPBitVec` + /// - `cp437_grid` is not written to or read from concurrently /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_set", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern void sp_cp437_grid_set(Cp437Grid* @this, nuint x, nuint y, byte value); + public static extern void sp_cp437_grid_set(Cp437Grid* cp437_grid, nuint x, nuint y, byte value); /// /// Sets the value of all cells in the `SPCp437Grid`. /// /// # Arguments /// - /// - `this`: instance to write to + /// - `cp437_grid`: 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 `SPCp437Grid` - /// - `this` is not written to or read from concurrently + /// - `cp437_grid` points to a valid `SPCp437Grid` + /// - `cp437_grid` is not written to or read from concurrently /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_fill", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern void sp_cp437_grid_fill(Cp437Grid* @this, byte value); + public static extern void sp_cp437_grid_fill(Cp437Grid* cp437_grid, byte value); /// /// Gets the width of the `SPCp437Grid` instance. /// /// # Arguments /// - /// - `this`: instance to read from + /// - `cp437_grid`: instance to read from /// /// # Safety /// /// The caller has to make sure that: /// - /// - `this` points to a valid `SPCp437Grid` + /// - `cp437_grid` points to a valid `SPCp437Grid` /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_width", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern nuint sp_cp437_grid_width(Cp437Grid* @this); + public static extern nuint sp_cp437_grid_width(Cp437Grid* cp437_grid); /// /// Gets the height of the `SPCp437Grid` instance. /// /// # Arguments /// - /// - `this`: instance to read from + /// - `cp437_grid`: instance to read from /// /// # Safety /// /// The caller has to make sure that: /// - /// - `this` points to a valid `SPCp437Grid` + /// - `cp437_grid` points to a valid `SPCp437Grid` /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_height", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern nuint sp_cp437_grid_height(Cp437Grid* @this); + public static extern nuint sp_cp437_grid_height(Cp437Grid* cp437_grid); /// /// Gets an unsafe reference to the data of the `SPCp437Grid` instance. @@ -907,12 +932,12 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `SPCp437Grid` + /// - `cp437_grid` points to a valid `SPCp437Grid` /// - the returned memory range is never accessed after the passed `SPCp437Grid` has been freed /// - the returned memory range is never accessed concurrently, either via the `SPCp437Grid` or directly /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_unsafe_data_ref", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern ByteSlice sp_cp437_grid_unsafe_data_ref(Cp437Grid* @this); + public static extern ByteSlice sp_cp437_grid_unsafe_data_ref(Cp437Grid* cp437_grid); /// /// Turns a `SPCommand` into a `SPPacket`. @@ -958,13 +983,13 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `SPPacket` - /// - `this` is not written to concurrently + /// - `packet` points to a valid `SPPacket` + /// - `packet` is not written to concurrently /// - the returned instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_packet_free`. /// [DllImport(__DllName, EntryPoint = "sp_packet_clone", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern Packet* sp_packet_clone(Packet* @this); + public static extern Packet* sp_packet_clone(Packet* packet); /// /// Deallocates a `SPPacket`. @@ -973,11 +998,11 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `SPPacket` - /// - `this` is not used concurrently or after this call + /// - `packet` points to a valid `SPPacket` + /// - `packet` is not used concurrently or after this call /// [DllImport(__DllName, EntryPoint = "sp_packet_free", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern void sp_packet_free(Packet* @this); + public static extern void sp_packet_free(Packet* packet); /// /// Creates a new `SPPixelGrid` with the specified dimensions. @@ -1038,13 +1063,13 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `SPPixelGrid` - /// - `this` is not written to concurrently + /// - `pixel_grid` points to a valid `SPPixelGrid` + /// - `pixel_grid` 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_free`. /// [DllImport(__DllName, EntryPoint = "sp_pixel_grid_clone", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern PixelGrid* sp_pixel_grid_clone(PixelGrid* @this); + public static extern PixelGrid* sp_pixel_grid_clone(PixelGrid* pixel_grid); /// /// Deallocates a `SPPixelGrid`. @@ -1053,19 +1078,19 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `SPPixelGrid` - /// - `this` is not used concurrently or after this call - /// - `this` was not passed to another consuming function, e.g. to create a `SPCommand` + /// - `pixel_grid` points to a valid `SPPixelGrid` + /// - `pixel_grid` is not used concurrently or after pixel_grid call + /// - `pixel_grid` was not passed to another consuming function, e.g. to create a `SPCommand` /// [DllImport(__DllName, EntryPoint = "sp_pixel_grid_free", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern void sp_pixel_grid_free(PixelGrid* @this); + public static extern void sp_pixel_grid_free(PixelGrid* pixel_grid); /// /// Gets the current value at the specified position in the `SPPixelGrid`. /// /// # Arguments /// - /// - `this`: instance to read from + /// - `pixel_grid`: instance to read from /// - `x` and `y`: position of the cell to read /// /// # Panics @@ -1076,19 +1101,19 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `SPPixelGrid` - /// - `this` is not written to concurrently + /// - `pixel_grid` points to a valid `SPPixelGrid` + /// - `pixel_grid` 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); + public static extern bool sp_pixel_grid_get(PixelGrid* pixel_grid, nuint x, nuint y); /// /// Sets the value of the specified position in the `SPPixelGrid`. /// /// # Arguments /// - /// - `this`: instance to write to + /// - `pixel_grid`: instance to write to /// - `x` and `y`: position of the cell /// - `value`: the value to write to the cell /// @@ -1102,61 +1127,61 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `SPPixelGrid` - /// - `this` is not written to or read from concurrently + /// - `pixel_grid` points to a valid `SPPixelGrid` + /// - `pixel_grid` 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); + public static extern void sp_pixel_grid_set(PixelGrid* pixel_grid, nuint x, nuint y, [MarshalAs(UnmanagedType.U1)] bool value); /// /// Sets the state of all pixels in the `SPPixelGrid`. /// /// # Arguments /// - /// - `this`: instance to write to + /// - `pixel_grid`: 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 `SPPixelGrid` - /// - `this` is not written to or read from concurrently + /// - `pixel_grid` points to a valid `SPPixelGrid` + /// - `pixel_grid` 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); + public static extern void sp_pixel_grid_fill(PixelGrid* pixel_grid, [MarshalAs(UnmanagedType.U1)] bool value); /// /// Gets the width in pixels of the `SPPixelGrid` instance. /// /// # Arguments /// - /// - `this`: instance to read from + /// - `pixel_grid`: instance to read from /// /// # Safety /// /// The caller has to make sure that: /// - /// - `this` points to a valid `SPPixelGrid` + /// - `pixel_grid` points to a valid `SPPixelGrid` /// [DllImport(__DllName, EntryPoint = "sp_pixel_grid_width", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern nuint sp_pixel_grid_width(PixelGrid* @this); + public static extern nuint sp_pixel_grid_width(PixelGrid* pixel_grid); /// /// Gets the height in pixels of the `SPPixelGrid` instance. /// /// # Arguments /// - /// - `this`: instance to read from + /// - `pixel_grid`: instance to read from /// /// # Safety /// /// The caller has to make sure that: /// - /// - `this` points to a valid `SPPixelGrid` + /// - `pixel_grid` points to a valid `SPPixelGrid` /// [DllImport(__DllName, EntryPoint = "sp_pixel_grid_height", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern nuint sp_pixel_grid_height(PixelGrid* @this); + public static extern nuint sp_pixel_grid_height(PixelGrid* pixel_grid); /// /// Gets an unsafe reference to the data of the `SPPixelGrid` instance. @@ -1165,12 +1190,12 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `this` points to a valid `SPPixelGrid` + /// - `pixel_grid` points to a valid `SPPixelGrid` /// - the returned memory range is never accessed after the passed `SPPixelGrid` has been freed /// - the returned memory range is never accessed concurrently, either via the `SPPixelGrid` or directly /// [DllImport(__DllName, EntryPoint = "sp_pixel_grid_unsafe_data_ref", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern ByteSlice sp_pixel_grid_unsafe_data_ref(PixelGrid* @this); + public static extern ByteSlice sp_pixel_grid_unsafe_data_ref(PixelGrid* pixel_grid); } From 96c010de56444c15c8e2d454d304ef24b8c2b314 Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Sat, 7 Sep 2024 15:14:44 +0200 Subject: [PATCH 29/31] set version to 0.8.0 --- Cargo.lock | 6 +++--- Cargo.toml | 2 +- crates/servicepoint/README.md | 2 +- crates/servicepoint_binding_c/Cargo.toml | 2 +- crates/servicepoint_binding_cs/Cargo.toml | 4 ++-- .../ServicePoint/ServicePoint.csproj | 2 +- 6 files changed, 9 insertions(+), 9 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 510a478..8660108 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -574,7 +574,7 @@ dependencies = [ [[package]] name = "servicepoint" -version = "0.7.0" +version = "0.8.0" dependencies = [ "bitvec", "bzip2", @@ -588,7 +588,7 @@ dependencies = [ [[package]] name = "servicepoint_binding_c" -version = "0.7.0" +version = "0.8.0" dependencies = [ "cbindgen", "servicepoint", @@ -596,7 +596,7 @@ dependencies = [ [[package]] name = "servicepoint_binding_cs" -version = "0.7.0" +version = "0.8.0" dependencies = [ "csbindgen", "servicepoint", diff --git a/Cargo.toml b/Cargo.toml index 47241fd..9efa925 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -6,7 +6,7 @@ members = [ ] [workspace.package] -version = "0.7.0" +version = "0.8.0" [workspace.lints.rust] missing-docs = "warn" diff --git a/crates/servicepoint/README.md b/crates/servicepoint/README.md index 1aa717f..daed5f3 100644 --- a/crates/servicepoint/README.md +++ b/crates/servicepoint/README.md @@ -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.7.0", default-features = false, features = ["compression-bz"] } +servicepoint = { version = "0.8.0", default-features = false, features = ["compression-bz"] } ``` ## Everything else diff --git a/crates/servicepoint_binding_c/Cargo.toml b/crates/servicepoint_binding_c/Cargo.toml index 16c2f81..a05d237 100644 --- a/crates/servicepoint_binding_c/Cargo.toml +++ b/crates/servicepoint_binding_c/Cargo.toml @@ -17,7 +17,7 @@ crate-type = ["staticlib", "cdylib", "rlib"] cbindgen = "0.26.0" [dependencies.servicepoint] -version = "0.7.0" +version = "0.8.0" path = "../servicepoint" features = ["all_compressions"] diff --git a/crates/servicepoint_binding_cs/Cargo.toml b/crates/servicepoint_binding_cs/Cargo.toml index fe3c106..798292d 100644 --- a/crates/servicepoint_binding_cs/Cargo.toml +++ b/crates/servicepoint_binding_cs/Cargo.toml @@ -13,8 +13,8 @@ test = false csbindgen = "1.9.3" [dependencies] -servicepoint_binding_c = { version = "0.7.0", path = "../servicepoint_binding_c" } -servicepoint = { version = "0.7.0", path = "../servicepoint" } +servicepoint_binding_c = { version = "0.8.0", path = "../servicepoint_binding_c" } +servicepoint = { version = "0.8.0", path = "../servicepoint" } [lints] workspace = true diff --git a/crates/servicepoint_binding_cs/ServicePoint/ServicePoint.csproj b/crates/servicepoint_binding_cs/ServicePoint/ServicePoint.csproj index 6053dc5..b1831d7 100644 --- a/crates/servicepoint_binding_cs/ServicePoint/ServicePoint.csproj +++ b/crates/servicepoint_binding_cs/ServicePoint/ServicePoint.csproj @@ -11,7 +11,7 @@ ServicePoint - 0.7.0 + 0.8.0 Repository Authors None ServicePoint From 9ab87f6748cbc5da659f6917dc4309dc15a979d2 Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Sat, 7 Sep 2024 15:16:36 +0200 Subject: [PATCH 30/31] update packages --- Cargo.lock | 236 ++++++++--------------- crates/servicepoint_binding_c/Cargo.toml | 2 +- 2 files changed, 81 insertions(+), 157 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 8660108..9328e45 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -66,29 +66,6 @@ dependencies = [ "windows-sys 0.52.0", ] -[[package]] -name = "atty" -version = "0.2.14" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "d9b39be18770d11421cdb1b9947a45dd3f37e93092cbf377614828a319d5fee8" -dependencies = [ - "hermit-abi", - "libc", - "winapi", -] - -[[package]] -name = "autocfg" -version = "1.3.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0c4b4d0bd25bd0b74681c0ad21497610ce1b7c91b1022cd21c80c6fbdd9476b0" - -[[package]] -name = "bitflags" -version = "1.3.2" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a" - [[package]] name = "bitflags" version = "2.6.0" @@ -136,11 +113,11 @@ dependencies = [ [[package]] name = "cbindgen" -version = "0.26.0" +version = "0.27.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "da6bc11b07529f16944307272d5bd9b22530bc7d05751717c9d416586cedab49" +checksum = "3fce8dd7fcfcbf3a0a87d8f515194b49d6135acab73e18bd380d1d93bb1a15eb" dependencies = [ - "clap 3.2.25", + "clap", "heck 0.4.1", "indexmap", "log", @@ -148,16 +125,16 @@ dependencies = [ "quote", "serde", "serde_json", - "syn 1.0.109", + "syn", "tempfile", "toml", ] [[package]] name = "cc" -version = "1.1.15" +version = "1.1.18" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "57b6a275aa2903740dc87da01c62040406b8812552e97129a63ea8850a17c6e6" +checksum = "b62ac837cdb5cb22e10a256099b4fc502b1dfe560cb282963a974d7abd80e476" dependencies = [ "jobserver", "libc", @@ -172,24 +149,9 @@ checksum = "baf1de4339761588bc0619e3cbc0120ee582ebb74b53b4efbf79117bd2da40fd" [[package]] name = "clap" -version = "3.2.25" +version = "4.5.17" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "4ea181bf566f71cb9a5d17a59e1871af638180a18fb0035c92ae62b705207123" -dependencies = [ - "atty", - "bitflags 1.3.2", - "clap_lex 0.2.4", - "indexmap", - "strsim 0.10.0", - "termcolor", - "textwrap", -] - -[[package]] -name = "clap" -version = "4.5.16" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ed6719fffa43d0d87e5fd8caeab59be1554fb028cd30edc88fc4369b17971019" +checksum = "3e5a21b8495e732f1b3c364c9949b201ca7bae518c502c80256c96ad79eaf6ac" dependencies = [ "clap_builder", "clap_derive", @@ -197,14 +159,14 @@ dependencies = [ [[package]] name = "clap_builder" -version = "4.5.15" +version = "4.5.17" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "216aec2b177652e3846684cbfe25c9964d18ec45234f0f5da5157b207ed1aab6" +checksum = "8cf2dd12af7a047ad9d6da2b6b249759a22a7abc0f474c1dae1777afa4b21a73" dependencies = [ "anstream", "anstyle", - "clap_lex 0.7.2", - "strsim 0.11.1", + "clap_lex", + "strsim", ] [[package]] @@ -216,16 +178,7 @@ dependencies = [ "heck 0.5.0", "proc-macro2", "quote", - "syn 2.0.76", -] - -[[package]] -name = "clap_lex" -version = "0.2.4" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "2850f2f5a82cbf437dd5af4d49848fbdfc27c157c3d010345776f952765261c5" -dependencies = [ - "os_str_bytes", + "syn", ] [[package]] @@ -256,9 +209,15 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "c26b9831049b947d154bba920e4124053def72447be6fb106a96f483874b482a" dependencies = [ "regex", - "syn 2.0.76", + "syn", ] +[[package]] +name = "equivalent" +version = "1.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5443807d6dff69373d433ab9ef5378ad8df50ca6298caf15de6e52e24aaf54d5" + [[package]] name = "errno" version = "0.3.9" @@ -304,9 +263,9 @@ dependencies = [ [[package]] name = "hashbrown" -version = "0.12.3" +version = "0.14.5" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "8a9ee70c43aaf417c914396645a0fa852624801b24ebb7ae78fe8272889ac888" +checksum = "e5274423e17b7c9fc20b6e7e208532f9b19825d82dfd615708b70edd83df41f1" [[package]] name = "heck" @@ -320,22 +279,13 @@ version = "0.5.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea" -[[package]] -name = "hermit-abi" -version = "0.1.19" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "62b467343b94ba476dcb2500d242dadbb39557df889310ac77c5d99100aaac33" -dependencies = [ - "libc", -] - [[package]] name = "indexmap" -version = "1.9.3" +version = "2.5.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "bd070e393353796e801d209ad339e89596eb4c8d430d18ede6a1cced8fafbd99" +checksum = "68b900aa2f7301e21c36462b170ee99994de34dff39a4a6a528e80e7376d07e5" dependencies = [ - "autocfg", + "equivalent", "hashbrown", ] @@ -407,12 +357,6 @@ version = "1.19.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "3fdb12b2476b595f9358c5161aa467c2438859caa136dec86c26fdd2efe17b92" -[[package]] -name = "os_str_bytes" -version = "6.6.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "e2355d85b9a3786f481747ced0e0ff2ba35213a1f9bd406ed906554d7af805a1" - [[package]] name = "pkg-config" version = "0.3.30" @@ -523,11 +467,11 @@ dependencies = [ [[package]] name = "rustix" -version = "0.38.35" +version = "0.38.36" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "a85d50532239da68e9addb745ba38ff4612a242c1c7ceea689c4bc7c2f43c36f" +checksum = "3f55e80d50763938498dd5ebb18647174e0c76dc38c5505294bb224624f30f36" dependencies = [ - "bitflags 2.6.0", + "bitflags", "errno", "libc", "linux-raw-sys", @@ -542,29 +486,29 @@ checksum = "f3cb5ba0dc43242ce17de99c180e96db90b235b8a9fdc9543c96d2209116bd9f" [[package]] name = "serde" -version = "1.0.209" +version = "1.0.210" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "99fce0ffe7310761ca6bf9faf5115afbc19688edd00171d81b1bb1b116c63e09" +checksum = "c8e3592472072e6e22e0a54d5904d9febf8508f65fb8552499a1abc7d1078c3a" dependencies = [ "serde_derive", ] [[package]] name = "serde_derive" -version = "1.0.209" +version = "1.0.210" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "a5831b979fd7b5439637af1752d535ff49f4860c0f341d1baeb6faf0f4242170" +checksum = "243902eda00fad750862fc144cea25caca5e20d615af0a81bee94ca738f1df1f" dependencies = [ "proc-macro2", "quote", - "syn 2.0.76", + "syn", ] [[package]] name = "serde_json" -version = "1.0.127" +version = "1.0.128" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "8043c06d9f82bd7271361ed64f415fe5e12a77fdb52e573e7f06a516dea329ad" +checksum = "6ff5456707a1de34e7e37f2a6fd3d3f808c318259cbd01ab6377795054b483d8" dependencies = [ "itoa", "memchr", @@ -572,13 +516,22 @@ dependencies = [ "serde", ] +[[package]] +name = "serde_spanned" +version = "0.6.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "eb5b1b31579f3811bf615c144393417496f152e12ac8b7663bf664f4a815306d" +dependencies = [ + "serde", +] + [[package]] name = "servicepoint" version = "0.8.0" dependencies = [ "bitvec", "bzip2", - "clap 4.5.16", + "clap", "flate2", "log", "rand", @@ -609,12 +562,6 @@ version = "1.3.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64" -[[package]] -name = "strsim" -version = "0.10.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "73473c0e59e6d5812c5dfe2a064a6444949f089e20eec9a2e5506596494e4623" - [[package]] name = "strsim" version = "0.11.1" @@ -623,20 +570,9 @@ checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f" [[package]] name = "syn" -version = "1.0.109" +version = "2.0.77" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "72b64191b275b66ffe2469e8af2c1cfe3bafa67b529ead792a6d0160888b4237" -dependencies = [ - "proc-macro2", - "quote", - "unicode-ident", -] - -[[package]] -name = "syn" -version = "2.0.76" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "578e081a14e0cefc3279b0472138c513f37b41a08d5a3cca9b6e4e8ceb6cd525" +checksum = "9f35bcdf61fd8e7be6caf75f429fdca8beb3ed76584befb503b1569faee373ed" dependencies = [ "proc-macro2", "quote", @@ -663,29 +599,39 @@ dependencies = [ ] [[package]] -name = "termcolor" -version = "1.4.1" +name = "toml" +version = "0.8.19" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "06794f8f6c5c898b3275aebefa6b8a1cb24cd2c6c79397ab15774837a0bc5755" +checksum = "a1ed1f98e3fdc28d6d910e6737ae6ab1a93bf1985935a1193e68f93eeb68d24e" dependencies = [ - "winapi-util", + "serde", + "serde_spanned", + "toml_datetime", + "toml_edit", ] [[package]] -name = "textwrap" -version = "0.16.1" +name = "toml_datetime" +version = "0.6.8" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "23d434d3f8967a09480fb04132ebe0a3e088c173e6d0ee7897abbdf4eab0f8b9" - -[[package]] -name = "toml" -version = "0.5.11" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "f4f7f0dd8d50a853a531c426359045b1998f04219d88799810762cd4ad314234" +checksum = "0dd7358ecb8fc2f8d014bf86f6f638ce72ba252a2c3a2572f2a795f1d23efb41" dependencies = [ "serde", ] +[[package]] +name = "toml_edit" +version = "0.22.20" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "583c44c02ad26b0c3f3066fe629275e50627026c51ac2e595cca4c230ce1ce1d" +dependencies = [ + "indexmap", + "serde", + "serde_spanned", + "toml_datetime", + "winnow", +] + [[package]] name = "unicode-ident" version = "1.0.12" @@ -710,37 +656,6 @@ version = "0.11.0+wasi-snapshot-preview1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "9c8d87e72b64a3b4db28d11ce29237c246188f4f51057d65a7eab63b7987e423" -[[package]] -name = "winapi" -version = "0.3.9" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "5c839a674fcd7a98952e593242ea400abe93992746761e38641405d28b00f419" -dependencies = [ - "winapi-i686-pc-windows-gnu", - "winapi-x86_64-pc-windows-gnu", -] - -[[package]] -name = "winapi-i686-pc-windows-gnu" -version = "0.4.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6" - -[[package]] -name = "winapi-util" -version = "0.1.9" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "cf221c93e13a30d793f7645a0e7762c55d169dbb0a49671918a2319d289b10bb" -dependencies = [ - "windows-sys 0.59.0", -] - -[[package]] -name = "winapi-x86_64-pc-windows-gnu" -version = "0.4.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f" - [[package]] name = "windows-sys" version = "0.52.0" @@ -823,6 +738,15 @@ version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec" +[[package]] +name = "winnow" +version = "0.6.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "68a9bda4691f099d435ad181000724da8e5899daa10713c2d432552b9ccd3a6f" +dependencies = [ + "memchr", +] + [[package]] name = "wyz" version = "0.5.1" @@ -850,7 +774,7 @@ checksum = "fa4f8080344d4671fb4e831a13ad1e68092748387dfc4f55e356242fae12ce3e" dependencies = [ "proc-macro2", "quote", - "syn 2.0.76", + "syn", ] [[package]] diff --git a/crates/servicepoint_binding_c/Cargo.toml b/crates/servicepoint_binding_c/Cargo.toml index a05d237..8b3ed7c 100644 --- a/crates/servicepoint_binding_c/Cargo.toml +++ b/crates/servicepoint_binding_c/Cargo.toml @@ -14,7 +14,7 @@ links = "servicepoint" crate-type = ["staticlib", "cdylib", "rlib"] [build-dependencies] -cbindgen = "0.26.0" +cbindgen = "0.27.0" [dependencies.servicepoint] version = "0.8.0" From eb43ccfa6d7272448af98d83dc302b6936ad2c4b Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Sat, 7 Sep 2024 15:18:51 +0200 Subject: [PATCH 31/31] convert cp437-grid to tuple --- crates/servicepoint_binding_c/src/command.rs | 2 +- .../servicepoint_binding_c/src/cp437_grid.rs | 28 +++++++------------ 2 files changed, 11 insertions(+), 19 deletions(-) diff --git a/crates/servicepoint_binding_c/src/command.rs b/crates/servicepoint_binding_c/src/command.rs index 06eafc4..d98b99f 100644 --- a/crates/servicepoint_binding_c/src/command.rs +++ b/crates/servicepoint_binding_c/src/command.rs @@ -345,7 +345,7 @@ pub unsafe extern "C" fn sp_command_cp437_data( let grid = *Box::from_raw(grid); Box::into_raw(Box::new(SPCommand(servicepoint::Command::Cp437Data( Origin::new(x, y), - grid.actual, + grid.0, )))) } diff --git a/crates/servicepoint_binding_c/src/cp437_grid.rs b/crates/servicepoint_binding_c/src/cp437_grid.rs index c29f6da..a8d4684 100644 --- a/crates/servicepoint_binding_c/src/cp437_grid.rs +++ b/crates/servicepoint_binding_c/src/cp437_grid.rs @@ -17,15 +17,11 @@ use servicepoint::{DataRef, Grid}; /// sp_cp437_grid_set(grid, 0, 0, '!'); /// sp_cp437_grid_free(grid); /// ``` -pub struct SPCp437Grid { - pub(crate) actual: servicepoint::Cp437Grid, -} +pub struct SPCp437Grid(pub(crate) servicepoint::Cp437Grid); impl Clone for SPCp437Grid { fn clone(&self) -> Self { - SPCp437Grid { - actual: self.actual.clone(), - } + SPCp437Grid(self.0.clone()) } } @@ -44,9 +40,7 @@ pub unsafe extern "C" fn sp_cp437_grid_new( width: usize, height: usize, ) -> *mut SPCp437Grid { - Box::into_raw(Box::new(SPCp437Grid { - actual: servicepoint::Cp437Grid::new(width, height), - })) + Box::into_raw(Box::new(SPCp437Grid(servicepoint::Cp437Grid::new(width, height)))) } /// Loads a `SPCp437Grid` with the specified dimensions from the provided data. @@ -73,9 +67,7 @@ pub unsafe extern "C" fn sp_cp437_grid_load( data_length: usize, ) -> *mut SPCp437Grid { let data = std::slice::from_raw_parts(data, data_length); - Box::into_raw(Box::new(SPCp437Grid { - actual: servicepoint::Cp437Grid::load(width, height, data), - })) + Box::into_raw(Box::new(SPCp437Grid(servicepoint::Cp437Grid::load(width, height, data)))) } /// Clones a `SPCp437Grid`. @@ -134,7 +126,7 @@ pub unsafe extern "C" fn sp_cp437_grid_get( x: usize, y: usize, ) -> u8 { - (*cp437_grid).actual.get(x, y) + (*cp437_grid).0.get(x, y) } /// Sets the value of the specified position in the `SPCp437Grid`. @@ -164,7 +156,7 @@ pub unsafe extern "C" fn sp_cp437_grid_set( y: usize, value: u8, ) { - (*cp437_grid).actual.set(x, y, value); + (*cp437_grid).0.set(x, y, value); } /// Sets the value of all cells in the `SPCp437Grid`. @@ -185,7 +177,7 @@ pub unsafe extern "C" fn sp_cp437_grid_fill( cp437_grid: *mut SPCp437Grid, value: u8, ) { - (*cp437_grid).actual.fill(value); + (*cp437_grid).0.fill(value); } /// Gets the width of the `SPCp437Grid` instance. @@ -203,7 +195,7 @@ pub unsafe extern "C" fn sp_cp437_grid_fill( pub unsafe extern "C" fn sp_cp437_grid_width( cp437_grid: *const SPCp437Grid, ) -> usize { - (*cp437_grid).actual.width() + (*cp437_grid).0.width() } /// Gets the height of the `SPCp437Grid` instance. @@ -221,7 +213,7 @@ pub unsafe extern "C" fn sp_cp437_grid_width( pub unsafe extern "C" fn sp_cp437_grid_height( cp437_grid: *const SPCp437Grid, ) -> usize { - (*cp437_grid).actual.height() + (*cp437_grid).0.height() } /// Gets an unsafe reference to the data of the `SPCp437Grid` instance. @@ -239,7 +231,7 @@ pub unsafe extern "C" fn sp_cp437_grid_height( pub unsafe extern "C" fn sp_cp437_grid_unsafe_data_ref( cp437_grid: *mut SPCp437Grid, ) -> SPByteSlice { - let data = (*cp437_grid).actual.data_ref_mut(); + let data = (*cp437_grid).0.data_ref_mut(); SPByteSlice { start: data.as_mut_ptr_range().start, length: data.len(),