From 84adf166a971b81ddb806b323ddccbda7af893df Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Mon, 5 May 2025 18:01:35 +0200 Subject: [PATCH 01/12] add heap_move_ok and heap_move_some helpers --- src/bitmap.rs | 30 +++++++++--------------------- src/bitvec.rs | 11 +++++------ src/brightness_grid.rs | 23 ++++++++++------------- src/char_grid.rs | 17 ++++++----------- src/cp437_grid.rs | 19 +++++++------------ src/lib.rs | 8 ++++++++ src/packet.rs | 15 +++++---------- src/typed_command.rs | 7 ++----- src/udp.rs | 14 +++----------- 9 files changed, 55 insertions(+), 89 deletions(-) diff --git a/src/bitmap.rs b/src/bitmap.rs index 5db4af0..b8b482f 100644 --- a/src/bitmap.rs +++ b/src/bitmap.rs @@ -1,5 +1,8 @@ use crate::byte_slice::ByteSlice; -use crate::{heap_drop, heap_move, heap_move_nonnull, heap_remove, SPBitVec}; +use crate::{ + heap_drop, heap_move_nonnull, heap_move_ok, heap_move_some, heap_remove, + SPBitVec, +}; use servicepoint::{ Bitmap, BitmapCommand, CompressionCode, DataRef, Grid, Origin, Packet, }; @@ -33,11 +36,7 @@ pub unsafe extern "C" fn sp_bitmap_new( width: usize, height: usize, ) -> *mut Bitmap { - if let Some(bitmap) = Bitmap::new(width, height) { - heap_move(bitmap) - } else { - std::ptr::null_mut() - } + heap_move_some(Bitmap::new(width, height)) } /// Creates a new [Bitmap] with a size matching the screen. @@ -63,11 +62,7 @@ pub unsafe extern "C" fn sp_bitmap_load( data: ByteSlice, ) -> *mut Bitmap { let data = unsafe { data.as_slice() }; - if let Ok(bitmap) = Bitmap::load(width, height, data) { - heap_move(bitmap) - } else { - std::ptr::null_mut() - } + heap_move_ok(Bitmap::load(width, height, data)) } /// Tries to convert the BitVec to a Bitmap. @@ -81,11 +76,7 @@ pub unsafe extern "C" fn sp_bitmap_from_bitvec( bitvec: NonNull, ) -> *mut Bitmap { let bitvec = unsafe { heap_remove(bitvec) }; - if let Ok(bitmap) = Bitmap::from_bitvec(width, bitvec.0) { - heap_move(bitmap) - } else { - std::ptr::null_mut() - } + heap_move_ok(Bitmap::from_bitvec(width, bitvec.0)) } /// Clones a [Bitmap]. @@ -215,12 +206,9 @@ pub unsafe extern "C" fn sp_bitmap_into_packet( compression: CompressionCode, ) -> *mut Packet { let bitmap = unsafe { heap_remove(bitmap) }; - match Packet::try_from(BitmapCommand { + heap_move_ok(Packet::try_from(BitmapCommand { bitmap, origin: Origin::new(x, y), compression, - }) { - Ok(packet) => heap_move(packet), - Err(_) => std::ptr::null_mut(), - } + })) } diff --git a/src/bitvec.rs b/src/bitvec.rs index 0e7ee5e..b988df6 100644 --- a/src/bitvec.rs +++ b/src/bitvec.rs @@ -1,4 +1,6 @@ -use crate::{heap_drop, heap_move, heap_move_nonnull, heap_remove, ByteSlice}; +use crate::{ + heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, ByteSlice, +}; use servicepoint::{ BinaryOperation, BitVecCommand, CompressionCode, DisplayBitVec, Packet, }; @@ -162,13 +164,10 @@ pub unsafe extern "C" fn sp_bitvec_into_packet( compression: CompressionCode, ) -> *mut Packet { let bitvec = unsafe { heap_remove(bitvec) }.0; - match Packet::try_from(BitVecCommand { + heap_move_ok(Packet::try_from(BitVecCommand { bitvec, offset, operation, compression, - }) { - Ok(packet) => heap_move(packet), - Err(_) => std::ptr::null_mut(), - } + })) } diff --git a/src/brightness_grid.rs b/src/brightness_grid.rs index 1099be0..2dd985a 100644 --- a/src/brightness_grid.rs +++ b/src/brightness_grid.rs @@ -1,4 +1,7 @@ -use crate::{heap_drop, heap_move, heap_move_nonnull, heap_remove, ByteSlice}; +use crate::{ + heap_drop, heap_move_nonnull, heap_move_ok, heap_move_some, heap_remove, + ByteSlice, +}; use servicepoint::{ Brightness, BrightnessGrid, BrightnessGridCommand, ByteGrid, DataRef, Grid, Origin, Packet, @@ -43,13 +46,10 @@ pub unsafe extern "C" fn sp_brightness_grid_load( data: ByteSlice, ) -> *mut BrightnessGrid { let data = unsafe { data.as_slice() }; - - match ByteGrid::load(width, height, data) - .map(move |grid| grid.map(Brightness::saturating_from)) - { - None => std::ptr::null_mut(), - Some(grid) => heap_move(grid), - } + heap_move_some( + ByteGrid::load(width, height, data) + .map(move |grid| grid.map(Brightness::saturating_from)), + ) } /// Clones a [BrightnessGrid]. @@ -187,11 +187,8 @@ pub unsafe extern "C" fn sp_brightness_grid_into_packet( y: usize, ) -> *mut Packet { let grid = unsafe { heap_remove(grid) }; - match Packet::try_from(BrightnessGridCommand { + heap_move_ok(Packet::try_from(BrightnessGridCommand { grid, origin: Origin::new(x, y), - }) { - Ok(packet) => heap_move(packet), - Err(_) => std::ptr::null_mut(), - } + })) } diff --git a/src/char_grid.rs b/src/char_grid.rs index bfb2585..e07e8db 100644 --- a/src/char_grid.rs +++ b/src/char_grid.rs @@ -1,4 +1,6 @@ -use crate::{heap_drop, heap_move, heap_move_nonnull, heap_remove, ByteSlice}; +use crate::{ + heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, ByteSlice, +}; use servicepoint::{CharGrid, CharGridCommand, Grid, Origin, Packet}; use std::ptr::NonNull; @@ -32,11 +34,7 @@ pub unsafe extern "C" fn sp_char_grid_load( data: ByteSlice, ) -> *mut CharGrid { let data = unsafe { data.as_slice() }; - if let Ok(grid) = CharGrid::load_utf8(width, height, data.to_vec()) { - heap_move(grid) - } else { - std::ptr::null_mut() - } + heap_move_ok(CharGrid::load_utf8(width, height, data.to_vec())) } /// Clones a [CharGrid]. @@ -145,11 +143,8 @@ pub unsafe extern "C" fn sp_char_grid_into_packet( y: usize, ) -> *mut Packet { let grid = unsafe { heap_remove(grid) }; - match Packet::try_from(CharGridCommand { + heap_move_ok(Packet::try_from(CharGridCommand { grid, origin: Origin::new(x, y), - }) { - Ok(packet) => heap_move(packet), - Err(_) => std::ptr::null_mut(), - } + })) } diff --git a/src/cp437_grid.rs b/src/cp437_grid.rs index ff70d2b..5a3daab 100644 --- a/src/cp437_grid.rs +++ b/src/cp437_grid.rs @@ -1,4 +1,7 @@ -use crate::{heap_drop, heap_move, heap_move_nonnull, heap_remove, ByteSlice}; +use crate::{ + heap_drop, heap_move_nonnull, heap_move_ok, heap_move_some, heap_remove, + ByteSlice, +}; use servicepoint::{ Cp437Grid, Cp437GridCommand, DataRef, Grid, Origin, Packet, }; @@ -23,12 +26,7 @@ pub unsafe extern "C" fn sp_cp437_grid_load( data: ByteSlice, ) -> *mut Cp437Grid { let data = unsafe { data.as_slice() }; - let grid = Cp437Grid::load(width, height, data); - if let Some(grid) = grid { - heap_move(grid) - } else { - std::ptr::null_mut() - } + heap_move_some(Cp437Grid::load(width, height, data)) } /// Clones a [Cp437Grid]. @@ -147,11 +145,8 @@ pub unsafe extern "C" fn sp_cp437_grid_into_packet( y: usize, ) -> *mut Packet { let grid = unsafe { heap_remove(grid) }; - match Packet::try_from(Cp437GridCommand { + heap_move_ok(Packet::try_from(Cp437GridCommand { grid, origin: Origin::new(x, y), - }) { - Ok(packet) => heap_move(packet), - Err(_) => std::ptr::null_mut(), - } + })) } diff --git a/src/lib.rs b/src/lib.rs index 60c42ab..f69f0b3 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -60,6 +60,14 @@ pub(crate) fn heap_move_nonnull(x: T) -> NonNull { NonNull::from(Box::leak(Box::new(x))) } +pub(crate) fn heap_move_ok(x: Result) -> *mut T { + x.map(|x| heap_move(x)).unwrap_or(std::ptr::null_mut()) +} + +pub(crate) fn heap_move_some(x: Option) -> *mut T { + x.map(|x| heap_move(x)).unwrap_or(std::ptr::null_mut()) +} + pub(crate) unsafe fn heap_drop(x: NonNull) { drop(unsafe { heap_remove(x) }); } diff --git a/src/packet.rs b/src/packet.rs index d8b1579..a454732 100644 --- a/src/packet.rs +++ b/src/packet.rs @@ -1,4 +1,6 @@ -use crate::{heap_drop, heap_move, heap_move_nonnull, heap_remove, ByteSlice}; +use crate::{ + heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, ByteSlice, +}; use servicepoint::{CommandCode, Header, Packet, TypedCommand}; use std::ptr::NonNull; @@ -11,11 +13,7 @@ pub unsafe extern "C" fn sp_packet_from_command( command: NonNull, ) -> *mut Packet { let command = unsafe { heap_remove(command) }; - if let Ok(packet) = command.try_into() { - heap_move(packet) - } else { - std::ptr::null_mut() - } + heap_move_ok(command.try_into()) } /// Tries to load a [Packet] from the passed array with the specified length. @@ -24,10 +22,7 @@ pub unsafe extern "C" fn sp_packet_from_command( #[no_mangle] pub unsafe extern "C" fn sp_packet_try_load(data: ByteSlice) -> *mut Packet { let data = unsafe { data.as_slice() }; - match servicepoint::Packet::try_from(data) { - Err(_) => std::ptr::null_mut(), - Ok(packet) => heap_move(packet), - } + heap_move_ok(servicepoint::Packet::try_from(data)) } /// Creates a raw [Packet] from parts. diff --git a/src/typed_command.rs b/src/typed_command.rs index 9e27540..df454c4 100644 --- a/src/typed_command.rs +++ b/src/typed_command.rs @@ -1,4 +1,4 @@ -use crate::{heap_drop, heap_move, heap_move_nonnull, SPBitVec}; +use crate::{heap_drop, heap_move, heap_move_nonnull, heap_move_ok, SPBitVec}; use servicepoint::{ BinaryOperation, Bitmap, Brightness, BrightnessGrid, CharGrid, CompressionCode, Cp437Grid, GlobalBrightnessCommand, Packet, TypedCommand, @@ -15,10 +15,7 @@ pub unsafe extern "C" fn sp_command_try_from_packet( packet: NonNull, ) -> *mut TypedCommand { let packet = *unsafe { Box::from_raw(packet.as_ptr()) }; - match servicepoint::TypedCommand::try_from(packet) { - Err(_) => std::ptr::null_mut(), - Ok(command) => heap_move(command), - } + heap_move_ok(servicepoint::TypedCommand::try_from(packet)) } /// Clones a [TypedCommand] instance. diff --git a/src/udp.rs b/src/udp.rs index f68aa16..bc8acc3 100644 --- a/src/udp.rs +++ b/src/udp.rs @@ -1,4 +1,4 @@ -use crate::{heap_drop, heap_move, heap_remove}; +use crate::{heap_drop, heap_move_ok, heap_remove}; use servicepoint::{Header, Packet, TypedCommand, UdpSocketExt}; use std::ffi::{c_char, CStr}; use std::net::{Ipv4Addr, SocketAddrV4, UdpSocket}; @@ -20,12 +20,8 @@ pub unsafe extern "C" fn sp_udp_open(host: NonNull) -> *mut UdpSocket { let host = unsafe { CStr::from_ptr(host.as_ptr()) } .to_str() .expect("Bad encoding"); - let connection = match UdpSocket::bind_connect(host) { - Err(_) => return std::ptr::null_mut(), - Ok(value) => value, - }; - heap_move(connection) + heap_move_ok(UdpSocket::bind_connect(host)) } /// Creates a new instance of [UdpConnection]. @@ -48,11 +44,7 @@ pub unsafe extern "C" fn sp_udp_open_ipv4( port: u16, ) -> *mut UdpSocket { let addr = SocketAddrV4::new(Ipv4Addr::from([ip1, ip2, ip3, ip4]), port); - let connection = match UdpSocket::bind_connect(addr) { - Err(_) => return std::ptr::null_mut(), - Ok(value) => value, - }; - heap_move(connection) + heap_move_ok(UdpSocket::bind_connect(addr)) } /// Sends a [Packet] to the display using the [UdpConnection]. -- 2.47.0 From 373725c648e104b55373fc6d0184c257ca022067 Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Mon, 5 May 2025 22:55:18 +0200 Subject: [PATCH 02/12] add first specific commands --- cbindgen.toml | 2 +- include/servicepoint.h | 135 ++++++++++++++++++++++++++++++--- src/commands/bitmap_command.rs | 110 +++++++++++++++++++++++++++ src/commands/bitvec_command.rs | 115 ++++++++++++++++++++++++++++ src/commands/mod.rs | 2 + src/lib.rs | 4 + src/typed_command.rs | 58 +------------- 7 files changed, 360 insertions(+), 66 deletions(-) create mode 100644 src/commands/bitmap_command.rs create mode 100644 src/commands/bitvec_command.rs create mode 100644 src/commands/mod.rs diff --git a/cbindgen.toml b/cbindgen.toml index 221e915..68723da 100644 --- a/cbindgen.toml +++ b/cbindgen.toml @@ -32,7 +32,7 @@ features = ["full"] [export] include = [] -exclude = [] +exclude = ["BitVec"] [export.rename] "SpBitVec" = "BitVec" diff --git a/include/servicepoint.h b/include/servicepoint.h index 5863ef5..8923756 100644 --- a/include/servicepoint.h +++ b/include/servicepoint.h @@ -179,6 +179,22 @@ enum CompressionCode typedef uint16_t CompressionCode; #endif // __cplusplus +/** + * 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 [`BinaryOperation`] will be applied on the display comparing old and sent bit. + * + * `new_bit = old_bit op sent_bit` + * + * For example, [`BinaryOperation::Or`] can be used to turn on some pixels without affecting other pixels. + * + * The contained [`DisplayBitVec`] is always uncompressed. + */ +typedef struct BitVecCommand BitVecCommand; + /** * A fixed-size 2D grid of booleans. * @@ -196,6 +212,38 @@ typedef uint16_t CompressionCode; */ typedef struct Bitmap Bitmap; +/** + * Overwrites a rectangular region of pixels. + * + * Origin coordinates must be divisible by 8. + * + * # Examples + * + * ```rust + * # use servicepoint::*; + * # let connection = FakeConnection; + * # + * let mut bitmap = Bitmap::max_sized(); + * // draw something to the pixels here + * # bitmap.set(2, 5, true); + * + * // create command to send pixels + * let command = BitmapCommand { + * bitmap, + * origin: Origin::ZERO, + * compression: CompressionCode::Uncompressed + * }; + * + * connection.send_command(command).expect("send failed"); + * ``` + */ +typedef struct BitmapCommand BitmapCommand; + +/** + * This is a type only used by cbindgen to have a type for pointers. + */ +typedef struct DisplayBitVec DisplayBitVec; + /** * The raw packet. * @@ -348,6 +396,11 @@ typedef uint8_t Brightness; */ typedef ValueGrid_char CharGrid; +/** + * Type alias for documenting the meaning of the u16 in enum values + */ +typedef size_t Offset; + /** * A grid containing codepage 437 characters. * @@ -908,17 +961,64 @@ void sp_char_grid_set(CharGrid */*notnull*/ char_grid, */ size_t sp_char_grid_width(CharGrid */*notnull*/ char_grid); +BitmapCommand */*notnull*/ sp_cmd_bitmap_from_bitmap(Bitmap */*notnull*/ bitmap); + +/** + * Returns a pointer to the provided `BitmapCommand`. + * + * # Safety + * + * - The returned bitmap inherits the lifetime of the command in which it is contained. + * - The returned pointer may not be used in a function that consumes the instance, e.g. to create a command. + */ +Bitmap */*notnull*/ sp_cmd_bitmap_get(BitmapCommand */*notnull*/ command); + +CompressionCode sp_cmd_bitmap_get_compression(BitmapCommand */*notnull*/ command); + +void sp_cmd_bitmap_get_origin(BitmapCommand */*notnull*/ command, + size_t */*notnull*/ origin_x, + size_t */*notnull*/ origin_y); + +Packet *sp_cmd_bitmap_into_packet(BitmapCommand */*notnull*/ command); + +TypedCommand */*notnull*/ sp_cmd_bitmap_into_typed(BitmapCommand */*notnull*/ command); + /** * Sets a window of pixels to the specified values. * * The passed [Bitmap] gets consumed. * - * Returns: a new [servicepoint::BitmapCommand] instance. + * Returns: a new [BitmapCommand] instance. */ -TypedCommand *sp_command_bitmap(size_t x, - size_t y, - Bitmap */*notnull*/ bitmap, - CompressionCode compression); +BitmapCommand */*notnull*/ sp_cmd_bitmap_new(Bitmap */*notnull*/ bitmap, + size_t origin_x, + size_t origin_y, + CompressionCode compression); + +/** + * Moves the provided bitmap to be contained in the command. + */ +void sp_cmd_bitmap_set(BitmapCommand */*notnull*/ command, + Bitmap */*notnull*/ bitmap); + +void sp_cmd_bitmap_set_compression(BitmapCommand */*notnull*/ command, + CompressionCode compression); + +void sp_cmd_bitmap_set_origin(BitmapCommand */*notnull*/ command, + size_t origin_x, + size_t origin_y); + +DisplayBitVec *sp_cmd_bitvec_get(BitVecCommand */*notnull*/ command); + +CompressionCode sp_cmd_bitvec_get_compression(BitVecCommand */*notnull*/ command); + +Offset sp_cmd_bitvec_get_offset(BitVecCommand */*notnull*/ command); + +BinaryOperation sp_cmd_bitvec_get_operation(BitVecCommand */*notnull*/ command); + +Packet *sp_cmd_bitvec_into_packet(BitVecCommand */*notnull*/ command); + +TypedCommand */*notnull*/ sp_cmd_bitvec_into_typed(BitVecCommand */*notnull*/ command); /** * Set pixel data starting at the pixel offset on screen. @@ -932,12 +1032,27 @@ TypedCommand *sp_command_bitmap(size_t x, * * For example, [`BinaryOperation::Or`] can be used to turn on some pixels without affecting other pixels. * - * The contained [`BitVecU8Msb0`] is always uncompressed. + * The contained [`DisplayBitVec`] is always uncompressed. */ -TypedCommand *sp_command_bitvec(size_t offset, - SPBitVec */*notnull*/ bit_vec, - CompressionCode compression, - BinaryOperation operation); +BitVecCommand */*notnull*/ sp_cmd_bitvec_new(DisplayBitVec */*notnull*/ bitvec, + size_t offset, + BinaryOperation operation, + CompressionCode compression); + +/** + * Moves the provided bitmap to be contained in the command. + */ +void sp_cmd_bitvec_set(BitVecCommand */*notnull*/ command, + DisplayBitVec */*notnull*/ bitvec); + +void sp_cmd_bitvec_set_compression(BitVecCommand */*notnull*/ command, + CompressionCode compression); + +void sp_cmd_bitvec_set_offset(BitVecCommand */*notnull*/ command, + Offset offset); + +void sp_cmd_bitvec_set_operation(BitVecCommand */*notnull*/ command, + BinaryOperation operation); /** * Set the brightness of individual tiles in a rectangular area of the display. diff --git a/src/commands/bitmap_command.rs b/src/commands/bitmap_command.rs new file mode 100644 index 0000000..b1ab343 --- /dev/null +++ b/src/commands/bitmap_command.rs @@ -0,0 +1,110 @@ +use crate::{heap_move_nonnull, heap_move_ok, heap_remove}; +use servicepoint::{ + Bitmap, BitmapCommand, CompressionCode, Origin, Packet, TypedCommand, +}; +use std::ptr::NonNull; + +/// Sets a window of pixels to the specified values. +/// +/// The passed [Bitmap] gets consumed. +/// +/// Returns: a new [BitmapCommand] instance. +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_bitmap_new( + bitmap: NonNull, + origin_x: usize, + origin_y: usize, + compression: CompressionCode, +) -> NonNull { + heap_move_nonnull(BitmapCommand { + bitmap: unsafe { heap_remove(bitmap) }, + origin: Origin::new(origin_x, origin_y), + compression, + }) +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_bitmap_from_bitmap( + bitmap: NonNull, +) -> NonNull { + heap_move_nonnull(unsafe { heap_remove(bitmap) }.into()) +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_bitmap_into_typed( + command: NonNull, +) -> NonNull { + heap_move_nonnull(unsafe { heap_remove(command) }.into()) +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_bitmap_into_packet( + command: NonNull, +) -> *mut Packet { + heap_move_ok(unsafe { heap_remove(command) }.try_into()) +} + +/// Returns a pointer to the provided `BitmapCommand`. +/// +/// # Safety +/// +/// - The returned bitmap inherits the lifetime of the command in which it is contained. +/// - The returned pointer may not be used in a function that consumes the instance, e.g. to create a command. +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_bitmap_get( + mut command: NonNull, +) -> NonNull { + unsafe { NonNull::from(&mut (command.as_mut().bitmap)) } +} + +/// Moves the provided bitmap to be contained in the command. +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_bitmap_set( + mut command: NonNull, + bitmap: NonNull, +) { + unsafe { + command.as_mut().bitmap = heap_remove(bitmap); + } +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_bitmap_get_origin( + command: NonNull, + origin_x: NonNull, + origin_y: NonNull, +) { + unsafe { + let origin = &command.as_ref().origin; + *origin_x.as_ptr() = origin.x; + *origin_y.as_ptr() = origin.y; + } +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_bitmap_set_origin( + mut command: NonNull, + origin_x: usize, + origin_y: usize, +) { + unsafe { + command.as_mut().origin = Origin::new(origin_x, origin_y); + } +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_bitmap_set_compression( + mut command: NonNull, + compression: CompressionCode, +) { + unsafe { + command.as_mut().compression = compression; + } +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_bitmap_get_compression( + command: NonNull, +) -> CompressionCode { + unsafe { command.as_ref().compression } +} diff --git a/src/commands/bitvec_command.rs b/src/commands/bitvec_command.rs new file mode 100644 index 0000000..39d5253 --- /dev/null +++ b/src/commands/bitvec_command.rs @@ -0,0 +1,115 @@ +use crate::{heap_move_nonnull, heap_move_ok, heap_remove}; +use servicepoint::{ + BinaryOperation, BitVecCommand, CompressionCode, DisplayBitVec, Offset, + Packet, TypedCommand, +}; +use std::ptr::NonNull; + +/// 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 [`BinaryOperation`] will be applied on the display comparing old and sent bit. +/// +/// `new_bit = old_bit op sent_bit` +/// +/// For example, [`BinaryOperation::Or`] can be used to turn on some pixels without affecting other pixels. +/// +/// The contained [`DisplayBitVec`] is always uncompressed. +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_bitvec_new( + bitvec: NonNull, + offset: usize, + operation: BinaryOperation, + compression: CompressionCode, +) -> NonNull { + heap_move_nonnull(BitVecCommand { + bitvec: unsafe { heap_remove(bitvec) }, + offset, + operation, + compression, + }) +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_bitvec_into_typed( + command: NonNull, +) -> NonNull { + heap_move_nonnull(unsafe { heap_remove(command) }.into()) +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_bitvec_into_packet( + command: NonNull, +) -> *mut Packet { + heap_move_ok(unsafe { heap_remove(command) }.try_into()) +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_bitvec_get( + mut command: NonNull, +) -> *mut DisplayBitVec { + &mut unsafe { command.as_mut() }.bitvec +} + +/// Moves the provided bitmap to be contained in the command. +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_bitvec_set( + mut command: NonNull, + bitvec: NonNull, +) { + unsafe { + command.as_mut().bitvec = heap_remove(bitvec); + } +} +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_bitvec_get_offset( + command: NonNull, +) -> Offset { + unsafe { command.as_ref().offset } +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_bitvec_set_offset( + mut command: NonNull, + offset: Offset, +) { + unsafe { + command.as_mut().offset = offset; + } +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_bitvec_get_operation( + command: NonNull, +) -> BinaryOperation { + unsafe { command.as_ref().operation.clone() } // TODO remove clone +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_bitvec_set_operation( + mut command: NonNull, + operation: BinaryOperation, +) { + unsafe { + command.as_mut().operation = operation; + } +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_bitvec_set_compression( + mut command: NonNull, + compression: CompressionCode, +) { + unsafe { + command.as_mut().compression = compression; + } +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_bitvec_get_compression( + command: NonNull, +) -> CompressionCode { + unsafe { command.as_ref().compression } +} diff --git a/src/commands/mod.rs b/src/commands/mod.rs new file mode 100644 index 0000000..45489df --- /dev/null +++ b/src/commands/mod.rs @@ -0,0 +1,2 @@ +mod bitmap_command; +mod bitvec_command; diff --git a/src/lib.rs b/src/lib.rs index f69f0b3..924a729 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -42,6 +42,7 @@ mod bitvec; mod brightness_grid; mod byte_slice; mod char_grid; +mod commands; mod cp437_grid; mod packet; mod typed_command; @@ -78,3 +79,6 @@ pub(crate) unsafe fn heap_remove(x: NonNull) -> T { /// This is a type only used by cbindgen to have a type for pointers. pub struct UdpSocket; + +/// This is a type only used by cbindgen to have a type for pointers. +pub struct DisplayBitVec; diff --git a/src/typed_command.rs b/src/typed_command.rs index df454c4..451c0b7 100644 --- a/src/typed_command.rs +++ b/src/typed_command.rs @@ -1,7 +1,7 @@ -use crate::{heap_drop, heap_move, heap_move_nonnull, heap_move_ok, SPBitVec}; +use crate::{heap_drop, heap_move_nonnull, heap_move_ok}; use servicepoint::{ - BinaryOperation, Bitmap, Brightness, BrightnessGrid, CharGrid, - CompressionCode, Cp437Grid, GlobalBrightnessCommand, Packet, TypedCommand, + Brightness, BrightnessGrid, CharGrid, Cp437Grid, GlobalBrightnessCommand, + Packet, TypedCommand, }; use std::ptr::NonNull; @@ -92,36 +92,6 @@ pub unsafe extern "C" fn sp_command_brightness_grid( heap_move_nonnull(result) } -/// 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 [`BinaryOperation`] will be applied on the display comparing old and sent bit. -/// -/// `new_bit = old_bit op sent_bit` -/// -/// For example, [`BinaryOperation::Or`] can be used to turn on some pixels without affecting other pixels. -/// -/// The contained [`BitVecU8Msb0`] is always uncompressed. -#[no_mangle] -pub unsafe extern "C" fn sp_command_bitvec( - offset: usize, - bit_vec: NonNull, - compression: CompressionCode, - operation: BinaryOperation, -) -> *mut TypedCommand { - let bit_vec = unsafe { *Box::from_raw(bit_vec.as_ptr()) }; - let command = servicepoint::BitVecCommand { - offset, - operation, - bitvec: bit_vec.0, - compression, - } - .into(); - heap_move(command) -} - /// Show codepage 437 encoded text on the screen. /// /// The passed [Cp437Grid] gets consumed. @@ -162,28 +132,6 @@ pub unsafe extern "C" fn sp_command_char_grid( heap_move_nonnull(result) } -/// Sets a window of pixels to the specified values. -/// -/// The passed [Bitmap] gets consumed. -/// -/// Returns: a new [servicepoint::BitmapCommand] instance. -#[no_mangle] -pub unsafe extern "C" fn sp_command_bitmap( - x: usize, - y: usize, - bitmap: NonNull, - compression: CompressionCode, -) -> *mut TypedCommand { - let bitmap = unsafe { *Box::from_raw(bitmap.as_ptr()) }; - let command = servicepoint::BitmapCommand { - origin: servicepoint::Origin::new(x, y), - bitmap, - compression, - } - .into(); - heap_move(command) -} - /// Deallocates a [TypedCommand]. /// /// # Examples -- 2.47.0 From 2165629befde7ef83f0ad69bd1c3d115f5489a7e Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Mon, 5 May 2025 22:59:06 +0200 Subject: [PATCH 03/12] add badges --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 4788c75..fa0a49b 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,11 @@ # servicepoint_binding_c +[![Release](https://git.berlin.ccc.de/servicepoint/servicepoint_binding_c/badges/release.svg)](https://git.berlin.ccc.de/servicepoint/servicepoint_binding_c/releases) [![crates.io](https://img.shields.io/crates/v/servicepoint_binding_c.svg)](https://crates.io/crates/servicepoint) [![Crates.io Total Downloads](https://img.shields.io/crates/d/servicepoint_binding_c)](https://crates.io/crates/servicepoint) [![docs.rs](https://img.shields.io/docsrs/servicepoint_binding_c)](https://docs.rs/servicepoint/latest/servicepoint/) [![GPLv3 licensed](https://img.shields.io/crates/l/servicepoint_binding_c)](./LICENSE) +[![CI](https://git.berlin.ccc.de/servicepoint/servicepoint_binding_c/badges/workflows/rust.yml/badge.svg)](https://git.berlin.ccc.de/servicepoint/servicepoint_binding_c) In [CCCB](https://berlin.ccc.de/), there is a big pixel matrix hanging on the wall. It is called "Service Point Display" or "Airport Display". @@ -12,7 +14,7 @@ This crate contains C bindings for the [servicepoint](https://git.berlin.ccc.de/ ## Examples -```c++ +```c #include #include "servicepoint.h" -- 2.47.0 From 4f0eca3ea0ee4caed7ea907033450b68b37db42b Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Tue, 6 May 2025 21:12:37 +0200 Subject: [PATCH 04/12] more commands --- example/src/brightness_tester.c | 44 ++++--- include/servicepoint.h | 146 ++++++++++++++++++++++++ src/commands/bitmap_command.rs | 14 ++- src/commands/bitvec_command.rs | 15 ++- src/commands/brightness_grid_command.rs | 95 +++++++++++++++ src/commands/char_grid_command.rs | 94 +++++++++++++++ src/commands/cp437_grid_command.rs | 94 +++++++++++++++ src/commands/mod.rs | 3 + src/typed_command.rs | 62 +--------- 9 files changed, 489 insertions(+), 78 deletions(-) create mode 100644 src/commands/brightness_grid_command.rs create mode 100644 src/commands/char_grid_command.rs create mode 100644 src/commands/cp437_grid_command.rs diff --git a/example/src/brightness_tester.c b/example/src/brightness_tester.c index c3e42ba..9476422 100644 --- a/example/src/brightness_tester.c +++ b/example/src/brightness_tester.c @@ -1,30 +1,44 @@ #include "servicepoint.h" -int main(void) { - UdpSocket *connection = sp_udp_open_ipv4(172, 23, 42, 29, 2342); - //UdpSocket *connection = sp_udp_open_ipv4(127, 0, 0, 1, 2342); - if (connection == NULL) - return -1; +static UdpSocket *connection = NULL; +void enable_all_pixels(void) { Bitmap *all_on = sp_bitmap_new_max_sized(); sp_bitmap_fill(all_on, true); - Packet *packet = sp_bitmap_into_packet(all_on, 0, 0, COMPRESSION_CODE_UNCOMPRESSED); - if (packet == NULL) - return -1; - - sp_udp_send_packet(connection, packet); - - BrightnessGrid *grid = sp_brightness_grid_new(TILE_WIDTH, TILE_HEIGHT); + BitmapCommand *bitmapCommand = sp_cmd_bitmap_from_bitmap(all_on); + Packet *packet = sp_cmd_bitmap_into_packet(bitmapCommand); + if (packet != NULL) + sp_udp_send_packet(connection, packet); +} +void make_brightness_pattern(BrightnessGrid *grid) { ByteSlice slice = sp_brightness_grid_unsafe_data_ref(grid); for (size_t index = 0; index < slice.length; index++) { slice.start[index] = (uint8_t) (index % ((size_t) Brightness_MAX)); } +} - packet = sp_brightness_grid_into_packet(grid, 0, 0); - sp_udp_send_packet(connection, packet); - +void run_at_exit() { sp_udp_free(connection); +} + +int main(void) { + //UdpSocket *connection = sp_udp_open_ipv4(172, 23, 42, 29, 2342); + connection = sp_udp_open_ipv4(127, 0, 0, 1, 2342); + if (connection == NULL) + return -1; + atexit(run_at_exit); + + enable_all_pixels(); + + BrightnessGrid *grid = sp_brightness_grid_new(TILE_WIDTH, TILE_HEIGHT); + make_brightness_pattern(grid); + + Packet *packet = sp_cmd_brightness_grid_into_packet(sp_cmd_brightness_grid_from_grid(grid)); + if (packet == NULL) + return -2; + + sp_udp_send_packet(connection, packet); return 0; } diff --git a/include/servicepoint.h b/include/servicepoint.h index 8923756..805d84b 100644 --- a/include/servicepoint.h +++ b/include/servicepoint.h @@ -239,6 +239,54 @@ typedef struct Bitmap Bitmap; */ typedef struct BitmapCommand BitmapCommand; +/** + * Set the brightness of individual tiles in a rectangular area of the display. + */ +typedef struct BrightnessGridCommand BrightnessGridCommand; + +/** + * Show text on the screen. + * + * The text is sent in the form of a 2D grid of UTF-8 encoded characters (the default encoding in rust). + * + * # Examples + * + * ```rust + * # use servicepoint::*; + * # let connection = FakeConnection; + * let grid = CharGrid::from("Hello,\nWorld!"); + * connection.send_command(CharGridCommand { origin: Origin::ZERO, grid }).expect("send failed"); + * ``` + */ +typedef struct CharGridCommand CharGridCommand; + +/** + * Show text on the screen. + * + * The text is sent in the form of a 2D grid of [CP-437] encoded characters. + * + *
You probably want to use [Command::Utf8Data] instead
+ * + * # Examples + * + * ```rust + * # use servicepoint::*; + * # let connection = FakeConnection; + * let grid = CharGrid::from("Hello,\nWorld!"); + * let grid = Cp437Grid::from(&grid); + * connection.send_command(Cp437GridCommand{ origin: Origin::ZERO, grid }).expect("send failed"); + * ``` + * + * ```rust + * # use servicepoint::*; + * # let connection = FakeConnection; + * let grid = Cp437Grid::load_ascii("Hello\nWorld", 5, false).unwrap(); + * connection.send_command(Cp437GridCommand{ origin: Origin::new(2, 2), grid }).unwrap(); + * ``` + * [CP-437]: https://en.wikipedia.org/wiki/Code_page_437 + */ +typedef struct Cp437GridCommand Cp437GridCommand; + /** * This is a type only used by cbindgen to have a type for pointers. */ @@ -961,6 +1009,10 @@ void sp_char_grid_set(CharGrid */*notnull*/ char_grid, */ size_t sp_char_grid_width(CharGrid */*notnull*/ char_grid); +BitmapCommand */*notnull*/ sp_cmd_bitmap_clone(BitmapCommand */*notnull*/ command); + +void sp_cmd_bitmap_free(BitmapCommand */*notnull*/ command); + BitmapCommand */*notnull*/ sp_cmd_bitmap_from_bitmap(Bitmap */*notnull*/ bitmap); /** @@ -1008,6 +1060,10 @@ void sp_cmd_bitmap_set_origin(BitmapCommand */*notnull*/ command, size_t origin_x, size_t origin_y); +BitVecCommand */*notnull*/ sp_cmd_bitvec_clone(BitVecCommand */*notnull*/ command); + +void sp_cmd_bitvec_free(BitVecCommand */*notnull*/ command); + DisplayBitVec *sp_cmd_bitvec_get(BitVecCommand */*notnull*/ command); CompressionCode sp_cmd_bitvec_get_compression(BitVecCommand */*notnull*/ command); @@ -1054,6 +1110,96 @@ void sp_cmd_bitvec_set_offset(BitVecCommand */*notnull*/ command, void sp_cmd_bitvec_set_operation(BitVecCommand */*notnull*/ command, BinaryOperation operation); +BrightnessGridCommand */*notnull*/ sp_cmd_brightness_grid_clone(BrightnessGridCommand */*notnull*/ command); + +void sp_cmd_brightness_grid_free(BitmapCommand */*notnull*/ command); + +BrightnessGridCommand */*notnull*/ sp_cmd_brightness_grid_from_grid(BrightnessGrid */*notnull*/ grid); + +BrightnessGrid *sp_cmd_brightness_grid_get(BrightnessGridCommand */*notnull*/ command); + +void sp_cmd_brightness_grid_get_origin(BrightnessGridCommand */*notnull*/ command, + size_t */*notnull*/ origin_x, + size_t */*notnull*/ origin_y); + +Packet *sp_cmd_brightness_grid_into_packet(BrightnessGridCommand */*notnull*/ command); + +TypedCommand */*notnull*/ sp_cmd_brightness_grid_into_typed(BrightnessGridCommand */*notnull*/ command); + +BrightnessGridCommand */*notnull*/ sp_cmd_brightness_grid_new(BrightnessGrid */*notnull*/ grid, + size_t origin_x, + size_t origin_y); + +/** + * Moves the provided bitmap to be contained in the command. + */ +void sp_cmd_brightness_grid_set(BrightnessGridCommand */*notnull*/ command, + BrightnessGrid */*notnull*/ grid); + +void sp_cmd_brightness_grid_set_origin(BrightnessGridCommand */*notnull*/ command, + size_t origin_x, + size_t origin_y); + +CharGridCommand */*notnull*/ sp_cmd_char_grid_clone(CharGridCommand */*notnull*/ command); + +void sp_cmd_char_grid_free(BitmapCommand */*notnull*/ command); + +CharGridCommand */*notnull*/ sp_cmd_char_grid_from_grid(CharGrid */*notnull*/ grid); + +CharGrid *sp_cmd_char_grid_get(CharGridCommand */*notnull*/ command); + +void sp_cmd_char_grid_get_origin(CharGridCommand */*notnull*/ command, + size_t */*notnull*/ origin_x, + size_t */*notnull*/ origin_y); + +Packet *sp_cmd_char_grid_into_packet(CharGridCommand */*notnull*/ command); + +TypedCommand */*notnull*/ sp_cmd_char_grid_into_typed(CharGridCommand */*notnull*/ command); + +CharGridCommand */*notnull*/ sp_cmd_char_grid_new(CharGrid */*notnull*/ grid, + size_t origin_x, + size_t origin_y); + +/** + * Moves the provided bitmap to be contained in the command. + */ +void sp_cmd_char_grid_set(CharGridCommand */*notnull*/ command, + CharGrid */*notnull*/ grid); + +void sp_cmd_char_grid_set_origin(CharGridCommand */*notnull*/ command, + size_t origin_x, + size_t origin_y); + +Cp437GridCommand */*notnull*/ sp_cmd_cp437_grid_clone(Cp437GridCommand */*notnull*/ command); + +void sp_cmd_cp437_grid_free(BitmapCommand */*notnull*/ command); + +Cp437GridCommand */*notnull*/ sp_cmd_cp437_grid_from_grid(Cp437Grid */*notnull*/ grid); + +Cp437Grid *sp_cmd_cp437_grid_get(Cp437GridCommand */*notnull*/ command); + +void sp_cmd_cp437_grid_get_origin(Cp437GridCommand */*notnull*/ command, + size_t */*notnull*/ origin_x, + size_t */*notnull*/ origin_y); + +Packet *sp_cmd_cp437_grid_into_packet(Cp437GridCommand */*notnull*/ command); + +TypedCommand */*notnull*/ sp_cmd_cp437_grid_into_typed(Cp437GridCommand */*notnull*/ command); + +Cp437GridCommand */*notnull*/ sp_cmd_cp437_grid_new(Cp437Grid */*notnull*/ grid, + size_t origin_x, + size_t origin_y); + +/** + * Moves the provided bitmap to be contained in the command. + */ +void sp_cmd_cp437_grid_set(Cp437GridCommand */*notnull*/ command, + Cp437Grid */*notnull*/ grid); + +void sp_cmd_cp437_grid_set_origin(Cp437GridCommand */*notnull*/ command, + size_t origin_x, + size_t origin_y); + /** * Set the brightness of individual tiles in a rectangular area of the display. * diff --git a/src/commands/bitmap_command.rs b/src/commands/bitmap_command.rs index b1ab343..4413a3c 100644 --- a/src/commands/bitmap_command.rs +++ b/src/commands/bitmap_command.rs @@ -1,4 +1,4 @@ -use crate::{heap_move_nonnull, heap_move_ok, heap_remove}; +use crate::{heap_drop, heap_move_nonnull, heap_move_ok, heap_remove}; use servicepoint::{ Bitmap, BitmapCommand, CompressionCode, Origin, Packet, TypedCommand, }; @@ -44,6 +44,18 @@ pub unsafe extern "C" fn sp_cmd_bitmap_into_packet( heap_move_ok(unsafe { heap_remove(command) }.try_into()) } +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_bitmap_clone( + command: NonNull, +) -> NonNull { + heap_move_nonnull(unsafe { command.as_ref().clone() }) +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_bitmap_free(command: NonNull) { + unsafe { heap_drop(command) } +} + /// Returns a pointer to the provided `BitmapCommand`. /// /// # Safety diff --git a/src/commands/bitvec_command.rs b/src/commands/bitvec_command.rs index 39d5253..5795017 100644 --- a/src/commands/bitvec_command.rs +++ b/src/commands/bitvec_command.rs @@ -1,4 +1,4 @@ -use crate::{heap_move_nonnull, heap_move_ok, heap_remove}; +use crate::{heap_drop, heap_move_nonnull, heap_move_ok, heap_remove}; use servicepoint::{ BinaryOperation, BitVecCommand, CompressionCode, DisplayBitVec, Offset, Packet, TypedCommand, @@ -46,6 +46,18 @@ pub unsafe extern "C" fn sp_cmd_bitvec_into_packet( heap_move_ok(unsafe { heap_remove(command) }.try_into()) } +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_bitvec_clone( + command: NonNull, +) -> NonNull { + heap_move_nonnull(unsafe { command.as_ref().clone() }) +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_bitvec_free(command: NonNull) { + unsafe { heap_drop(command) } +} + #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitvec_get( mut command: NonNull, @@ -63,6 +75,7 @@ pub unsafe extern "C" fn sp_cmd_bitvec_set( command.as_mut().bitvec = heap_remove(bitvec); } } + #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitvec_get_offset( command: NonNull, diff --git a/src/commands/brightness_grid_command.rs b/src/commands/brightness_grid_command.rs new file mode 100644 index 0000000..18a2836 --- /dev/null +++ b/src/commands/brightness_grid_command.rs @@ -0,0 +1,95 @@ +use crate::{heap_drop, heap_move_nonnull, heap_move_ok, heap_remove}; +use servicepoint::{ + BitmapCommand, BrightnessGrid, BrightnessGridCommand, Origin, Packet, + TypedCommand, +}; +use std::ptr::NonNull; + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_brightness_grid_new( + grid: NonNull, + origin_x: usize, + origin_y: usize, +) -> NonNull { + heap_move_nonnull(BrightnessGridCommand { + grid: unsafe { heap_remove(grid) }, + origin: Origin::new(origin_x, origin_y), + }) +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_brightness_grid_from_grid( + grid: NonNull, +) -> NonNull { + heap_move_nonnull(unsafe { heap_remove(grid) }.into()) +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_brightness_grid_into_typed( + command: NonNull, +) -> NonNull { + heap_move_nonnull(unsafe { heap_remove(command) }.into()) +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_brightness_grid_into_packet( + command: NonNull, +) -> *mut Packet { + heap_move_ok(unsafe { heap_remove(command) }.try_into()) +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_brightness_grid_clone( + command: NonNull, +) -> NonNull { + heap_move_nonnull(unsafe { command.as_ref().clone() }) +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_brightness_grid_free( + command: NonNull, +) { + unsafe { heap_drop(command) } +} + +/// Moves the provided bitmap to be contained in the command. +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_brightness_grid_set( + mut command: NonNull, + grid: NonNull, +) { + unsafe { + command.as_mut().grid = heap_remove(grid); + } +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_brightness_grid_get( + mut command: NonNull, +) -> *mut BrightnessGrid { + &mut unsafe { command.as_mut() }.grid +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_brightness_grid_get_origin( + command: NonNull, + origin_x: NonNull, + origin_y: NonNull, +) { + unsafe { + let origin = &command.as_ref().origin; + *origin_x.as_ptr() = origin.x; + *origin_y.as_ptr() = origin.y; + } +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_brightness_grid_set_origin( + mut command: NonNull, + origin_x: usize, + origin_y: usize, +) { + unsafe { + command.as_mut().origin = Origin::new(origin_x, origin_y); + } +} diff --git a/src/commands/char_grid_command.rs b/src/commands/char_grid_command.rs new file mode 100644 index 0000000..933e4cd --- /dev/null +++ b/src/commands/char_grid_command.rs @@ -0,0 +1,94 @@ +use crate::{heap_drop, heap_move_nonnull, heap_move_ok, heap_remove}; +use servicepoint::{ + BitmapCommand, CharGrid, CharGridCommand, Origin, Packet, TypedCommand, +}; +use std::ptr::NonNull; + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_char_grid_new( + grid: NonNull, + origin_x: usize, + origin_y: usize, +) -> NonNull { + heap_move_nonnull(CharGridCommand { + grid: unsafe { heap_remove(grid) }, + origin: Origin::new(origin_x, origin_y), + }) +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_char_grid_from_grid( + grid: NonNull, +) -> NonNull { + heap_move_nonnull(unsafe { heap_remove(grid) }.into()) +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_char_grid_into_typed( + command: NonNull, +) -> NonNull { + heap_move_nonnull(unsafe { heap_remove(command) }.into()) +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_char_grid_into_packet( + command: NonNull, +) -> *mut Packet { + heap_move_ok(unsafe { heap_remove(command) }.try_into()) +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_char_grid_clone( + command: NonNull, +) -> NonNull { + heap_move_nonnull(unsafe { command.as_ref().clone() }) +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_char_grid_free( + command: NonNull, +) { + unsafe { heap_drop(command) } +} + +/// Moves the provided bitmap to be contained in the command. +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_char_grid_set( + mut command: NonNull, + grid: NonNull, +) { + unsafe { + command.as_mut().grid = heap_remove(grid); + } +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_char_grid_get( + mut command: NonNull, +) -> *mut CharGrid { + &mut unsafe { command.as_mut() }.grid +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_char_grid_get_origin( + command: NonNull, + origin_x: NonNull, + origin_y: NonNull, +) { + unsafe { + let origin = &command.as_ref().origin; + *origin_x.as_ptr() = origin.x; + *origin_y.as_ptr() = origin.y; + } +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_char_grid_set_origin( + mut command: NonNull, + origin_x: usize, + origin_y: usize, +) { + unsafe { + command.as_mut().origin = Origin::new(origin_x, origin_y); + } +} diff --git a/src/commands/cp437_grid_command.rs b/src/commands/cp437_grid_command.rs new file mode 100644 index 0000000..0f3d9e2 --- /dev/null +++ b/src/commands/cp437_grid_command.rs @@ -0,0 +1,94 @@ +use crate::{heap_drop, heap_move_nonnull, heap_move_ok, heap_remove}; +use servicepoint::{ + BitmapCommand, Cp437Grid, Cp437GridCommand, Origin, Packet, TypedCommand, +}; +use std::ptr::NonNull; + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_cp437_grid_new( + grid: NonNull, + origin_x: usize, + origin_y: usize, +) -> NonNull { + heap_move_nonnull(Cp437GridCommand { + grid: unsafe { heap_remove(grid) }, + origin: Origin::new(origin_x, origin_y), + }) +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_cp437_grid_from_grid( + grid: NonNull, +) -> NonNull { + heap_move_nonnull(unsafe { heap_remove(grid) }.into()) +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_cp437_grid_into_typed( + command: NonNull, +) -> NonNull { + heap_move_nonnull(unsafe { heap_remove(command) }.into()) +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_cp437_grid_into_packet( + command: NonNull, +) -> *mut Packet { + heap_move_ok(unsafe { heap_remove(command) }.try_into()) +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_cp437_grid_clone( + command: NonNull, +) -> NonNull { + heap_move_nonnull(unsafe { command.as_ref().clone() }) +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_cp437_grid_free( + command: NonNull, +) { + unsafe { heap_drop(command) } +} + +/// Moves the provided bitmap to be contained in the command. +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_cp437_grid_set( + mut command: NonNull, + grid: NonNull, +) { + unsafe { + command.as_mut().grid = heap_remove(grid); + } +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_cp437_grid_get( + mut command: NonNull, +) -> *mut Cp437Grid { + &mut unsafe { command.as_mut() }.grid +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_cp437_grid_get_origin( + command: NonNull, + origin_x: NonNull, + origin_y: NonNull, +) { + unsafe { + let origin = &command.as_ref().origin; + *origin_x.as_ptr() = origin.x; + *origin_y.as_ptr() = origin.y; + } +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_cp437_grid_set_origin( + mut command: NonNull, + origin_x: usize, + origin_y: usize, +) { + unsafe { + command.as_mut().origin = Origin::new(origin_x, origin_y); + } +} diff --git a/src/commands/mod.rs b/src/commands/mod.rs index 45489df..90422ff 100644 --- a/src/commands/mod.rs +++ b/src/commands/mod.rs @@ -1,2 +1,5 @@ mod bitmap_command; mod bitvec_command; +mod brightness_grid_command; +mod char_grid_command; +mod cp437_grid_command; diff --git a/src/typed_command.rs b/src/typed_command.rs index 451c0b7..26c33f1 100644 --- a/src/typed_command.rs +++ b/src/typed_command.rs @@ -1,6 +1,6 @@ use crate::{heap_drop, heap_move_nonnull, heap_move_ok}; use servicepoint::{ - Brightness, BrightnessGrid, CharGrid, Cp437Grid, GlobalBrightnessCommand, + Brightness, GlobalBrightnessCommand, Packet, TypedCommand, }; use std::ptr::NonNull; @@ -72,66 +72,6 @@ pub unsafe extern "C" fn sp_command_global_brightness( heap_move_nonnull(GlobalBrightnessCommand::from(brightness).into()) } -/// Set the brightness of individual tiles in a rectangular area of the display. -/// -/// The passed [BrightnessGrid] gets consumed. -/// -/// Returns: a new [servicepoint::Command::CharBrightness] instance. -#[no_mangle] -pub unsafe extern "C" fn sp_command_brightness_grid( - x: usize, - y: usize, - grid: NonNull, -) -> NonNull { - let grid = unsafe { *Box::from_raw(grid.as_ptr()) }; - let result = servicepoint::BrightnessGridCommand { - origin: servicepoint::Origin::new(x, y), - grid, - } - .into(); - heap_move_nonnull(result) -} - -/// Show codepage 437 encoded text on the screen. -/// -/// The passed [Cp437Grid] gets consumed. -/// -/// Returns: a new [servicepoint::Cp437GridCommand] instance. -#[no_mangle] -pub unsafe extern "C" fn sp_command_cp437_grid( - x: usize, - y: usize, - grid: NonNull, -) -> NonNull { - let grid = *unsafe { Box::from_raw(grid.as_ptr()) }; - let result = servicepoint::Cp437GridCommand { - origin: servicepoint::Origin::new(x, y), - grid, - } - .into(); - heap_move_nonnull(result) -} - -/// Show UTF-8 encoded text on the screen. -/// -/// The passed [CharGrid] gets consumed. -/// -/// Returns: a new [servicepoint::CharGridCommand] instance. -#[no_mangle] -pub unsafe extern "C" fn sp_command_char_grid( - x: usize, - y: usize, - grid: NonNull, -) -> NonNull { - let grid = unsafe { *Box::from_raw(grid.as_ptr()) }; - let result = servicepoint::CharGridCommand { - origin: servicepoint::Origin::new(x, y), - grid, - } - .into(); - heap_move_nonnull(result) -} - /// Deallocates a [TypedCommand]. /// /// # Examples -- 2.47.0 From 32d39f8006623d5d0124a69e9b7b9e20fbcda1a0 Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Tue, 6 May 2025 21:25:36 +0200 Subject: [PATCH 05/12] misc mod and doc changes --- include/servicepoint.h | 28 +++++++++++++++++----------- src/bitmap.rs | 3 +-- src/bitvec.rs | 2 +- src/brightness_grid.rs | 8 ++++---- src/char_grid.rs | 2 +- src/commands/bitmap_command.rs | 4 ++++ src/commands/mod.rs | 6 ++++++ src/cp437_grid.rs | 2 +- src/lib.rs | 32 +++++++++++--------------------- src/packet.rs | 2 +- src/udp.rs | 16 ++++++++-------- 11 files changed, 55 insertions(+), 50 deletions(-) diff --git a/include/servicepoint.h b/include/servicepoint.h index 805d84b..02f4676 100644 --- a/include/servicepoint.h +++ b/include/servicepoint.h @@ -845,15 +845,15 @@ BrightnessGrid *sp_brightness_grid_load(size_t width, * * # Examples * ```C - * UdpConnection connection = sp_udp_open("127.0.0.1:2342"); + * UdpSocket *connection = sp_udp_open("127.0.0.1:2342"); * if (connection == NULL) * return 1; * - * BrightnessGrid grid = sp_brightness_grid_new(2, 2); + * BrightnessGrid *grid = sp_brightness_grid_new(2, 2); * sp_brightness_grid_set(grid, 0, 0, 0); * sp_brightness_grid_set(grid, 1, 1, 10); * - * TypedCommand command = sp_command_char_brightness(grid); + * TypedCommand *command = sp_command_char_brightness(grid); * sp_udp_free(connection); * ``` */ @@ -1013,6 +1013,12 @@ BitmapCommand */*notnull*/ sp_cmd_bitmap_clone(BitmapCommand */*notnull*/ comman void sp_cmd_bitmap_free(BitmapCommand */*notnull*/ command); +/** + * Move the provided [Bitmap] into a new [BitmapCommand], + * leaving other fields as their default values. + * + * Rust equivalent: [`>::from`] + */ BitmapCommand */*notnull*/ sp_cmd_bitmap_from_bitmap(Bitmap */*notnull*/ bitmap); /** @@ -1475,19 +1481,19 @@ bool sp_u16_to_command_code(uint16_t code, CommandCode *result); /** - * Closes and deallocates a [UdpConnection]. + * Closes and deallocates a [UdpSocket]. */ void sp_udp_free(UdpSocket */*notnull*/ connection); /** - * Creates a new instance of [UdpConnection]. + * Creates a new instance of [UdpSocket]. * * returns: NULL if connection fails, or connected instance * * # Examples * * ```C - * UdpConnection connection = sp_udp_open("172.23.42.29:2342"); + * UdpSocket connection = sp_udp_open("172.23.42.29:2342"); * if (connection != NULL) * sp_udp_send_command(connection, sp_command_clear()); * ``` @@ -1495,14 +1501,14 @@ void sp_udp_free(UdpSocket */*notnull*/ connection); UdpSocket *sp_udp_open(char */*notnull*/ host); /** - * Creates a new instance of [UdpConnection]. + * Creates a new instance of [UdpSocket]. * * returns: NULL if connection fails, or connected instance * * # Examples * * ```C - * UdpConnection connection = sp_udp_open_ipv4(172, 23, 42, 29, 2342); + * UdpSocket connection = sp_udp_open_ipv4(172, 23, 42, 29, 2342); * if (connection != NULL) * sp_udp_send_command(connection, sp_command_clear()); * ``` @@ -1514,7 +1520,7 @@ UdpSocket *sp_udp_open_ipv4(uint8_t ip1, uint16_t port); /** - * Sends a [TypedCommand] to the display using the [UdpConnection]. + * Sends a [TypedCommand] to the display using the [UdpSocket]. * * The passed `command` gets consumed. * @@ -1530,7 +1536,7 @@ bool sp_udp_send_command(UdpSocket */*notnull*/ connection, TypedCommand */*notnull*/ command); /** - * Sends a [Header] to the display using the [UdpConnection]. + * Sends a [Header] to the display using the [UdpSocket]. * * returns: true in case of success * @@ -1543,7 +1549,7 @@ bool sp_udp_send_command(UdpSocket */*notnull*/ connection, bool sp_udp_send_header(UdpSocket */*notnull*/ udp_connection, Header header); /** - * Sends a [Packet] to the display using the [UdpConnection]. + * Sends a [Packet] to the display using the [UdpSocket]. * * The passed `packet` gets consumed. * diff --git a/src/bitmap.rs b/src/bitmap.rs index b8b482f..9e7f4bd 100644 --- a/src/bitmap.rs +++ b/src/bitmap.rs @@ -1,7 +1,6 @@ -use crate::byte_slice::ByteSlice; use crate::{ heap_drop, heap_move_nonnull, heap_move_ok, heap_move_some, heap_remove, - SPBitVec, + byte_slice::ByteSlice, bitvec::SPBitVec, }; use servicepoint::{ Bitmap, BitmapCommand, CompressionCode, DataRef, Grid, Origin, Packet, diff --git a/src/bitvec.rs b/src/bitvec.rs index b988df6..b7743aa 100644 --- a/src/bitvec.rs +++ b/src/bitvec.rs @@ -1,5 +1,5 @@ use crate::{ - heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, ByteSlice, + heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, byte_slice::ByteSlice, }; use servicepoint::{ BinaryOperation, BitVecCommand, CompressionCode, DisplayBitVec, Packet, diff --git a/src/brightness_grid.rs b/src/brightness_grid.rs index 2dd985a..496c53f 100644 --- a/src/brightness_grid.rs +++ b/src/brightness_grid.rs @@ -1,6 +1,6 @@ use crate::{ heap_drop, heap_move_nonnull, heap_move_ok, heap_move_some, heap_remove, - ByteSlice, + byte_slice::ByteSlice, }; use servicepoint::{ Brightness, BrightnessGrid, BrightnessGridCommand, ByteGrid, DataRef, Grid, @@ -15,15 +15,15 @@ use std::ptr::NonNull; /// /// # Examples /// ```C -/// UdpConnection connection = sp_udp_open("127.0.0.1:2342"); +/// UdpSocket *connection = sp_udp_open("127.0.0.1:2342"); /// if (connection == NULL) /// return 1; /// -/// BrightnessGrid grid = sp_brightness_grid_new(2, 2); +/// BrightnessGrid *grid = sp_brightness_grid_new(2, 2); /// sp_brightness_grid_set(grid, 0, 0, 0); /// sp_brightness_grid_set(grid, 1, 1, 10); /// -/// TypedCommand command = sp_command_char_brightness(grid); +/// TypedCommand *command = sp_command_char_brightness(grid); /// sp_udp_free(connection); /// ``` #[no_mangle] diff --git a/src/char_grid.rs b/src/char_grid.rs index e07e8db..42502a7 100644 --- a/src/char_grid.rs +++ b/src/char_grid.rs @@ -1,5 +1,5 @@ use crate::{ - heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, ByteSlice, + heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, byte_slice::ByteSlice, }; use servicepoint::{CharGrid, CharGridCommand, Grid, Origin, Packet}; use std::ptr::NonNull; diff --git a/src/commands/bitmap_command.rs b/src/commands/bitmap_command.rs index 4413a3c..a45a155 100644 --- a/src/commands/bitmap_command.rs +++ b/src/commands/bitmap_command.rs @@ -23,6 +23,10 @@ pub unsafe extern "C" fn sp_cmd_bitmap_new( }) } +/// Move the provided [Bitmap] into a new [BitmapCommand], +/// leaving other fields as their default values. +/// +/// Rust equivalent: [`>::from`] #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitmap_from_bitmap( bitmap: NonNull, diff --git a/src/commands/mod.rs b/src/commands/mod.rs index 90422ff..e4b1d4a 100644 --- a/src/commands/mod.rs +++ b/src/commands/mod.rs @@ -3,3 +3,9 @@ mod bitvec_command; mod brightness_grid_command; mod char_grid_command; mod cp437_grid_command; + +pub use bitmap_command::*; +pub use bitvec_command::*; +pub use brightness_grid_command::*; +pub use char_grid_command::*; +pub use cp437_grid_command::*; diff --git a/src/cp437_grid.rs b/src/cp437_grid.rs index 5a3daab..c39118e 100644 --- a/src/cp437_grid.rs +++ b/src/cp437_grid.rs @@ -1,6 +1,6 @@ use crate::{ heap_drop, heap_move_nonnull, heap_move_ok, heap_move_some, heap_remove, - ByteSlice, + byte_slice::ByteSlice, }; use servicepoint::{ Cp437Grid, Cp437GridCommand, DataRef, Grid, Origin, Packet, diff --git a/src/lib.rs b/src/lib.rs index 924a729..c98318a 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -9,7 +9,7 @@ //! #include "servicepoint.h" //! //! int main(void) { -//! UdpConnection *connection = sp_udp_open("172.23.42.29:2342"); +//! UdpSocket *connection = sp_udp_open("172.23.42.29:2342"); //! if (connection == NULL) //! return 1; //! @@ -25,28 +25,18 @@ //! } //! ``` -pub use crate::bitmap::*; -pub use crate::bitvec::*; -pub use crate::brightness_grid::*; -pub use crate::byte_slice::*; -pub use crate::char_grid::*; -pub use crate::cp437_grid::*; -pub use crate::packet::*; -pub use crate::typed_command::*; -pub use crate::udp::*; -pub use servicepoint::CommandCode; use std::ptr::NonNull; -mod bitmap; -mod bitvec; -mod brightness_grid; -mod byte_slice; -mod char_grid; -mod commands; -mod cp437_grid; -mod packet; -mod typed_command; -mod udp; +pub mod bitmap; +pub mod bitvec; +pub mod brightness_grid; +pub mod byte_slice; +pub mod char_grid; +pub mod commands; +pub mod cp437_grid; +pub mod packet; +pub mod typed_command; +pub mod udp; use std::time::Duration; diff --git a/src/packet.rs b/src/packet.rs index a454732..ea41597 100644 --- a/src/packet.rs +++ b/src/packet.rs @@ -1,5 +1,5 @@ use crate::{ - heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, ByteSlice, + heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, byte_slice::ByteSlice, }; use servicepoint::{CommandCode, Header, Packet, TypedCommand}; use std::ptr::NonNull; diff --git a/src/udp.rs b/src/udp.rs index bc8acc3..b75f13d 100644 --- a/src/udp.rs +++ b/src/udp.rs @@ -4,14 +4,14 @@ use std::ffi::{c_char, CStr}; use std::net::{Ipv4Addr, SocketAddrV4, UdpSocket}; use std::ptr::NonNull; -/// Creates a new instance of [UdpConnection]. +/// Creates a new instance of [UdpSocket]. /// /// returns: NULL if connection fails, or connected instance /// /// # Examples /// /// ```C -/// UdpConnection connection = sp_udp_open("172.23.42.29:2342"); +/// UdpSocket connection = sp_udp_open("172.23.42.29:2342"); /// if (connection != NULL) /// sp_udp_send_command(connection, sp_command_clear()); /// ``` @@ -24,14 +24,14 @@ pub unsafe extern "C" fn sp_udp_open(host: NonNull) -> *mut UdpSocket { heap_move_ok(UdpSocket::bind_connect(host)) } -/// Creates a new instance of [UdpConnection]. +/// Creates a new instance of [UdpSocket]. /// /// returns: NULL if connection fails, or connected instance /// /// # Examples /// /// ```C -/// UdpConnection connection = sp_udp_open_ipv4(172, 23, 42, 29, 2342); +/// UdpSocket connection = sp_udp_open_ipv4(172, 23, 42, 29, 2342); /// if (connection != NULL) /// sp_udp_send_command(connection, sp_command_clear()); /// ``` @@ -47,7 +47,7 @@ pub unsafe extern "C" fn sp_udp_open_ipv4( heap_move_ok(UdpSocket::bind_connect(addr)) } -/// Sends a [Packet] to the display using the [UdpConnection]. +/// Sends a [Packet] to the display using the [UdpSocket]. /// /// The passed `packet` gets consumed. /// @@ -61,7 +61,7 @@ pub unsafe extern "C" fn sp_udp_send_packet( unsafe { connection.as_ref().send(&Vec::from(packet)) }.is_ok() } -/// Sends a [TypedCommand] to the display using the [UdpConnection]. +/// Sends a [TypedCommand] to the display using the [UdpSocket]. /// /// The passed `command` gets consumed. /// @@ -81,7 +81,7 @@ pub unsafe extern "C" fn sp_udp_send_command( unsafe { connection.as_ref().send_command(command) }.is_some() } -/// Sends a [Header] to the display using the [UdpConnection]. +/// Sends a [Header] to the display using the [UdpSocket]. /// /// returns: true in case of success /// @@ -104,7 +104,7 @@ pub unsafe extern "C" fn sp_udp_send_header( .is_ok() } -/// Closes and deallocates a [UdpConnection]. +/// Closes and deallocates a [UdpSocket]. #[no_mangle] pub unsafe extern "C" fn sp_udp_free(connection: NonNull) { unsafe { heap_drop(connection) } -- 2.47.0 From 85ccf4123c36918c93aa7d4bffb85826027c858e Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Tue, 6 May 2025 22:54:54 +0200 Subject: [PATCH 06/12] expose tagged union instead of TypedCommand to C --- cbindgen.toml | 1 + include/servicepoint.h | 280 +++++++++++++-------- src/bitmap.rs | 6 +- src/bitvec.rs | 5 +- src/brightness_grid.rs | 8 +- src/char_grid.rs | 7 +- src/commands/bitmap_command.rs | 15 +- src/commands/bitvec_command.rs | 15 +- src/commands/brightness_grid_command.rs | 14 +- src/commands/cc_only_commands.rs | 54 +++++ src/commands/char_grid_command.rs | 15 +- src/commands/cp437_grid_command.rs | 15 +- src/commands/generic_command.rs | 281 ++++++++++++++++++++++ src/commands/global_brightness_command.rs | 53 ++++ src/commands/mod.rs | 4 + src/cp437_grid.rs | 8 +- src/lib.rs | 5 +- src/packet.rs | 19 +- src/typed_command.rs | 86 ------- src/udp.rs | 43 +++- 20 files changed, 657 insertions(+), 277 deletions(-) create mode 100644 src/commands/cc_only_commands.rs create mode 100644 src/commands/generic_command.rs create mode 100644 src/commands/global_brightness_command.rs delete mode 100644 src/typed_command.rs diff --git a/cbindgen.toml b/cbindgen.toml index 68723da..eca3164 100644 --- a/cbindgen.toml +++ b/cbindgen.toml @@ -37,6 +37,7 @@ exclude = ["BitVec"] [export.rename] "SpBitVec" = "BitVec" "SpByteSlice" = "ByteSlice" +"SpCommand" = "Command" [enum] rename_variants = "QualifiedScreamingSnakeCase" diff --git a/include/servicepoint.h b/include/servicepoint.h index 02f4676..404e291 100644 --- a/include/servicepoint.h +++ b/include/servicepoint.h @@ -125,6 +125,27 @@ enum CommandCode typedef uint16_t CommandCode; #endif // __cplusplus +enum CommandTag +#ifdef __cplusplus + : uint8_t +#endif // __cplusplus + { + COMMAND_TAG_INVALID = 0, + COMMAND_TAG_BITMAP, + COMMAND_TAG_BIT_VEC, + COMMAND_TAG_BRIGHTNESS_GRID, + COMMAND_TAG_CHAR_GRID, + COMMAND_TAG_CP437_GRID, + COMMAND_TAG_GLOBAL_BRIGHTNESS, + COMMAND_TAG_CLEAR, + COMMAND_TAG_HARD_RESET, + COMMAND_TAG_FADE_OUT, + COMMAND_TAG_BITMAP_LEGACY, +}; +#ifndef __cplusplus +typedef uint8_t CommandTag; +#endif // __cplusplus + /** * Specifies the kind of compression to use. Availability depends on features. * @@ -239,6 +260,23 @@ typedef struct Bitmap Bitmap; */ typedef struct BitmapCommand BitmapCommand; +/** + * Legacy command code, gets ignored by the real display. + * + * Might be useful as a noop package. + * + * # Examples + * + * ```rust + * # use servicepoint::*; + * # let connection = FakeConnection; + * // this sends a packet that does nothing + * # #[allow(deprecated)] + * connection.send_command(BitmapLegacyCommand).unwrap(); + * ``` + */ +typedef struct BitmapLegacyCommand BitmapLegacyCommand; + /** * Set the brightness of individual tiles in a rectangular area of the display. */ @@ -260,6 +298,19 @@ typedef struct BrightnessGridCommand BrightnessGridCommand; */ typedef struct CharGridCommand CharGridCommand; +/** + * Set all pixels to the off state. Does not affect brightness. + * + * # Examples + * + * ```rust + * # use servicepoint::*; + * # let connection = FakeConnection; + * connection.send_command(ClearCommand).unwrap(); + * ``` + */ +typedef struct ClearCommand ClearCommand; + /** * Show text on the screen. * @@ -292,6 +343,50 @@ typedef struct Cp437GridCommand Cp437GridCommand; */ typedef struct DisplayBitVec DisplayBitVec; +/** + *
Untested
+ * + * Slowly decrease brightness until off or something like that? + * + * # Examples + * + * ```rust + * # use servicepoint::*; + * # let connection = FakeConnection; + * connection.send_command(FadeOutCommand).unwrap(); + * ``` + */ +typedef struct FadeOutCommand FadeOutCommand; + +/** + * Set the brightness of all tiles to the same value. + * + * # Examples + * + * ```rust + * # use servicepoint::*; + * # let connection = FakeConnection; + * let command = GlobalBrightnessCommand { brightness: Brightness::MAX }; + * connection.send_command(command).unwrap(); + * ``` + */ +typedef struct GlobalBrightnessCommand GlobalBrightnessCommand; + +/** + * Kills the udp daemon on the display, which usually results in a restart. + * + * Please do not send this in your normal program flow. + * + * # Examples + * + * ```rust + * # use servicepoint::*; + * # let connection = FakeConnection; + * connection.send_command(HardResetCommand).unwrap(); + * ``` + */ +typedef struct HardResetCommand HardResetCommand; + /** * The raw packet. * @@ -313,14 +408,6 @@ typedef struct Packet Packet; */ typedef struct SPBitVec SPBitVec; -/** - * This enum contains all commands provided by the library. - * This is useful in case you want one data type for all kinds of commands without using `dyn`. - * - * Please look at the contained structs for documentation per command. - */ -typedef struct TypedCommand TypedCommand; - /** * This is a type only used by cbindgen to have a type for pointers. */ @@ -456,6 +543,31 @@ typedef size_t Offset; */ typedef ValueGrid_u8 Cp437Grid; +typedef union { + uint8_t *null; + BitmapCommand */*notnull*/ bitmap; + BitVecCommand */*notnull*/ bitvec; + BrightnessGridCommand */*notnull*/ brightness_grid; + CharGridCommand */*notnull*/ char_grid; + Cp437GridCommand */*notnull*/ cp437_grid; + GlobalBrightnessCommand */*notnull*/ global_brightness; + ClearCommand */*notnull*/ clear; + BitmapLegacyCommand */*notnull*/ bitmap_legacy; + HardResetCommand */*notnull*/ hard_reset; + FadeOutCommand */*notnull*/ fade_out; +} CommandUnion; + +typedef struct { + /** + * Specifies which kind of command struct is contained in `data` + */ + CommandTag tag; + /** + * The pointer to the command struct + */ + CommandUnion data; +} SPCommand; + /** * A raw header. * @@ -770,7 +882,7 @@ ByteSlice sp_bitvec_unsafe_data_ref(SPBitVec */*notnull*/ bit_vec); /** * Clones a [BrightnessGrid]. */ -BrightnessGrid */*notnull*/ sp_brightness_grid_clone(BrightnessGrid */*notnull*/ brightness_grid); +BrightnessGrid */*notnull*/ sp_brightness_grid_clone(BrightnessGrid */*notnull*/ grid); /** * Sets the value of all cells in the [BrightnessGrid]. @@ -906,7 +1018,7 @@ size_t sp_brightness_grid_width(BrightnessGrid */*notnull*/ brightness_grid); /** * Clones a [CharGrid]. */ -CharGrid */*notnull*/ sp_char_grid_clone(CharGrid */*notnull*/ char_grid); +CharGrid */*notnull*/ sp_char_grid_clone(CharGrid */*notnull*/ grid); /** * Sets the value of all cells in the [CharGrid]. @@ -1039,8 +1151,6 @@ void sp_cmd_bitmap_get_origin(BitmapCommand */*notnull*/ command, Packet *sp_cmd_bitmap_into_packet(BitmapCommand */*notnull*/ command); -TypedCommand */*notnull*/ sp_cmd_bitmap_into_typed(BitmapCommand */*notnull*/ command); - /** * Sets a window of pixels to the specified values. * @@ -1080,8 +1190,6 @@ BinaryOperation sp_cmd_bitvec_get_operation(BitVecCommand */*notnull*/ command); Packet *sp_cmd_bitvec_into_packet(BitVecCommand */*notnull*/ command); -TypedCommand */*notnull*/ sp_cmd_bitvec_into_typed(BitVecCommand */*notnull*/ command); - /** * Set pixel data starting at the pixel offset on screen. * @@ -1116,6 +1224,22 @@ void sp_cmd_bitvec_set_offset(BitVecCommand */*notnull*/ command, void sp_cmd_bitvec_set_operation(BitVecCommand */*notnull*/ command, BinaryOperation operation); +GlobalBrightnessCommand */*notnull*/ sp_cmd_brightness_global_clone(GlobalBrightnessCommand */*notnull*/ command); + +void sp_cmd_brightness_global_free(BitmapCommand */*notnull*/ command); + +Brightness *sp_cmd_brightness_global_get(GlobalBrightnessCommand */*notnull*/ command); + +Packet *sp_cmd_brightness_global_into_packet(GlobalBrightnessCommand */*notnull*/ command); + +GlobalBrightnessCommand */*notnull*/ sp_cmd_brightness_global_new(Brightness brightness); + +/** + * Moves the provided bitmap to be contained in the command. + */ +void sp_cmd_brightness_global_set(GlobalBrightnessCommand */*notnull*/ command, + Brightness brightness); + BrightnessGridCommand */*notnull*/ sp_cmd_brightness_grid_clone(BrightnessGridCommand */*notnull*/ command); void sp_cmd_brightness_grid_free(BitmapCommand */*notnull*/ command); @@ -1130,8 +1254,6 @@ void sp_cmd_brightness_grid_get_origin(BrightnessGridCommand */*notnull*/ comman Packet *sp_cmd_brightness_grid_into_packet(BrightnessGridCommand */*notnull*/ command); -TypedCommand */*notnull*/ sp_cmd_brightness_grid_into_typed(BrightnessGridCommand */*notnull*/ command); - BrightnessGridCommand */*notnull*/ sp_cmd_brightness_grid_new(BrightnessGrid */*notnull*/ grid, size_t origin_x, size_t origin_y); @@ -1160,8 +1282,6 @@ void sp_cmd_char_grid_get_origin(CharGridCommand */*notnull*/ command, Packet *sp_cmd_char_grid_into_packet(CharGridCommand */*notnull*/ command); -TypedCommand */*notnull*/ sp_cmd_char_grid_into_typed(CharGridCommand */*notnull*/ command); - CharGridCommand */*notnull*/ sp_cmd_char_grid_new(CharGrid */*notnull*/ grid, size_t origin_x, size_t origin_y); @@ -1176,6 +1296,23 @@ void sp_cmd_char_grid_set_origin(CharGridCommand */*notnull*/ command, size_t origin_x, size_t origin_y); +void sp_cmd_clear_free(ClearCommand */*notnull*/ command); + +/** + * Set all pixels to the off state. + * + * Does not affect brightness. + * + * Returns: a new [ClearCommand] instance. + * + * # Examples + * + * ```C + * sp_udp_send_command(connection, sp_cmd_clear()); + * ``` + */ +ClearCommand */*notnull*/ sp_cmd_clear_new(void); + Cp437GridCommand */*notnull*/ sp_cmd_cp437_grid_clone(Cp437GridCommand */*notnull*/ command); void sp_cmd_cp437_grid_free(BitmapCommand */*notnull*/ command); @@ -1190,8 +1327,6 @@ void sp_cmd_cp437_grid_get_origin(Cp437GridCommand */*notnull*/ command, Packet *sp_cmd_cp437_grid_into_packet(Cp437GridCommand */*notnull*/ command); -TypedCommand */*notnull*/ sp_cmd_cp437_grid_into_typed(Cp437GridCommand */*notnull*/ command); - Cp437GridCommand */*notnull*/ sp_cmd_cp437_grid_new(Cp437Grid */*notnull*/ grid, size_t origin_x, size_t origin_y); @@ -1206,70 +1341,24 @@ void sp_cmd_cp437_grid_set_origin(Cp437GridCommand */*notnull*/ command, size_t origin_x, size_t origin_y); -/** - * Set the brightness of individual tiles in a rectangular area of the display. - * - * The passed [BrightnessGrid] gets consumed. - * - * Returns: a new [servicepoint::Command::CharBrightness] instance. - */ -TypedCommand */*notnull*/ sp_command_brightness_grid(size_t x, - size_t y, - BrightnessGrid */*notnull*/ grid); - -/** - * Show UTF-8 encoded text on the screen. - * - * The passed [CharGrid] gets consumed. - * - * Returns: a new [servicepoint::CharGridCommand] instance. - */ -TypedCommand */*notnull*/ sp_command_char_grid(size_t x, - size_t y, - CharGrid */*notnull*/ grid); - -/** - * Set all pixels to the off state. - * - * Does not affect brightness. - * - * Returns: a new [servicepoint::Command::Clear] instance. - * - * # Examples - * - * ```C - * sp_udp_send_command(connection, sp_command_clear()); - * ``` - */ -TypedCommand */*notnull*/ sp_command_clear(void); - -/** - * Clones a [TypedCommand] instance. - * - * returns: new [TypedCommand] instance. - */ -TypedCommand */*notnull*/ sp_command_clone(TypedCommand */*notnull*/ command); - -/** - * Show codepage 437 encoded text on the screen. - * - * The passed [Cp437Grid] gets consumed. - * - * Returns: a new [servicepoint::Cp437GridCommand] instance. - */ -TypedCommand */*notnull*/ sp_command_cp437_grid(size_t x, - size_t y, - Cp437Grid */*notnull*/ grid); +void sp_cmd_fade_out_free(ClearCommand */*notnull*/ command); /** * A yet-to-be-tested command. * - * Returns: a new [servicepoint::Command::FadeOut] instance. + * Returns: a new [FadeOutCommand] instance. */ -TypedCommand */*notnull*/ sp_command_fade_out(void); +FadeOutCommand */*notnull*/ sp_cmd_fade_out_new(void); /** - * Deallocates a [TypedCommand]. + * Clones a [SPCommand] instance. + * + * returns: new [SPCommand] instance. + */ +SPCommand sp_cmd_generic_clone(SPCommand command); + +/** + * Deallocates a [SPCommand]. * * # Examples * @@ -1278,37 +1367,31 @@ TypedCommand */*notnull*/ sp_command_fade_out(void); * sp_command_free(c); * ``` */ -void sp_command_free(TypedCommand */*notnull*/ command); +void sp_cmd_generic_free(SPCommand command); /** - * Set the brightness of all tiles to the same value. + * Turns a [TypedCommand] into a [Packet]. + * The [TypedCommand] gets consumed. * - * Returns: a new [servicepoint::Command::Brightness] instance. + * Returns NULL in case of an error. */ -TypedCommand */*notnull*/ sp_command_global_brightness(Brightness brightness); +Packet *sp_cmd_generic_into_packet(SPCommand command); + +void sp_cmd_hard_reset_free(ClearCommand */*notnull*/ command); /** * 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 [servicepoint::Command::HardReset] instance. + * Returns: a new [HardResetCommand] instance. */ -TypedCommand */*notnull*/ sp_command_hard_reset(void); - -/** - * Tries to turn a [Packet] into a [TypedCommand]. - * - * The packet is deallocated in the process. - * - * Returns: pointer to new [TypedCommand] instance or NULL if parsing failed. - */ -TypedCommand *sp_command_try_from_packet(Packet */*notnull*/ packet); +HardResetCommand */*notnull*/ sp_cmd_hard_reset_new(void); /** * Clones a [Cp437Grid]. */ -Cp437Grid */*notnull*/ sp_cp437_grid_clone(Cp437Grid */*notnull*/ cp437_grid); +Cp437Grid */*notnull*/ sp_cp437_grid_clone(Cp437Grid */*notnull*/ grid); /** * Sets the value of all cells in the [Cp437Grid]. @@ -1419,14 +1502,6 @@ Packet */*notnull*/ sp_packet_clone(Packet */*notnull*/ packet); */ void sp_packet_free(Packet */*notnull*/ packet); -/** - * Turns a [TypedCommand] into a [Packet]. - * The [TypedCommand] gets consumed. - * - * Returns NULL in case of an error. - */ -Packet *sp_packet_from_command(TypedCommand */*notnull*/ command); - /** * Creates a raw [Packet] from parts. * @@ -1532,8 +1607,7 @@ UdpSocket *sp_udp_open_ipv4(uint8_t ip1, * sp_udp_send_command(connection, sp_command_brightness(5)); * ``` */ -bool sp_udp_send_command(UdpSocket */*notnull*/ connection, - TypedCommand */*notnull*/ command); +bool sp_udp_send_command(UdpSocket */*notnull*/ connection, SPCommand command); /** * Sends a [Header] to the display using the [UdpSocket]. diff --git a/src/bitmap.rs b/src/bitmap.rs index 9e7f4bd..8341c59 100644 --- a/src/bitmap.rs +++ b/src/bitmap.rs @@ -1,6 +1,6 @@ use crate::{ - heap_drop, heap_move_nonnull, heap_move_ok, heap_move_some, heap_remove, - byte_slice::ByteSlice, bitvec::SPBitVec, + bitvec::SPBitVec, byte_slice::ByteSlice, heap_clone, heap_drop, + heap_move_nonnull, heap_move_ok, heap_move_some, heap_remove, }; use servicepoint::{ Bitmap, BitmapCommand, CompressionCode, DataRef, Grid, Origin, Packet, @@ -83,7 +83,7 @@ pub unsafe extern "C" fn sp_bitmap_from_bitvec( pub unsafe extern "C" fn sp_bitmap_clone( bitmap: NonNull, ) -> NonNull { - heap_move_nonnull(unsafe { bitmap.as_ref().clone() }) + unsafe { heap_clone(bitmap) } } /// Deallocates a [Bitmap]. diff --git a/src/bitvec.rs b/src/bitvec.rs index b7743aa..3fa7412 100644 --- a/src/bitvec.rs +++ b/src/bitvec.rs @@ -1,5 +1,6 @@ use crate::{ - heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, byte_slice::ByteSlice, + byte_slice::ByteSlice, heap_clone, heap_drop, heap_move_nonnull, + heap_move_ok, heap_remove, }; use servicepoint::{ BinaryOperation, BitVecCommand, CompressionCode, DisplayBitVec, Packet, @@ -52,7 +53,7 @@ pub unsafe extern "C" fn sp_bitvec_load(data: ByteSlice) -> NonNull { pub unsafe extern "C" fn sp_bitvec_clone( bit_vec: NonNull, ) -> NonNull { - heap_move_nonnull(unsafe { bit_vec.as_ref().clone() }) + unsafe { heap_clone(bit_vec) } } /// Deallocates a [SPBitVec]. diff --git a/src/brightness_grid.rs b/src/brightness_grid.rs index 496c53f..dc3b2f7 100644 --- a/src/brightness_grid.rs +++ b/src/brightness_grid.rs @@ -1,6 +1,6 @@ use crate::{ - heap_drop, heap_move_nonnull, heap_move_ok, heap_move_some, heap_remove, - byte_slice::ByteSlice, + byte_slice::ByteSlice, heap_clone, heap_drop, heap_move_nonnull, + heap_move_ok, heap_move_some, heap_remove, }; use servicepoint::{ Brightness, BrightnessGrid, BrightnessGridCommand, ByteGrid, DataRef, Grid, @@ -55,9 +55,9 @@ pub unsafe extern "C" fn sp_brightness_grid_load( /// Clones a [BrightnessGrid]. #[no_mangle] pub unsafe extern "C" fn sp_brightness_grid_clone( - brightness_grid: NonNull, + grid: NonNull, ) -> NonNull { - heap_move_nonnull(unsafe { brightness_grid.as_ref().clone() }) + unsafe { heap_clone(grid) } } /// Deallocates a [BrightnessGrid]. diff --git a/src/char_grid.rs b/src/char_grid.rs index 42502a7..62aba87 100644 --- a/src/char_grid.rs +++ b/src/char_grid.rs @@ -1,5 +1,6 @@ use crate::{ - heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, byte_slice::ByteSlice, + byte_slice::ByteSlice, heap_clone, heap_drop, heap_move_nonnull, + heap_move_ok, heap_remove, }; use servicepoint::{CharGrid, CharGridCommand, Grid, Origin, Packet}; use std::ptr::NonNull; @@ -40,9 +41,9 @@ pub unsafe extern "C" fn sp_char_grid_load( /// Clones a [CharGrid]. #[no_mangle] pub unsafe extern "C" fn sp_char_grid_clone( - char_grid: NonNull, + grid: NonNull, ) -> NonNull { - heap_move_nonnull(unsafe { char_grid.as_ref().clone() }) + unsafe { heap_clone(grid) } } /// Deallocates a [CharGrid]. diff --git a/src/commands/bitmap_command.rs b/src/commands/bitmap_command.rs index a45a155..b2ff3d8 100644 --- a/src/commands/bitmap_command.rs +++ b/src/commands/bitmap_command.rs @@ -1,7 +1,7 @@ -use crate::{heap_drop, heap_move_nonnull, heap_move_ok, heap_remove}; -use servicepoint::{ - Bitmap, BitmapCommand, CompressionCode, Origin, Packet, TypedCommand, +use crate::{ + heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, }; +use servicepoint::{Bitmap, BitmapCommand, CompressionCode, Origin, Packet}; use std::ptr::NonNull; /// Sets a window of pixels to the specified values. @@ -34,13 +34,6 @@ pub unsafe extern "C" fn sp_cmd_bitmap_from_bitmap( heap_move_nonnull(unsafe { heap_remove(bitmap) }.into()) } -#[no_mangle] -pub unsafe extern "C" fn sp_cmd_bitmap_into_typed( - command: NonNull, -) -> NonNull { - heap_move_nonnull(unsafe { heap_remove(command) }.into()) -} - #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitmap_into_packet( command: NonNull, @@ -52,7 +45,7 @@ pub unsafe extern "C" fn sp_cmd_bitmap_into_packet( pub unsafe extern "C" fn sp_cmd_bitmap_clone( command: NonNull, ) -> NonNull { - heap_move_nonnull(unsafe { command.as_ref().clone() }) + unsafe { heap_clone(command) } } #[no_mangle] diff --git a/src/commands/bitvec_command.rs b/src/commands/bitvec_command.rs index 5795017..bfe2d33 100644 --- a/src/commands/bitvec_command.rs +++ b/src/commands/bitvec_command.rs @@ -1,7 +1,9 @@ -use crate::{heap_drop, heap_move_nonnull, heap_move_ok, heap_remove}; +use crate::{ + heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, +}; use servicepoint::{ BinaryOperation, BitVecCommand, CompressionCode, DisplayBitVec, Offset, - Packet, TypedCommand, + Packet, }; use std::ptr::NonNull; @@ -32,13 +34,6 @@ pub unsafe extern "C" fn sp_cmd_bitvec_new( }) } -#[no_mangle] -pub unsafe extern "C" fn sp_cmd_bitvec_into_typed( - command: NonNull, -) -> NonNull { - heap_move_nonnull(unsafe { heap_remove(command) }.into()) -} - #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitvec_into_packet( command: NonNull, @@ -50,7 +45,7 @@ pub unsafe extern "C" fn sp_cmd_bitvec_into_packet( pub unsafe extern "C" fn sp_cmd_bitvec_clone( command: NonNull, ) -> NonNull { - heap_move_nonnull(unsafe { command.as_ref().clone() }) + unsafe { heap_clone(command) } } #[no_mangle] diff --git a/src/commands/brightness_grid_command.rs b/src/commands/brightness_grid_command.rs index 18a2836..bd975d6 100644 --- a/src/commands/brightness_grid_command.rs +++ b/src/commands/brightness_grid_command.rs @@ -1,7 +1,8 @@ -use crate::{heap_drop, heap_move_nonnull, heap_move_ok, heap_remove}; +use crate::{ + heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, +}; use servicepoint::{ BitmapCommand, BrightnessGrid, BrightnessGridCommand, Origin, Packet, - TypedCommand, }; use std::ptr::NonNull; @@ -24,13 +25,6 @@ pub unsafe extern "C" fn sp_cmd_brightness_grid_from_grid( heap_move_nonnull(unsafe { heap_remove(grid) }.into()) } -#[no_mangle] -pub unsafe extern "C" fn sp_cmd_brightness_grid_into_typed( - command: NonNull, -) -> NonNull { - heap_move_nonnull(unsafe { heap_remove(command) }.into()) -} - #[no_mangle] pub unsafe extern "C" fn sp_cmd_brightness_grid_into_packet( command: NonNull, @@ -42,7 +36,7 @@ pub unsafe extern "C" fn sp_cmd_brightness_grid_into_packet( pub unsafe extern "C" fn sp_cmd_brightness_grid_clone( command: NonNull, ) -> NonNull { - heap_move_nonnull(unsafe { command.as_ref().clone() }) + unsafe { heap_clone(command) } } #[no_mangle] diff --git a/src/commands/cc_only_commands.rs b/src/commands/cc_only_commands.rs new file mode 100644 index 0000000..751a6ab --- /dev/null +++ b/src/commands/cc_only_commands.rs @@ -0,0 +1,54 @@ +use crate::{heap_drop, heap_move_nonnull}; +use servicepoint::{ClearCommand, FadeOutCommand, HardResetCommand}; +use std::ptr::NonNull; + +/// Set all pixels to the off state. +/// +/// Does not affect brightness. +/// +/// Returns: a new [ClearCommand] instance. +/// +/// # Examples +/// +/// ```C +/// sp_udp_send_command(connection, sp_cmd_clear()); +/// ``` +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_clear_new() -> NonNull { + heap_move_nonnull(ClearCommand) +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_clear_free(command: NonNull) { + unsafe { heap_drop(command) } +} + +/// 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 [HardResetCommand] instance. +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_hard_reset_new() -> NonNull { + heap_move_nonnull(HardResetCommand) +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_hard_reset_free( + command: NonNull, +) { + unsafe { heap_drop(command) } +} + +/// A yet-to-be-tested command. +/// +/// Returns: a new [FadeOutCommand] instance. +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_fade_out_new() -> NonNull { + heap_move_nonnull(FadeOutCommand) +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_fade_out_free(command: NonNull) { + unsafe { heap_drop(command) } +} diff --git a/src/commands/char_grid_command.rs b/src/commands/char_grid_command.rs index 933e4cd..bc078cd 100644 --- a/src/commands/char_grid_command.rs +++ b/src/commands/char_grid_command.rs @@ -1,7 +1,7 @@ -use crate::{heap_drop, heap_move_nonnull, heap_move_ok, heap_remove}; -use servicepoint::{ - BitmapCommand, CharGrid, CharGridCommand, Origin, Packet, TypedCommand, +use crate::{ + heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, }; +use servicepoint::{BitmapCommand, CharGrid, CharGridCommand, Origin, Packet}; use std::ptr::NonNull; #[no_mangle] @@ -23,13 +23,6 @@ pub unsafe extern "C" fn sp_cmd_char_grid_from_grid( heap_move_nonnull(unsafe { heap_remove(grid) }.into()) } -#[no_mangle] -pub unsafe extern "C" fn sp_cmd_char_grid_into_typed( - command: NonNull, -) -> NonNull { - heap_move_nonnull(unsafe { heap_remove(command) }.into()) -} - #[no_mangle] pub unsafe extern "C" fn sp_cmd_char_grid_into_packet( command: NonNull, @@ -41,7 +34,7 @@ pub unsafe extern "C" fn sp_cmd_char_grid_into_packet( pub unsafe extern "C" fn sp_cmd_char_grid_clone( command: NonNull, ) -> NonNull { - heap_move_nonnull(unsafe { command.as_ref().clone() }) + unsafe { heap_clone(command) } } #[no_mangle] diff --git a/src/commands/cp437_grid_command.rs b/src/commands/cp437_grid_command.rs index 0f3d9e2..1e1598a 100644 --- a/src/commands/cp437_grid_command.rs +++ b/src/commands/cp437_grid_command.rs @@ -1,6 +1,8 @@ -use crate::{heap_drop, heap_move_nonnull, heap_move_ok, heap_remove}; +use crate::{ + heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, +}; use servicepoint::{ - BitmapCommand, Cp437Grid, Cp437GridCommand, Origin, Packet, TypedCommand, + BitmapCommand, Cp437Grid, Cp437GridCommand, Origin, Packet, }; use std::ptr::NonNull; @@ -23,13 +25,6 @@ pub unsafe extern "C" fn sp_cmd_cp437_grid_from_grid( heap_move_nonnull(unsafe { heap_remove(grid) }.into()) } -#[no_mangle] -pub unsafe extern "C" fn sp_cmd_cp437_grid_into_typed( - command: NonNull, -) -> NonNull { - heap_move_nonnull(unsafe { heap_remove(command) }.into()) -} - #[no_mangle] pub unsafe extern "C" fn sp_cmd_cp437_grid_into_packet( command: NonNull, @@ -41,7 +36,7 @@ pub unsafe extern "C" fn sp_cmd_cp437_grid_into_packet( pub unsafe extern "C" fn sp_cmd_cp437_grid_clone( command: NonNull, ) -> NonNull { - heap_move_nonnull(unsafe { command.as_ref().clone() }) + unsafe { heap_clone(command) } } #[no_mangle] diff --git a/src/commands/generic_command.rs b/src/commands/generic_command.rs new file mode 100644 index 0000000..5066022 --- /dev/null +++ b/src/commands/generic_command.rs @@ -0,0 +1,281 @@ +use crate::{ + heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, +}; +use servicepoint::{ + BitVecCommand, BitmapCommand, BitmapLegacyCommand, BrightnessGridCommand, + CharGridCommand, ClearCommand, Cp437GridCommand, FadeOutCommand, + GlobalBrightnessCommand, HardResetCommand, Packet, TypedCommand, +}; +use std::ptr::{null_mut, NonNull}; + +#[repr(C)] +pub union CommandUnion { + pub null: *mut u8, + pub bitmap: NonNull, + pub bitvec: NonNull, + pub brightness_grid: NonNull, + pub char_grid: NonNull, + pub cp437_grid: NonNull, + pub global_brightness: NonNull, + pub clear: NonNull, + #[allow(deprecated)] + pub bitmap_legacy: NonNull, + pub hard_reset: NonNull, + pub fade_out: NonNull, +} + +#[repr(u8)] +pub enum CommandTag { + Invalid = 0, + Bitmap, + BitVec, + BrightnessGrid, + CharGrid, + Cp437Grid, + GlobalBrightness, + Clear, + HardReset, + FadeOut, + BitmapLegacy, +} + +#[repr(C)] +pub struct SPCommand { + /// Specifies which kind of command struct is contained in `data` + pub tag: CommandTag, + /// The pointer to the command struct + pub data: CommandUnion, +} + +impl SPCommand { + const INVALID: SPCommand = SPCommand { + tag: CommandTag::Invalid, + data: CommandUnion { null: null_mut() }, + }; +} + +/// Tries to turn a [Packet] into a [TypedCommand]. +/// +/// The packet is deallocated in the process. +/// +/// Returns: pointer to new [TypedCommand] instance or NULL if parsing failed. +/// #[no_mangle] +pub unsafe extern "C" fn sp_cmd_generic_try_from_packet( + packet: NonNull, +) -> *mut SPCommand { + let packet = *unsafe { Box::from_raw(packet.as_ptr()) }; + heap_move_ok(servicepoint::TypedCommand::try_from(packet).map(|value| { + match value { + TypedCommand::Clear(clear) => SPCommand { + tag: CommandTag::Clear, + data: CommandUnion { + clear: heap_move_nonnull(clear), + }, + }, + TypedCommand::CharGrid(char_grid) => SPCommand { + tag: CommandTag::CharGrid, + data: CommandUnion { + char_grid: heap_move_nonnull(char_grid), + }, + }, + TypedCommand::Cp437Grid(cp437_grid) => SPCommand { + tag: CommandTag::Cp437Grid, + data: CommandUnion { + cp437_grid: heap_move_nonnull(cp437_grid), + }, + }, + TypedCommand::Bitmap(bitmap) => SPCommand { + tag: CommandTag::Bitmap, + data: CommandUnion { + bitmap: heap_move_nonnull(bitmap), + }, + }, + TypedCommand::Brightness(global_brightness) => SPCommand { + tag: CommandTag::GlobalBrightness, + data: CommandUnion { + global_brightness: heap_move_nonnull(global_brightness), + }, + }, + TypedCommand::BrightnessGrid(brightness_grid) => SPCommand { + tag: CommandTag::BrightnessGrid, + data: CommandUnion { + brightness_grid: heap_move_nonnull(brightness_grid), + }, + }, + TypedCommand::BitVec(bitvec) => SPCommand { + tag: CommandTag::BitVec, + data: CommandUnion { + bitvec: heap_move_nonnull(bitvec), + }, + }, + TypedCommand::HardReset(hard_reset) => SPCommand { + tag: CommandTag::HardReset, + data: CommandUnion { + hard_reset: heap_move_nonnull(hard_reset), + }, + }, + TypedCommand::FadeOut(fade_out) => SPCommand { + tag: CommandTag::FadeOut, + data: CommandUnion { + fade_out: heap_move_nonnull(fade_out), + }, + }, + #[allow(deprecated)] + TypedCommand::BitmapLegacy(bitmap_legacy) => SPCommand { + tag: CommandTag::BitmapLegacy, + data: CommandUnion { + bitmap_legacy: heap_move_nonnull(bitmap_legacy), + }, + }, + } + })) +} + +/// Clones a [SPCommand] instance. +/// +/// returns: new [SPCommand] instance. +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_generic_clone(command: SPCommand) -> SPCommand { + unsafe { + match command.tag { + CommandTag::Clear => SPCommand { + tag: CommandTag::Clear, + data: CommandUnion { + clear: heap_clone(command.data.clear), + }, + }, + CommandTag::CharGrid => SPCommand { + tag: CommandTag::CharGrid, + data: CommandUnion { + char_grid: heap_clone(command.data.char_grid), + }, + }, + CommandTag::Cp437Grid => SPCommand { + tag: CommandTag::Cp437Grid, + data: CommandUnion { + cp437_grid: heap_clone(command.data.cp437_grid), + }, + }, + CommandTag::Bitmap => SPCommand { + tag: CommandTag::Bitmap, + data: CommandUnion { + bitmap: heap_clone(command.data.bitmap), + }, + }, + CommandTag::GlobalBrightness => SPCommand { + tag: CommandTag::GlobalBrightness, + data: CommandUnion { + global_brightness: heap_clone( + command.data.global_brightness, + ), + }, + }, + CommandTag::BrightnessGrid => SPCommand { + tag: CommandTag::BrightnessGrid, + data: CommandUnion { + brightness_grid: heap_clone(command.data.brightness_grid), + }, + }, + CommandTag::BitVec => SPCommand { + tag: CommandTag::BitVec, + data: CommandUnion { + bitvec: heap_clone(command.data.bitvec), + }, + }, + CommandTag::HardReset => SPCommand { + tag: CommandTag::HardReset, + data: CommandUnion { + hard_reset: heap_clone(command.data.hard_reset), + }, + }, + CommandTag::FadeOut => SPCommand { + tag: CommandTag::FadeOut, + data: CommandUnion { + fade_out: heap_clone(command.data.fade_out), + }, + }, + #[allow(deprecated)] + CommandTag::BitmapLegacy => SPCommand { + tag: CommandTag::BitmapLegacy, + data: CommandUnion { + bitmap_legacy: heap_clone(command.data.bitmap_legacy), + }, + }, + CommandTag::Invalid => SPCommand::INVALID, + } + } +} + +/// Deallocates a [SPCommand]. +/// +/// # Examples +/// +/// ```C +/// TypedCommand c = sp_command_clear(); +/// sp_command_free(c); +/// ``` +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_generic_free(command: SPCommand) { + unsafe { + match command.tag { + CommandTag::Invalid => return, + CommandTag::Bitmap => heap_drop(command.data.bitmap), + CommandTag::BitVec => heap_drop(command.data.bitvec), + CommandTag::BrightnessGrid => { + heap_drop(command.data.brightness_grid) + } + CommandTag::CharGrid => heap_drop(command.data.char_grid), + CommandTag::Cp437Grid => heap_drop(command.data.cp437_grid), + CommandTag::GlobalBrightness => { + heap_drop(command.data.global_brightness) + } + CommandTag::Clear => heap_drop(command.data.clear), + CommandTag::HardReset => heap_drop(command.data.hard_reset), + CommandTag::FadeOut => heap_drop(command.data.fade_out), + CommandTag::BitmapLegacy => heap_drop(command.data.bitmap_legacy), + } + } +} + +/// Turns a [TypedCommand] into a [Packet]. +/// The [TypedCommand] gets consumed. +/// +/// Returns NULL in case of an error. +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_generic_into_packet( + command: SPCommand, +) -> *mut Packet { + match command.tag { + CommandTag::Invalid => null_mut(), + CommandTag::Bitmap => { + heap_move_ok(unsafe { heap_remove(command.data.bitmap).try_into() }) + } + CommandTag::BitVec => { + heap_move_ok(unsafe { heap_remove(command.data.bitvec).try_into() }) + } + CommandTag::BrightnessGrid => heap_move_ok(unsafe { + heap_remove(command.data.brightness_grid).try_into() + }), + CommandTag::CharGrid => heap_move_ok(unsafe { + heap_remove(command.data.char_grid).try_into() + }), + CommandTag::Cp437Grid => heap_move_ok(unsafe { + heap_remove(command.data.cp437_grid).try_into() + }), + CommandTag::GlobalBrightness => heap_move_ok(unsafe { + heap_remove(command.data.global_brightness).try_into() + }), + CommandTag::Clear => { + heap_move_ok(unsafe { heap_remove(command.data.clear).try_into() }) + } + CommandTag::HardReset => heap_move_ok(unsafe { + heap_remove(command.data.hard_reset).try_into() + }), + CommandTag::FadeOut => heap_move_ok(unsafe { + heap_remove(command.data.fade_out).try_into() + }), + CommandTag::BitmapLegacy => heap_move_ok(unsafe { + heap_remove(command.data.bitmap_legacy).try_into() + }), + } +} diff --git a/src/commands/global_brightness_command.rs b/src/commands/global_brightness_command.rs new file mode 100644 index 0000000..29e7c19 --- /dev/null +++ b/src/commands/global_brightness_command.rs @@ -0,0 +1,53 @@ +use crate::{ + heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, +}; +use servicepoint::{ + BitmapCommand, Brightness, GlobalBrightnessCommand, Packet, +}; +use std::ptr::NonNull; + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_brightness_global_new( + brightness: Brightness, +) -> NonNull { + heap_move_nonnull(GlobalBrightnessCommand::from(brightness)) +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_brightness_global_into_packet( + command: NonNull, +) -> *mut Packet { + heap_move_ok(unsafe { heap_remove(command) }.try_into()) +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_brightness_global_clone( + command: NonNull, +) -> NonNull { + unsafe { heap_clone(command) } +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_brightness_global_free( + command: NonNull, +) { + unsafe { heap_drop(command) } +} + +/// Moves the provided bitmap to be contained in the command. +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_brightness_global_set( + mut command: NonNull, + brightness: Brightness, +) { + unsafe { + command.as_mut().brightness = brightness; + } +} + +#[no_mangle] +pub unsafe extern "C" fn sp_cmd_brightness_global_get( + mut command: NonNull, +) -> *mut Brightness { + &mut unsafe { command.as_mut() }.brightness +} diff --git a/src/commands/mod.rs b/src/commands/mod.rs index e4b1d4a..3cbb99a 100644 --- a/src/commands/mod.rs +++ b/src/commands/mod.rs @@ -1,11 +1,15 @@ mod bitmap_command; mod bitvec_command; mod brightness_grid_command; +mod cc_only_commands; mod char_grid_command; mod cp437_grid_command; +mod generic_command; +mod global_brightness_command; pub use bitmap_command::*; pub use bitvec_command::*; pub use brightness_grid_command::*; pub use char_grid_command::*; pub use cp437_grid_command::*; +pub use generic_command::*; diff --git a/src/cp437_grid.rs b/src/cp437_grid.rs index c39118e..b4d449e 100644 --- a/src/cp437_grid.rs +++ b/src/cp437_grid.rs @@ -1,6 +1,6 @@ use crate::{ - heap_drop, heap_move_nonnull, heap_move_ok, heap_move_some, heap_remove, - byte_slice::ByteSlice, + byte_slice::ByteSlice, heap_clone, heap_drop, heap_move_nonnull, + heap_move_ok, heap_move_some, heap_remove, }; use servicepoint::{ Cp437Grid, Cp437GridCommand, DataRef, Grid, Origin, Packet, @@ -32,9 +32,9 @@ pub unsafe extern "C" fn sp_cp437_grid_load( /// Clones a [Cp437Grid]. #[no_mangle] pub unsafe extern "C" fn sp_cp437_grid_clone( - cp437_grid: NonNull, + grid: NonNull, ) -> NonNull { - heap_move_nonnull(unsafe { cp437_grid.as_ref().clone() }) + unsafe { heap_clone(grid) } } /// Deallocates a [Cp437Grid]. diff --git a/src/lib.rs b/src/lib.rs index c98318a..de22866 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -35,7 +35,6 @@ pub mod char_grid; pub mod commands; pub mod cp437_grid; pub mod packet; -pub mod typed_command; pub mod udp; use std::time::Duration; @@ -67,6 +66,10 @@ pub(crate) unsafe fn heap_remove(x: NonNull) -> T { unsafe { *Box::from_raw(x.as_ptr()) } } +unsafe fn heap_clone(source: NonNull) -> NonNull { + heap_move_nonnull(unsafe { source.as_ref().clone() }) +} + /// This is a type only used by cbindgen to have a type for pointers. pub struct UdpSocket; diff --git a/src/packet.rs b/src/packet.rs index ea41597..16509be 100644 --- a/src/packet.rs +++ b/src/packet.rs @@ -1,21 +1,10 @@ use crate::{ - heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, byte_slice::ByteSlice, + byte_slice::ByteSlice, heap_clone, heap_drop, heap_move_nonnull, + heap_move_ok, }; -use servicepoint::{CommandCode, Header, Packet, TypedCommand}; +use servicepoint::{CommandCode, Header, Packet}; use std::ptr::NonNull; -/// Turns a [TypedCommand] into a [Packet]. -/// The [TypedCommand] gets consumed. -/// -/// Returns NULL in case of an error. -#[no_mangle] -pub unsafe extern "C" fn sp_packet_from_command( - command: NonNull, -) -> *mut Packet { - let command = unsafe { heap_remove(command) }; - heap_move_ok(command.try_into()) -} - /// 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 @@ -94,7 +83,7 @@ pub unsafe extern "C" fn sp_packet_serialize_to( pub unsafe extern "C" fn sp_packet_clone( packet: NonNull, ) -> NonNull { - heap_move_nonnull(unsafe { packet.as_ref().clone() }) + unsafe { heap_clone(packet) } } /// Deallocates a [Packet]. diff --git a/src/typed_command.rs b/src/typed_command.rs deleted file mode 100644 index 26c33f1..0000000 --- a/src/typed_command.rs +++ /dev/null @@ -1,86 +0,0 @@ -use crate::{heap_drop, heap_move_nonnull, heap_move_ok}; -use servicepoint::{ - Brightness, GlobalBrightnessCommand, - Packet, TypedCommand, -}; -use std::ptr::NonNull; - -/// Tries to turn a [Packet] into a [TypedCommand]. -/// -/// The packet is deallocated in the process. -/// -/// Returns: pointer to new [TypedCommand] instance or NULL if parsing failed. -#[no_mangle] -pub unsafe extern "C" fn sp_command_try_from_packet( - packet: NonNull, -) -> *mut TypedCommand { - let packet = *unsafe { Box::from_raw(packet.as_ptr()) }; - heap_move_ok(servicepoint::TypedCommand::try_from(packet)) -} - -/// Clones a [TypedCommand] instance. -/// -/// returns: new [TypedCommand] instance. -#[no_mangle] -pub unsafe extern "C" fn sp_command_clone( - command: NonNull, -) -> NonNull { - heap_move_nonnull(unsafe { command.as_ref().clone() }) -} - -/// Set all pixels to the off state. -/// -/// Does not affect brightness. -/// -/// Returns: a new [servicepoint::Command::Clear] instance. -/// -/// # Examples -/// -/// ```C -/// sp_udp_send_command(connection, sp_command_clear()); -/// ``` -#[no_mangle] -pub unsafe extern "C" fn sp_command_clear() -> NonNull { - heap_move_nonnull(servicepoint::ClearCommand.into()) -} - -/// 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 [servicepoint::Command::HardReset] instance. -#[no_mangle] -pub unsafe extern "C" fn sp_command_hard_reset() -> NonNull { - heap_move_nonnull(servicepoint::HardResetCommand.into()) -} - -/// A yet-to-be-tested command. -/// -/// Returns: a new [servicepoint::Command::FadeOut] instance. -#[no_mangle] -pub unsafe extern "C" fn sp_command_fade_out() -> NonNull { - heap_move_nonnull(servicepoint::FadeOutCommand.into()) -} - -/// Set the brightness of all tiles to the same value. -/// -/// Returns: a new [servicepoint::Command::Brightness] instance. -#[no_mangle] -pub unsafe extern "C" fn sp_command_global_brightness( - brightness: Brightness, -) -> NonNull { - heap_move_nonnull(GlobalBrightnessCommand::from(brightness).into()) -} - -/// Deallocates a [TypedCommand]. -/// -/// # Examples -/// -/// ```C -/// TypedCommand c = sp_command_clear(); -/// sp_command_free(c); -/// ``` -#[no_mangle] -pub unsafe extern "C" fn sp_command_free(command: NonNull) { - unsafe { heap_drop(command) } -} diff --git a/src/udp.rs b/src/udp.rs index b75f13d..7b659cf 100644 --- a/src/udp.rs +++ b/src/udp.rs @@ -1,5 +1,6 @@ +use crate::commands::{CommandTag, SPCommand}; use crate::{heap_drop, heap_move_ok, heap_remove}; -use servicepoint::{Header, Packet, TypedCommand, UdpSocketExt}; +use servicepoint::{Header, Packet, UdpSocketExt}; use std::ffi::{c_char, CStr}; use std::net::{Ipv4Addr, SocketAddrV4, UdpSocket}; use std::ptr::NonNull; @@ -75,10 +76,44 @@ pub unsafe extern "C" fn sp_udp_send_packet( #[no_mangle] pub unsafe extern "C" fn sp_udp_send_command( connection: NonNull, - command: NonNull, + command: SPCommand, ) -> bool { - let command = unsafe { heap_remove(command) }; - unsafe { connection.as_ref().send_command(command) }.is_some() + unsafe { + match command.tag { + CommandTag::Invalid => return false, + CommandTag::Bitmap => connection + .as_ref() + .send_command(heap_remove(command.data.bitmap)), + CommandTag::BitVec => connection + .as_ref() + .send_command(heap_remove(command.data.bitvec)), + CommandTag::BrightnessGrid => connection + .as_ref() + .send_command(heap_remove(command.data.brightness_grid)), + CommandTag::CharGrid => connection + .as_ref() + .send_command(heap_remove(command.data.char_grid)), + CommandTag::Cp437Grid => connection + .as_ref() + .send_command(heap_remove(command.data.cp437_grid)), + CommandTag::GlobalBrightness => connection + .as_ref() + .send_command(heap_remove(command.data.global_brightness)), + CommandTag::Clear => connection + .as_ref() + .send_command(heap_remove(command.data.clear)), + CommandTag::HardReset => connection + .as_ref() + .send_command(heap_remove(command.data.hard_reset)), + CommandTag::FadeOut => connection + .as_ref() + .send_command(heap_remove(command.data.fade_out)), + CommandTag::BitmapLegacy => connection + .as_ref() + .send_command(heap_remove(command.data.bitmap_legacy)), + } + } + .is_some() } /// Sends a [Header] to the display using the [UdpSocket]. -- 2.47.0 From a4bacd53a2b5c6df7cb80d755044f252585461ea Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Tue, 6 May 2025 23:05:06 +0200 Subject: [PATCH 07/12] remove SPBitVec wrapper type --- cbindgen.toml | 1 - include/servicepoint.h | 40 ++++++++------------- src/bitmap.rs | 15 ++++---- src/bitvec.rs | 62 +++++++++++++-------------------- src/commands/generic_command.rs | 4 +-- 5 files changed, 48 insertions(+), 74 deletions(-) diff --git a/cbindgen.toml b/cbindgen.toml index eca3164..4aabb7e 100644 --- a/cbindgen.toml +++ b/cbindgen.toml @@ -35,7 +35,6 @@ include = [] exclude = ["BitVec"] [export.rename] -"SpBitVec" = "BitVec" "SpByteSlice" = "ByteSlice" "SpCommand" = "Command" diff --git a/include/servicepoint.h b/include/servicepoint.h index 404e291..ec722f5 100644 --- a/include/servicepoint.h +++ b/include/servicepoint.h @@ -396,18 +396,6 @@ typedef struct HardResetCommand HardResetCommand; */ typedef struct Packet Packet; -/** - * A vector of bits - * - * # Examples - * ```C - * SPBitVec vec = sp_bitvec_new(8); - * sp_bitvec_set(vec, 5, true); - * sp_bitvec_free(vec); - * ``` - */ -typedef struct SPBitVec SPBitVec; - /** * This is a type only used by cbindgen to have a type for pointers. */ @@ -634,7 +622,7 @@ void sp_bitmap_free(Bitmap */*notnull*/ bitmap); * * Returns NULL in case of error. */ -Bitmap *sp_bitmap_from_bitvec(size_t width, SPBitVec */*notnull*/ bitvec); +Bitmap *sp_bitmap_from_bitvec(size_t width, DisplayBitVec */*notnull*/ bitvec); /** * Gets the current value at the specified position in the [Bitmap]. @@ -662,7 +650,7 @@ size_t sp_bitmap_height(Bitmap */*notnull*/ bitmap); /** * Consumes the Bitmap and returns the contained BitVec */ -SPBitVec */*notnull*/ sp_bitmap_into_bitvec(Bitmap */*notnull*/ bitmap); +DisplayBitVec */*notnull*/ sp_bitmap_into_bitvec(Bitmap */*notnull*/ bitmap); /** * Creates a [BitmapCommand] and immediately turns that into a [Packet]. @@ -768,7 +756,7 @@ size_t sp_bitmap_width(Bitmap */*notnull*/ bitmap); /** * Clones a [SPBitVec]. */ -SPBitVec */*notnull*/ sp_bitvec_clone(SPBitVec */*notnull*/ bit_vec); +DisplayBitVec */*notnull*/ sp_bitvec_clone(DisplayBitVec */*notnull*/ bit_vec); /** * Sets the value of all bits in the [SPBitVec]. @@ -778,12 +766,12 @@ SPBitVec */*notnull*/ sp_bitvec_clone(SPBitVec */*notnull*/ bit_vec); * - `bit_vec`: instance to write to * - `value`: the value to set all bits to */ -void sp_bitvec_fill(SPBitVec */*notnull*/ bit_vec, bool value); +void sp_bitvec_fill(DisplayBitVec */*notnull*/ bit_vec, bool value); /** * Deallocates a [SPBitVec]. */ -void sp_bitvec_free(SPBitVec */*notnull*/ bit_vec); +void sp_bitvec_free(DisplayBitVec */*notnull*/ bit_vec); /** * Gets the value of a bit from the [SPBitVec]. @@ -799,7 +787,7 @@ void sp_bitvec_free(SPBitVec */*notnull*/ bit_vec); * * - when accessing `index` out of bounds */ -bool sp_bitvec_get(SPBitVec */*notnull*/ bit_vec, size_t index); +bool sp_bitvec_get(DisplayBitVec */*notnull*/ bit_vec, size_t index); /** * Creates a [BitVecCommand] and immediately turns that into a [Packet]. @@ -808,7 +796,7 @@ bool sp_bitvec_get(SPBitVec */*notnull*/ bit_vec, size_t index); * * Returns NULL in case of an error. */ -Packet *sp_bitvec_into_packet(SPBitVec */*notnull*/ bitvec, +Packet *sp_bitvec_into_packet(DisplayBitVec */*notnull*/ bitvec, size_t offset, BinaryOperation operation, CompressionCode compression); @@ -820,7 +808,7 @@ Packet *sp_bitvec_into_packet(SPBitVec */*notnull*/ bitvec, * * - `bit_vec`: instance to write to */ -bool sp_bitvec_is_empty(SPBitVec */*notnull*/ bit_vec); +bool sp_bitvec_is_empty(DisplayBitVec */*notnull*/ bit_vec); /** * Gets the length of the [SPBitVec] in bits. @@ -829,14 +817,14 @@ bool sp_bitvec_is_empty(SPBitVec */*notnull*/ bit_vec); * * - `bit_vec`: instance to write to */ -size_t sp_bitvec_len(SPBitVec */*notnull*/ bit_vec); +size_t sp_bitvec_len(DisplayBitVec */*notnull*/ bit_vec); /** * Interpret the data as a series of bits and load then into a new [SPBitVec] instance. * * returns: [SPBitVec] instance containing data. */ -SPBitVec */*notnull*/ sp_bitvec_load(ByteSlice data); +DisplayBitVec */*notnull*/ sp_bitvec_load(ByteSlice data); /** * Creates a new [SPBitVec] instance. @@ -851,7 +839,7 @@ SPBitVec */*notnull*/ sp_bitvec_load(ByteSlice data); * * - when `size` is not divisible by 8. */ -SPBitVec */*notnull*/ sp_bitvec_new(size_t size); +DisplayBitVec */*notnull*/ sp_bitvec_new(size_t size); /** * Sets the value of a bit in the [SPBitVec]. @@ -866,7 +854,9 @@ SPBitVec */*notnull*/ sp_bitvec_new(size_t size); * * - when accessing `index` out of bounds */ -void sp_bitvec_set(SPBitVec */*notnull*/ bit_vec, size_t index, bool value); +void sp_bitvec_set(DisplayBitVec */*notnull*/ bit_vec, + size_t index, + bool value); /** * Gets an unsafe reference to the data of the [SPBitVec] instance. @@ -877,7 +867,7 @@ void sp_bitvec_set(SPBitVec */*notnull*/ bit_vec, size_t index, bool value); * * - `bit_vec`: instance to write to */ -ByteSlice sp_bitvec_unsafe_data_ref(SPBitVec */*notnull*/ bit_vec); +ByteSlice sp_bitvec_unsafe_data_ref(DisplayBitVec */*notnull*/ bit_vec); /** * Clones a [BrightnessGrid]. diff --git a/src/bitmap.rs b/src/bitmap.rs index 8341c59..3393671 100644 --- a/src/bitmap.rs +++ b/src/bitmap.rs @@ -1,9 +1,6 @@ -use crate::{ - bitvec::SPBitVec, byte_slice::ByteSlice, heap_clone, heap_drop, - heap_move_nonnull, heap_move_ok, heap_move_some, heap_remove, -}; +use crate::{byte_slice::ByteSlice, heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_move_some, heap_remove}; use servicepoint::{ - Bitmap, BitmapCommand, CompressionCode, DataRef, Grid, Origin, Packet, + Bitmap, BitmapCommand, CompressionCode, DataRef, Grid, Origin, Packet, DisplayBitVec }; use std::ptr::NonNull; @@ -72,10 +69,10 @@ pub unsafe extern "C" fn sp_bitmap_load( #[no_mangle] pub unsafe extern "C" fn sp_bitmap_from_bitvec( width: usize, - bitvec: NonNull, + bitvec: NonNull, ) -> *mut Bitmap { let bitvec = unsafe { heap_remove(bitvec) }; - heap_move_ok(Bitmap::from_bitvec(width, bitvec.0)) + heap_move_ok(Bitmap::from_bitvec(width, bitvec)) } /// Clones a [Bitmap]. @@ -187,9 +184,9 @@ pub unsafe extern "C" fn sp_bitmap_unsafe_data_ref( #[no_mangle] pub unsafe extern "C" fn sp_bitmap_into_bitvec( bitmap: NonNull, -) -> NonNull { +) -> NonNull { let bitmap = unsafe { heap_remove(bitmap) }; - heap_move_nonnull(SPBitVec(bitmap.into())) + heap_move_nonnull(bitmap.into()) } /// Creates a [BitmapCommand] and immediately turns that into a [Packet]. diff --git a/src/bitvec.rs b/src/bitvec.rs index 3fa7412..1ba49a7 100644 --- a/src/bitvec.rs +++ b/src/bitvec.rs @@ -7,22 +7,6 @@ use servicepoint::{ }; use std::ptr::NonNull; -/// A vector of bits -/// -/// # Examples -/// ```C -/// SPBitVec vec = sp_bitvec_new(8); -/// sp_bitvec_set(vec, 5, true); -/// sp_bitvec_free(vec); -/// ``` -pub struct SPBitVec(pub(crate) DisplayBitVec); - -impl Clone for SPBitVec { - fn clone(&self) -> Self { - SPBitVec(self.0.clone()) - } -} - /// Creates a new [SPBitVec] instance. /// /// # Arguments @@ -35,30 +19,32 @@ impl Clone for SPBitVec { /// /// - when `size` is not divisible by 8. #[no_mangle] -pub unsafe extern "C" fn sp_bitvec_new(size: usize) -> NonNull { - heap_move_nonnull(SPBitVec(DisplayBitVec::repeat(false, size))) +pub unsafe extern "C" fn sp_bitvec_new(size: usize) -> NonNull { + heap_move_nonnull(DisplayBitVec::repeat(false, size)) } /// Interpret the data as a series of bits and load then into a new [SPBitVec] instance. /// /// returns: [SPBitVec] instance containing data. #[no_mangle] -pub unsafe extern "C" fn sp_bitvec_load(data: ByteSlice) -> NonNull { +pub unsafe extern "C" fn sp_bitvec_load( + data: ByteSlice, +) -> NonNull { let data = unsafe { data.as_slice() }; - heap_move_nonnull(SPBitVec(DisplayBitVec::from_slice(data))) + heap_move_nonnull(DisplayBitVec::from_slice(data)) } /// Clones a [SPBitVec]. #[no_mangle] pub unsafe extern "C" fn sp_bitvec_clone( - bit_vec: NonNull, -) -> NonNull { + bit_vec: NonNull, +) -> NonNull { unsafe { heap_clone(bit_vec) } } /// Deallocates a [SPBitVec]. #[no_mangle] -pub unsafe extern "C" fn sp_bitvec_free(bit_vec: NonNull) { +pub unsafe extern "C" fn sp_bitvec_free(bit_vec: NonNull) { unsafe { heap_drop(bit_vec) } } @@ -76,10 +62,10 @@ pub unsafe extern "C" fn sp_bitvec_free(bit_vec: NonNull) { /// - when accessing `index` out of bounds #[no_mangle] pub unsafe extern "C" fn sp_bitvec_get( - bit_vec: NonNull, + bit_vec: NonNull, index: usize, ) -> bool { - unsafe { *bit_vec.as_ref().0.get(index).unwrap() } + unsafe { *bit_vec.as_ref().get(index).unwrap() } } /// Sets the value of a bit in the [SPBitVec]. @@ -95,11 +81,11 @@ pub unsafe extern "C" fn sp_bitvec_get( /// - when accessing `index` out of bounds #[no_mangle] pub unsafe extern "C" fn sp_bitvec_set( - bit_vec: NonNull, + bit_vec: NonNull, index: usize, value: bool, ) { - unsafe { (*bit_vec.as_ptr()).0.set(index, value) } + unsafe { (*bit_vec.as_ptr()).set(index, value) } } /// Sets the value of all bits in the [SPBitVec]. @@ -110,10 +96,10 @@ pub unsafe extern "C" fn sp_bitvec_set( /// - `value`: the value to set all bits to #[no_mangle] pub unsafe extern "C" fn sp_bitvec_fill( - bit_vec: NonNull, + bit_vec: NonNull, value: bool, ) { - unsafe { (*bit_vec.as_ptr()).0.fill(value) } + unsafe { (*bit_vec.as_ptr()).fill(value) } } /// Gets the length of the [SPBitVec] in bits. @@ -122,8 +108,10 @@ pub unsafe extern "C" fn sp_bitvec_fill( /// /// - `bit_vec`: instance to write to #[no_mangle] -pub unsafe extern "C" fn sp_bitvec_len(bit_vec: NonNull) -> usize { - unsafe { bit_vec.as_ref().0.len() } +pub unsafe extern "C" fn sp_bitvec_len( + bit_vec: NonNull, +) -> usize { + unsafe { bit_vec.as_ref().len() } } /// Returns true if length is 0. @@ -133,9 +121,9 @@ pub unsafe extern "C" fn sp_bitvec_len(bit_vec: NonNull) -> usize { /// - `bit_vec`: instance to write to #[no_mangle] pub unsafe extern "C" fn sp_bitvec_is_empty( - bit_vec: NonNull, + bit_vec: NonNull, ) -> bool { - unsafe { bit_vec.as_ref().0.is_empty() } + unsafe { bit_vec.as_ref().is_empty() } } /// Gets an unsafe reference to the data of the [SPBitVec] instance. @@ -147,9 +135,9 @@ pub unsafe extern "C" fn sp_bitvec_is_empty( /// - `bit_vec`: instance to write to #[no_mangle] pub unsafe extern "C" fn sp_bitvec_unsafe_data_ref( - bit_vec: NonNull, + bit_vec: NonNull, ) -> ByteSlice { - unsafe { ByteSlice::from_slice((*bit_vec.as_ptr()).0.as_raw_mut_slice()) } + unsafe { ByteSlice::from_slice((*bit_vec.as_ptr()).as_raw_mut_slice()) } } /// Creates a [BitVecCommand] and immediately turns that into a [Packet]. @@ -159,12 +147,12 @@ pub unsafe extern "C" fn sp_bitvec_unsafe_data_ref( /// Returns NULL in case of an error. #[no_mangle] pub unsafe extern "C" fn sp_bitvec_into_packet( - bitvec: NonNull, + bitvec: NonNull, offset: usize, operation: BinaryOperation, compression: CompressionCode, ) -> *mut Packet { - let bitvec = unsafe { heap_remove(bitvec) }.0; + let bitvec = unsafe { heap_remove(bitvec) }; heap_move_ok(Packet::try_from(BitVecCommand { bitvec, offset, diff --git a/src/commands/generic_command.rs b/src/commands/generic_command.rs index 5066022..e3da8fd 100644 --- a/src/commands/generic_command.rs +++ b/src/commands/generic_command.rs @@ -2,7 +2,7 @@ use crate::{ heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, }; use servicepoint::{ - BitVecCommand, BitmapCommand, BitmapLegacyCommand, BrightnessGridCommand, + BitVecCommand, BitmapCommand, BrightnessGridCommand, CharGridCommand, ClearCommand, Cp437GridCommand, FadeOutCommand, GlobalBrightnessCommand, HardResetCommand, Packet, TypedCommand, }; @@ -19,7 +19,7 @@ pub union CommandUnion { pub global_brightness: NonNull, pub clear: NonNull, #[allow(deprecated)] - pub bitmap_legacy: NonNull, + pub bitmap_legacy: NonNull, pub hard_reset: NonNull, pub fade_out: NonNull, } -- 2.47.0 From e7cad5b5a3a79e6e1cf6fd4dcfdbbbf03fecdddd Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Wed, 7 May 2025 08:29:16 +0200 Subject: [PATCH 08/12] doc changes --- include/servicepoint.h | 66 +++++++++++++++++++++++------- src/bitvec.rs | 24 +++++------ src/commands/bitmap_command.rs | 2 +- src/commands/cp437_grid_command.rs | 11 ++++- src/commands/generic_command.rs | 13 +++++- src/udp.rs | 2 +- 6 files changed, 87 insertions(+), 31 deletions(-) diff --git a/include/servicepoint.h b/include/servicepoint.h index ec722f5..131fe41 100644 --- a/include/servicepoint.h +++ b/include/servicepoint.h @@ -125,6 +125,11 @@ enum CommandCode typedef uint16_t CommandCode; #endif // __cplusplus +/** + * Specifies the kind of command struct. + * + * This is _not_ equivalent to the [servicepoint::CommandCode]s. + */ enum CommandTag #ifdef __cplusplus : uint8_t @@ -531,6 +536,9 @@ typedef size_t Offset; */ typedef ValueGrid_u8 Cp437Grid; +/** + * Pointer to one of the available command structs. + */ typedef union { uint8_t *null; BitmapCommand */*notnull*/ bitmap; @@ -545,6 +553,13 @@ typedef union { FadeOutCommand */*notnull*/ fade_out; } CommandUnion; +/** + * This struct represents a pointer to one of the possible command structs. + * + * Only ever access `data` with the correct data type as specified by `tag`! + * + * Rust equivalent: [TypedCommand]. + */ typedef struct { /** * Specifies which kind of command struct is contained in `data` @@ -754,12 +769,12 @@ ByteSlice sp_bitmap_unsafe_data_ref(Bitmap */*notnull*/ bitmap); size_t sp_bitmap_width(Bitmap */*notnull*/ bitmap); /** - * Clones a [SPBitVec]. + * Clones a [DisplayBitVec]. */ DisplayBitVec */*notnull*/ sp_bitvec_clone(DisplayBitVec */*notnull*/ bit_vec); /** - * Sets the value of all bits in the [SPBitVec]. + * Sets the value of all bits in the [DisplayBitVec]. * * # Arguments * @@ -769,12 +784,12 @@ DisplayBitVec */*notnull*/ sp_bitvec_clone(DisplayBitVec */*notnull*/ bit_vec); void sp_bitvec_fill(DisplayBitVec */*notnull*/ bit_vec, bool value); /** - * Deallocates a [SPBitVec]. + * Deallocates a [DisplayBitVec]. */ void sp_bitvec_free(DisplayBitVec */*notnull*/ bit_vec); /** - * Gets the value of a bit from the [SPBitVec]. + * Gets the value of a bit from the [DisplayBitVec]. * * # Arguments * @@ -792,7 +807,7 @@ bool sp_bitvec_get(DisplayBitVec */*notnull*/ bit_vec, size_t index); /** * Creates a [BitVecCommand] and immediately turns that into a [Packet]. * - * The provided [SPBitVec] gets consumed. + * The provided [DisplayBitVec] gets consumed. * * Returns NULL in case of an error. */ @@ -811,7 +826,7 @@ Packet *sp_bitvec_into_packet(DisplayBitVec */*notnull*/ bitvec, bool sp_bitvec_is_empty(DisplayBitVec */*notnull*/ bit_vec); /** - * Gets the length of the [SPBitVec] in bits. + * Gets the length of the [DisplayBitVec] in bits. * * # Arguments * @@ -820,20 +835,20 @@ bool sp_bitvec_is_empty(DisplayBitVec */*notnull*/ bit_vec); size_t sp_bitvec_len(DisplayBitVec */*notnull*/ bit_vec); /** - * Interpret the data as a series of bits and load then into a new [SPBitVec] instance. + * Interpret the data as a series of bits and load then into a new [DisplayBitVec] instance. * - * returns: [SPBitVec] instance containing data. + * returns: [DisplayBitVec] instance containing data. */ DisplayBitVec */*notnull*/ sp_bitvec_load(ByteSlice data); /** - * Creates a new [SPBitVec] instance. + * Creates a new [DisplayBitVec] instance. * * # Arguments * * - `size`: size in bits. * - * returns: [SPBitVec] with all bits set to false. + * returns: [DisplayBitVec] with all bits set to false. * * # Panics * @@ -842,7 +857,7 @@ DisplayBitVec */*notnull*/ sp_bitvec_load(ByteSlice data); DisplayBitVec */*notnull*/ sp_bitvec_new(size_t size); /** - * Sets the value of a bit in the [SPBitVec]. + * Sets the value of a bit in the [DisplayBitVec]. * * # Arguments * @@ -859,7 +874,7 @@ void sp_bitvec_set(DisplayBitVec */*notnull*/ bit_vec, bool value); /** - * Gets an unsafe reference to the data of the [SPBitVec] instance. + * Gets an unsafe reference to the data of the [DisplayBitVec] instance. * * The returned memory is valid for the lifetime of the bitvec. * @@ -1119,7 +1134,7 @@ void sp_cmd_bitmap_free(BitmapCommand */*notnull*/ command); * Move the provided [Bitmap] into a new [BitmapCommand], * leaving other fields as their default values. * - * Rust equivalent: [`>::from`] + * Rust equivalent: `BitmapCommand::from(bitmap)` */ BitmapCommand */*notnull*/ sp_cmd_bitmap_from_bitmap(Bitmap */*notnull*/ bitmap); @@ -1311,6 +1326,11 @@ Cp437GridCommand */*notnull*/ sp_cmd_cp437_grid_from_grid(Cp437Grid */*notnull*/ Cp437Grid *sp_cmd_cp437_grid_get(Cp437GridCommand */*notnull*/ command); +/** + * Gets the origin field of the [Cp437GridCommand]. + * + * Rust equivalent: `cp437_command.origin` + */ void sp_cmd_cp437_grid_get_origin(Cp437GridCommand */*notnull*/ command, size_t */*notnull*/ origin_x, size_t */*notnull*/ origin_y); @@ -1322,11 +1342,18 @@ Cp437GridCommand */*notnull*/ sp_cmd_cp437_grid_new(Cp437Grid */*notnull*/ grid, size_t origin_y); /** - * Moves the provided bitmap to be contained in the command. + * Moves the provided bitmap into the provided command. + * + * This drops the previously contained [Cp437Grid]. */ void sp_cmd_cp437_grid_set(Cp437GridCommand */*notnull*/ command, Cp437Grid */*notnull*/ grid); +/** + * Sets the origin field of the [Cp437GridCommand]. + * + * Rust equivalent: `cp437_command.origin = Origin::new(origin_x, origin_y)` + */ void sp_cmd_cp437_grid_set_origin(Cp437GridCommand */*notnull*/ command, size_t origin_x, size_t origin_y); @@ -1367,6 +1394,15 @@ void sp_cmd_generic_free(SPCommand command); */ Packet *sp_cmd_generic_into_packet(SPCommand command); +/** + * Tries to turn a [Packet] into a [TypedCommand]. + * + * The packet is deallocated in the process. + * + * Returns: pointer to new [TypedCommand] instance or NULL if parsing failed. + */ +SPCommand *sp_cmd_generic_try_from_packet(Packet */*notnull*/ packet); + void sp_cmd_hard_reset_free(ClearCommand */*notnull*/ command); /** @@ -1585,7 +1621,7 @@ UdpSocket *sp_udp_open_ipv4(uint8_t ip1, uint16_t port); /** - * Sends a [TypedCommand] to the display using the [UdpSocket]. + * Sends a [SPCommand] to the display using the [UdpSocket]. * * The passed `command` gets consumed. * diff --git a/src/bitvec.rs b/src/bitvec.rs index 1ba49a7..ec5aa4c 100644 --- a/src/bitvec.rs +++ b/src/bitvec.rs @@ -7,13 +7,13 @@ use servicepoint::{ }; use std::ptr::NonNull; -/// Creates a new [SPBitVec] instance. +/// Creates a new [DisplayBitVec] instance. /// /// # Arguments /// /// - `size`: size in bits. /// -/// returns: [SPBitVec] with all bits set to false. +/// returns: [DisplayBitVec] with all bits set to false. /// /// # Panics /// @@ -23,9 +23,9 @@ pub unsafe extern "C" fn sp_bitvec_new(size: usize) -> NonNull { heap_move_nonnull(DisplayBitVec::repeat(false, size)) } -/// Interpret the data as a series of bits and load then into a new [SPBitVec] instance. +/// Interpret the data as a series of bits and load then into a new [DisplayBitVec] instance. /// -/// returns: [SPBitVec] instance containing data. +/// returns: [DisplayBitVec] instance containing data. #[no_mangle] pub unsafe extern "C" fn sp_bitvec_load( data: ByteSlice, @@ -34,7 +34,7 @@ pub unsafe extern "C" fn sp_bitvec_load( heap_move_nonnull(DisplayBitVec::from_slice(data)) } -/// Clones a [SPBitVec]. +/// Clones a [DisplayBitVec]. #[no_mangle] pub unsafe extern "C" fn sp_bitvec_clone( bit_vec: NonNull, @@ -42,13 +42,13 @@ pub unsafe extern "C" fn sp_bitvec_clone( unsafe { heap_clone(bit_vec) } } -/// Deallocates a [SPBitVec]. +/// Deallocates a [DisplayBitVec]. #[no_mangle] pub unsafe extern "C" fn sp_bitvec_free(bit_vec: NonNull) { unsafe { heap_drop(bit_vec) } } -/// Gets the value of a bit from the [SPBitVec]. +/// Gets the value of a bit from the [DisplayBitVec]. /// /// # Arguments /// @@ -68,7 +68,7 @@ pub unsafe extern "C" fn sp_bitvec_get( unsafe { *bit_vec.as_ref().get(index).unwrap() } } -/// Sets the value of a bit in the [SPBitVec]. +/// Sets the value of a bit in the [DisplayBitVec]. /// /// # Arguments /// @@ -88,7 +88,7 @@ pub unsafe extern "C" fn sp_bitvec_set( unsafe { (*bit_vec.as_ptr()).set(index, value) } } -/// Sets the value of all bits in the [SPBitVec]. +/// Sets the value of all bits in the [DisplayBitVec]. /// /// # Arguments /// @@ -102,7 +102,7 @@ pub unsafe extern "C" fn sp_bitvec_fill( unsafe { (*bit_vec.as_ptr()).fill(value) } } -/// Gets the length of the [SPBitVec] in bits. +/// Gets the length of the [DisplayBitVec] in bits. /// /// # Arguments /// @@ -126,7 +126,7 @@ pub unsafe extern "C" fn sp_bitvec_is_empty( unsafe { bit_vec.as_ref().is_empty() } } -/// Gets an unsafe reference to the data of the [SPBitVec] instance. +/// Gets an unsafe reference to the data of the [DisplayBitVec] instance. /// /// The returned memory is valid for the lifetime of the bitvec. /// @@ -142,7 +142,7 @@ pub unsafe extern "C" fn sp_bitvec_unsafe_data_ref( /// Creates a [BitVecCommand] and immediately turns that into a [Packet]. /// -/// The provided [SPBitVec] gets consumed. +/// The provided [DisplayBitVec] gets consumed. /// /// Returns NULL in case of an error. #[no_mangle] diff --git a/src/commands/bitmap_command.rs b/src/commands/bitmap_command.rs index b2ff3d8..2adf9a8 100644 --- a/src/commands/bitmap_command.rs +++ b/src/commands/bitmap_command.rs @@ -26,7 +26,7 @@ pub unsafe extern "C" fn sp_cmd_bitmap_new( /// Move the provided [Bitmap] into a new [BitmapCommand], /// leaving other fields as their default values. /// -/// Rust equivalent: [`>::from`] +/// Rust equivalent: `BitmapCommand::from(bitmap)` #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitmap_from_bitmap( bitmap: NonNull, diff --git a/src/commands/cp437_grid_command.rs b/src/commands/cp437_grid_command.rs index 1e1598a..2ccb000 100644 --- a/src/commands/cp437_grid_command.rs +++ b/src/commands/cp437_grid_command.rs @@ -46,7 +46,9 @@ pub unsafe extern "C" fn sp_cmd_cp437_grid_free( unsafe { heap_drop(command) } } -/// Moves the provided bitmap to be contained in the command. +/// Moves the provided bitmap into the provided command. +/// +/// This drops the previously contained [Cp437Grid]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_cp437_grid_set( mut command: NonNull, @@ -64,6 +66,9 @@ pub unsafe extern "C" fn sp_cmd_cp437_grid_get( &mut unsafe { command.as_mut() }.grid } +/// Gets the origin field of the [Cp437GridCommand]. +/// +/// Rust equivalent: `cp437_command.origin` #[no_mangle] pub unsafe extern "C" fn sp_cmd_cp437_grid_get_origin( command: NonNull, @@ -77,6 +82,10 @@ pub unsafe extern "C" fn sp_cmd_cp437_grid_get_origin( } } + +/// Sets the origin field of the [Cp437GridCommand]. +/// +/// Rust equivalent: `cp437_command.origin = Origin::new(origin_x, origin_y)` #[no_mangle] pub unsafe extern "C" fn sp_cmd_cp437_grid_set_origin( mut command: NonNull, diff --git a/src/commands/generic_command.rs b/src/commands/generic_command.rs index e3da8fd..561d041 100644 --- a/src/commands/generic_command.rs +++ b/src/commands/generic_command.rs @@ -8,7 +8,9 @@ use servicepoint::{ }; use std::ptr::{null_mut, NonNull}; +/// Pointer to one of the available command structs. #[repr(C)] +#[allow(missing_docs)] pub union CommandUnion { pub null: *mut u8, pub bitmap: NonNull, @@ -24,7 +26,11 @@ pub union CommandUnion { pub fade_out: NonNull, } +/// Specifies the kind of command struct. +/// +/// This is _not_ equivalent to the [servicepoint::CommandCode]s. #[repr(u8)] +#[allow(missing_docs)] pub enum CommandTag { Invalid = 0, Bitmap, @@ -39,6 +45,11 @@ pub enum CommandTag { BitmapLegacy, } +/// This struct represents a pointer to one of the possible command structs. +/// +/// Only ever access `data` with the correct data type as specified by `tag`! +/// +/// Rust equivalent: [TypedCommand]. #[repr(C)] pub struct SPCommand { /// Specifies which kind of command struct is contained in `data` @@ -59,7 +70,7 @@ impl SPCommand { /// The packet is deallocated in the process. /// /// Returns: pointer to new [TypedCommand] instance or NULL if parsing failed. -/// #[no_mangle] +#[no_mangle] pub unsafe extern "C" fn sp_cmd_generic_try_from_packet( packet: NonNull, ) -> *mut SPCommand { diff --git a/src/udp.rs b/src/udp.rs index 7b659cf..4f778b0 100644 --- a/src/udp.rs +++ b/src/udp.rs @@ -62,7 +62,7 @@ pub unsafe extern "C" fn sp_udp_send_packet( unsafe { connection.as_ref().send(&Vec::from(packet)) }.is_ok() } -/// Sends a [TypedCommand] to the display using the [UdpSocket]. +/// Sends a [SPCommand] to the display using the [UdpSocket]. /// /// The passed `command` gets consumed. /// -- 2.47.0 From cf6e6385ec502788a0ce2cb6973189f6dd525336 Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Wed, 7 May 2025 08:43:13 +0200 Subject: [PATCH 09/12] move containers to own mod --- src/commands/cp437_grid_command.rs | 1 - src/commands/generic_command.rs | 6 +++--- src/{ => containers}/bitmap.rs | 8 ++++++-- src/{ => containers}/bitvec.rs | 2 +- src/{ => containers}/brightness_grid.rs | 2 +- src/{ => containers}/byte_slice.rs | 0 src/{ => containers}/char_grid.rs | 2 +- src/{ => containers}/cp437_grid.rs | 2 +- src/containers/mod.rs | 13 +++++++++++++ src/lib.rs | 7 +------ src/packet.rs | 2 +- 11 files changed, 28 insertions(+), 17 deletions(-) rename src/{ => containers}/bitmap.rs (95%) rename src/{ => containers}/bitvec.rs (98%) rename src/{ => containers}/brightness_grid.rs (98%) rename src/{ => containers}/byte_slice.rs (100%) rename src/{ => containers}/char_grid.rs (98%) rename src/{ => containers}/cp437_grid.rs (98%) create mode 100644 src/containers/mod.rs diff --git a/src/commands/cp437_grid_command.rs b/src/commands/cp437_grid_command.rs index 2ccb000..eb42d15 100644 --- a/src/commands/cp437_grid_command.rs +++ b/src/commands/cp437_grid_command.rs @@ -82,7 +82,6 @@ pub unsafe extern "C" fn sp_cmd_cp437_grid_get_origin( } } - /// Sets the origin field of the [Cp437GridCommand]. /// /// Rust equivalent: `cp437_command.origin = Origin::new(origin_x, origin_y)` diff --git a/src/commands/generic_command.rs b/src/commands/generic_command.rs index 561d041..2b5327d 100644 --- a/src/commands/generic_command.rs +++ b/src/commands/generic_command.rs @@ -2,9 +2,9 @@ use crate::{ heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, }; use servicepoint::{ - BitVecCommand, BitmapCommand, BrightnessGridCommand, - CharGridCommand, ClearCommand, Cp437GridCommand, FadeOutCommand, - GlobalBrightnessCommand, HardResetCommand, Packet, TypedCommand, + BitVecCommand, BitmapCommand, BrightnessGridCommand, CharGridCommand, + ClearCommand, Cp437GridCommand, FadeOutCommand, GlobalBrightnessCommand, + HardResetCommand, Packet, TypedCommand, }; use std::ptr::{null_mut, NonNull}; diff --git a/src/bitmap.rs b/src/containers/bitmap.rs similarity index 95% rename from src/bitmap.rs rename to src/containers/bitmap.rs index 3393671..f928596 100644 --- a/src/bitmap.rs +++ b/src/containers/bitmap.rs @@ -1,6 +1,10 @@ -use crate::{byte_slice::ByteSlice, heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_move_some, heap_remove}; +use crate::{ + containers::ByteSlice, heap_clone, heap_drop, heap_move_nonnull, + heap_move_ok, heap_move_some, heap_remove, +}; use servicepoint::{ - Bitmap, BitmapCommand, CompressionCode, DataRef, Grid, Origin, Packet, DisplayBitVec + Bitmap, BitmapCommand, CompressionCode, DataRef, DisplayBitVec, Grid, + Origin, Packet, }; use std::ptr::NonNull; diff --git a/src/bitvec.rs b/src/containers/bitvec.rs similarity index 98% rename from src/bitvec.rs rename to src/containers/bitvec.rs index ec5aa4c..fd1132d 100644 --- a/src/bitvec.rs +++ b/src/containers/bitvec.rs @@ -1,5 +1,5 @@ use crate::{ - byte_slice::ByteSlice, heap_clone, heap_drop, heap_move_nonnull, + containers::ByteSlice, heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, }; use servicepoint::{ diff --git a/src/brightness_grid.rs b/src/containers/brightness_grid.rs similarity index 98% rename from src/brightness_grid.rs rename to src/containers/brightness_grid.rs index dc3b2f7..b6b3f04 100644 --- a/src/brightness_grid.rs +++ b/src/containers/brightness_grid.rs @@ -1,5 +1,5 @@ use crate::{ - byte_slice::ByteSlice, heap_clone, heap_drop, heap_move_nonnull, + containers::ByteSlice, heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_move_some, heap_remove, }; use servicepoint::{ diff --git a/src/byte_slice.rs b/src/containers/byte_slice.rs similarity index 100% rename from src/byte_slice.rs rename to src/containers/byte_slice.rs diff --git a/src/char_grid.rs b/src/containers/char_grid.rs similarity index 98% rename from src/char_grid.rs rename to src/containers/char_grid.rs index 62aba87..4e11e19 100644 --- a/src/char_grid.rs +++ b/src/containers/char_grid.rs @@ -1,5 +1,5 @@ use crate::{ - byte_slice::ByteSlice, heap_clone, heap_drop, heap_move_nonnull, + containers::ByteSlice, heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, }; use servicepoint::{CharGrid, CharGridCommand, Grid, Origin, Packet}; diff --git a/src/cp437_grid.rs b/src/containers/cp437_grid.rs similarity index 98% rename from src/cp437_grid.rs rename to src/containers/cp437_grid.rs index b4d449e..3d3885a 100644 --- a/src/cp437_grid.rs +++ b/src/containers/cp437_grid.rs @@ -1,5 +1,5 @@ use crate::{ - byte_slice::ByteSlice, heap_clone, heap_drop, heap_move_nonnull, + containers::ByteSlice, heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_move_some, heap_remove, }; use servicepoint::{ diff --git a/src/containers/mod.rs b/src/containers/mod.rs new file mode 100644 index 0000000..62d51d0 --- /dev/null +++ b/src/containers/mod.rs @@ -0,0 +1,13 @@ +mod bitmap; +mod bitvec; +mod brightness_grid; +mod byte_slice; +mod char_grid; +mod cp437_grid; + +pub use bitmap::*; +pub use bitvec::*; +pub use brightness_grid::*; +pub use byte_slice::*; +pub use char_grid::*; +pub use cp437_grid::*; diff --git a/src/lib.rs b/src/lib.rs index de22866..8196e3b 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -27,13 +27,8 @@ use std::ptr::NonNull; -pub mod bitmap; -pub mod bitvec; -pub mod brightness_grid; -pub mod byte_slice; -pub mod char_grid; pub mod commands; -pub mod cp437_grid; +pub mod containers; pub mod packet; pub mod udp; diff --git a/src/packet.rs b/src/packet.rs index 16509be..a6fde16 100644 --- a/src/packet.rs +++ b/src/packet.rs @@ -1,5 +1,5 @@ use crate::{ - byte_slice::ByteSlice, heap_clone, heap_drop, heap_move_nonnull, + containers::ByteSlice, heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, }; use servicepoint::{CommandCode, Header, Packet}; -- 2.47.0 From 626a887480c3e823323f51d82713c830d754f5b6 Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Wed, 7 May 2025 08:53:49 +0200 Subject: [PATCH 10/12] move heap functions to own mod --- src/commands/bitmap_command.rs | 2 +- src/commands/bitvec_command.rs | 2 +- src/commands/brightness_grid_command.rs | 2 +- src/commands/cc_only_commands.rs | 2 +- src/commands/char_grid_command.rs | 2 +- src/commands/cp437_grid_command.rs | 2 +- src/commands/generic_command.rs | 22 ++++++++-------- src/commands/global_brightness_command.rs | 2 +- src/containers/bitmap.rs | 7 +++-- src/containers/bitvec.rs | 6 +++-- src/containers/brightness_grid.rs | 7 +++-- src/containers/char_grid.rs | 6 +++-- src/containers/cp437_grid.rs | 7 +++-- src/lib.rs | 31 +---------------------- src/mem.rs | 29 +++++++++++++++++++++ src/packet.rs | 4 +-- src/udp.rs | 14 ++++++---- 17 files changed, 82 insertions(+), 65 deletions(-) create mode 100644 src/mem.rs diff --git a/src/commands/bitmap_command.rs b/src/commands/bitmap_command.rs index 2adf9a8..d67a59f 100644 --- a/src/commands/bitmap_command.rs +++ b/src/commands/bitmap_command.rs @@ -1,4 +1,4 @@ -use crate::{ +use crate::mem::{ heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, }; use servicepoint::{Bitmap, BitmapCommand, CompressionCode, Origin, Packet}; diff --git a/src/commands/bitvec_command.rs b/src/commands/bitvec_command.rs index bfe2d33..a717e0c 100644 --- a/src/commands/bitvec_command.rs +++ b/src/commands/bitvec_command.rs @@ -1,4 +1,4 @@ -use crate::{ +use crate::mem::{ heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, }; use servicepoint::{ diff --git a/src/commands/brightness_grid_command.rs b/src/commands/brightness_grid_command.rs index bd975d6..ac4b302 100644 --- a/src/commands/brightness_grid_command.rs +++ b/src/commands/brightness_grid_command.rs @@ -1,4 +1,4 @@ -use crate::{ +use crate::mem::{ heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, }; use servicepoint::{ diff --git a/src/commands/cc_only_commands.rs b/src/commands/cc_only_commands.rs index 751a6ab..ca24f7d 100644 --- a/src/commands/cc_only_commands.rs +++ b/src/commands/cc_only_commands.rs @@ -1,4 +1,4 @@ -use crate::{heap_drop, heap_move_nonnull}; +use crate::mem::{heap_drop, heap_move_nonnull}; use servicepoint::{ClearCommand, FadeOutCommand, HardResetCommand}; use std::ptr::NonNull; diff --git a/src/commands/char_grid_command.rs b/src/commands/char_grid_command.rs index bc078cd..d3f6816 100644 --- a/src/commands/char_grid_command.rs +++ b/src/commands/char_grid_command.rs @@ -1,4 +1,4 @@ -use crate::{ +use crate::mem::{ heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, }; use servicepoint::{BitmapCommand, CharGrid, CharGridCommand, Origin, Packet}; diff --git a/src/commands/cp437_grid_command.rs b/src/commands/cp437_grid_command.rs index eb42d15..2ab4e54 100644 --- a/src/commands/cp437_grid_command.rs +++ b/src/commands/cp437_grid_command.rs @@ -1,4 +1,4 @@ -use crate::{ +use crate::mem::{ heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, }; use servicepoint::{ diff --git a/src/commands/generic_command.rs b/src/commands/generic_command.rs index 2b5327d..59eb8f8 100644 --- a/src/commands/generic_command.rs +++ b/src/commands/generic_command.rs @@ -1,4 +1,4 @@ -use crate::{ +use crate::mem::{ heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, }; use servicepoint::{ @@ -65,11 +65,11 @@ impl SPCommand { }; } -/// Tries to turn a [Packet] into a [TypedCommand]. +/// Tries to turn a [Packet] into a [SPCommand]. /// -/// The packet is deallocated in the process. +/// The packet is dropped in the process. /// -/// Returns: pointer to new [TypedCommand] instance or NULL if parsing failed. +/// Returns: pointer to new [SPCommand] instance or NULL if parsing failed. #[no_mangle] pub unsafe extern "C" fn sp_cmd_generic_try_from_packet( packet: NonNull, @@ -142,9 +142,9 @@ pub unsafe extern "C" fn sp_cmd_generic_try_from_packet( })) } -/// Clones a [SPCommand] instance. +/// Clones an [SPCommand] instance. /// -/// returns: new [SPCommand] instance. +/// returns: a new [SPCommand] instance. #[no_mangle] pub unsafe extern "C" fn sp_cmd_generic_clone(command: SPCommand) -> SPCommand { unsafe { @@ -217,12 +217,12 @@ pub unsafe extern "C" fn sp_cmd_generic_clone(command: SPCommand) -> SPCommand { } } -/// Deallocates a [SPCommand]. +/// Deallocates an [SPCommand]. /// /// # Examples /// /// ```C -/// TypedCommand c = sp_command_clear(); +/// SPCommand c = sp_cmd_clear_into_generic(sp_cmd_clear_new()); /// sp_command_free(c); /// ``` #[no_mangle] @@ -248,10 +248,10 @@ pub unsafe extern "C" fn sp_cmd_generic_free(command: SPCommand) { } } -/// Turns a [TypedCommand] into a [Packet]. -/// The [TypedCommand] gets consumed. +/// Tries to turn a [SPCommand] into a [Packet]. +/// The [SPCommand] gets consumed. /// -/// Returns NULL in case of an error. +/// Returns tag [CommandTag::Invalid] in case of an error. #[no_mangle] pub unsafe extern "C" fn sp_cmd_generic_into_packet( command: SPCommand, diff --git a/src/commands/global_brightness_command.rs b/src/commands/global_brightness_command.rs index 29e7c19..9d1690c 100644 --- a/src/commands/global_brightness_command.rs +++ b/src/commands/global_brightness_command.rs @@ -1,4 +1,4 @@ -use crate::{ +use crate::mem::{ heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, }; use servicepoint::{ diff --git a/src/containers/bitmap.rs b/src/containers/bitmap.rs index f928596..7a1b633 100644 --- a/src/containers/bitmap.rs +++ b/src/containers/bitmap.rs @@ -1,6 +1,9 @@ use crate::{ - containers::ByteSlice, heap_clone, heap_drop, heap_move_nonnull, - heap_move_ok, heap_move_some, heap_remove, + containers::ByteSlice, + mem::{ + heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_move_some, + heap_remove, + }, }; use servicepoint::{ Bitmap, BitmapCommand, CompressionCode, DataRef, DisplayBitVec, Grid, diff --git a/src/containers/bitvec.rs b/src/containers/bitvec.rs index fd1132d..e9eeb68 100644 --- a/src/containers/bitvec.rs +++ b/src/containers/bitvec.rs @@ -1,6 +1,8 @@ use crate::{ - containers::ByteSlice, heap_clone, heap_drop, heap_move_nonnull, - heap_move_ok, heap_remove, + containers::ByteSlice, + mem::{ + heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, + }, }; use servicepoint::{ BinaryOperation, BitVecCommand, CompressionCode, DisplayBitVec, Packet, diff --git a/src/containers/brightness_grid.rs b/src/containers/brightness_grid.rs index b6b3f04..3a7ae5f 100644 --- a/src/containers/brightness_grid.rs +++ b/src/containers/brightness_grid.rs @@ -1,6 +1,9 @@ use crate::{ - containers::ByteSlice, heap_clone, heap_drop, heap_move_nonnull, - heap_move_ok, heap_move_some, heap_remove, + containers::ByteSlice, + mem::{ + heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_move_some, + heap_remove, + }, }; use servicepoint::{ Brightness, BrightnessGrid, BrightnessGridCommand, ByteGrid, DataRef, Grid, diff --git a/src/containers/char_grid.rs b/src/containers/char_grid.rs index 4e11e19..3363d43 100644 --- a/src/containers/char_grid.rs +++ b/src/containers/char_grid.rs @@ -1,6 +1,8 @@ use crate::{ - containers::ByteSlice, heap_clone, heap_drop, heap_move_nonnull, - heap_move_ok, heap_remove, + containers::ByteSlice, + mem::{ + heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, + }, }; use servicepoint::{CharGrid, CharGridCommand, Grid, Origin, Packet}; use std::ptr::NonNull; diff --git a/src/containers/cp437_grid.rs b/src/containers/cp437_grid.rs index 3d3885a..a636295 100644 --- a/src/containers/cp437_grid.rs +++ b/src/containers/cp437_grid.rs @@ -1,6 +1,9 @@ use crate::{ - containers::ByteSlice, heap_clone, heap_drop, heap_move_nonnull, - heap_move_ok, heap_move_some, heap_remove, + containers::ByteSlice, + mem::{ + heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_move_some, + heap_remove, + }, }; use servicepoint::{ Cp437Grid, Cp437GridCommand, DataRef, Grid, Origin, Packet, diff --git a/src/lib.rs b/src/lib.rs index 8196e3b..14b172d 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -25,10 +25,9 @@ //! } //! ``` -use std::ptr::NonNull; - pub mod commands; pub mod containers; +pub mod mem; pub mod packet; pub mod udp; @@ -37,34 +36,6 @@ use std::time::Duration; /// 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(); -pub(crate) fn heap_move(x: T) -> *mut T { - Box::into_raw(Box::new(x)) -} - -pub(crate) fn heap_move_nonnull(x: T) -> NonNull { - NonNull::from(Box::leak(Box::new(x))) -} - -pub(crate) fn heap_move_ok(x: Result) -> *mut T { - x.map(|x| heap_move(x)).unwrap_or(std::ptr::null_mut()) -} - -pub(crate) fn heap_move_some(x: Option) -> *mut T { - x.map(|x| heap_move(x)).unwrap_or(std::ptr::null_mut()) -} - -pub(crate) unsafe fn heap_drop(x: NonNull) { - drop(unsafe { heap_remove(x) }); -} - -pub(crate) unsafe fn heap_remove(x: NonNull) -> T { - unsafe { *Box::from_raw(x.as_ptr()) } -} - -unsafe fn heap_clone(source: NonNull) -> NonNull { - heap_move_nonnull(unsafe { source.as_ref().clone() }) -} - /// This is a type only used by cbindgen to have a type for pointers. pub struct UdpSocket; diff --git a/src/mem.rs b/src/mem.rs new file mode 100644 index 0000000..6555999 --- /dev/null +++ b/src/mem.rs @@ -0,0 +1,29 @@ +use std::ptr::NonNull; + +pub(crate) fn heap_move(x: T) -> *mut T { + Box::into_raw(Box::new(x)) +} + +pub(crate) fn heap_move_nonnull(x: T) -> NonNull { + NonNull::from(Box::leak(Box::new(x))) +} + +pub(crate) fn heap_move_ok(x: Result) -> *mut T { + x.map(|x| heap_move(x)).unwrap_or(std::ptr::null_mut()) +} + +pub(crate) fn heap_move_some(x: Option) -> *mut T { + x.map(|x| heap_move(x)).unwrap_or(std::ptr::null_mut()) +} + +pub(crate) unsafe fn heap_drop(x: NonNull) { + drop(unsafe { heap_remove(x) }); +} + +pub(crate) unsafe fn heap_remove(x: NonNull) -> T { + unsafe { *Box::from_raw(x.as_ptr()) } +} + +pub(crate) unsafe fn heap_clone(source: NonNull) -> NonNull { + heap_move_nonnull(unsafe { source.as_ref().clone() }) +} diff --git a/src/packet.rs b/src/packet.rs index a6fde16..5fe7572 100644 --- a/src/packet.rs +++ b/src/packet.rs @@ -1,6 +1,6 @@ use crate::{ - containers::ByteSlice, heap_clone, heap_drop, heap_move_nonnull, - heap_move_ok, + containers::ByteSlice, + mem::{heap_clone, heap_drop, heap_move_nonnull, heap_move_ok}, }; use servicepoint::{CommandCode, Header, Packet}; use std::ptr::NonNull; diff --git a/src/udp.rs b/src/udp.rs index 4f778b0..7c2ab2f 100644 --- a/src/udp.rs +++ b/src/udp.rs @@ -1,9 +1,13 @@ -use crate::commands::{CommandTag, SPCommand}; -use crate::{heap_drop, heap_move_ok, heap_remove}; +use crate::{ + commands::{CommandTag, SPCommand}, + mem::{heap_drop, heap_move_ok, heap_remove}, +}; use servicepoint::{Header, Packet, UdpSocketExt}; -use std::ffi::{c_char, CStr}; -use std::net::{Ipv4Addr, SocketAddrV4, UdpSocket}; -use std::ptr::NonNull; +use std::{ + ffi::{c_char, CStr}, + net::{Ipv4Addr, SocketAddrV4, UdpSocket}, + ptr::NonNull, +}; /// Creates a new instance of [UdpSocket]. /// -- 2.47.0 From 36f3d84dc8e8f9aa07b384a5e98d4a0303876abe Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Wed, 7 May 2025 22:27:06 +0200 Subject: [PATCH 11/12] a bunch of docs --- cbindgen.toml | 4 +- include/servicepoint.h | 175 ++++++++++++++++------ src/commands/bitmap_command.rs | 3 + src/commands/bitvec_command.rs | 4 + src/commands/brightness_grid_command.rs | 11 ++ src/commands/cc_only_commands.rs | 9 +- src/commands/char_grid_command.rs | 11 ++ src/commands/cp437_grid_command.rs | 17 +++ src/commands/generic_command.rs | 29 ++-- src/commands/global_brightness_command.rs | 14 +- src/lib.rs | 6 +- src/packet.rs | 2 + 12 files changed, 215 insertions(+), 70 deletions(-) diff --git a/cbindgen.toml b/cbindgen.toml index 4aabb7e..7841755 100644 --- a/cbindgen.toml +++ b/cbindgen.toml @@ -35,8 +35,8 @@ include = [] exclude = ["BitVec"] [export.rename] -"SpByteSlice" = "ByteSlice" -"SpCommand" = "Command" +"SPCommand" = "Command" +"DisplayBitVec" = "BitVec" [enum] rename_variants = "QualifiedScreamingSnakeCase" diff --git a/include/servicepoint.h b/include/servicepoint.h index 131fe41..a5b3ac7 100644 --- a/include/servicepoint.h +++ b/include/servicepoint.h @@ -346,7 +346,7 @@ typedef struct Cp437GridCommand Cp437GridCommand; /** * This is a type only used by cbindgen to have a type for pointers. */ -typedef struct DisplayBitVec DisplayBitVec; +typedef struct BitVec BitVec; /** *
Untested
@@ -569,7 +569,7 @@ typedef struct { * The pointer to the command struct */ CommandUnion data; -} SPCommand; +} Command; /** * A raw header. @@ -637,7 +637,7 @@ void sp_bitmap_free(Bitmap */*notnull*/ bitmap); * * Returns NULL in case of error. */ -Bitmap *sp_bitmap_from_bitvec(size_t width, DisplayBitVec */*notnull*/ bitvec); +Bitmap *sp_bitmap_from_bitvec(size_t width, BitVec */*notnull*/ bitvec); /** * Gets the current value at the specified position in the [Bitmap]. @@ -665,7 +665,7 @@ size_t sp_bitmap_height(Bitmap */*notnull*/ bitmap); /** * Consumes the Bitmap and returns the contained BitVec */ -DisplayBitVec */*notnull*/ sp_bitmap_into_bitvec(Bitmap */*notnull*/ bitmap); +BitVec */*notnull*/ sp_bitmap_into_bitvec(Bitmap */*notnull*/ bitmap); /** * Creates a [BitmapCommand] and immediately turns that into a [Packet]. @@ -771,7 +771,7 @@ size_t sp_bitmap_width(Bitmap */*notnull*/ bitmap); /** * Clones a [DisplayBitVec]. */ -DisplayBitVec */*notnull*/ sp_bitvec_clone(DisplayBitVec */*notnull*/ bit_vec); +BitVec */*notnull*/ sp_bitvec_clone(BitVec */*notnull*/ bit_vec); /** * Sets the value of all bits in the [DisplayBitVec]. @@ -781,12 +781,12 @@ DisplayBitVec */*notnull*/ sp_bitvec_clone(DisplayBitVec */*notnull*/ bit_vec); * - `bit_vec`: instance to write to * - `value`: the value to set all bits to */ -void sp_bitvec_fill(DisplayBitVec */*notnull*/ bit_vec, bool value); +void sp_bitvec_fill(BitVec */*notnull*/ bit_vec, bool value); /** * Deallocates a [DisplayBitVec]. */ -void sp_bitvec_free(DisplayBitVec */*notnull*/ bit_vec); +void sp_bitvec_free(BitVec */*notnull*/ bit_vec); /** * Gets the value of a bit from the [DisplayBitVec]. @@ -802,7 +802,7 @@ void sp_bitvec_free(DisplayBitVec */*notnull*/ bit_vec); * * - when accessing `index` out of bounds */ -bool sp_bitvec_get(DisplayBitVec */*notnull*/ bit_vec, size_t index); +bool sp_bitvec_get(BitVec */*notnull*/ bit_vec, size_t index); /** * Creates a [BitVecCommand] and immediately turns that into a [Packet]. @@ -811,7 +811,7 @@ bool sp_bitvec_get(DisplayBitVec */*notnull*/ bit_vec, size_t index); * * Returns NULL in case of an error. */ -Packet *sp_bitvec_into_packet(DisplayBitVec */*notnull*/ bitvec, +Packet *sp_bitvec_into_packet(BitVec */*notnull*/ bitvec, size_t offset, BinaryOperation operation, CompressionCode compression); @@ -823,7 +823,7 @@ Packet *sp_bitvec_into_packet(DisplayBitVec */*notnull*/ bitvec, * * - `bit_vec`: instance to write to */ -bool sp_bitvec_is_empty(DisplayBitVec */*notnull*/ bit_vec); +bool sp_bitvec_is_empty(BitVec */*notnull*/ bit_vec); /** * Gets the length of the [DisplayBitVec] in bits. @@ -832,14 +832,14 @@ bool sp_bitvec_is_empty(DisplayBitVec */*notnull*/ bit_vec); * * - `bit_vec`: instance to write to */ -size_t sp_bitvec_len(DisplayBitVec */*notnull*/ bit_vec); +size_t sp_bitvec_len(BitVec */*notnull*/ bit_vec); /** * Interpret the data as a series of bits and load then into a new [DisplayBitVec] instance. * * returns: [DisplayBitVec] instance containing data. */ -DisplayBitVec */*notnull*/ sp_bitvec_load(ByteSlice data); +BitVec */*notnull*/ sp_bitvec_load(ByteSlice data); /** * Creates a new [DisplayBitVec] instance. @@ -854,7 +854,7 @@ DisplayBitVec */*notnull*/ sp_bitvec_load(ByteSlice data); * * - when `size` is not divisible by 8. */ -DisplayBitVec */*notnull*/ sp_bitvec_new(size_t size); +BitVec */*notnull*/ sp_bitvec_new(size_t size); /** * Sets the value of a bit in the [DisplayBitVec]. @@ -869,9 +869,7 @@ DisplayBitVec */*notnull*/ sp_bitvec_new(size_t size); * * - when accessing `index` out of bounds */ -void sp_bitvec_set(DisplayBitVec */*notnull*/ bit_vec, - size_t index, - bool value); +void sp_bitvec_set(BitVec */*notnull*/ bit_vec, size_t index, bool value); /** * Gets an unsafe reference to the data of the [DisplayBitVec] instance. @@ -882,7 +880,7 @@ void sp_bitvec_set(DisplayBitVec */*notnull*/ bit_vec, * * - `bit_vec`: instance to write to */ -ByteSlice sp_bitvec_unsafe_data_ref(DisplayBitVec */*notnull*/ bit_vec); +ByteSlice sp_bitvec_unsafe_data_ref(BitVec */*notnull*/ bit_vec); /** * Clones a [BrightnessGrid]. @@ -1126,6 +1124,11 @@ void sp_char_grid_set(CharGrid */*notnull*/ char_grid, */ size_t sp_char_grid_width(CharGrid */*notnull*/ char_grid); +/** + * Clones an [BitmapCommand] instance. + * + * returns: a new [BitmapCommand] instance. + */ BitmapCommand */*notnull*/ sp_cmd_bitmap_clone(BitmapCommand */*notnull*/ command); void sp_cmd_bitmap_free(BitmapCommand */*notnull*/ command); @@ -1181,11 +1184,19 @@ void sp_cmd_bitmap_set_origin(BitmapCommand */*notnull*/ command, size_t origin_x, size_t origin_y); +/** + * Clones an [BitVecCommand] instance. + * + * returns: a new [BitVecCommand] instance. + */ BitVecCommand */*notnull*/ sp_cmd_bitvec_clone(BitVecCommand */*notnull*/ command); +/** + * Deallocates a [BitVecCommand]. + */ void sp_cmd_bitvec_free(BitVecCommand */*notnull*/ command); -DisplayBitVec *sp_cmd_bitvec_get(BitVecCommand */*notnull*/ command); +BitVec *sp_cmd_bitvec_get(BitVecCommand */*notnull*/ command); CompressionCode sp_cmd_bitvec_get_compression(BitVecCommand */*notnull*/ command); @@ -1209,7 +1220,7 @@ Packet *sp_cmd_bitvec_into_packet(BitVecCommand */*notnull*/ command); * * The contained [`DisplayBitVec`] is always uncompressed. */ -BitVecCommand */*notnull*/ sp_cmd_bitvec_new(DisplayBitVec */*notnull*/ bitvec, +BitVecCommand */*notnull*/ sp_cmd_bitvec_new(BitVec */*notnull*/ bitvec, size_t offset, BinaryOperation operation, CompressionCode compression); @@ -1218,7 +1229,7 @@ BitVecCommand */*notnull*/ sp_cmd_bitvec_new(DisplayBitVec */*notnull*/ bitvec, * Moves the provided bitmap to be contained in the command. */ void sp_cmd_bitvec_set(BitVecCommand */*notnull*/ command, - DisplayBitVec */*notnull*/ bitvec); + BitVec */*notnull*/ bitvec); void sp_cmd_bitvec_set_compression(BitVecCommand */*notnull*/ command, CompressionCode compression); @@ -1229,14 +1240,24 @@ void sp_cmd_bitvec_set_offset(BitVecCommand */*notnull*/ command, void sp_cmd_bitvec_set_operation(BitVecCommand */*notnull*/ command, BinaryOperation operation); +/** + * Clones an [GlobalBrightnessCommand] instance. + * + * returns: a new [GlobalBrightnessCommand] instance. + */ GlobalBrightnessCommand */*notnull*/ sp_cmd_brightness_global_clone(GlobalBrightnessCommand */*notnull*/ command); void sp_cmd_brightness_global_free(BitmapCommand */*notnull*/ command); Brightness *sp_cmd_brightness_global_get(GlobalBrightnessCommand */*notnull*/ command); -Packet *sp_cmd_brightness_global_into_packet(GlobalBrightnessCommand */*notnull*/ command); +Packet */*notnull*/ sp_cmd_brightness_global_into_packet(GlobalBrightnessCommand */*notnull*/ command); +/** + * Set the brightness of all tiles to the same value. + * + * Returns: a new [GlobalBrightnessCommand] instance. + */ GlobalBrightnessCommand */*notnull*/ sp_cmd_brightness_global_new(Brightness brightness); /** @@ -1245,10 +1266,22 @@ GlobalBrightnessCommand */*notnull*/ sp_cmd_brightness_global_new(Brightness bri void sp_cmd_brightness_global_set(GlobalBrightnessCommand */*notnull*/ command, Brightness brightness); +/** + * Clones an [BrightnessGridCommand] instance. + * + * returns: a new [BrightnessGridCommand] instance. + */ BrightnessGridCommand */*notnull*/ sp_cmd_brightness_grid_clone(BrightnessGridCommand */*notnull*/ command); +/** + * Deallocates a [BitmapCommand]. + */ void sp_cmd_brightness_grid_free(BitmapCommand */*notnull*/ command); +/** + * Moves the provided [BrightnessGrid] into a new [BrightnessGridCommand], + * leaving other fields as their default values. + */ BrightnessGridCommand */*notnull*/ sp_cmd_brightness_grid_from_grid(BrightnessGrid */*notnull*/ grid); BrightnessGrid *sp_cmd_brightness_grid_get(BrightnessGridCommand */*notnull*/ command); @@ -1259,6 +1292,13 @@ void sp_cmd_brightness_grid_get_origin(BrightnessGridCommand */*notnull*/ comman Packet *sp_cmd_brightness_grid_into_packet(BrightnessGridCommand */*notnull*/ command); +/** + * Set the brightness of individual tiles in a rectangular area of the display. + * + * The passed [BrightnessGrid] gets consumed. + * + * Returns: a new [BrightnessGridCommand] instance. + */ BrightnessGridCommand */*notnull*/ sp_cmd_brightness_grid_new(BrightnessGrid */*notnull*/ grid, size_t origin_x, size_t origin_y); @@ -1273,10 +1313,22 @@ void sp_cmd_brightness_grid_set_origin(BrightnessGridCommand */*notnull*/ comman size_t origin_x, size_t origin_y); +/** + * Clones an [CharGridCommand] instance. + * + * returns: a new [CharGridCommand] instance. + */ CharGridCommand */*notnull*/ sp_cmd_char_grid_clone(CharGridCommand */*notnull*/ command); +/** + * Deallocates a [BitmapCommand]. + */ void sp_cmd_char_grid_free(BitmapCommand */*notnull*/ command); +/** + * Moves the provided [CharGrid] into a new [CharGridCommand], + * leaving other fields as their default values. + */ CharGridCommand */*notnull*/ sp_cmd_char_grid_from_grid(CharGrid */*notnull*/ grid); CharGrid *sp_cmd_char_grid_get(CharGridCommand */*notnull*/ command); @@ -1287,6 +1339,13 @@ void sp_cmd_char_grid_get_origin(CharGridCommand */*notnull*/ command, Packet *sp_cmd_char_grid_into_packet(CharGridCommand */*notnull*/ command); +/** + * Show UTF-8 encoded text on the screen. + * + * The passed [CharGrid] gets consumed. + * + * Returns: a new [CharGridCommand] instance. + */ CharGridCommand */*notnull*/ sp_cmd_char_grid_new(CharGrid */*notnull*/ grid, size_t origin_x, size_t origin_y); @@ -1301,6 +1360,9 @@ void sp_cmd_char_grid_set_origin(CharGridCommand */*notnull*/ command, size_t origin_x, size_t origin_y); +/** + * Deallocates a [ClearCommand]. + */ void sp_cmd_clear_free(ClearCommand */*notnull*/ command); /** @@ -1309,21 +1371,35 @@ void sp_cmd_clear_free(ClearCommand */*notnull*/ command); * Does not affect brightness. * * Returns: a new [ClearCommand] instance. - * - * # Examples - * - * ```C - * sp_udp_send_command(connection, sp_cmd_clear()); - * ``` */ ClearCommand */*notnull*/ sp_cmd_clear_new(void); +/** + * Clones an [Cp437GridCommand] instance. + * + * returns: a new [Cp437GridCommand] instance. + */ Cp437GridCommand */*notnull*/ sp_cmd_cp437_grid_clone(Cp437GridCommand */*notnull*/ command); +/** + * Deallocates a [Cp437GridCommand]. + */ void sp_cmd_cp437_grid_free(BitmapCommand */*notnull*/ command); +/** + * Moves the provided [Cp437Grid] into a new [Cp437GridCommand], + * leaving other fields as their default values. + */ Cp437GridCommand */*notnull*/ sp_cmd_cp437_grid_from_grid(Cp437Grid */*notnull*/ grid); +/** + * Show text on the screen. + * + * The text is sent in the form of a 2D grid of [CP-437] encoded characters. + * For sending UTF-8 encoded characters, see [servicepoint::CharGridCommand]. + * + * [CP-437]: https://en.wikipedia.org/wiki/Code_page_437 + */ Cp437Grid *sp_cmd_cp437_grid_get(Cp437GridCommand */*notnull*/ command); /** @@ -1337,6 +1413,13 @@ void sp_cmd_cp437_grid_get_origin(Cp437GridCommand */*notnull*/ command, Packet *sp_cmd_cp437_grid_into_packet(Cp437GridCommand */*notnull*/ command); +/** + * Show text on the screen. + * + * The text is sent in the form of a 2D grid of [CP-437] encoded characters. + * + * The origin is relative to the top-left of the display. + */ Cp437GridCommand */*notnull*/ sp_cmd_cp437_grid_new(Cp437Grid */*notnull*/ grid, size_t origin_x, size_t origin_y); @@ -1358,6 +1441,9 @@ void sp_cmd_cp437_grid_set_origin(Cp437GridCommand */*notnull*/ command, size_t origin_x, size_t origin_y); +/** + * Deallocates a [FadeOutCommand]. + */ void sp_cmd_fade_out_free(ClearCommand */*notnull*/ command); /** @@ -1368,41 +1454,44 @@ void sp_cmd_fade_out_free(ClearCommand */*notnull*/ command); FadeOutCommand */*notnull*/ sp_cmd_fade_out_new(void); /** - * Clones a [SPCommand] instance. + * Clones an [SPCommand] instance. * - * returns: new [SPCommand] instance. + * returns: a new [SPCommand] instance. */ -SPCommand sp_cmd_generic_clone(SPCommand command); +Command sp_cmd_generic_clone(Command command); /** - * Deallocates a [SPCommand]. + * Deallocates an [SPCommand]. * * # Examples * * ```C - * TypedCommand c = sp_command_clear(); + * SPCommand c = sp_cmd_clear_into_generic(sp_cmd_clear_new()); * sp_command_free(c); * ``` */ -void sp_cmd_generic_free(SPCommand command); +void sp_cmd_generic_free(Command command); /** - * Turns a [TypedCommand] into a [Packet]. - * The [TypedCommand] gets consumed. + * Tries to turn a [SPCommand] into a [Packet]. + * The [SPCommand] gets consumed. * - * Returns NULL in case of an error. + * Returns tag [CommandTag::Invalid] in case of an error. */ -Packet *sp_cmd_generic_into_packet(SPCommand command); +Packet *sp_cmd_generic_into_packet(Command command); /** - * Tries to turn a [Packet] into a [TypedCommand]. + * Tries to turn a [Packet] into a [SPCommand]. * - * The packet is deallocated in the process. + * The packet is dropped in the process. * - * Returns: pointer to new [TypedCommand] instance or NULL if parsing failed. + * Returns: pointer to new [SPCommand] instance or NULL if parsing failed. */ -SPCommand *sp_cmd_generic_try_from_packet(Packet */*notnull*/ packet); +Command *sp_cmd_generic_try_from_packet(Packet */*notnull*/ packet); +/** + * Deallocates a [HardResetCommand]. + */ void sp_cmd_hard_reset_free(ClearCommand */*notnull*/ command); /** @@ -1520,6 +1609,8 @@ size_t sp_cp437_grid_width(Cp437Grid */*notnull*/ cp437_grid); /** * Clones a [Packet]. + * + * returns: a new [Packet] instance. */ Packet */*notnull*/ sp_packet_clone(Packet */*notnull*/ packet); @@ -1633,7 +1724,7 @@ UdpSocket *sp_udp_open_ipv4(uint8_t ip1, * sp_udp_send_command(connection, sp_command_brightness(5)); * ``` */ -bool sp_udp_send_command(UdpSocket */*notnull*/ connection, SPCommand command); +bool sp_udp_send_command(UdpSocket */*notnull*/ connection, Command command); /** * Sends a [Header] to the display using the [UdpSocket]. diff --git a/src/commands/bitmap_command.rs b/src/commands/bitmap_command.rs index d67a59f..731a644 100644 --- a/src/commands/bitmap_command.rs +++ b/src/commands/bitmap_command.rs @@ -41,6 +41,9 @@ pub unsafe extern "C" fn sp_cmd_bitmap_into_packet( heap_move_ok(unsafe { heap_remove(command) }.try_into()) } +/// Clones an [BitmapCommand] instance. +/// +/// returns: a new [BitmapCommand] instance. #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitmap_clone( command: NonNull, diff --git a/src/commands/bitvec_command.rs b/src/commands/bitvec_command.rs index a717e0c..7734c05 100644 --- a/src/commands/bitvec_command.rs +++ b/src/commands/bitvec_command.rs @@ -41,6 +41,9 @@ pub unsafe extern "C" fn sp_cmd_bitvec_into_packet( heap_move_ok(unsafe { heap_remove(command) }.try_into()) } +/// Clones an [BitVecCommand] instance. +/// +/// returns: a new [BitVecCommand] instance. #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitvec_clone( command: NonNull, @@ -48,6 +51,7 @@ pub unsafe extern "C" fn sp_cmd_bitvec_clone( unsafe { heap_clone(command) } } +/// Deallocates a [BitVecCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitvec_free(command: NonNull) { unsafe { heap_drop(command) } diff --git a/src/commands/brightness_grid_command.rs b/src/commands/brightness_grid_command.rs index ac4b302..aa1caab 100644 --- a/src/commands/brightness_grid_command.rs +++ b/src/commands/brightness_grid_command.rs @@ -6,6 +6,11 @@ use servicepoint::{ }; use std::ptr::NonNull; +/// Set the brightness of individual tiles in a rectangular area of the display. +/// +/// The passed [BrightnessGrid] gets consumed. +/// +/// Returns: a new [BrightnessGridCommand] instance. #[no_mangle] pub unsafe extern "C" fn sp_cmd_brightness_grid_new( grid: NonNull, @@ -18,6 +23,8 @@ pub unsafe extern "C" fn sp_cmd_brightness_grid_new( }) } +/// Moves the provided [BrightnessGrid] into a new [BrightnessGridCommand], +/// leaving other fields as their default values. #[no_mangle] pub unsafe extern "C" fn sp_cmd_brightness_grid_from_grid( grid: NonNull, @@ -32,6 +39,9 @@ pub unsafe extern "C" fn sp_cmd_brightness_grid_into_packet( heap_move_ok(unsafe { heap_remove(command) }.try_into()) } +/// Clones an [BrightnessGridCommand] instance. +/// +/// returns: a new [BrightnessGridCommand] instance. #[no_mangle] pub unsafe extern "C" fn sp_cmd_brightness_grid_clone( command: NonNull, @@ -39,6 +49,7 @@ pub unsafe extern "C" fn sp_cmd_brightness_grid_clone( unsafe { heap_clone(command) } } +/// Deallocates a [BitmapCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_brightness_grid_free( command: NonNull, diff --git a/src/commands/cc_only_commands.rs b/src/commands/cc_only_commands.rs index ca24f7d..2a48c12 100644 --- a/src/commands/cc_only_commands.rs +++ b/src/commands/cc_only_commands.rs @@ -7,17 +7,12 @@ use std::ptr::NonNull; /// Does not affect brightness. /// /// Returns: a new [ClearCommand] instance. -/// -/// # Examples -/// -/// ```C -/// sp_udp_send_command(connection, sp_cmd_clear()); -/// ``` #[no_mangle] pub unsafe extern "C" fn sp_cmd_clear_new() -> NonNull { heap_move_nonnull(ClearCommand) } +/// Deallocates a [ClearCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_clear_free(command: NonNull) { unsafe { heap_drop(command) } @@ -33,6 +28,7 @@ pub unsafe extern "C" fn sp_cmd_hard_reset_new() -> NonNull { heap_move_nonnull(HardResetCommand) } +/// Deallocates a [HardResetCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_hard_reset_free( command: NonNull, @@ -48,6 +44,7 @@ pub unsafe extern "C" fn sp_cmd_fade_out_new() -> NonNull { heap_move_nonnull(FadeOutCommand) } +/// Deallocates a [FadeOutCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_fade_out_free(command: NonNull) { unsafe { heap_drop(command) } diff --git a/src/commands/char_grid_command.rs b/src/commands/char_grid_command.rs index d3f6816..c9e5d9b 100644 --- a/src/commands/char_grid_command.rs +++ b/src/commands/char_grid_command.rs @@ -4,6 +4,11 @@ use crate::mem::{ use servicepoint::{BitmapCommand, CharGrid, CharGridCommand, Origin, Packet}; use std::ptr::NonNull; +/// Show UTF-8 encoded text on the screen. +/// +/// The passed [CharGrid] gets consumed. +/// +/// Returns: a new [CharGridCommand] instance. #[no_mangle] pub unsafe extern "C" fn sp_cmd_char_grid_new( grid: NonNull, @@ -16,6 +21,8 @@ pub unsafe extern "C" fn sp_cmd_char_grid_new( }) } +/// Moves the provided [CharGrid] into a new [CharGridCommand], +/// leaving other fields as their default values. #[no_mangle] pub unsafe extern "C" fn sp_cmd_char_grid_from_grid( grid: NonNull, @@ -30,6 +37,9 @@ pub unsafe extern "C" fn sp_cmd_char_grid_into_packet( heap_move_ok(unsafe { heap_remove(command) }.try_into()) } +/// Clones an [CharGridCommand] instance. +/// +/// returns: a new [CharGridCommand] instance. #[no_mangle] pub unsafe extern "C" fn sp_cmd_char_grid_clone( command: NonNull, @@ -37,6 +47,7 @@ pub unsafe extern "C" fn sp_cmd_char_grid_clone( unsafe { heap_clone(command) } } +/// Deallocates a [BitmapCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_char_grid_free( command: NonNull, diff --git a/src/commands/cp437_grid_command.rs b/src/commands/cp437_grid_command.rs index 2ab4e54..f6b8f9d 100644 --- a/src/commands/cp437_grid_command.rs +++ b/src/commands/cp437_grid_command.rs @@ -6,6 +6,11 @@ use servicepoint::{ }; use std::ptr::NonNull; +/// Show text on the screen. +/// +/// The text is sent in the form of a 2D grid of [CP-437] encoded characters. +/// +/// The origin is relative to the top-left of the display. #[no_mangle] pub unsafe extern "C" fn sp_cmd_cp437_grid_new( grid: NonNull, @@ -18,6 +23,8 @@ pub unsafe extern "C" fn sp_cmd_cp437_grid_new( }) } +/// Moves the provided [Cp437Grid] into a new [Cp437GridCommand], +/// leaving other fields as their default values. #[no_mangle] pub unsafe extern "C" fn sp_cmd_cp437_grid_from_grid( grid: NonNull, @@ -32,6 +39,9 @@ pub unsafe extern "C" fn sp_cmd_cp437_grid_into_packet( heap_move_ok(unsafe { heap_remove(command) }.try_into()) } +/// Clones an [Cp437GridCommand] instance. +/// +/// returns: a new [Cp437GridCommand] instance. #[no_mangle] pub unsafe extern "C" fn sp_cmd_cp437_grid_clone( command: NonNull, @@ -39,6 +49,7 @@ pub unsafe extern "C" fn sp_cmd_cp437_grid_clone( unsafe { heap_clone(command) } } +/// Deallocates a [Cp437GridCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_cp437_grid_free( command: NonNull, @@ -59,6 +70,12 @@ pub unsafe extern "C" fn sp_cmd_cp437_grid_set( } } +/// Show text on the screen. +/// +/// The text is sent in the form of a 2D grid of [CP-437] encoded characters. +/// For sending UTF-8 encoded characters, see [servicepoint::CharGridCommand]. +/// +/// [CP-437]: https://en.wikipedia.org/wiki/Code_page_437 #[no_mangle] pub unsafe extern "C" fn sp_cmd_cp437_grid_get( mut command: NonNull, diff --git a/src/commands/generic_command.rs b/src/commands/generic_command.rs index 59eb8f8..bdeab5e 100644 --- a/src/commands/generic_command.rs +++ b/src/commands/generic_command.rs @@ -1,5 +1,6 @@ use crate::mem::{ - heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, + heap_clone, heap_drop, heap_move, heap_move_nonnull, heap_move_ok, + heap_remove, }; use servicepoint::{ BitVecCommand, BitmapCommand, BrightnessGridCommand, CharGridCommand, @@ -229,7 +230,7 @@ pub unsafe extern "C" fn sp_cmd_generic_clone(command: SPCommand) -> SPCommand { pub unsafe extern "C" fn sp_cmd_generic_free(command: SPCommand) { unsafe { match command.tag { - CommandTag::Invalid => return, + CommandTag::Invalid => (), CommandTag::Bitmap => heap_drop(command.data.bitmap), CommandTag::BitVec => heap_drop(command.data.bitvec), CommandTag::BrightnessGrid => { @@ -273,20 +274,20 @@ pub unsafe extern "C" fn sp_cmd_generic_into_packet( CommandTag::Cp437Grid => heap_move_ok(unsafe { heap_remove(command.data.cp437_grid).try_into() }), - CommandTag::GlobalBrightness => heap_move_ok(unsafe { - heap_remove(command.data.global_brightness).try_into() + CommandTag::GlobalBrightness => heap_move(unsafe { + heap_remove(command.data.global_brightness).into() }), CommandTag::Clear => { - heap_move_ok(unsafe { heap_remove(command.data.clear).try_into() }) + heap_move(unsafe { heap_remove(command.data.clear).into() }) + } + CommandTag::HardReset => { + heap_move(unsafe { heap_remove(command.data.hard_reset).into() }) + } + CommandTag::FadeOut => { + heap_move(unsafe { heap_remove(command.data.fade_out).into() }) + } + CommandTag::BitmapLegacy => { + heap_move(unsafe { heap_remove(command.data.bitmap_legacy).into() }) } - CommandTag::HardReset => heap_move_ok(unsafe { - heap_remove(command.data.hard_reset).try_into() - }), - CommandTag::FadeOut => heap_move_ok(unsafe { - heap_remove(command.data.fade_out).try_into() - }), - CommandTag::BitmapLegacy => heap_move_ok(unsafe { - heap_remove(command.data.bitmap_legacy).try_into() - }), } } diff --git a/src/commands/global_brightness_command.rs b/src/commands/global_brightness_command.rs index 9d1690c..063dea7 100644 --- a/src/commands/global_brightness_command.rs +++ b/src/commands/global_brightness_command.rs @@ -1,11 +1,12 @@ -use crate::mem::{ - heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, -}; +use crate::mem::{heap_clone, heap_drop, heap_move_nonnull, heap_remove}; use servicepoint::{ BitmapCommand, Brightness, GlobalBrightnessCommand, Packet, }; use std::ptr::NonNull; +/// Set the brightness of all tiles to the same value. +/// +/// Returns: a new [GlobalBrightnessCommand] instance. #[no_mangle] pub unsafe extern "C" fn sp_cmd_brightness_global_new( brightness: Brightness, @@ -16,10 +17,13 @@ pub unsafe extern "C" fn sp_cmd_brightness_global_new( #[no_mangle] pub unsafe extern "C" fn sp_cmd_brightness_global_into_packet( command: NonNull, -) -> *mut Packet { - heap_move_ok(unsafe { heap_remove(command) }.try_into()) +) -> NonNull { + heap_move_nonnull(unsafe { heap_remove(command) }.into()) } +/// Clones an [GlobalBrightnessCommand] instance. +/// +/// returns: a new [GlobalBrightnessCommand] instance. #[no_mangle] pub unsafe extern "C" fn sp_cmd_brightness_global_clone( command: NonNull, diff --git a/src/lib.rs b/src/lib.rs index 14b172d..377b2a0 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -25,10 +25,14 @@ //! } //! ``` +/// Functions related to commands. pub mod commands; +/// Functions related to [servicepoint::Bitmap], [servicepoint::CharGrid] and friends. pub mod containers; -pub mod mem; +pub(crate) mod mem; +/// Functions related to [Packet]. pub mod packet; +/// Functions related to [UdpSocket]. pub mod udp; use std::time::Duration; diff --git a/src/packet.rs b/src/packet.rs index 5fe7572..e9593c9 100644 --- a/src/packet.rs +++ b/src/packet.rs @@ -79,6 +79,8 @@ pub unsafe extern "C" fn sp_packet_serialize_to( } /// Clones a [Packet]. +/// +/// returns: a new [Packet] instance. #[no_mangle] pub unsafe extern "C" fn sp_packet_clone( packet: NonNull, -- 2.47.0 From b8a55d0433afef5848b865078345b4c4f47c649a Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Wed, 7 May 2025 22:50:53 +0200 Subject: [PATCH 12/12] even more docs --- example/src/brightness_tester.c | 2 +- include/servicepoint.h | 103 +++++++++++++++++++++--- src/commands/bitmap_command.rs | 12 ++- src/commands/bitvec_command.rs | 14 +++- src/commands/brightness_grid_command.rs | 8 +- src/commands/char_grid_command.rs | 10 ++- src/commands/cp437_grid_command.rs | 5 +- 7 files changed, 133 insertions(+), 21 deletions(-) diff --git a/example/src/brightness_tester.c b/example/src/brightness_tester.c index 9476422..21d814d 100644 --- a/example/src/brightness_tester.c +++ b/example/src/brightness_tester.c @@ -7,7 +7,7 @@ void enable_all_pixels(void) { sp_bitmap_fill(all_on, true); BitmapCommand *bitmapCommand = sp_cmd_bitmap_from_bitmap(all_on); - Packet *packet = sp_cmd_bitmap_into_packet(bitmapCommand); + Packet *packet = sp_cmd_bitmap_try_into_packet(bitmapCommand); if (packet != NULL) sp_udp_send_packet(connection, packet); } diff --git a/include/servicepoint.h b/include/servicepoint.h index a5b3ac7..d5b0199 100644 --- a/include/servicepoint.h +++ b/include/servicepoint.h @@ -1131,6 +1131,9 @@ size_t sp_char_grid_width(CharGrid */*notnull*/ char_grid); */ BitmapCommand */*notnull*/ sp_cmd_bitmap_clone(BitmapCommand */*notnull*/ command); +/** + * Deallocates a [BitmapCommand] instance. + */ void sp_cmd_bitmap_free(BitmapCommand */*notnull*/ command); /** @@ -1151,14 +1154,18 @@ BitmapCommand */*notnull*/ sp_cmd_bitmap_from_bitmap(Bitmap */*notnull*/ bitmap) */ Bitmap */*notnull*/ sp_cmd_bitmap_get(BitmapCommand */*notnull*/ command); +/** + * Reads the compression kind of the [BitmapCommand]. + */ CompressionCode sp_cmd_bitmap_get_compression(BitmapCommand */*notnull*/ command); +/** + * Reads the origin field of the [BitmapCommand]. + */ void sp_cmd_bitmap_get_origin(BitmapCommand */*notnull*/ command, size_t */*notnull*/ origin_x, size_t */*notnull*/ origin_y); -Packet *sp_cmd_bitmap_into_packet(BitmapCommand */*notnull*/ command); - /** * Sets a window of pixels to the specified values. * @@ -1172,18 +1179,31 @@ BitmapCommand */*notnull*/ sp_cmd_bitmap_new(Bitmap */*notnull*/ bitmap, CompressionCode compression); /** - * Moves the provided bitmap to be contained in the command. + * Moves the provided [Bitmap] to be contained in the [BitmapCommand]. */ void sp_cmd_bitmap_set(BitmapCommand */*notnull*/ command, Bitmap */*notnull*/ bitmap); +/** + * Overwrites the compression kind of the [BitmapCommand]. + */ void sp_cmd_bitmap_set_compression(BitmapCommand */*notnull*/ command, CompressionCode compression); +/** + * Overwrites the origin field of the [BitmapCommand]. + */ void sp_cmd_bitmap_set_origin(BitmapCommand */*notnull*/ command, size_t origin_x, size_t origin_y); +/** + * Tries to turn a [BitmapCommand] into a [Packet]. + * + * Returns: NULL or a [Packet] containing the command. + */ +Packet *sp_cmd_bitmap_try_into_packet(BitmapCommand */*notnull*/ command); + /** * Clones an [BitVecCommand] instance. * @@ -1196,16 +1216,26 @@ BitVecCommand */*notnull*/ sp_cmd_bitvec_clone(BitVecCommand */*notnull*/ comman */ void sp_cmd_bitvec_free(BitVecCommand */*notnull*/ command); +/** + * Returns a pointer to the [BitVec] contained in the [BitVecCommand]. + */ BitVec *sp_cmd_bitvec_get(BitVecCommand */*notnull*/ command); +/** + * Reads the compression kind of the [BitVecCommand]. + */ CompressionCode sp_cmd_bitvec_get_compression(BitVecCommand */*notnull*/ command); +/** + * Reads the offset field of the [BitVecCommand]. + */ Offset sp_cmd_bitvec_get_offset(BitVecCommand */*notnull*/ command); +/** + * Returns the [BinaryOperation] of the command. + */ BinaryOperation sp_cmd_bitvec_get_operation(BitVecCommand */*notnull*/ command); -Packet *sp_cmd_bitvec_into_packet(BitVecCommand */*notnull*/ command); - /** * Set pixel data starting at the pixel offset on screen. * @@ -1226,20 +1256,36 @@ BitVecCommand */*notnull*/ sp_cmd_bitvec_new(BitVec */*notnull*/ bitvec, CompressionCode compression); /** - * Moves the provided bitmap to be contained in the command. + * Moves the provided [BitVec] to be contained in the [BitVecCommand]. */ void sp_cmd_bitvec_set(BitVecCommand */*notnull*/ command, BitVec */*notnull*/ bitvec); +/** + * Overwrites the compression kind of the [BitVecCommand]. + */ void sp_cmd_bitvec_set_compression(BitVecCommand */*notnull*/ command, CompressionCode compression); +/** + * Overwrites the offset field of the [BitVecCommand]. + */ void sp_cmd_bitvec_set_offset(BitVecCommand */*notnull*/ command, Offset offset); +/** + * Overwrites the [BinaryOperation] of the command. + */ void sp_cmd_bitvec_set_operation(BitVecCommand */*notnull*/ command, BinaryOperation operation); +/** + * Tries to turn a [BitVecCommand] into a [Packet]. + * + * Returns: NULL or a [Packet] containing the command. + */ +Packet *sp_cmd_bitvec_try_into_packet(BitVecCommand */*notnull*/ command); + /** * Clones an [GlobalBrightnessCommand] instance. * @@ -1284,12 +1330,23 @@ void sp_cmd_brightness_grid_free(BitmapCommand */*notnull*/ command); */ BrightnessGridCommand */*notnull*/ sp_cmd_brightness_grid_from_grid(BrightnessGrid */*notnull*/ grid); +/** + * Returns a pointer to the [BrightnessGrid] contained in the [BrightnessGridCommand]. + */ BrightnessGrid *sp_cmd_brightness_grid_get(BrightnessGridCommand */*notnull*/ command); +/** + * Overwrites the origin field of the [BrightnessGridCommand]. + */ void sp_cmd_brightness_grid_get_origin(BrightnessGridCommand */*notnull*/ command, size_t */*notnull*/ origin_x, size_t */*notnull*/ origin_y); +/** + * Tries to turn a [BrightnessGridCommand] into a [Packet]. + * + * Returns: NULL or a [Packet] containing the command. + */ Packet *sp_cmd_brightness_grid_into_packet(BrightnessGridCommand */*notnull*/ command); /** @@ -1304,11 +1361,14 @@ BrightnessGridCommand */*notnull*/ sp_cmd_brightness_grid_new(BrightnessGrid */* size_t origin_y); /** - * Moves the provided bitmap to be contained in the command. + * Moves the provided [BrightnessGrid] to be contained in the [BrightnessGridCommand]. */ void sp_cmd_brightness_grid_set(BrightnessGridCommand */*notnull*/ command, BrightnessGrid */*notnull*/ grid); +/** + * Reads the origin field of the [BrightnessGridCommand]. + */ void sp_cmd_brightness_grid_set_origin(BrightnessGridCommand */*notnull*/ command, size_t origin_x, size_t origin_y); @@ -1331,14 +1391,18 @@ void sp_cmd_char_grid_free(BitmapCommand */*notnull*/ command); */ CharGridCommand */*notnull*/ sp_cmd_char_grid_from_grid(CharGrid */*notnull*/ grid); +/** + * Returns a pointer to the [CharGrid] contained in the [CharGridCommand]. + */ CharGrid *sp_cmd_char_grid_get(CharGridCommand */*notnull*/ command); +/** + * Reads the origin field of the [CharGridCommand]. + */ void sp_cmd_char_grid_get_origin(CharGridCommand */*notnull*/ command, size_t */*notnull*/ origin_x, size_t */*notnull*/ origin_y); -Packet *sp_cmd_char_grid_into_packet(CharGridCommand */*notnull*/ command); - /** * Show UTF-8 encoded text on the screen. * @@ -1351,15 +1415,25 @@ CharGridCommand */*notnull*/ sp_cmd_char_grid_new(CharGrid */*notnull*/ grid, size_t origin_y); /** - * Moves the provided bitmap to be contained in the command. + * Moves the provided [CharGrid] to be contained in the [CharGridCommand]. */ void sp_cmd_char_grid_set(CharGridCommand */*notnull*/ command, CharGrid */*notnull*/ grid); +/** + * Overwrites the origin field of the [CharGridCommand]. + */ void sp_cmd_char_grid_set_origin(CharGridCommand */*notnull*/ command, size_t origin_x, size_t origin_y); +/** + * Tries to turn a [CharGridCommand] into a [Packet]. + * + * Returns: NULL or a [Packet] containing the command. + */ +Packet *sp_cmd_char_grid_try_into_packet(CharGridCommand */*notnull*/ command); + /** * Deallocates a [ClearCommand]. */ @@ -1411,8 +1485,6 @@ void sp_cmd_cp437_grid_get_origin(Cp437GridCommand */*notnull*/ command, size_t */*notnull*/ origin_x, size_t */*notnull*/ origin_y); -Packet *sp_cmd_cp437_grid_into_packet(Cp437GridCommand */*notnull*/ command); - /** * Show text on the screen. * @@ -1441,6 +1513,13 @@ void sp_cmd_cp437_grid_set_origin(Cp437GridCommand */*notnull*/ command, size_t origin_x, size_t origin_y); +/** + * Tries to turn a [Cp437GridCommand] into a [Packet]. + * + * Returns: NULL or a [Packet] containing the command. + */ +Packet *sp_cmd_cp437_grid_try_into_packet(Cp437GridCommand */*notnull*/ command); + /** * Deallocates a [FadeOutCommand]. */ diff --git a/src/commands/bitmap_command.rs b/src/commands/bitmap_command.rs index 731a644..286a6f1 100644 --- a/src/commands/bitmap_command.rs +++ b/src/commands/bitmap_command.rs @@ -34,8 +34,11 @@ pub unsafe extern "C" fn sp_cmd_bitmap_from_bitmap( heap_move_nonnull(unsafe { heap_remove(bitmap) }.into()) } +/// Tries to turn a [BitmapCommand] into a [Packet]. +/// +/// Returns: NULL or a [Packet] containing the command. #[no_mangle] -pub unsafe extern "C" fn sp_cmd_bitmap_into_packet( +pub unsafe extern "C" fn sp_cmd_bitmap_try_into_packet( command: NonNull, ) -> *mut Packet { heap_move_ok(unsafe { heap_remove(command) }.try_into()) @@ -51,6 +54,7 @@ pub unsafe extern "C" fn sp_cmd_bitmap_clone( unsafe { heap_clone(command) } } +/// Deallocates a [BitmapCommand] instance. #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitmap_free(command: NonNull) { unsafe { heap_drop(command) } @@ -69,7 +73,7 @@ pub unsafe extern "C" fn sp_cmd_bitmap_get( unsafe { NonNull::from(&mut (command.as_mut().bitmap)) } } -/// Moves the provided bitmap to be contained in the command. +/// Moves the provided [Bitmap] to be contained in the [BitmapCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitmap_set( mut command: NonNull, @@ -80,6 +84,7 @@ pub unsafe extern "C" fn sp_cmd_bitmap_set( } } +/// Reads the origin field of the [BitmapCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitmap_get_origin( command: NonNull, @@ -93,6 +98,7 @@ pub unsafe extern "C" fn sp_cmd_bitmap_get_origin( } } +/// Overwrites the origin field of the [BitmapCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitmap_set_origin( mut command: NonNull, @@ -104,6 +110,7 @@ pub unsafe extern "C" fn sp_cmd_bitmap_set_origin( } } +/// Overwrites the compression kind of the [BitmapCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitmap_set_compression( mut command: NonNull, @@ -114,6 +121,7 @@ pub unsafe extern "C" fn sp_cmd_bitmap_set_compression( } } +/// Reads the compression kind of the [BitmapCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitmap_get_compression( command: NonNull, diff --git a/src/commands/bitvec_command.rs b/src/commands/bitvec_command.rs index 7734c05..617e3af 100644 --- a/src/commands/bitvec_command.rs +++ b/src/commands/bitvec_command.rs @@ -34,8 +34,11 @@ pub unsafe extern "C" fn sp_cmd_bitvec_new( }) } +/// Tries to turn a [BitVecCommand] into a [Packet]. +/// +/// Returns: NULL or a [Packet] containing the command. #[no_mangle] -pub unsafe extern "C" fn sp_cmd_bitvec_into_packet( +pub unsafe extern "C" fn sp_cmd_bitvec_try_into_packet( command: NonNull, ) -> *mut Packet { heap_move_ok(unsafe { heap_remove(command) }.try_into()) @@ -57,6 +60,7 @@ pub unsafe extern "C" fn sp_cmd_bitvec_free(command: NonNull) { unsafe { heap_drop(command) } } +/// Returns a pointer to the [BitVec] contained in the [BitVecCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitvec_get( mut command: NonNull, @@ -64,7 +68,7 @@ pub unsafe extern "C" fn sp_cmd_bitvec_get( &mut unsafe { command.as_mut() }.bitvec } -/// Moves the provided bitmap to be contained in the command. +/// Moves the provided [BitVec] to be contained in the [BitVecCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitvec_set( mut command: NonNull, @@ -75,6 +79,7 @@ pub unsafe extern "C" fn sp_cmd_bitvec_set( } } +/// Reads the offset field of the [BitVecCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitvec_get_offset( command: NonNull, @@ -82,6 +87,7 @@ pub unsafe extern "C" fn sp_cmd_bitvec_get_offset( unsafe { command.as_ref().offset } } +/// Overwrites the offset field of the [BitVecCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitvec_set_offset( mut command: NonNull, @@ -92,6 +98,7 @@ pub unsafe extern "C" fn sp_cmd_bitvec_set_offset( } } +/// Returns the [BinaryOperation] of the command. #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitvec_get_operation( command: NonNull, @@ -99,6 +106,7 @@ pub unsafe extern "C" fn sp_cmd_bitvec_get_operation( unsafe { command.as_ref().operation.clone() } // TODO remove clone } +/// Overwrites the [BinaryOperation] of the command. #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitvec_set_operation( mut command: NonNull, @@ -109,6 +117,7 @@ pub unsafe extern "C" fn sp_cmd_bitvec_set_operation( } } +/// Overwrites the compression kind of the [BitVecCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitvec_set_compression( mut command: NonNull, @@ -119,6 +128,7 @@ pub unsafe extern "C" fn sp_cmd_bitvec_set_compression( } } +/// Reads the compression kind of the [BitVecCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitvec_get_compression( command: NonNull, diff --git a/src/commands/brightness_grid_command.rs b/src/commands/brightness_grid_command.rs index aa1caab..80e1b89 100644 --- a/src/commands/brightness_grid_command.rs +++ b/src/commands/brightness_grid_command.rs @@ -32,6 +32,9 @@ pub unsafe extern "C" fn sp_cmd_brightness_grid_from_grid( heap_move_nonnull(unsafe { heap_remove(grid) }.into()) } +/// Tries to turn a [BrightnessGridCommand] into a [Packet]. +/// +/// Returns: NULL or a [Packet] containing the command. #[no_mangle] pub unsafe extern "C" fn sp_cmd_brightness_grid_into_packet( command: NonNull, @@ -57,7 +60,7 @@ pub unsafe extern "C" fn sp_cmd_brightness_grid_free( unsafe { heap_drop(command) } } -/// Moves the provided bitmap to be contained in the command. +/// Moves the provided [BrightnessGrid] to be contained in the [BrightnessGridCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_brightness_grid_set( mut command: NonNull, @@ -68,6 +71,7 @@ pub unsafe extern "C" fn sp_cmd_brightness_grid_set( } } +/// Returns a pointer to the [BrightnessGrid] contained in the [BrightnessGridCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_brightness_grid_get( mut command: NonNull, @@ -75,6 +79,7 @@ pub unsafe extern "C" fn sp_cmd_brightness_grid_get( &mut unsafe { command.as_mut() }.grid } +/// Overwrites the origin field of the [BrightnessGridCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_brightness_grid_get_origin( command: NonNull, @@ -88,6 +93,7 @@ pub unsafe extern "C" fn sp_cmd_brightness_grid_get_origin( } } +/// Reads the origin field of the [BrightnessGridCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_brightness_grid_set_origin( mut command: NonNull, diff --git a/src/commands/char_grid_command.rs b/src/commands/char_grid_command.rs index c9e5d9b..8a220a5 100644 --- a/src/commands/char_grid_command.rs +++ b/src/commands/char_grid_command.rs @@ -30,8 +30,11 @@ pub unsafe extern "C" fn sp_cmd_char_grid_from_grid( heap_move_nonnull(unsafe { heap_remove(grid) }.into()) } +/// Tries to turn a [CharGridCommand] into a [Packet]. +/// +/// Returns: NULL or a [Packet] containing the command. #[no_mangle] -pub unsafe extern "C" fn sp_cmd_char_grid_into_packet( +pub unsafe extern "C" fn sp_cmd_char_grid_try_into_packet( command: NonNull, ) -> *mut Packet { heap_move_ok(unsafe { heap_remove(command) }.try_into()) @@ -55,7 +58,7 @@ pub unsafe extern "C" fn sp_cmd_char_grid_free( unsafe { heap_drop(command) } } -/// Moves the provided bitmap to be contained in the command. +/// Moves the provided [CharGrid] to be contained in the [CharGridCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_char_grid_set( mut command: NonNull, @@ -66,6 +69,7 @@ pub unsafe extern "C" fn sp_cmd_char_grid_set( } } +/// Returns a pointer to the [CharGrid] contained in the [CharGridCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_char_grid_get( mut command: NonNull, @@ -73,6 +77,7 @@ pub unsafe extern "C" fn sp_cmd_char_grid_get( &mut unsafe { command.as_mut() }.grid } +/// Reads the origin field of the [CharGridCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_char_grid_get_origin( command: NonNull, @@ -86,6 +91,7 @@ pub unsafe extern "C" fn sp_cmd_char_grid_get_origin( } } +/// Overwrites the origin field of the [CharGridCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_char_grid_set_origin( mut command: NonNull, diff --git a/src/commands/cp437_grid_command.rs b/src/commands/cp437_grid_command.rs index f6b8f9d..f653ef5 100644 --- a/src/commands/cp437_grid_command.rs +++ b/src/commands/cp437_grid_command.rs @@ -32,8 +32,11 @@ pub unsafe extern "C" fn sp_cmd_cp437_grid_from_grid( heap_move_nonnull(unsafe { heap_remove(grid) }.into()) } +/// Tries to turn a [Cp437GridCommand] into a [Packet]. +/// +/// Returns: NULL or a [Packet] containing the command. #[no_mangle] -pub unsafe extern "C" fn sp_cmd_cp437_grid_into_packet( +pub unsafe extern "C" fn sp_cmd_cp437_grid_try_into_packet( command: NonNull, ) -> *mut Packet { heap_move_ok(unsafe { heap_remove(command) }.try_into()) -- 2.47.0