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. ///