diff --git a/cbindgen.toml b/cbindgen.toml index 7841755..4aabb7e 100644 --- a/cbindgen.toml +++ b/cbindgen.toml @@ -35,8 +35,8 @@ include = [] exclude = ["BitVec"] [export.rename] -"SPCommand" = "Command" -"DisplayBitVec" = "BitVec" +"SpByteSlice" = "ByteSlice" +"SpCommand" = "Command" [enum] rename_variants = "QualifiedScreamingSnakeCase" diff --git a/include/servicepoint.h b/include/servicepoint.h index d5b0199..ec722f5 100644 --- a/include/servicepoint.h +++ b/include/servicepoint.h @@ -125,11 +125,6 @@ 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 @@ -346,7 +341,7 @@ typedef struct Cp437GridCommand Cp437GridCommand; /** * This is a type only used by cbindgen to have a type for pointers. */ -typedef struct BitVec BitVec; +typedef struct DisplayBitVec DisplayBitVec; /** *
Untested
@@ -536,9 +531,6 @@ typedef size_t Offset; */ typedef ValueGrid_u8 Cp437Grid; -/** - * Pointer to one of the available command structs. - */ typedef union { uint8_t *null; BitmapCommand */*notnull*/ bitmap; @@ -553,13 +545,6 @@ 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` @@ -569,7 +554,7 @@ typedef struct { * The pointer to the command struct */ CommandUnion data; -} Command; +} SPCommand; /** * A raw header. @@ -637,7 +622,7 @@ void sp_bitmap_free(Bitmap */*notnull*/ bitmap); * * Returns NULL in case of error. */ -Bitmap *sp_bitmap_from_bitvec(size_t width, BitVec */*notnull*/ bitvec); +Bitmap *sp_bitmap_from_bitvec(size_t width, DisplayBitVec */*notnull*/ bitvec); /** * Gets the current value at the specified position in the [Bitmap]. @@ -665,7 +650,7 @@ size_t sp_bitmap_height(Bitmap */*notnull*/ bitmap); /** * Consumes the Bitmap and returns the contained BitVec */ -BitVec */*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]. @@ -769,27 +754,27 @@ ByteSlice sp_bitmap_unsafe_data_ref(Bitmap */*notnull*/ bitmap); size_t sp_bitmap_width(Bitmap */*notnull*/ bitmap); /** - * Clones a [DisplayBitVec]. + * Clones a [SPBitVec]. */ -BitVec */*notnull*/ sp_bitvec_clone(BitVec */*notnull*/ bit_vec); +DisplayBitVec */*notnull*/ sp_bitvec_clone(DisplayBitVec */*notnull*/ bit_vec); /** - * Sets the value of all bits in the [DisplayBitVec]. + * Sets the value of all bits in the [SPBitVec]. * * # Arguments * * - `bit_vec`: instance to write to * - `value`: the value to set all bits to */ -void sp_bitvec_fill(BitVec */*notnull*/ bit_vec, bool value); +void sp_bitvec_fill(DisplayBitVec */*notnull*/ bit_vec, bool value); /** - * Deallocates a [DisplayBitVec]. + * Deallocates a [SPBitVec]. */ -void sp_bitvec_free(BitVec */*notnull*/ bit_vec); +void sp_bitvec_free(DisplayBitVec */*notnull*/ bit_vec); /** - * Gets the value of a bit from the [DisplayBitVec]. + * Gets the value of a bit from the [SPBitVec]. * * # Arguments * @@ -802,16 +787,16 @@ void sp_bitvec_free(BitVec */*notnull*/ bit_vec); * * - when accessing `index` out of bounds */ -bool sp_bitvec_get(BitVec */*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]. * - * The provided [DisplayBitVec] gets consumed. + * The provided [SPBitVec] gets consumed. * * Returns NULL in case of an error. */ -Packet *sp_bitvec_into_packet(BitVec */*notnull*/ bitvec, +Packet *sp_bitvec_into_packet(DisplayBitVec */*notnull*/ bitvec, size_t offset, BinaryOperation operation, CompressionCode compression); @@ -823,41 +808,41 @@ Packet *sp_bitvec_into_packet(BitVec */*notnull*/ bitvec, * * - `bit_vec`: instance to write to */ -bool sp_bitvec_is_empty(BitVec */*notnull*/ bit_vec); +bool sp_bitvec_is_empty(DisplayBitVec */*notnull*/ bit_vec); /** - * Gets the length of the [DisplayBitVec] in bits. + * Gets the length of the [SPBitVec] in bits. * * # Arguments * * - `bit_vec`: instance to write to */ -size_t sp_bitvec_len(BitVec */*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 [DisplayBitVec] instance. + * Interpret the data as a series of bits and load then into a new [SPBitVec] instance. * - * returns: [DisplayBitVec] instance containing data. + * returns: [SPBitVec] instance containing data. */ -BitVec */*notnull*/ sp_bitvec_load(ByteSlice data); +DisplayBitVec */*notnull*/ sp_bitvec_load(ByteSlice data); /** - * Creates a new [DisplayBitVec] instance. + * Creates a new [SPBitVec] instance. * * # Arguments * * - `size`: size in bits. * - * returns: [DisplayBitVec] with all bits set to false. + * returns: [SPBitVec] with all bits set to false. * * # Panics * * - when `size` is not divisible by 8. */ -BitVec */*notnull*/ sp_bitvec_new(size_t size); +DisplayBitVec */*notnull*/ sp_bitvec_new(size_t size); /** - * Sets the value of a bit in the [DisplayBitVec]. + * Sets the value of a bit in the [SPBitVec]. * * # Arguments * @@ -869,10 +854,12 @@ BitVec */*notnull*/ sp_bitvec_new(size_t size); * * - when accessing `index` out of bounds */ -void sp_bitvec_set(BitVec */*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 [DisplayBitVec] instance. + * Gets an unsafe reference to the data of the [SPBitVec] instance. * * The returned memory is valid for the lifetime of the bitvec. * @@ -880,7 +867,7 @@ void sp_bitvec_set(BitVec */*notnull*/ bit_vec, size_t index, bool value); * * - `bit_vec`: instance to write to */ -ByteSlice sp_bitvec_unsafe_data_ref(BitVec */*notnull*/ bit_vec); +ByteSlice sp_bitvec_unsafe_data_ref(DisplayBitVec */*notnull*/ bit_vec); /** * Clones a [BrightnessGrid]. @@ -1124,23 +1111,15 @@ 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); -/** - * Deallocates a [BitmapCommand] instance. - */ 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: `BitmapCommand::from(bitmap)` + * Rust equivalent: [`>::from`] */ BitmapCommand */*notnull*/ sp_cmd_bitmap_from_bitmap(Bitmap */*notnull*/ bitmap); @@ -1154,18 +1133,14 @@ 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. * @@ -1179,63 +1154,32 @@ BitmapCommand */*notnull*/ sp_cmd_bitmap_new(Bitmap */*notnull*/ bitmap, CompressionCode compression); /** - * Moves the provided [Bitmap] to be contained in the [BitmapCommand]. + * Moves the provided bitmap to be contained in the command. */ 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. - * - * 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); -/** - * Returns a pointer to the [BitVec] contained in the [BitVecCommand]. - */ -BitVec *sp_cmd_bitvec_get(BitVecCommand */*notnull*/ command); +DisplayBitVec *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. * @@ -1250,60 +1194,34 @@ BinaryOperation sp_cmd_bitvec_get_operation(BitVecCommand */*notnull*/ command); * * The contained [`DisplayBitVec`] is always uncompressed. */ -BitVecCommand */*notnull*/ sp_cmd_bitvec_new(BitVec */*notnull*/ bitvec, +BitVecCommand */*notnull*/ sp_cmd_bitvec_new(DisplayBitVec */*notnull*/ bitvec, size_t offset, BinaryOperation operation, CompressionCode compression); /** - * Moves the provided [BitVec] to be contained in the [BitVecCommand]. + * Moves the provided bitmap to be contained in the command. */ void sp_cmd_bitvec_set(BitVecCommand */*notnull*/ command, - BitVec */*notnull*/ bitvec); + DisplayBitVec */*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. - * - * 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 */*notnull*/ sp_cmd_brightness_global_into_packet(GlobalBrightnessCommand */*notnull*/ command); +Packet *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); /** @@ -1312,131 +1230,62 @@ 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); -/** - * 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); -/** - * 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); /** - * Moves the provided [BrightnessGrid] to be contained in the [BrightnessGridCommand]. + * Moves the provided bitmap to be contained in the command. */ 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); -/** - * 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); -/** - * 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); -/** - * Show UTF-8 encoded text on the screen. - * - * The passed [CharGrid] gets consumed. - * - * Returns: a new [CharGridCommand] instance. - */ +Packet *sp_cmd_char_grid_into_packet(CharGridCommand */*notnull*/ command); + CharGridCommand */*notnull*/ sp_cmd_char_grid_new(CharGrid */*notnull*/ grid, size_t origin_x, size_t origin_y); /** - * Moves the provided [CharGrid] to be contained in the [CharGridCommand]. + * Moves the provided bitmap to be contained in the command. */ 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]. - */ void sp_cmd_clear_free(ClearCommand */*notnull*/ command); /** @@ -1445,84 +1294,43 @@ 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); -/** - * 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); -/** - * 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. - */ +Packet *sp_cmd_cp437_grid_into_packet(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 into the provided command. - * - * This drops the previously contained [Cp437Grid]. + * Moves the provided bitmap to be contained in the command. */ 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); -/** - * 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]. - */ void sp_cmd_fade_out_free(ClearCommand */*notnull*/ command); /** @@ -1533,44 +1341,32 @@ void sp_cmd_fade_out_free(ClearCommand */*notnull*/ command); FadeOutCommand */*notnull*/ sp_cmd_fade_out_new(void); /** - * Clones an [SPCommand] instance. + * Clones a [SPCommand] instance. * - * returns: a new [SPCommand] instance. + * returns: new [SPCommand] instance. */ -Command sp_cmd_generic_clone(Command command); +SPCommand sp_cmd_generic_clone(SPCommand command); /** - * Deallocates an [SPCommand]. + * Deallocates a [SPCommand]. * * # Examples * * ```C - * SPCommand c = sp_cmd_clear_into_generic(sp_cmd_clear_new()); + * TypedCommand c = sp_command_clear(); * sp_command_free(c); * ``` */ -void sp_cmd_generic_free(Command command); +void sp_cmd_generic_free(SPCommand command); /** - * Tries to turn a [SPCommand] into a [Packet]. - * The [SPCommand] gets consumed. + * Turns a [TypedCommand] into a [Packet]. + * The [TypedCommand] gets consumed. * - * Returns tag [CommandTag::Invalid] in case of an error. + * Returns NULL in case of an error. */ -Packet *sp_cmd_generic_into_packet(Command command); +Packet *sp_cmd_generic_into_packet(SPCommand command); -/** - * Tries to turn a [Packet] into a [SPCommand]. - * - * The packet is dropped in the process. - * - * Returns: pointer to new [SPCommand] instance or NULL if parsing failed. - */ -Command *sp_cmd_generic_try_from_packet(Packet */*notnull*/ packet); - -/** - * Deallocates a [HardResetCommand]. - */ void sp_cmd_hard_reset_free(ClearCommand */*notnull*/ command); /** @@ -1688,8 +1484,6 @@ 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); @@ -1791,7 +1585,7 @@ UdpSocket *sp_udp_open_ipv4(uint8_t ip1, uint16_t port); /** - * Sends a [SPCommand] to the display using the [UdpSocket]. + * Sends a [TypedCommand] to the display using the [UdpSocket]. * * The passed `command` gets consumed. * @@ -1803,7 +1597,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, Command command); +bool sp_udp_send_command(UdpSocket */*notnull*/ connection, SPCommand command); /** * Sends a [Header] to the display using the [UdpSocket]. diff --git a/src/containers/bitmap.rs b/src/bitmap.rs similarity index 95% rename from src/containers/bitmap.rs rename to src/bitmap.rs index 7a1b633..3393671 100644 --- a/src/containers/bitmap.rs +++ b/src/bitmap.rs @@ -1,13 +1,6 @@ -use crate::{ - containers::ByteSlice, - mem::{ - 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, DisplayBitVec, Grid, - Origin, Packet, + Bitmap, BitmapCommand, CompressionCode, DataRef, Grid, Origin, Packet, DisplayBitVec }; use std::ptr::NonNull; diff --git a/src/containers/bitvec.rs b/src/bitvec.rs similarity index 82% rename from src/containers/bitvec.rs rename to src/bitvec.rs index e9eeb68..1ba49a7 100644 --- a/src/containers/bitvec.rs +++ b/src/bitvec.rs @@ -1,21 +1,19 @@ use crate::{ - containers::ByteSlice, - mem::{ - heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, - }, + byte_slice::ByteSlice, heap_clone, heap_drop, heap_move_nonnull, + heap_move_ok, heap_remove, }; use servicepoint::{ BinaryOperation, BitVecCommand, CompressionCode, DisplayBitVec, Packet, }; use std::ptr::NonNull; -/// Creates a new [DisplayBitVec] instance. +/// Creates a new [SPBitVec] instance. /// /// # Arguments /// /// - `size`: size in bits. /// -/// returns: [DisplayBitVec] with all bits set to false. +/// returns: [SPBitVec] with all bits set to false. /// /// # Panics /// @@ -25,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 [DisplayBitVec] instance. +/// Interpret the data as a series of bits and load then into a new [SPBitVec] instance. /// -/// returns: [DisplayBitVec] instance containing data. +/// returns: [SPBitVec] instance containing data. #[no_mangle] pub unsafe extern "C" fn sp_bitvec_load( data: ByteSlice, @@ -36,7 +34,7 @@ pub unsafe extern "C" fn sp_bitvec_load( heap_move_nonnull(DisplayBitVec::from_slice(data)) } -/// Clones a [DisplayBitVec]. +/// Clones a [SPBitVec]. #[no_mangle] pub unsafe extern "C" fn sp_bitvec_clone( bit_vec: NonNull, @@ -44,13 +42,13 @@ pub unsafe extern "C" fn sp_bitvec_clone( unsafe { heap_clone(bit_vec) } } -/// Deallocates a [DisplayBitVec]. +/// Deallocates a [SPBitVec]. #[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 [DisplayBitVec]. +/// Gets the value of a bit from the [SPBitVec]. /// /// # Arguments /// @@ -70,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 [DisplayBitVec]. +/// Sets the value of a bit in the [SPBitVec]. /// /// # Arguments /// @@ -90,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 [DisplayBitVec]. +/// Sets the value of all bits in the [SPBitVec]. /// /// # Arguments /// @@ -104,7 +102,7 @@ pub unsafe extern "C" fn sp_bitvec_fill( unsafe { (*bit_vec.as_ptr()).fill(value) } } -/// Gets the length of the [DisplayBitVec] in bits. +/// Gets the length of the [SPBitVec] in bits. /// /// # Arguments /// @@ -128,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 [DisplayBitVec] instance. +/// Gets an unsafe reference to the data of the [SPBitVec] instance. /// /// The returned memory is valid for the lifetime of the bitvec. /// @@ -144,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 [DisplayBitVec] gets consumed. +/// The provided [SPBitVec] gets consumed. /// /// Returns NULL in case of an error. #[no_mangle] diff --git a/src/containers/brightness_grid.rs b/src/brightness_grid.rs similarity index 97% rename from src/containers/brightness_grid.rs rename to src/brightness_grid.rs index 3a7ae5f..dc3b2f7 100644 --- a/src/containers/brightness_grid.rs +++ b/src/brightness_grid.rs @@ -1,9 +1,6 @@ use crate::{ - containers::ByteSlice, - mem::{ - heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_move_some, - heap_remove, - }, + 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, diff --git a/src/containers/byte_slice.rs b/src/byte_slice.rs similarity index 100% rename from src/containers/byte_slice.rs rename to src/byte_slice.rs diff --git a/src/containers/char_grid.rs b/src/char_grid.rs similarity index 96% rename from src/containers/char_grid.rs rename to src/char_grid.rs index 3363d43..62aba87 100644 --- a/src/containers/char_grid.rs +++ b/src/char_grid.rs @@ -1,8 +1,6 @@ use crate::{ - containers::ByteSlice, - mem::{ - heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, - }, + 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; diff --git a/src/commands/bitmap_command.rs b/src/commands/bitmap_command.rs index 286a6f1..b2ff3d8 100644 --- a/src/commands/bitmap_command.rs +++ b/src/commands/bitmap_command.rs @@ -1,4 +1,4 @@ -use crate::mem::{ +use crate::{ heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, }; use servicepoint::{Bitmap, BitmapCommand, CompressionCode, Origin, Packet}; @@ -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: `BitmapCommand::from(bitmap)` +/// Rust equivalent: [`>::from`] #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitmap_from_bitmap( bitmap: NonNull, @@ -34,19 +34,13 @@ 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_try_into_packet( +pub unsafe extern "C" fn sp_cmd_bitmap_into_packet( command: NonNull, ) -> *mut 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, @@ -54,7 +48,6 @@ 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) } @@ -73,7 +66,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 [BitmapCommand]. +/// Moves the provided bitmap to be contained in the command. #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitmap_set( mut command: NonNull, @@ -84,7 +77,6 @@ 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, @@ -98,7 +90,6 @@ 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, @@ -110,7 +101,6 @@ 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, @@ -121,7 +111,6 @@ 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 617e3af..bfe2d33 100644 --- a/src/commands/bitvec_command.rs +++ b/src/commands/bitvec_command.rs @@ -1,4 +1,4 @@ -use crate::mem::{ +use crate::{ heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, }; use servicepoint::{ @@ -34,19 +34,13 @@ 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_try_into_packet( +pub unsafe extern "C" fn sp_cmd_bitvec_into_packet( command: NonNull, ) -> *mut 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, @@ -54,13 +48,11 @@ 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) } } -/// Returns a pointer to the [BitVec] contained in the [BitVecCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitvec_get( mut command: NonNull, @@ -68,7 +60,7 @@ pub unsafe extern "C" fn sp_cmd_bitvec_get( &mut unsafe { command.as_mut() }.bitvec } -/// Moves the provided [BitVec] to be contained in the [BitVecCommand]. +/// Moves the provided bitmap to be contained in the command. #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitvec_set( mut command: NonNull, @@ -79,7 +71,6 @@ 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, @@ -87,7 +78,6 @@ 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, @@ -98,7 +88,6 @@ 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, @@ -106,7 +95,6 @@ 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, @@ -117,7 +105,6 @@ 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, @@ -128,7 +115,6 @@ 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 80e1b89..bd975d6 100644 --- a/src/commands/brightness_grid_command.rs +++ b/src/commands/brightness_grid_command.rs @@ -1,4 +1,4 @@ -use crate::mem::{ +use crate::{ heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, }; use servicepoint::{ @@ -6,11 +6,6 @@ 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, @@ -23,8 +18,6 @@ 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,9 +25,6 @@ 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, @@ -42,9 +32,6 @@ 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, @@ -52,7 +39,6 @@ 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, @@ -60,7 +46,7 @@ pub unsafe extern "C" fn sp_cmd_brightness_grid_free( unsafe { heap_drop(command) } } -/// Moves the provided [BrightnessGrid] to be contained in the [BrightnessGridCommand]. +/// 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, @@ -71,7 +57,6 @@ 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, @@ -79,7 +64,6 @@ 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, @@ -93,7 +77,6 @@ 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/cc_only_commands.rs b/src/commands/cc_only_commands.rs index 2a48c12..751a6ab 100644 --- a/src/commands/cc_only_commands.rs +++ b/src/commands/cc_only_commands.rs @@ -1,4 +1,4 @@ -use crate::mem::{heap_drop, heap_move_nonnull}; +use crate::{heap_drop, heap_move_nonnull}; use servicepoint::{ClearCommand, FadeOutCommand, HardResetCommand}; use std::ptr::NonNull; @@ -7,12 +7,17 @@ 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) } @@ -28,7 +33,6 @@ 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, @@ -44,7 +48,6 @@ 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 8a220a5..bc078cd 100644 --- a/src/commands/char_grid_command.rs +++ b/src/commands/char_grid_command.rs @@ -1,14 +1,9 @@ -use crate::mem::{ +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; -/// 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, @@ -21,8 +16,6 @@ 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,19 +23,13 @@ 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_try_into_packet( +pub unsafe extern "C" fn sp_cmd_char_grid_into_packet( command: NonNull, ) -> *mut 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, @@ -50,7 +37,6 @@ 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, @@ -58,7 +44,7 @@ pub unsafe extern "C" fn sp_cmd_char_grid_free( unsafe { heap_drop(command) } } -/// Moves the provided [CharGrid] to be contained in the [CharGridCommand]. +/// 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, @@ -69,7 +55,6 @@ 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, @@ -77,7 +62,6 @@ 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, @@ -91,7 +75,6 @@ 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 f653ef5..1e1598a 100644 --- a/src/commands/cp437_grid_command.rs +++ b/src/commands/cp437_grid_command.rs @@ -1,4 +1,4 @@ -use crate::mem::{ +use crate::{ heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove, }; use servicepoint::{ @@ -6,11 +6,6 @@ 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, @@ -23,8 +18,6 @@ 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,19 +25,13 @@ 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_try_into_packet( +pub unsafe extern "C" fn sp_cmd_cp437_grid_into_packet( command: NonNull, ) -> *mut 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, @@ -52,7 +39,6 @@ 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, @@ -60,9 +46,7 @@ pub unsafe extern "C" fn sp_cmd_cp437_grid_free( unsafe { heap_drop(command) } } -/// Moves the provided bitmap into the provided command. -/// -/// This drops the previously contained [Cp437Grid]. +/// 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, @@ -73,12 +57,6 @@ 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, @@ -86,9 +64,6 @@ 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, @@ -102,9 +77,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)` #[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 bdeab5e..e3da8fd 100644 --- a/src/commands/generic_command.rs +++ b/src/commands/generic_command.rs @@ -1,17 +1,14 @@ -use crate::mem::{ - heap_clone, heap_drop, heap_move, heap_move_nonnull, heap_move_ok, - heap_remove, +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}; -/// Pointer to one of the available command structs. #[repr(C)] -#[allow(missing_docs)] pub union CommandUnion { pub null: *mut u8, pub bitmap: NonNull, @@ -27,11 +24,7 @@ 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, @@ -46,11 +39,6 @@ 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` @@ -66,12 +54,12 @@ impl SPCommand { }; } -/// Tries to turn a [Packet] into a [SPCommand]. +/// Tries to turn a [Packet] into a [TypedCommand]. /// -/// The packet is dropped in the process. +/// The packet is deallocated in the process. /// -/// Returns: pointer to new [SPCommand] instance or NULL if parsing failed. -#[no_mangle] +/// 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 { @@ -143,9 +131,9 @@ pub unsafe extern "C" fn sp_cmd_generic_try_from_packet( })) } -/// Clones an [SPCommand] instance. +/// Clones a [SPCommand] instance. /// -/// returns: a new [SPCommand] instance. +/// returns: new [SPCommand] instance. #[no_mangle] pub unsafe extern "C" fn sp_cmd_generic_clone(command: SPCommand) -> SPCommand { unsafe { @@ -218,19 +206,19 @@ pub unsafe extern "C" fn sp_cmd_generic_clone(command: SPCommand) -> SPCommand { } } -/// Deallocates an [SPCommand]. +/// Deallocates a [SPCommand]. /// /// # Examples /// /// ```C -/// SPCommand c = sp_cmd_clear_into_generic(sp_cmd_clear_new()); +/// 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 => (), + CommandTag::Invalid => return, CommandTag::Bitmap => heap_drop(command.data.bitmap), CommandTag::BitVec => heap_drop(command.data.bitvec), CommandTag::BrightnessGrid => { @@ -249,10 +237,10 @@ pub unsafe extern "C" fn sp_cmd_generic_free(command: SPCommand) { } } -/// Tries to turn a [SPCommand] into a [Packet]. -/// The [SPCommand] gets consumed. +/// Turns a [TypedCommand] into a [Packet]. +/// The [TypedCommand] gets consumed. /// -/// Returns tag [CommandTag::Invalid] in case of an error. +/// Returns NULL in case of an error. #[no_mangle] pub unsafe extern "C" fn sp_cmd_generic_into_packet( command: SPCommand, @@ -274,20 +262,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(unsafe { - heap_remove(command.data.global_brightness).into() + CommandTag::GlobalBrightness => heap_move_ok(unsafe { + heap_remove(command.data.global_brightness).try_into() }), CommandTag::Clear => { - 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() }) + 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 index 063dea7..29e7c19 100644 --- a/src/commands/global_brightness_command.rs +++ b/src/commands/global_brightness_command.rs @@ -1,12 +1,11 @@ -use crate::mem::{heap_clone, heap_drop, heap_move_nonnull, heap_remove}; +use crate::{ + heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, 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, @@ -17,13 +16,10 @@ 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, -) -> NonNull { - heap_move_nonnull(unsafe { heap_remove(command) }.into()) +) -> *mut Packet { + heap_move_ok(unsafe { heap_remove(command) }.try_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/containers/mod.rs b/src/containers/mod.rs deleted file mode 100644 index 62d51d0..0000000 --- a/src/containers/mod.rs +++ /dev/null @@ -1,13 +0,0 @@ -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/containers/cp437_grid.rs b/src/cp437_grid.rs similarity index 96% rename from src/containers/cp437_grid.rs rename to src/cp437_grid.rs index a636295..b4d449e 100644 --- a/src/containers/cp437_grid.rs +++ b/src/cp437_grid.rs @@ -1,9 +1,6 @@ use crate::{ - containers::ByteSlice, - mem::{ - heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_move_some, - heap_remove, - }, + 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, diff --git a/src/lib.rs b/src/lib.rs index 377b2a0..de22866 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -25,14 +25,16 @@ //! } //! ``` -/// Functions related to commands. +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; -/// Functions related to [servicepoint::Bitmap], [servicepoint::CharGrid] and friends. -pub mod containers; -pub(crate) mod mem; -/// Functions related to [Packet]. +pub mod cp437_grid; pub mod packet; -/// Functions related to [UdpSocket]. pub mod udp; use std::time::Duration; @@ -40,6 +42,34 @@ 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 deleted file mode 100644 index 6555999..0000000 --- a/src/mem.rs +++ /dev/null @@ -1,29 +0,0 @@ -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 e9593c9..16509be 100644 --- a/src/packet.rs +++ b/src/packet.rs @@ -1,6 +1,6 @@ use crate::{ - containers::ByteSlice, - mem::{heap_clone, heap_drop, heap_move_nonnull, heap_move_ok}, + byte_slice::ByteSlice, heap_clone, heap_drop, heap_move_nonnull, + heap_move_ok, }; use servicepoint::{CommandCode, Header, Packet}; use std::ptr::NonNull; @@ -79,8 +79,6 @@ 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, diff --git a/src/udp.rs b/src/udp.rs index 7c2ab2f..7b659cf 100644 --- a/src/udp.rs +++ b/src/udp.rs @@ -1,13 +1,9 @@ -use crate::{ - commands::{CommandTag, SPCommand}, - mem::{heap_drop, heap_move_ok, heap_remove}, -}; +use crate::commands::{CommandTag, SPCommand}; +use crate::{heap_drop, heap_move_ok, heap_remove}; use servicepoint::{Header, Packet, UdpSocketExt}; -use std::{ - ffi::{c_char, CStr}, - net::{Ipv4Addr, SocketAddrV4, UdpSocket}, - ptr::NonNull, -}; +use std::ffi::{c_char, CStr}; +use std::net::{Ipv4Addr, SocketAddrV4, UdpSocket}; +use std::ptr::NonNull; /// Creates a new instance of [UdpSocket]. /// @@ -66,7 +62,7 @@ pub unsafe extern "C" fn sp_udp_send_packet( unsafe { connection.as_ref().send(&Vec::from(packet)) }.is_ok() } -/// Sends a [SPCommand] to the display using the [UdpSocket]. +/// Sends a [TypedCommand] to the display using the [UdpSocket]. /// /// The passed `command` gets consumed. ///