From 36f3d84dc8e8f9aa07b384a5e98d4a0303876abe Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Wed, 7 May 2025 22:27:06 +0200 Subject: [PATCH] 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,