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,