diff --git a/example/src/brightness_tester.c b/example/src/brightness_tester.c index 9476422..21d814d 100644 --- a/example/src/brightness_tester.c +++ b/example/src/brightness_tester.c @@ -7,7 +7,7 @@ void enable_all_pixels(void) { sp_bitmap_fill(all_on, true); BitmapCommand *bitmapCommand = sp_cmd_bitmap_from_bitmap(all_on); - Packet *packet = sp_cmd_bitmap_into_packet(bitmapCommand); + Packet *packet = sp_cmd_bitmap_try_into_packet(bitmapCommand); if (packet != NULL) sp_udp_send_packet(connection, packet); } diff --git a/include/servicepoint.h b/include/servicepoint.h index a5b3ac7..d5b0199 100644 --- a/include/servicepoint.h +++ b/include/servicepoint.h @@ -1131,6 +1131,9 @@ size_t sp_char_grid_width(CharGrid */*notnull*/ char_grid); */ BitmapCommand */*notnull*/ sp_cmd_bitmap_clone(BitmapCommand */*notnull*/ command); +/** + * Deallocates a [BitmapCommand] instance. + */ void sp_cmd_bitmap_free(BitmapCommand */*notnull*/ command); /** @@ -1151,14 +1154,18 @@ BitmapCommand */*notnull*/ sp_cmd_bitmap_from_bitmap(Bitmap */*notnull*/ bitmap) */ Bitmap */*notnull*/ sp_cmd_bitmap_get(BitmapCommand */*notnull*/ command); +/** + * Reads the compression kind of the [BitmapCommand]. + */ CompressionCode sp_cmd_bitmap_get_compression(BitmapCommand */*notnull*/ command); +/** + * Reads the origin field of the [BitmapCommand]. + */ void sp_cmd_bitmap_get_origin(BitmapCommand */*notnull*/ command, size_t */*notnull*/ origin_x, size_t */*notnull*/ origin_y); -Packet *sp_cmd_bitmap_into_packet(BitmapCommand */*notnull*/ command); - /** * Sets a window of pixels to the specified values. * @@ -1172,18 +1179,31 @@ BitmapCommand */*notnull*/ sp_cmd_bitmap_new(Bitmap */*notnull*/ bitmap, CompressionCode compression); /** - * Moves the provided bitmap to be contained in the command. + * Moves the provided [Bitmap] to be contained in the [BitmapCommand]. */ void sp_cmd_bitmap_set(BitmapCommand */*notnull*/ command, Bitmap */*notnull*/ bitmap); +/** + * Overwrites the compression kind of the [BitmapCommand]. + */ void sp_cmd_bitmap_set_compression(BitmapCommand */*notnull*/ command, CompressionCode compression); +/** + * Overwrites the origin field of the [BitmapCommand]. + */ void sp_cmd_bitmap_set_origin(BitmapCommand */*notnull*/ command, size_t origin_x, size_t origin_y); +/** + * Tries to turn a [BitmapCommand] into a [Packet]. + * + * Returns: NULL or a [Packet] containing the command. + */ +Packet *sp_cmd_bitmap_try_into_packet(BitmapCommand */*notnull*/ command); + /** * Clones an [BitVecCommand] instance. * @@ -1196,16 +1216,26 @@ BitVecCommand */*notnull*/ sp_cmd_bitvec_clone(BitVecCommand */*notnull*/ comman */ void sp_cmd_bitvec_free(BitVecCommand */*notnull*/ command); +/** + * Returns a pointer to the [BitVec] contained in the [BitVecCommand]. + */ BitVec *sp_cmd_bitvec_get(BitVecCommand */*notnull*/ command); +/** + * Reads the compression kind of the [BitVecCommand]. + */ CompressionCode sp_cmd_bitvec_get_compression(BitVecCommand */*notnull*/ command); +/** + * Reads the offset field of the [BitVecCommand]. + */ Offset sp_cmd_bitvec_get_offset(BitVecCommand */*notnull*/ command); +/** + * Returns the [BinaryOperation] of the command. + */ BinaryOperation sp_cmd_bitvec_get_operation(BitVecCommand */*notnull*/ command); -Packet *sp_cmd_bitvec_into_packet(BitVecCommand */*notnull*/ command); - /** * Set pixel data starting at the pixel offset on screen. * @@ -1226,20 +1256,36 @@ BitVecCommand */*notnull*/ sp_cmd_bitvec_new(BitVec */*notnull*/ bitvec, CompressionCode compression); /** - * Moves the provided bitmap to be contained in the command. + * Moves the provided [BitVec] to be contained in the [BitVecCommand]. */ void sp_cmd_bitvec_set(BitVecCommand */*notnull*/ command, BitVec */*notnull*/ bitvec); +/** + * Overwrites the compression kind of the [BitVecCommand]. + */ void sp_cmd_bitvec_set_compression(BitVecCommand */*notnull*/ command, CompressionCode compression); +/** + * Overwrites the offset field of the [BitVecCommand]. + */ void sp_cmd_bitvec_set_offset(BitVecCommand */*notnull*/ command, Offset offset); +/** + * Overwrites the [BinaryOperation] of the command. + */ void sp_cmd_bitvec_set_operation(BitVecCommand */*notnull*/ command, BinaryOperation operation); +/** + * Tries to turn a [BitVecCommand] into a [Packet]. + * + * Returns: NULL or a [Packet] containing the command. + */ +Packet *sp_cmd_bitvec_try_into_packet(BitVecCommand */*notnull*/ command); + /** * Clones an [GlobalBrightnessCommand] instance. * @@ -1284,12 +1330,23 @@ void sp_cmd_brightness_grid_free(BitmapCommand */*notnull*/ command); */ BrightnessGridCommand */*notnull*/ sp_cmd_brightness_grid_from_grid(BrightnessGrid */*notnull*/ grid); +/** + * Returns a pointer to the [BrightnessGrid] contained in the [BrightnessGridCommand]. + */ BrightnessGrid *sp_cmd_brightness_grid_get(BrightnessGridCommand */*notnull*/ command); +/** + * Overwrites the origin field of the [BrightnessGridCommand]. + */ void sp_cmd_brightness_grid_get_origin(BrightnessGridCommand */*notnull*/ command, size_t */*notnull*/ origin_x, size_t */*notnull*/ origin_y); +/** + * Tries to turn a [BrightnessGridCommand] into a [Packet]. + * + * Returns: NULL or a [Packet] containing the command. + */ Packet *sp_cmd_brightness_grid_into_packet(BrightnessGridCommand */*notnull*/ command); /** @@ -1304,11 +1361,14 @@ BrightnessGridCommand */*notnull*/ sp_cmd_brightness_grid_new(BrightnessGrid */* size_t origin_y); /** - * Moves the provided bitmap to be contained in the command. + * Moves the provided [BrightnessGrid] to be contained in the [BrightnessGridCommand]. */ void sp_cmd_brightness_grid_set(BrightnessGridCommand */*notnull*/ command, BrightnessGrid */*notnull*/ grid); +/** + * Reads the origin field of the [BrightnessGridCommand]. + */ void sp_cmd_brightness_grid_set_origin(BrightnessGridCommand */*notnull*/ command, size_t origin_x, size_t origin_y); @@ -1331,14 +1391,18 @@ void sp_cmd_char_grid_free(BitmapCommand */*notnull*/ command); */ CharGridCommand */*notnull*/ sp_cmd_char_grid_from_grid(CharGrid */*notnull*/ grid); +/** + * Returns a pointer to the [CharGrid] contained in the [CharGridCommand]. + */ CharGrid *sp_cmd_char_grid_get(CharGridCommand */*notnull*/ command); +/** + * Reads the origin field of the [CharGridCommand]. + */ void sp_cmd_char_grid_get_origin(CharGridCommand */*notnull*/ command, size_t */*notnull*/ origin_x, size_t */*notnull*/ origin_y); -Packet *sp_cmd_char_grid_into_packet(CharGridCommand */*notnull*/ command); - /** * Show UTF-8 encoded text on the screen. * @@ -1351,15 +1415,25 @@ CharGridCommand */*notnull*/ sp_cmd_char_grid_new(CharGrid */*notnull*/ grid, size_t origin_y); /** - * Moves the provided bitmap to be contained in the command. + * Moves the provided [CharGrid] to be contained in the [CharGridCommand]. */ void sp_cmd_char_grid_set(CharGridCommand */*notnull*/ command, CharGrid */*notnull*/ grid); +/** + * Overwrites the origin field of the [CharGridCommand]. + */ void sp_cmd_char_grid_set_origin(CharGridCommand */*notnull*/ command, size_t origin_x, size_t origin_y); +/** + * Tries to turn a [CharGridCommand] into a [Packet]. + * + * Returns: NULL or a [Packet] containing the command. + */ +Packet *sp_cmd_char_grid_try_into_packet(CharGridCommand */*notnull*/ command); + /** * Deallocates a [ClearCommand]. */ @@ -1411,8 +1485,6 @@ void sp_cmd_cp437_grid_get_origin(Cp437GridCommand */*notnull*/ command, size_t */*notnull*/ origin_x, size_t */*notnull*/ origin_y); -Packet *sp_cmd_cp437_grid_into_packet(Cp437GridCommand */*notnull*/ command); - /** * Show text on the screen. * @@ -1441,6 +1513,13 @@ void sp_cmd_cp437_grid_set_origin(Cp437GridCommand */*notnull*/ command, size_t origin_x, size_t origin_y); +/** + * Tries to turn a [Cp437GridCommand] into a [Packet]. + * + * Returns: NULL or a [Packet] containing the command. + */ +Packet *sp_cmd_cp437_grid_try_into_packet(Cp437GridCommand */*notnull*/ command); + /** * Deallocates a [FadeOutCommand]. */ diff --git a/src/commands/bitmap_command.rs b/src/commands/bitmap_command.rs index 731a644..286a6f1 100644 --- a/src/commands/bitmap_command.rs +++ b/src/commands/bitmap_command.rs @@ -34,8 +34,11 @@ pub unsafe extern "C" fn sp_cmd_bitmap_from_bitmap( heap_move_nonnull(unsafe { heap_remove(bitmap) }.into()) } +/// Tries to turn a [BitmapCommand] into a [Packet]. +/// +/// Returns: NULL or a [Packet] containing the command. #[no_mangle] -pub unsafe extern "C" fn sp_cmd_bitmap_into_packet( +pub unsafe extern "C" fn sp_cmd_bitmap_try_into_packet( command: NonNull, ) -> *mut Packet { heap_move_ok(unsafe { heap_remove(command) }.try_into()) @@ -51,6 +54,7 @@ pub unsafe extern "C" fn sp_cmd_bitmap_clone( unsafe { heap_clone(command) } } +/// Deallocates a [BitmapCommand] instance. #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitmap_free(command: NonNull) { unsafe { heap_drop(command) } @@ -69,7 +73,7 @@ pub unsafe extern "C" fn sp_cmd_bitmap_get( unsafe { NonNull::from(&mut (command.as_mut().bitmap)) } } -/// Moves the provided bitmap to be contained in the command. +/// Moves the provided [Bitmap] to be contained in the [BitmapCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitmap_set( mut command: NonNull, @@ -80,6 +84,7 @@ pub unsafe extern "C" fn sp_cmd_bitmap_set( } } +/// Reads the origin field of the [BitmapCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitmap_get_origin( command: NonNull, @@ -93,6 +98,7 @@ pub unsafe extern "C" fn sp_cmd_bitmap_get_origin( } } +/// Overwrites the origin field of the [BitmapCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitmap_set_origin( mut command: NonNull, @@ -104,6 +110,7 @@ pub unsafe extern "C" fn sp_cmd_bitmap_set_origin( } } +/// Overwrites the compression kind of the [BitmapCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitmap_set_compression( mut command: NonNull, @@ -114,6 +121,7 @@ pub unsafe extern "C" fn sp_cmd_bitmap_set_compression( } } +/// Reads the compression kind of the [BitmapCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitmap_get_compression( command: NonNull, diff --git a/src/commands/bitvec_command.rs b/src/commands/bitvec_command.rs index 7734c05..617e3af 100644 --- a/src/commands/bitvec_command.rs +++ b/src/commands/bitvec_command.rs @@ -34,8 +34,11 @@ pub unsafe extern "C" fn sp_cmd_bitvec_new( }) } +/// Tries to turn a [BitVecCommand] into a [Packet]. +/// +/// Returns: NULL or a [Packet] containing the command. #[no_mangle] -pub unsafe extern "C" fn sp_cmd_bitvec_into_packet( +pub unsafe extern "C" fn sp_cmd_bitvec_try_into_packet( command: NonNull, ) -> *mut Packet { heap_move_ok(unsafe { heap_remove(command) }.try_into()) @@ -57,6 +60,7 @@ pub unsafe extern "C" fn sp_cmd_bitvec_free(command: NonNull) { unsafe { heap_drop(command) } } +/// Returns a pointer to the [BitVec] contained in the [BitVecCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitvec_get( mut command: NonNull, @@ -64,7 +68,7 @@ pub unsafe extern "C" fn sp_cmd_bitvec_get( &mut unsafe { command.as_mut() }.bitvec } -/// Moves the provided bitmap to be contained in the command. +/// Moves the provided [BitVec] to be contained in the [BitVecCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitvec_set( mut command: NonNull, @@ -75,6 +79,7 @@ pub unsafe extern "C" fn sp_cmd_bitvec_set( } } +/// Reads the offset field of the [BitVecCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitvec_get_offset( command: NonNull, @@ -82,6 +87,7 @@ pub unsafe extern "C" fn sp_cmd_bitvec_get_offset( unsafe { command.as_ref().offset } } +/// Overwrites the offset field of the [BitVecCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitvec_set_offset( mut command: NonNull, @@ -92,6 +98,7 @@ pub unsafe extern "C" fn sp_cmd_bitvec_set_offset( } } +/// Returns the [BinaryOperation] of the command. #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitvec_get_operation( command: NonNull, @@ -99,6 +106,7 @@ pub unsafe extern "C" fn sp_cmd_bitvec_get_operation( unsafe { command.as_ref().operation.clone() } // TODO remove clone } +/// Overwrites the [BinaryOperation] of the command. #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitvec_set_operation( mut command: NonNull, @@ -109,6 +117,7 @@ pub unsafe extern "C" fn sp_cmd_bitvec_set_operation( } } +/// Overwrites the compression kind of the [BitVecCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitvec_set_compression( mut command: NonNull, @@ -119,6 +128,7 @@ pub unsafe extern "C" fn sp_cmd_bitvec_set_compression( } } +/// Reads the compression kind of the [BitVecCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_bitvec_get_compression( command: NonNull, diff --git a/src/commands/brightness_grid_command.rs b/src/commands/brightness_grid_command.rs index aa1caab..80e1b89 100644 --- a/src/commands/brightness_grid_command.rs +++ b/src/commands/brightness_grid_command.rs @@ -32,6 +32,9 @@ pub unsafe extern "C" fn sp_cmd_brightness_grid_from_grid( heap_move_nonnull(unsafe { heap_remove(grid) }.into()) } +/// Tries to turn a [BrightnessGridCommand] into a [Packet]. +/// +/// Returns: NULL or a [Packet] containing the command. #[no_mangle] pub unsafe extern "C" fn sp_cmd_brightness_grid_into_packet( command: NonNull, @@ -57,7 +60,7 @@ pub unsafe extern "C" fn sp_cmd_brightness_grid_free( unsafe { heap_drop(command) } } -/// Moves the provided bitmap to be contained in the command. +/// Moves the provided [BrightnessGrid] to be contained in the [BrightnessGridCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_brightness_grid_set( mut command: NonNull, @@ -68,6 +71,7 @@ pub unsafe extern "C" fn sp_cmd_brightness_grid_set( } } +/// Returns a pointer to the [BrightnessGrid] contained in the [BrightnessGridCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_brightness_grid_get( mut command: NonNull, @@ -75,6 +79,7 @@ pub unsafe extern "C" fn sp_cmd_brightness_grid_get( &mut unsafe { command.as_mut() }.grid } +/// Overwrites the origin field of the [BrightnessGridCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_brightness_grid_get_origin( command: NonNull, @@ -88,6 +93,7 @@ pub unsafe extern "C" fn sp_cmd_brightness_grid_get_origin( } } +/// Reads the origin field of the [BrightnessGridCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_brightness_grid_set_origin( mut command: NonNull, diff --git a/src/commands/char_grid_command.rs b/src/commands/char_grid_command.rs index c9e5d9b..8a220a5 100644 --- a/src/commands/char_grid_command.rs +++ b/src/commands/char_grid_command.rs @@ -30,8 +30,11 @@ pub unsafe extern "C" fn sp_cmd_char_grid_from_grid( heap_move_nonnull(unsafe { heap_remove(grid) }.into()) } +/// Tries to turn a [CharGridCommand] into a [Packet]. +/// +/// Returns: NULL or a [Packet] containing the command. #[no_mangle] -pub unsafe extern "C" fn sp_cmd_char_grid_into_packet( +pub unsafe extern "C" fn sp_cmd_char_grid_try_into_packet( command: NonNull, ) -> *mut Packet { heap_move_ok(unsafe { heap_remove(command) }.try_into()) @@ -55,7 +58,7 @@ pub unsafe extern "C" fn sp_cmd_char_grid_free( unsafe { heap_drop(command) } } -/// Moves the provided bitmap to be contained in the command. +/// Moves the provided [CharGrid] to be contained in the [CharGridCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_char_grid_set( mut command: NonNull, @@ -66,6 +69,7 @@ pub unsafe extern "C" fn sp_cmd_char_grid_set( } } +/// Returns a pointer to the [CharGrid] contained in the [CharGridCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_char_grid_get( mut command: NonNull, @@ -73,6 +77,7 @@ pub unsafe extern "C" fn sp_cmd_char_grid_get( &mut unsafe { command.as_mut() }.grid } +/// Reads the origin field of the [CharGridCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_char_grid_get_origin( command: NonNull, @@ -86,6 +91,7 @@ pub unsafe extern "C" fn sp_cmd_char_grid_get_origin( } } +/// Overwrites the origin field of the [CharGridCommand]. #[no_mangle] pub unsafe extern "C" fn sp_cmd_char_grid_set_origin( mut command: NonNull, diff --git a/src/commands/cp437_grid_command.rs b/src/commands/cp437_grid_command.rs index f6b8f9d..f653ef5 100644 --- a/src/commands/cp437_grid_command.rs +++ b/src/commands/cp437_grid_command.rs @@ -32,8 +32,11 @@ pub unsafe extern "C" fn sp_cmd_cp437_grid_from_grid( heap_move_nonnull(unsafe { heap_remove(grid) }.into()) } +/// Tries to turn a [Cp437GridCommand] into a [Packet]. +/// +/// Returns: NULL or a [Packet] containing the command. #[no_mangle] -pub unsafe extern "C" fn sp_cmd_cp437_grid_into_packet( +pub unsafe extern "C" fn sp_cmd_cp437_grid_try_into_packet( command: NonNull, ) -> *mut Packet { heap_move_ok(unsafe { heap_remove(command) }.try_into())