From 0c3bc0b0040b1b5513de64afa1efdab05f6a39dd Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Sat, 12 Apr 2025 13:34:02 +0200 Subject: [PATCH] wip fix documentation --- cbindgen.toml | 3 +- example/main.c | 2 +- examples/.gitignore | 4 + include/servicepoint.h | 414 +++++++++++++++++++++-------------------- src/bitmap.rs | 74 ++++---- src/bitvec.rs | 4 +- src/brightness_grid.rs | 56 +++--- src/char_grid.rs | 36 ++-- src/command.rs | 72 ++++--- src/connection.rs | 24 +-- src/cp437_grid.rs | 44 ++--- src/lib.rs | 6 +- src/packet.rs | 46 +++-- 13 files changed, 405 insertions(+), 380 deletions(-) create mode 100644 examples/.gitignore diff --git a/cbindgen.toml b/cbindgen.toml index 48ef574..363d001 100644 --- a/cbindgen.toml +++ b/cbindgen.toml @@ -35,7 +35,8 @@ include = [] exclude = [] [export.rename] -"TypedCommand" = "Command" +"SpBitVec" = "BitVec" +"SpByteSlice" = "ByteSlice" [enum] rename_variants = "QualifiedScreamingSnakeCase" diff --git a/example/main.c b/example/main.c index 80a1756..4e63dec 100644 --- a/example/main.c +++ b/example/main.c @@ -12,7 +12,7 @@ int main(void) { sp_bitmap_fill(pixels, true); - Command *command = sp_command_bitmap_linear_win(0, 0, pixels, COMPRESSION_CODE_UNCOMPRESSED); + TypedCommand *command = sp_command_bitmap_linear_win(0, 0, pixels, COMPRESSION_CODE_UNCOMPRESSED); if (command == NULL) return 1; diff --git a/examples/.gitignore b/examples/.gitignore new file mode 100644 index 0000000..9415aeb --- /dev/null +++ b/examples/.gitignore @@ -0,0 +1,4 @@ +# examples only use library in this repo +Cargo.lock +out +target diff --git a/include/servicepoint.h b/include/servicepoint.h index b63e9bf..07bc8f8 100644 --- a/include/servicepoint.h +++ b/include/servicepoint.h @@ -37,21 +37,6 @@ */ #define PIXEL_WIDTH (TILE_WIDTH * TILE_SIZE) -/** - * Count of possible brightness values - */ -#define SP_BRIGHTNESS_LEVELS 12 - -/** - * see [servicepoint::Brightness::MAX] - */ -#define SP_BRIGHTNESS_MAX 11 - -/** - * see [servicepoint::Brightness::MIN] - */ -#define SP_BRIGHTNESS_MIN 0 - /** * Display tile count in the y-direction * @@ -179,7 +164,7 @@ typedef struct SPBitVec SPBitVec; * * Please look at the contained structs for documentation per command. */ -typedef struct Command Command; +typedef struct TypedCommand TypedCommand; /** * A connection using the UDP protocol. @@ -359,7 +344,7 @@ extern "C" { #endif // __cplusplus /** - * Clones a [SPBitmap]. + * Clones a [Bitmap]. * * Will never return NULL. * @@ -371,7 +356,7 @@ extern "C" { * * The caller has to make sure that: * - * - `bitmap` points to a valid [SPBitmap] + * - `bitmap` points to a valid [Bitmap] * - `bitmap` is not written to concurrently * - the returned instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_bitmap_free`. @@ -379,7 +364,7 @@ extern "C" { Bitmap */*notnull*/ sp_bitmap_clone(Bitmap */*notnull*/ bitmap); /** - * Sets the state of all pixels in the [SPBitmap]. + * Sets the state of all pixels in the [Bitmap]. * * # Arguments * @@ -394,13 +379,13 @@ Bitmap */*notnull*/ sp_bitmap_clone(Bitmap */*notnull*/ bitmap); * * The caller has to make sure that: * - * - `bitmap` points to a valid [SPBitmap] + * - `bitmap` points to a valid [Bitmap] * - `bitmap` is not written to or read from concurrently */ void sp_bitmap_fill(Bitmap */*notnull*/ bitmap, bool value); /** - * Deallocates a [SPBitmap]. + * Deallocates a [Bitmap]. * * # Panics * @@ -410,14 +395,14 @@ void sp_bitmap_fill(Bitmap */*notnull*/ bitmap, bool value); * * The caller has to make sure that: * - * - `bitmap` points to a valid [SPBitmap] + * - `bitmap` points to a valid [Bitmap] * - * [SPCommand]: [crate::SPCommand] + * [TypedCommand]: [crate::TypedCommand] */ void sp_bitmap_free(Bitmap */*notnull*/ bitmap); /** - * Gets the current value at the specified position in the [SPBitmap]. + * Gets the current value at the specified position in the [Bitmap]. * * # Arguments * @@ -433,13 +418,13 @@ void sp_bitmap_free(Bitmap */*notnull*/ bitmap); * * The caller has to make sure that: * - * - `bitmap` points to a valid [SPBitmap] + * - `bitmap` points to a valid [Bitmap] * - `bitmap` is not written to concurrently */ bool sp_bitmap_get(Bitmap */*notnull*/ bitmap, size_t x, size_t y); /** - * Gets the height in pixels of the [SPBitmap] instance. + * Gets the height in pixels of the [Bitmap] instance. * * # Arguments * @@ -453,19 +438,19 @@ bool sp_bitmap_get(Bitmap */*notnull*/ bitmap, size_t x, size_t y); * * The caller has to make sure that: * - * - `bitmap` points to a valid [SPBitmap] + * - `bitmap` points to a valid [Bitmap] */ size_t sp_bitmap_height(Bitmap */*notnull*/ bitmap); /** - * Loads a [SPBitmap] with the specified dimensions from the provided data. + * Loads a [Bitmap] with the specified dimensions from the provided data. * * # Arguments * * - `width`: size in pixels in x-direction * - `height`: size in pixels in y-direction * - * returns: [SPBitmap] that contains a copy of the provided data, or NULL in case of an error. + * returns: [Bitmap] that contains a copy of the provided data, or NULL in case of an error. * * # Errors * @@ -491,14 +476,14 @@ Bitmap *sp_bitmap_load(size_t width, SPByteSlice data); /** - * Creates a new [SPBitmap] with the specified dimensions. + * Creates a new [Bitmap] with the specified dimensions. * * # Arguments * * - `width`: size in pixels in x-direction * - `height`: size in pixels in y-direction * - * returns: [SPBitmap] initialized to all pixels off, or NULL in case of an error. + * returns: [Bitmap] initialized to all pixels off, or NULL in case of an error. * * # Errors * @@ -512,14 +497,23 @@ Bitmap *sp_bitmap_load(size_t width, * * - the returned instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_bitmap_free`. + * + * # Examples + * + * ```C + * Cp437Grid grid = sp_bitmap_new(8, 3); + * sp_bitmap_fill(grid, true); + * sp_bitmap_set(grid, 0, 0, false); + * sp_bitmap_free(grid); + * ``` */ Bitmap *sp_bitmap_new(size_t width, size_t height); /** - * Creates a new [SPBitmap] with a size matching the screen. + * Creates a new [Bitmap] with a size matching the screen. * - * returns: [SPBitmap] initialized to all pixels off. Will never return NULL. + * returns: [Bitmap] initialized to all pixels off. Will never return NULL. * * # Safety * @@ -531,7 +525,7 @@ Bitmap *sp_bitmap_new(size_t width, Bitmap */*notnull*/ sp_bitmap_new_screen_sized(void); /** - * Sets the value of the specified position in the [SPBitmap]. + * Sets the value of the specified position in the [Bitmap]. * * # Arguments * @@ -550,13 +544,13 @@ Bitmap */*notnull*/ sp_bitmap_new_screen_sized(void); * * The caller has to make sure that: * - * - `bitmap` points to a valid [SPBitmap] + * - `bitmap` points to a valid [Bitmap] * - `bitmap` is not written to or read from concurrently */ void sp_bitmap_set(Bitmap */*notnull*/ bitmap, size_t x, size_t y, bool value); /** - * Gets an unsafe reference to the data of the [SPBitmap] instance. + * Gets an unsafe reference to the data of the [Bitmap] instance. * * # Panics * @@ -566,14 +560,14 @@ void sp_bitmap_set(Bitmap */*notnull*/ bitmap, size_t x, size_t y, bool value); * * The caller has to make sure that: * - * - `bitmap` points to a valid [SPBitmap] - * - the returned memory range is never accessed after the passed [SPBitmap] has been freed - * - the returned memory range is never accessed concurrently, either via the [SPBitmap] or directly + * - `bitmap` points to a valid [Bitmap] + * - the returned memory range is never accessed after the passed [Bitmap] has been freed + * - the returned memory range is never accessed concurrently, either via the [Bitmap] or directly */ SPByteSlice sp_bitmap_unsafe_data_ref(Bitmap */*notnull*/ bitmap); /** - * Gets the width in pixels of the [SPBitmap] instance. + * Gets the width in pixels of the [Bitmap] instance. * * # Arguments * @@ -587,7 +581,7 @@ SPByteSlice sp_bitmap_unsafe_data_ref(Bitmap */*notnull*/ bitmap); * * The caller has to make sure that: * - * - `bitmap` points to a valid [SPBitmap] + * - `bitmap` points to a valid [Bitmap] */ size_t sp_bitmap_width(Bitmap */*notnull*/ bitmap); @@ -645,9 +639,9 @@ void sp_bitvec_fill(SPBitVec */*notnull*/ bit_vec, bool value); * * - `bit_vec` points to a valid [SPBitVec] * - `bit_vec` is not used concurrently or after this call - * - `bit_vec` was not passed to another consuming function, e.g. to create a [SPCommand] + * - `bit_vec` was not passed to another consuming function, e.g. to create a [TypedCommand] * - * [SPCommand]: [crate::SPCommand] + * [TypedCommand]: [crate::TypedCommand] */ void sp_bitvec_free(SPBitVec */*notnull*/ bit_vec); @@ -800,13 +794,13 @@ void sp_bitvec_set(SPBitVec */*notnull*/ bit_vec, size_t index, bool value); SPByteSlice sp_bitvec_unsafe_data_ref(SPBitVec */*notnull*/ bit_vec); /** - * Clones a [SPBrightnessGrid]. + * Clones a [BrightnessGrid]. * * # Arguments * * - `brightness_grid`: instance to read from * - * returns: new [SPBrightnessGrid] instance. Will never return NULL. + * returns: new [BrightnessGrid] instance. Will never return NULL. * * # Panics * @@ -816,7 +810,7 @@ SPByteSlice sp_bitvec_unsafe_data_ref(SPBitVec */*notnull*/ bit_vec); * * The caller has to make sure that: * - * - `brightness_grid` points to a valid [SPBrightnessGrid] + * - `brightness_grid` points to a valid [BrightnessGrid] * - `brightness_grid` is not written to concurrently * - the returned instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_brightness_grid_free`. @@ -824,7 +818,7 @@ SPByteSlice sp_bitvec_unsafe_data_ref(SPBitVec */*notnull*/ bit_vec); BrightnessGrid */*notnull*/ sp_brightness_grid_clone(BrightnessGrid */*notnull*/ brightness_grid); /** - * Sets the value of all cells in the [SPBrightnessGrid]. + * Sets the value of all cells in the [BrightnessGrid]. * * # Arguments * @@ -840,14 +834,14 @@ BrightnessGrid */*notnull*/ sp_brightness_grid_clone(BrightnessGrid */*notnull*/ * * The caller has to make sure that: * - * - `brightness_grid` points to a valid [SPBrightnessGrid] + * - `brightness_grid` points to a valid [BrightnessGrid] * - `brightness_grid` is not written to or read from concurrently */ void sp_brightness_grid_fill(BrightnessGrid */*notnull*/ brightness_grid, Brightness value); /** - * Deallocates a [SPBrightnessGrid]. + * Deallocates a [BrightnessGrid]. * * # Arguments * @@ -861,11 +855,11 @@ void sp_brightness_grid_fill(BrightnessGrid */*notnull*/ brightness_grid, * * The caller has to make sure that: * - * - `brightness_grid` points to a valid [SPBrightnessGrid] + * - `brightness_grid` points to a valid [BrightnessGrid] * - `brightness_grid` is not used concurrently or after this call - * - `brightness_grid` was not passed to another consuming function, e.g. to create a [SPCommand] + * - `brightness_grid` was not passed to another consuming function, e.g. to create a [TypedCommand] * - * [SPCommand]: [crate::SPCommand] + * [TypedCommand]: [crate::TypedCommand] */ void sp_brightness_grid_free(BrightnessGrid */*notnull*/ brightness_grid); @@ -888,7 +882,7 @@ void sp_brightness_grid_free(BrightnessGrid */*notnull*/ brightness_grid); * * The caller has to make sure that: * - * - `brightness_grid` points to a valid [SPBrightnessGrid] + * - `brightness_grid` points to a valid [BrightnessGrid] * - `brightness_grid` is not written to concurrently */ Brightness sp_brightness_grid_get(BrightnessGrid */*notnull*/ brightness_grid, @@ -896,7 +890,7 @@ Brightness sp_brightness_grid_get(BrightnessGrid */*notnull*/ brightness_grid, size_t y); /** - * Gets the height of the [SPBrightnessGrid] instance. + * Gets the height of the [BrightnessGrid] instance. * * # Arguments * @@ -912,14 +906,14 @@ Brightness sp_brightness_grid_get(BrightnessGrid */*notnull*/ brightness_grid, * * The caller has to make sure that: * - * - `brightness_grid` points to a valid [SPBrightnessGrid] + * - `brightness_grid` points to a valid [BrightnessGrid] */ size_t sp_brightness_grid_height(BrightnessGrid */*notnull*/ brightness_grid); /** - * Loads a [SPBrightnessGrid] with the specified dimensions from the provided data. + * Loads a [BrightnessGrid] with the specified dimensions from the provided data. * - * returns: new [SPBrightnessGrid] instance. Will never return NULL. + * returns: new [BrightnessGrid] instance. Will never return NULL. * * # Panics * @@ -940,9 +934,9 @@ BrightnessGrid *sp_brightness_grid_load(size_t width, SPByteSlice data); /** - * Creates a new [SPBrightnessGrid] with the specified dimensions. + * Creates a new [BrightnessGrid] with the specified dimensions. * - * returns: [SPBrightnessGrid] initialized to 0. Will never return NULL. + * returns: [BrightnessGrid] initialized to 0. Will never return NULL. * * # Safety * @@ -955,7 +949,7 @@ BrightnessGrid */*notnull*/ sp_brightness_grid_new(size_t width, size_t height); /** - * Sets the value of the specified position in the [SPBrightnessGrid]. + * Sets the value of the specified position in the [BrightnessGrid]. * * # Arguments * @@ -975,7 +969,7 @@ BrightnessGrid */*notnull*/ sp_brightness_grid_new(size_t width, * * The caller has to make sure that: * - * - `brightness_grid` points to a valid [SPBrightnessGrid] + * - `brightness_grid` points to a valid [BrightnessGrid] * - `brightness_grid` is not written to or read from concurrently */ void sp_brightness_grid_set(BrightnessGrid */*notnull*/ brightness_grid, @@ -984,7 +978,7 @@ void sp_brightness_grid_set(BrightnessGrid */*notnull*/ brightness_grid, Brightness value); /** - * Gets an unsafe reference to the data of the [SPBrightnessGrid] instance. + * Gets an unsafe reference to the data of the [BrightnessGrid] instance. * * # Arguments * @@ -1000,14 +994,14 @@ void sp_brightness_grid_set(BrightnessGrid */*notnull*/ brightness_grid, * * The caller has to make sure that: * - * - `brightness_grid` points to a valid [SPBrightnessGrid] - * - the returned memory range is never accessed after the passed [SPBrightnessGrid] has been freed - * - the returned memory range is never accessed concurrently, either via the [SPBrightnessGrid] or directly + * - `brightness_grid` points to a valid [BrightnessGrid] + * - the returned memory range is never accessed after the passed [BrightnessGrid] has been freed + * - the returned memory range is never accessed concurrently, either via the [BrightnessGrid] or directly */ SPByteSlice sp_brightness_grid_unsafe_data_ref(BrightnessGrid */*notnull*/ brightness_grid); /** - * Gets the width of the [SPBrightnessGrid] instance. + * Gets the width of the [BrightnessGrid] instance. * * # Arguments * @@ -1023,12 +1017,12 @@ SPByteSlice sp_brightness_grid_unsafe_data_ref(BrightnessGrid */*notnull*/ brigh * * The caller has to make sure that: * - * - `brightness_grid` points to a valid [SPBrightnessGrid] + * - `brightness_grid` points to a valid [BrightnessGrid] */ size_t sp_brightness_grid_width(BrightnessGrid */*notnull*/ brightness_grid); /** - * Clones a [SPCharGrid]. + * Clones a [CharGrid]. * * Will never return NULL. * @@ -1040,7 +1034,7 @@ size_t sp_brightness_grid_width(BrightnessGrid */*notnull*/ brightness_grid); * * The caller has to make sure that: * - * - `char_grid` points to a valid [SPCharGrid] + * - `char_grid` points to a valid [CharGrid] * - `char_grid` is not written to concurrently * - the returned instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_char_grid_free`. @@ -1048,7 +1042,7 @@ size_t sp_brightness_grid_width(BrightnessGrid */*notnull*/ brightness_grid); CharGrid */*notnull*/ sp_char_grid_clone(CharGrid */*notnull*/ char_grid); /** - * Sets the value of all cells in the [SPCharGrid]. + * Sets the value of all cells in the [CharGrid]. * * # Arguments * @@ -1063,13 +1057,13 @@ CharGrid */*notnull*/ sp_char_grid_clone(CharGrid */*notnull*/ char_grid); * * The caller has to make sure that: * - * - `char_grid` points to a valid [SPCharGrid] + * - `char_grid` points to a valid [CharGrid] * - `char_grid` is not written to or read from concurrently */ void sp_char_grid_fill(CharGrid */*notnull*/ char_grid, uint32_t value); /** - * Deallocates a [SPCharGrid]. + * Deallocates a [CharGrid]. * * # Panics * @@ -1079,11 +1073,11 @@ void sp_char_grid_fill(CharGrid */*notnull*/ char_grid, uint32_t value); * * The caller has to make sure that: * - * - `char_grid` points to a valid [SPCharGrid] + * - `char_grid` points to a valid [CharGrid] * - `char_grid` is not used concurrently or after char_grid call - * - `char_grid` was not passed to another consuming function, e.g. to create a [SPCommand] + * - `char_grid` was not passed to another consuming function, e.g. to create a [TypedCommand] * - * [SPCommand]: [crate::SPCommand] + * [TypedCommand]: [crate::TypedCommand] */ void sp_char_grid_free(CharGrid */*notnull*/ char_grid); @@ -1104,13 +1098,13 @@ void sp_char_grid_free(CharGrid */*notnull*/ char_grid); * * The caller has to make sure that: * - * - `char_grid` points to a valid [SPCharGrid] + * - `char_grid` points to a valid [CharGrid] * - `char_grid` is not written to concurrently */ uint32_t sp_char_grid_get(CharGrid */*notnull*/ char_grid, size_t x, size_t y); /** - * Gets the height of the [SPCharGrid] instance. + * Gets the height of the [CharGrid] instance. * * # Arguments * @@ -1124,12 +1118,12 @@ uint32_t sp_char_grid_get(CharGrid */*notnull*/ char_grid, size_t x, size_t y); * * The caller has to make sure that: * - * - `char_grid` points to a valid [SPCharGrid] + * - `char_grid` points to a valid [CharGrid] */ size_t sp_char_grid_height(CharGrid */*notnull*/ char_grid); /** - * Loads a [SPCharGrid] with the specified dimensions from the provided data. + * Loads a [CharGrid] with the specified dimensions from the provided data. * * Will never return NULL. * @@ -1153,9 +1147,9 @@ CharGrid */*notnull*/ sp_char_grid_load(size_t width, SPByteSlice data); /** - * Creates a new [SPCharGrid] with the specified dimensions. + * Creates a new [CharGrid] with the specified dimensions. * - * returns: [SPCharGrid] initialized to 0. Will never return NULL. + * returns: [CharGrid] initialized to 0. Will never return NULL. * * # Safety * @@ -1168,7 +1162,7 @@ CharGrid */*notnull*/ sp_char_grid_new(size_t width, size_t height); /** - * Sets the value of the specified position in the [SPCharGrid]. + * Sets the value of the specified position in the [CharGrid]. * * # Arguments * @@ -1198,7 +1192,7 @@ void sp_char_grid_set(CharGrid */*notnull*/ char_grid, uint32_t value); /** - * Gets the width of the [SPCharGrid] instance. + * Gets the width of the [CharGrid] instance. * * # Arguments * @@ -1212,7 +1206,7 @@ void sp_char_grid_set(CharGrid */*notnull*/ char_grid, * * The caller has to make sure that: * - * - `char_grid` points to a valid [SPCharGrid] + * - `char_grid` points to a valid [CharGrid] */ size_t sp_char_grid_width(CharGrid */*notnull*/ char_grid); @@ -1240,12 +1234,12 @@ size_t sp_char_grid_width(CharGrid */*notnull*/ char_grid); * - `bit_vec` points to a valid instance of [SPBitVec] * - `bit_vec` is not used concurrently or after this call * - `compression` matches one of the allowed enum values - * - the returned [SPCommand] instance is freed in some way, either by using a consuming function or + * - the returned [TypedCommand] instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_free`. */ -Command *sp_command_bitmap_linear(size_t offset, - SPBitVec */*notnull*/ bit_vec, - CompressionCode compression); +TypedCommand *sp_command_bitmap_linear(size_t offset, + SPBitVec */*notnull*/ bit_vec, + CompressionCode compression); /** * Set pixel data according to an and-mask starting at the offset. @@ -1271,12 +1265,12 @@ Command *sp_command_bitmap_linear(size_t offset, * - `bit_vec` points to a valid instance of [SPBitVec] * - `bit_vec` is not used concurrently or after this call * - `compression` matches one of the allowed enum values - * - the returned [SPCommand] instance is freed in some way, either by using a consuming function or + * - the returned [TypedCommand] instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_free`. */ -Command *sp_command_bitmap_linear_and(size_t offset, - SPBitVec */*notnull*/ bit_vec, - CompressionCode compression); +TypedCommand *sp_command_bitmap_linear_and(size_t offset, + SPBitVec */*notnull*/ bit_vec, + CompressionCode compression); /** * Set pixel data according to an or-mask starting at the offset. @@ -1302,17 +1296,17 @@ Command *sp_command_bitmap_linear_and(size_t offset, * - `bit_vec` points to a valid instance of [SPBitVec] * - `bit_vec` is not used concurrently or after this call * - `compression` matches one of the allowed enum values - * - the returned [SPCommand] instance is freed in some way, either by using a consuming function or + * - the returned [TypedCommand] instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_free`. */ -Command *sp_command_bitmap_linear_or(size_t offset, - SPBitVec */*notnull*/ bit_vec, - CompressionCode compression); +TypedCommand *sp_command_bitmap_linear_or(size_t offset, + SPBitVec */*notnull*/ bit_vec, + CompressionCode compression); /** * Sets a window of pixels to the specified values. * - * The passed [SPBitmap] gets consumed. + * The passed [Bitmap] gets consumed. * * Returns: a new [servicepoint::Command::BitmapLinearWin] instance. Will never return NULL. * @@ -1325,16 +1319,16 @@ Command *sp_command_bitmap_linear_or(size_t offset, * * The caller has to make sure that: * - * - `bitmap` points to a valid instance of [SPBitmap] + * - `bitmap` points to a valid instance of [Bitmap] * - `bitmap` is not used concurrently or after this call * - `compression` matches one of the allowed enum values - * - the returned [SPCommand] instance is freed in some way, either by using a consuming function or + * - the returned [TypedCommand] instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_free`. */ -Command *sp_command_bitmap_linear_win(size_t x, - size_t y, - Bitmap */*notnull*/ bitmap, - CompressionCode compression); +TypedCommand *sp_command_bitmap_linear_win(size_t x, + size_t y, + Bitmap */*notnull*/ bitmap, + CompressionCode compression); /** * Set pixel data according to a xor-mask starting at the offset. @@ -1360,12 +1354,12 @@ Command *sp_command_bitmap_linear_win(size_t x, * - `bit_vec` points to a valid instance of [SPBitVec] * - `bit_vec` is not used concurrently or after this call * - `compression` matches one of the allowed enum values - * - the returned [SPCommand] instance is freed in some way, either by using a consuming function or + * - the returned [TypedCommand] instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_free`. */ -Command *sp_command_bitmap_linear_xor(size_t offset, - SPBitVec */*notnull*/ bit_vec, - CompressionCode compression); +TypedCommand *sp_command_bitmap_linear_xor(size_t offset, + SPBitVec */*notnull*/ bit_vec, + CompressionCode compression); /** * Set the brightness of all tiles to the same value. @@ -1380,15 +1374,15 @@ Command *sp_command_bitmap_linear_xor(size_t offset, * * The caller has to make sure that: * - * - the returned [SPCommand] instance is freed in some way, either by using a consuming function or + * - the returned [TypedCommand] instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_free`. */ -Command */*notnull*/ sp_command_brightness(Brightness brightness); +TypedCommand */*notnull*/ sp_command_brightness(Brightness brightness); /** * Set the brightness of individual tiles in a rectangular area of the display. * - * The passed [SPBrightnessGrid] gets consumed. + * The passed [BrightnessGrid] gets consumed. * * Returns: a new [servicepoint::Command::CharBrightness] instance. Will never return NULL. * @@ -1400,14 +1394,14 @@ Command */*notnull*/ sp_command_brightness(Brightness brightness); * * The caller has to make sure that: * - * - `grid` points to a valid instance of [SPBrightnessGrid] + * - `grid` points to a valid instance of [BrightnessGrid] * - `grid` is not used concurrently or after this call - * - the returned [SPCommand] instance is freed in some way, either by using a consuming function or + * - the returned [TypedCommand] instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_free`. */ -Command */*notnull*/ sp_command_char_brightness(size_t x, - size_t y, - BrightnessGrid */*notnull*/ grid); +TypedCommand */*notnull*/ sp_command_char_brightness(size_t x, + size_t y, + BrightnessGrid */*notnull*/ grid); /** * Set all pixels to the off state. @@ -1426,15 +1420,15 @@ Command */*notnull*/ sp_command_char_brightness(size_t x, * * The caller has to make sure that: * - * - the returned [SPCommand] instance is freed in some way, either by using a consuming function or + * - the returned [TypedCommand] instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_free`. */ -Command */*notnull*/ sp_command_clear(void); +TypedCommand */*notnull*/ sp_command_clear(void); /** - * Clones a [SPCommand] instance. + * Clones a [TypedCommand] instance. * - * returns: new [SPCommand] instance. Will never return NULL. + * returns: new [TypedCommand] instance. Will never return NULL. * * # Panics * @@ -1444,17 +1438,17 @@ Command */*notnull*/ sp_command_clear(void); * * The caller has to make sure that: * - * - `command` points to a valid instance of [SPCommand] + * - `command` points to a valid instance of [TypedCommand] * - `command` is not written to concurrently - * - the returned [SPCommand] instance is freed in some way, either by using a consuming function or + * - the returned [TypedCommand] instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_free`. */ -Command */*notnull*/ sp_command_clone(Command */*notnull*/ command); +TypedCommand */*notnull*/ sp_command_clone(TypedCommand */*notnull*/ command); /** * Show codepage 437 encoded text on the screen. * - * The passed [SPCp437Grid] gets consumed. + * The passed [Cp437Grid] gets consumed. * * Returns: a new [servicepoint::Command::Cp437Data] instance. Will never return NULL. * @@ -1466,14 +1460,14 @@ Command */*notnull*/ sp_command_clone(Command */*notnull*/ command); * * The caller has to make sure that: * - * - `grid` points to a valid instance of [SPCp437Grid] + * - `grid` points to a valid instance of [Cp437Grid] * - `grid` is not used concurrently or after this call - * - the returned [SPCommand] instance is freed in some way, either by using a consuming function or + * - the returned [TypedCommand] instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_free`. */ -Command */*notnull*/ sp_command_cp437_data(size_t x, - size_t y, - Cp437Grid */*notnull*/ grid); +TypedCommand */*notnull*/ sp_command_cp437_data(size_t x, + size_t y, + Cp437Grid */*notnull*/ grid); /** * A yet-to-be-tested command. @@ -1484,18 +1478,18 @@ Command */*notnull*/ sp_command_cp437_data(size_t x, * * The caller has to make sure that: * - * - the returned [SPCommand] instance is freed in some way, either by using a consuming function or + * - the returned [TypedCommand] instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_free`. */ -Command */*notnull*/ sp_command_fade_out(void); +TypedCommand */*notnull*/ sp_command_fade_out(void); /** - * Deallocates a [SPCommand]. + * Deallocates a [TypedCommand]. * * # Examples * * ```C - * SPCommand c = sp_command_clear(); + * TypedCommand c = sp_command_clear(); * sp_command_free(c); * ``` * @@ -1507,11 +1501,11 @@ Command */*notnull*/ sp_command_fade_out(void); * * The caller has to make sure that: * - * - `command` points to a valid [SPCommand] + * - `command` points to a valid [TypedCommand] * - `command` is not used concurrently or after this call - * - `command` was not passed to another consuming function, e.g. to create a [SPPacket] + * - `command` was not passed to another consuming function, e.g. to create a [Packet] */ -void sp_command_free(Command */*notnull*/ command); +void sp_command_free(TypedCommand */*notnull*/ command); /** * Kills the udp daemon on the display, which usually results in a restart. @@ -1524,17 +1518,17 @@ void sp_command_free(Command */*notnull*/ command); * * The caller has to make sure that: * - * - the returned [SPCommand] instance is freed in some way, either by using a consuming function or + * - the returned [TypedCommand] instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_free`. */ -Command */*notnull*/ sp_command_hard_reset(void); +TypedCommand */*notnull*/ sp_command_hard_reset(void); /** * A low-level display command. * * This struct and associated functions implement the UDP protocol for the display. * - * To send a [SPCommand], use a [SPConnection]. + * To send a [TypedCommand], use a [UdpConnection]. * * # Examples * @@ -1542,13 +1536,11 @@ Command */*notnull*/ sp_command_hard_reset(void); * sp_connection_send_command(connection, sp_command_clear()); * sp_connection_send_command(connection, sp_command_brightness(5)); * ``` - * - * [SPConnection]: [crate::SPConnection] - * Tries to turn a [SPPacket] into a [SPCommand]. + * Tries to turn a [Packet] into a [TypedCommand]. * * The packet is deallocated in the process. * - * Returns: pointer to new [SPCommand] instance or NULL if parsing failed. + * Returns: pointer to new [TypedCommand] instance or NULL if parsing failed. * * # Panics * @@ -1558,18 +1550,18 @@ Command */*notnull*/ sp_command_hard_reset(void); * * The caller has to make sure that: * - * - [SPPacket] points to a valid instance of [SPPacket] - * - [SPPacket] is not used concurrently or after this call + * - [Packet] points to a valid instance of [Packet] + * - [Packet] is not used concurrently or after this call * - the result is checked for NULL - * - the returned [SPCommand] instance is freed in some way, either by using a consuming function or + * - the returned [TypedCommand] instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_free`. */ -Command *sp_command_try_from_packet(Packet */*notnull*/ packet); +TypedCommand *sp_command_try_from_packet(Packet */*notnull*/ packet); /** * Show UTF-8 encoded text on the screen. * - * The passed [SPCharGrid] gets consumed. + * The passed [CharGrid] gets consumed. * * Returns: a new [servicepoint::Command::Utf8Data] instance. Will never return NULL. * @@ -1581,17 +1573,17 @@ Command *sp_command_try_from_packet(Packet */*notnull*/ packet); * * The caller has to make sure that: * - * - `grid` points to a valid instance of [SPCharGrid] + * - `grid` points to a valid instance of [CharGrid] * - `grid` is not used concurrently or after this call - * - the returned [SPCommand] instance is freed in some way, either by using a consuming function or + * - the returned [TypedCommand] instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_free`. */ -Command */*notnull*/ sp_command_utf8_data(size_t x, - size_t y, - CharGrid */*notnull*/ grid); +TypedCommand */*notnull*/ sp_command_utf8_data(size_t x, + size_t y, + CharGrid */*notnull*/ grid); /** - * Closes and deallocates a [SPConnection]. + * Closes and deallocates a [UdpConnection]. * * # Panics * @@ -1601,13 +1593,13 @@ Command */*notnull*/ sp_command_utf8_data(size_t x, * * The caller has to make sure that: * - * - `connection` points to a valid [SPConnection] + * - `connection` points to a valid [UdpConnection] * - `connection` is not used concurrently or after this call */ void sp_connection_free(UdpConnection */*notnull*/ connection); /** - * Creates a new instance of [SPConnection]. + * Creates a new instance of [UdpConnection]. * * returns: NULL if connection fails, or connected instance * @@ -1625,7 +1617,7 @@ void sp_connection_free(UdpConnection */*notnull*/ connection); UdpConnection *sp_connection_open(char */*notnull*/ host); /** - * Sends a [SPCommand] to the display using the [SPConnection]. + * Sends a [TypedCommand] to the display using the [UdpConnection]. * * The passed `command` gets consumed. * @@ -1640,15 +1632,15 @@ UdpConnection *sp_connection_open(char */*notnull*/ host); * * The caller has to make sure that: * - * - `connection` points to a valid instance of [SPConnection] - * - `command` points to a valid instance of [SPPacket] + * - `connection` points to a valid instance of [UdpConnection] + * - `command` points to a valid instance of [Packet] * - `command` is not used concurrently or after this call */ bool sp_connection_send_command(UdpConnection */*notnull*/ connection, - Command */*notnull*/ command); + TypedCommand */*notnull*/ command); /** - * Sends a [SPPacket] to the display using the [SPConnection]. + * Sends a [Packet] to the display using the [UdpConnection]. * * The passed `packet` gets consumed. * @@ -1663,15 +1655,15 @@ bool sp_connection_send_command(UdpConnection */*notnull*/ connection, * * The caller has to make sure that: * - * - `connection` points to a valid instance of [SPConnection] - * - `packet` points to a valid instance of [SPPacket] + * - `connection` points to a valid instance of [UdpConnection] + * - `packet` points to a valid instance of [Packet] * - `packet` is not used concurrently or after this call */ bool sp_connection_send_packet(UdpConnection */*notnull*/ connection, Packet */*notnull*/ packet); /** - * Clones a [SPCp437Grid]. + * Clones a [Cp437Grid]. * * Will never return NULL. * @@ -1683,7 +1675,7 @@ bool sp_connection_send_packet(UdpConnection */*notnull*/ connection, * * The caller has to make sure that: * - * - `cp437_grid` points to a valid [SPCp437Grid] + * - `cp437_grid` points to a valid [Cp437Grid] * - `cp437_grid` is not written to concurrently * - the returned instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_cp437_grid_free`. @@ -1691,7 +1683,7 @@ bool sp_connection_send_packet(UdpConnection */*notnull*/ connection, Cp437Grid */*notnull*/ sp_cp437_grid_clone(Cp437Grid */*notnull*/ cp437_grid); /** - * Sets the value of all cells in the [SPCp437Grid]. + * Sets the value of all cells in the [Cp437Grid]. * * # Arguments * @@ -1706,13 +1698,13 @@ Cp437Grid */*notnull*/ sp_cp437_grid_clone(Cp437Grid */*notnull*/ cp437_grid); * * The caller has to make sure that: * - * - `cp437_grid` points to a valid [SPCp437Grid] + * - `cp437_grid` points to a valid [Cp437Grid] * - `cp437_grid` is not written to or read from concurrently */ void sp_cp437_grid_fill(Cp437Grid */*notnull*/ cp437_grid, uint8_t value); /** - * Deallocates a [SPCp437Grid]. + * Deallocates a [Cp437Grid]. * * # Panics * @@ -1722,11 +1714,11 @@ void sp_cp437_grid_fill(Cp437Grid */*notnull*/ cp437_grid, uint8_t value); * * The caller has to make sure that: * - * - `cp437_grid` points to a valid [SPCp437Grid] + * - `cp437_grid` points to a valid [Cp437Grid] * - `cp437_grid` is not used concurrently or after cp437_grid call - * - `cp437_grid` was not passed to another consuming function, e.g. to create a [SPCommand] + * - `cp437_grid` was not passed to another consuming function, e.g. to create a [TypedCommand] * - * [SPCommand]: [crate::SPCommand] + * [TypedCommand]: [crate::TypedCommand] */ void sp_cp437_grid_free(Cp437Grid */*notnull*/ cp437_grid); @@ -1747,7 +1739,7 @@ void sp_cp437_grid_free(Cp437Grid */*notnull*/ cp437_grid); * * The caller has to make sure that: * - * - `cp437_grid` points to a valid [SPCp437Grid] + * - `cp437_grid` points to a valid [Cp437Grid] * - `cp437_grid` is not written to concurrently */ uint8_t sp_cp437_grid_get(Cp437Grid */*notnull*/ cp437_grid, @@ -1755,7 +1747,7 @@ uint8_t sp_cp437_grid_get(Cp437Grid */*notnull*/ cp437_grid, size_t y); /** - * Gets the height of the [SPCp437Grid] instance. + * Gets the height of the [Cp437Grid] instance. * * # Arguments * @@ -1769,12 +1761,12 @@ uint8_t sp_cp437_grid_get(Cp437Grid */*notnull*/ cp437_grid, * * The caller has to make sure that: * - * - `cp437_grid` points to a valid [SPCp437Grid] + * - `cp437_grid` points to a valid [Cp437Grid] */ size_t sp_cp437_grid_height(Cp437Grid */*notnull*/ cp437_grid); /** - * Loads a [SPCp437Grid] with the specified dimensions from the provided data. + * Loads a [Cp437Grid] with the specified dimensions from the provided data. * * Will never return NULL. * @@ -1797,9 +1789,9 @@ Cp437Grid *sp_cp437_grid_load(size_t width, SPByteSlice data); /** - * Creates a new [SPCp437Grid] with the specified dimensions. + * Creates a new [Cp437Grid] with the specified dimensions. * - * returns: [SPCp437Grid] initialized to 0. Will never return NULL. + * returns: [Cp437Grid] initialized to 0. Will never return NULL. * * # Safety * @@ -1812,7 +1804,7 @@ Cp437Grid */*notnull*/ sp_cp437_grid_new(size_t width, size_t height); /** - * Sets the value of the specified position in the [SPCp437Grid]. + * Sets the value of the specified position in the [Cp437Grid]. * * # Arguments * @@ -1842,7 +1834,7 @@ void sp_cp437_grid_set(Cp437Grid */*notnull*/ cp437_grid, uint8_t value); /** - * Gets an unsafe reference to the data of the [SPCp437Grid] instance. + * Gets an unsafe reference to the data of the [Cp437Grid] instance. * * Will never return NULL. * @@ -1854,14 +1846,14 @@ void sp_cp437_grid_set(Cp437Grid */*notnull*/ cp437_grid, * * The caller has to make sure that: * - * - `cp437_grid` points to a valid [SPCp437Grid] - * - the returned memory range is never accessed after the passed [SPCp437Grid] has been freed - * - the returned memory range is never accessed concurrently, either via the [SPCp437Grid] or directly + * - `cp437_grid` points to a valid [Cp437Grid] + * - the returned memory range is never accessed after the passed [Cp437Grid] has been freed + * - the returned memory range is never accessed concurrently, either via the [Cp437Grid] or directly */ SPByteSlice sp_cp437_grid_unsafe_data_ref(Cp437Grid */*notnull*/ cp437_grid); /** - * Gets the width of the [SPCp437Grid] instance. + * Gets the width of the [Cp437Grid] instance. * * # Arguments * @@ -1875,12 +1867,12 @@ SPByteSlice sp_cp437_grid_unsafe_data_ref(Cp437Grid */*notnull*/ cp437_grid); * * The caller has to make sure that: * - * - `cp437_grid` points to a valid [SPCp437Grid] + * - `cp437_grid` points to a valid [Cp437Grid] */ size_t sp_cp437_grid_width(Cp437Grid */*notnull*/ cp437_grid); /** - * Clones a [SPPacket]. + * Clones a [Packet]. * * Will never return NULL. * @@ -1892,7 +1884,7 @@ size_t sp_cp437_grid_width(Cp437Grid */*notnull*/ cp437_grid); * * The caller has to make sure that: * - * - `packet` points to a valid [SPPacket] + * - `packet` points to a valid [Packet] * - `packet` is not written to concurrently * - the returned instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_packet_free`. @@ -1900,7 +1892,7 @@ size_t sp_cp437_grid_width(Cp437Grid */*notnull*/ cp437_grid); Packet */*notnull*/ sp_packet_clone(Packet */*notnull*/ packet); /** - * Deallocates a [SPPacket]. + * Deallocates a [Packet]. * * # Panics * @@ -1910,16 +1902,16 @@ Packet */*notnull*/ sp_packet_clone(Packet */*notnull*/ packet); * * The caller has to make sure that: * - * - `packet` points to a valid [SPPacket] + * - `packet` points to a valid [Packet] * - `packet` is not used concurrently or after this call */ void sp_packet_free(Packet */*notnull*/ packet); /** - * Turns a [SPCommand] into a [SPPacket]. - * The [SPCommand] gets consumed. + * Turns a [TypedCommand] into a [Packet]. + * The [TypedCommand] gets consumed. * - * Will never return NULL. + * Returns NULL in case of an error. * * # Panics * @@ -1929,15 +1921,15 @@ void sp_packet_free(Packet */*notnull*/ packet); * * The caller has to make sure that: * - * - [SPCommand] points to a valid instance of [SPCommand] - * - [SPCommand] is not used concurrently or after this call - * - the returned [SPPacket] instance is freed in some way, either by using a consuming function or + * - [TypedCommand] points to a valid instance of [TypedCommand] + * - [TypedCommand] is not used concurrently or after this call + * - the returned [Packet] instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_packet_free`. */ -Packet *sp_packet_from_command(Command */*notnull*/ command); +Packet *sp_packet_from_command(TypedCommand */*notnull*/ command); /** - * Creates a raw [SPPacket] from parts. + * Creates a raw [Packet] from parts. * * # Arguments * @@ -1959,20 +1951,44 @@ Packet *sp_packet_from_command(Command */*notnull*/ command); * * - `payload` points to a valid memory region of at least `payload_len` bytes * - `payload` is not written to concurrently - * - the returned [SPPacket] instance is freed in some way, either by using a consuming function or + * - the returned [Packet] instance is freed in some way, either by using a consuming function or * by explicitly calling [sp_packet_free]. */ Packet */*notnull*/ sp_packet_from_parts(Header header, const SPByteSlice *payload); +/** + * Returns a pointer to the header field of the provided packet. + * + * The returned header can be changed and will be valid for the lifetime of the packet. + */ Header */*notnull*/ sp_packet_get_header(Packet */*notnull*/ packet); +/** + * Returns a pointer to the current payload of the provided packet. + * + * The returned memory can be changed and will be valid until a new payload is set. + */ SPByteSlice sp_packet_get_payload(Packet */*notnull*/ packet); +/** + * Serialize the packet into the provided buffer. + * + * # Panics + * + * - if the buffer is not big enough to hold header+payload. + */ +void sp_packet_serialize_to(Packet */*notnull*/ packet, SPByteSlice buffer); + +/** + * Sets the payload of the provided packet to the provided data. + * + * This makes previous payload pointers invalid. + */ void sp_packet_set_payload(Packet */*notnull*/ packet, SPByteSlice data); /** - * Tries to load a [SPPacket] from the passed array with the specified length. + * Tries to load a [Packet] from the passed array with the specified length. * * returns: NULL in case of an error, pointer to the allocated packet otherwise * @@ -1986,13 +2002,11 @@ void sp_packet_set_payload(Packet */*notnull*/ packet, SPByteSlice data); * * - `data` points to a valid memory region of at least `length` bytes * - `data` is not written to concurrently - * - the returned [SPPacket] instance is freed in some way, either by using a consuming function or + * - the returned [Packet] instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_packet_free`. */ Packet *sp_packet_try_load(SPByteSlice data); -void sp_packet_write_to(Packet */*notnull*/ packet, SPByteSlice buffer); - #ifdef __cplusplus } // extern "C" #endif // __cplusplus diff --git a/src/bitmap.rs b/src/bitmap.rs index 2e70efc..5da6e7e 100644 --- a/src/bitmap.rs +++ b/src/bitmap.rs @@ -1,31 +1,16 @@ -//! C functions for interacting with [SPBitmap]s -//! -//! prefix `sp_bitmap_` -//! -//! A grid of pixels. -//! -//! # Examples -//! -//! ```C -//! Cp437Grid grid = sp_bitmap_new(8, 3); -//! sp_bitmap_fill(grid, true); -//! sp_bitmap_set(grid, 0, 0, false); -//! sp_bitmap_free(grid); -//! ``` - use servicepoint::{Bitmap, DataRef, Grid}; use std::ptr::NonNull; use crate::byte_slice::SPByteSlice; -/// Creates a new [SPBitmap] with the specified dimensions. +/// Creates a new [Bitmap] with the specified dimensions. /// /// # Arguments /// /// - `width`: size in pixels in x-direction /// - `height`: size in pixels in y-direction /// -/// returns: [SPBitmap] initialized to all pixels off, or NULL in case of an error. +/// returns: [Bitmap] initialized to all pixels off, or NULL in case of an error. /// /// # Errors /// @@ -39,6 +24,15 @@ use crate::byte_slice::SPByteSlice; /// /// - the returned instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_bitmap_free`. +/// +/// # Examples +/// +/// ```C +/// Cp437Grid grid = sp_bitmap_new(8, 3); +/// sp_bitmap_fill(grid, true); +/// sp_bitmap_set(grid, 0, 0, false); +/// sp_bitmap_free(grid); +/// ``` #[no_mangle] pub unsafe extern "C" fn sp_bitmap_new( width: usize, @@ -51,9 +45,9 @@ pub unsafe extern "C" fn sp_bitmap_new( } } -/// Creates a new [SPBitmap] with a size matching the screen. +/// Creates a new [Bitmap] with a size matching the screen. /// -/// returns: [SPBitmap] initialized to all pixels off. Will never return NULL. +/// returns: [Bitmap] initialized to all pixels off. Will never return NULL. /// /// # Safety /// @@ -67,14 +61,14 @@ pub unsafe extern "C" fn sp_bitmap_new_screen_sized() -> NonNull { NonNull::from(Box::leak(result)) } -/// Loads a [SPBitmap] with the specified dimensions from the provided data. +/// Loads a [Bitmap] with the specified dimensions from the provided data. /// /// # Arguments /// /// - `width`: size in pixels in x-direction /// - `height`: size in pixels in y-direction /// -/// returns: [SPBitmap] that contains a copy of the provided data, or NULL in case of an error. +/// returns: [Bitmap] that contains a copy of the provided data, or NULL in case of an error. /// /// # Errors /// @@ -108,7 +102,7 @@ pub unsafe extern "C" fn sp_bitmap_load( } } -/// Clones a [SPBitmap]. +/// Clones a [Bitmap]. /// /// Will never return NULL. /// @@ -120,7 +114,7 @@ pub unsafe extern "C" fn sp_bitmap_load( /// /// The caller has to make sure that: /// -/// - `bitmap` points to a valid [SPBitmap] +/// - `bitmap` points to a valid [Bitmap] /// - `bitmap` is not written to concurrently /// - the returned instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_bitmap_free`. @@ -132,7 +126,7 @@ pub unsafe extern "C" fn sp_bitmap_clone( NonNull::from(Box::leak(result)) } -/// Deallocates a [SPBitmap]. +/// Deallocates a [Bitmap]. /// /// # Panics /// @@ -142,15 +136,15 @@ pub unsafe extern "C" fn sp_bitmap_clone( /// /// The caller has to make sure that: /// -/// - `bitmap` points to a valid [SPBitmap] +/// - `bitmap` points to a valid [Bitmap] /// -/// [SPCommand]: [crate::SPCommand] +/// [TypedCommand]: [crate::TypedCommand] #[no_mangle] pub unsafe extern "C" fn sp_bitmap_free(bitmap: NonNull) { _ = unsafe { Box::from_raw(bitmap.as_ptr()) }; } -/// Gets the current value at the specified position in the [SPBitmap]. +/// Gets the current value at the specified position in the [Bitmap]. /// /// # Arguments /// @@ -166,7 +160,7 @@ pub unsafe extern "C" fn sp_bitmap_free(bitmap: NonNull) { /// /// The caller has to make sure that: /// -/// - `bitmap` points to a valid [SPBitmap] +/// - `bitmap` points to a valid [Bitmap] /// - `bitmap` is not written to concurrently #[no_mangle] pub unsafe extern "C" fn sp_bitmap_get( @@ -177,7 +171,7 @@ pub unsafe extern "C" fn sp_bitmap_get( unsafe { bitmap.as_ref().get(x, y) } } -/// Sets the value of the specified position in the [SPBitmap]. +/// Sets the value of the specified position in the [Bitmap]. /// /// # Arguments /// @@ -196,7 +190,7 @@ pub unsafe extern "C" fn sp_bitmap_get( /// /// The caller has to make sure that: /// -/// - `bitmap` points to a valid [SPBitmap] +/// - `bitmap` points to a valid [Bitmap] /// - `bitmap` is not written to or read from concurrently #[no_mangle] pub unsafe extern "C" fn sp_bitmap_set( @@ -208,7 +202,7 @@ pub unsafe extern "C" fn sp_bitmap_set( unsafe { (*bitmap.as_ptr()).set(x, y, value) }; } -/// Sets the state of all pixels in the [SPBitmap]. +/// Sets the state of all pixels in the [Bitmap]. /// /// # Arguments /// @@ -223,14 +217,14 @@ pub unsafe extern "C" fn sp_bitmap_set( /// /// The caller has to make sure that: /// -/// - `bitmap` points to a valid [SPBitmap] +/// - `bitmap` points to a valid [Bitmap] /// - `bitmap` is not written to or read from concurrently #[no_mangle] pub unsafe extern "C" fn sp_bitmap_fill(bitmap: NonNull, value: bool) { unsafe { (*bitmap.as_ptr()).fill(value) }; } -/// Gets the width in pixels of the [SPBitmap] instance. +/// Gets the width in pixels of the [Bitmap] instance. /// /// # Arguments /// @@ -244,13 +238,13 @@ pub unsafe extern "C" fn sp_bitmap_fill(bitmap: NonNull, value: bool) { /// /// The caller has to make sure that: /// -/// - `bitmap` points to a valid [SPBitmap] +/// - `bitmap` points to a valid [Bitmap] #[no_mangle] pub unsafe extern "C" fn sp_bitmap_width(bitmap: NonNull) -> usize { unsafe { bitmap.as_ref().width() } } -/// Gets the height in pixels of the [SPBitmap] instance. +/// Gets the height in pixels of the [Bitmap] instance. /// /// # Arguments /// @@ -264,13 +258,13 @@ pub unsafe extern "C" fn sp_bitmap_width(bitmap: NonNull) -> usize { /// /// The caller has to make sure that: /// -/// - `bitmap` points to a valid [SPBitmap] +/// - `bitmap` points to a valid [Bitmap] #[no_mangle] pub unsafe extern "C" fn sp_bitmap_height(bitmap: NonNull) -> usize { unsafe { bitmap.as_ref().height() } } -/// Gets an unsafe reference to the data of the [SPBitmap] instance. +/// Gets an unsafe reference to the data of the [Bitmap] instance. /// /// # Panics /// @@ -280,9 +274,9 @@ pub unsafe extern "C" fn sp_bitmap_height(bitmap: NonNull) -> usize { /// /// The caller has to make sure that: /// -/// - `bitmap` points to a valid [SPBitmap] -/// - the returned memory range is never accessed after the passed [SPBitmap] has been freed -/// - the returned memory range is never accessed concurrently, either via the [SPBitmap] or directly +/// - `bitmap` points to a valid [Bitmap] +/// - the returned memory range is never accessed after the passed [Bitmap] has been freed +/// - the returned memory range is never accessed concurrently, either via the [Bitmap] or directly #[no_mangle] pub unsafe extern "C" fn sp_bitmap_unsafe_data_ref( mut bitmap: NonNull, diff --git a/src/bitvec.rs b/src/bitvec.rs index c32ce78..a2ff022 100644 --- a/src/bitvec.rs +++ b/src/bitvec.rs @@ -108,9 +108,9 @@ pub unsafe extern "C" fn sp_bitvec_clone( /// /// - `bit_vec` points to a valid [SPBitVec] /// - `bit_vec` is not used concurrently or after this call -/// - `bit_vec` was not passed to another consuming function, e.g. to create a [SPCommand] +/// - `bit_vec` was not passed to another consuming function, e.g. to create a [TypedCommand] /// -/// [SPCommand]: [crate::SPCommand] +/// [TypedCommand]: [crate::TypedCommand] #[no_mangle] pub unsafe extern "C" fn sp_bitvec_free(bit_vec: NonNull) { _ = unsafe { Box::from_raw(bit_vec.as_ptr()) }; diff --git a/src/brightness_grid.rs b/src/brightness_grid.rs index 0e9a052..ff40ef9 100644 --- a/src/brightness_grid.rs +++ b/src/brightness_grid.rs @@ -1,4 +1,4 @@ -//! C functions for interacting with [SPBrightnessGrid]s +//! C functions for interacting with [BrightnessGrid]s //! //! prefix `sp_brightness_grid_` //! @@ -7,15 +7,15 @@ //! //! # Examples //! ```C -//! SPConnection connection = sp_connection_open("127.0.0.1:2342"); +//! UdpConnection connection = sp_connection_open("127.0.0.1:2342"); //! if (connection == NULL) //! return 1; //! -//! SPBrightnessGrid grid = sp_brightness_grid_new(2, 2); +//! BrightnessGrid grid = sp_brightness_grid_new(2, 2); //! sp_brightness_grid_set(grid, 0, 0, 0); //! sp_brightness_grid_set(grid, 1, 1, 10); //! -//! SPCommand command = sp_command_char_brightness(grid); +//! TypedCommand command = sp_command_char_brightness(grid); //! sp_connection_free(connection); //! ``` @@ -24,9 +24,9 @@ use servicepoint::{Brightness, BrightnessGrid, DataRef, Grid}; use std::mem::transmute; use std::ptr::NonNull; -/// Creates a new [SPBrightnessGrid] with the specified dimensions. +/// Creates a new [BrightnessGrid] with the specified dimensions. /// -/// returns: [SPBrightnessGrid] initialized to 0. Will never return NULL. +/// returns: [BrightnessGrid] initialized to 0. Will never return NULL. /// /// # Safety /// @@ -43,9 +43,9 @@ pub unsafe extern "C" fn sp_brightness_grid_new( NonNull::from(Box::leak(result)) } -/// Loads a [SPBrightnessGrid] with the specified dimensions from the provided data. +/// Loads a [BrightnessGrid] with the specified dimensions from the provided data. /// -/// returns: new [SPBrightnessGrid] instance. Will never return NULL. +/// returns: new [BrightnessGrid] instance. Will never return NULL. /// /// # Panics /// @@ -78,13 +78,13 @@ pub unsafe extern "C" fn sp_brightness_grid_load( } } -/// Clones a [SPBrightnessGrid]. +/// Clones a [BrightnessGrid]. /// /// # Arguments /// /// - `brightness_grid`: instance to read from /// -/// returns: new [SPBrightnessGrid] instance. Will never return NULL. +/// returns: new [BrightnessGrid] instance. Will never return NULL. /// /// # Panics /// @@ -94,7 +94,7 @@ pub unsafe extern "C" fn sp_brightness_grid_load( /// /// The caller has to make sure that: /// -/// - `brightness_grid` points to a valid [SPBrightnessGrid] +/// - `brightness_grid` points to a valid [BrightnessGrid] /// - `brightness_grid` is not written to concurrently /// - the returned instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_brightness_grid_free`. @@ -106,7 +106,7 @@ pub unsafe extern "C" fn sp_brightness_grid_clone( NonNull::from(Box::leak(result)) } -/// Deallocates a [SPBrightnessGrid]. +/// Deallocates a [BrightnessGrid]. /// /// # Arguments /// @@ -120,11 +120,11 @@ pub unsafe extern "C" fn sp_brightness_grid_clone( /// /// The caller has to make sure that: /// -/// - `brightness_grid` points to a valid [SPBrightnessGrid] +/// - `brightness_grid` points to a valid [BrightnessGrid] /// - `brightness_grid` is not used concurrently or after this call -/// - `brightness_grid` was not passed to another consuming function, e.g. to create a [SPCommand] +/// - `brightness_grid` was not passed to another consuming function, e.g. to create a [TypedCommand] /// -/// [SPCommand]: [crate::SPCommand] +/// [TypedCommand]: [crate::TypedCommand] #[no_mangle] pub unsafe extern "C" fn sp_brightness_grid_free( brightness_grid: NonNull, @@ -150,7 +150,7 @@ pub unsafe extern "C" fn sp_brightness_grid_free( /// /// The caller has to make sure that: /// -/// - `brightness_grid` points to a valid [SPBrightnessGrid] +/// - `brightness_grid` points to a valid [BrightnessGrid] /// - `brightness_grid` is not written to concurrently #[no_mangle] pub unsafe extern "C" fn sp_brightness_grid_get( @@ -161,7 +161,7 @@ pub unsafe extern "C" fn sp_brightness_grid_get( unsafe { brightness_grid.as_ref().get(x, y) } } -/// Sets the value of the specified position in the [SPBrightnessGrid]. +/// Sets the value of the specified position in the [BrightnessGrid]. /// /// # Arguments /// @@ -181,7 +181,7 @@ pub unsafe extern "C" fn sp_brightness_grid_get( /// /// The caller has to make sure that: /// -/// - `brightness_grid` points to a valid [SPBrightnessGrid] +/// - `brightness_grid` points to a valid [BrightnessGrid] /// - `brightness_grid` is not written to or read from concurrently #[no_mangle] pub unsafe extern "C" fn sp_brightness_grid_set( @@ -193,7 +193,7 @@ pub unsafe extern "C" fn sp_brightness_grid_set( unsafe { (*brightness_grid.as_ptr()).set(x, y, value) }; } -/// Sets the value of all cells in the [SPBrightnessGrid]. +/// Sets the value of all cells in the [BrightnessGrid]. /// /// # Arguments /// @@ -209,7 +209,7 @@ pub unsafe extern "C" fn sp_brightness_grid_set( /// /// The caller has to make sure that: /// -/// - `brightness_grid` points to a valid [SPBrightnessGrid] +/// - `brightness_grid` points to a valid [BrightnessGrid] /// - `brightness_grid` is not written to or read from concurrently #[no_mangle] pub unsafe extern "C" fn sp_brightness_grid_fill( @@ -219,7 +219,7 @@ pub unsafe extern "C" fn sp_brightness_grid_fill( unsafe { (*brightness_grid.as_ptr()).fill(value) }; } -/// Gets the width of the [SPBrightnessGrid] instance. +/// Gets the width of the [BrightnessGrid] instance. /// /// # Arguments /// @@ -235,7 +235,7 @@ pub unsafe extern "C" fn sp_brightness_grid_fill( /// /// The caller has to make sure that: /// -/// - `brightness_grid` points to a valid [SPBrightnessGrid] +/// - `brightness_grid` points to a valid [BrightnessGrid] #[no_mangle] pub unsafe extern "C" fn sp_brightness_grid_width( brightness_grid: NonNull, @@ -243,7 +243,7 @@ pub unsafe extern "C" fn sp_brightness_grid_width( unsafe { brightness_grid.as_ref().width() } } -/// Gets the height of the [SPBrightnessGrid] instance. +/// Gets the height of the [BrightnessGrid] instance. /// /// # Arguments /// @@ -259,7 +259,7 @@ pub unsafe extern "C" fn sp_brightness_grid_width( /// /// The caller has to make sure that: /// -/// - `brightness_grid` points to a valid [SPBrightnessGrid] +/// - `brightness_grid` points to a valid [BrightnessGrid] #[no_mangle] pub unsafe extern "C" fn sp_brightness_grid_height( brightness_grid: NonNull, @@ -267,7 +267,7 @@ pub unsafe extern "C" fn sp_brightness_grid_height( unsafe { brightness_grid.as_ref().height() } } -/// Gets an unsafe reference to the data of the [SPBrightnessGrid] instance. +/// Gets an unsafe reference to the data of the [BrightnessGrid] instance. /// /// # Arguments /// @@ -283,9 +283,9 @@ pub unsafe extern "C" fn sp_brightness_grid_height( /// /// The caller has to make sure that: /// -/// - `brightness_grid` points to a valid [SPBrightnessGrid] -/// - the returned memory range is never accessed after the passed [SPBrightnessGrid] has been freed -/// - the returned memory range is never accessed concurrently, either via the [SPBrightnessGrid] or directly +/// - `brightness_grid` points to a valid [BrightnessGrid] +/// - the returned memory range is never accessed after the passed [BrightnessGrid] has been freed +/// - the returned memory range is never accessed concurrently, either via the [BrightnessGrid] or directly #[no_mangle] pub unsafe extern "C" fn sp_brightness_grid_unsafe_data_ref( brightness_grid: NonNull, diff --git a/src/char_grid.rs b/src/char_grid.rs index a845f4e..30e9953 100644 --- a/src/char_grid.rs +++ b/src/char_grid.rs @@ -1,4 +1,4 @@ -//! C functions for interacting with [SPCharGrid]s +//! C functions for interacting with [CharGrid]s //! //! prefix `sp_char_grid_` //! @@ -22,9 +22,9 @@ use crate::SPByteSlice; use servicepoint::{CharGrid, Grid}; use std::ptr::NonNull; -/// Creates a new [SPCharGrid] with the specified dimensions. +/// Creates a new [CharGrid] with the specified dimensions. /// -/// returns: [SPCharGrid] initialized to 0. Will never return NULL. +/// returns: [CharGrid] initialized to 0. Will never return NULL. /// /// # Safety /// @@ -41,7 +41,7 @@ pub unsafe extern "C" fn sp_char_grid_new( NonNull::from(Box::leak(result)) } -/// Loads a [SPCharGrid] with the specified dimensions from the provided data. +/// Loads a [CharGrid] with the specified dimensions from the provided data. /// /// Will never return NULL. /// @@ -72,7 +72,7 @@ pub unsafe extern "C" fn sp_char_grid_load( NonNull::from(Box::leak(result)) } -/// Clones a [SPCharGrid]. +/// Clones a [CharGrid]. /// /// Will never return NULL. /// @@ -84,7 +84,7 @@ pub unsafe extern "C" fn sp_char_grid_load( /// /// The caller has to make sure that: /// -/// - `char_grid` points to a valid [SPCharGrid] +/// - `char_grid` points to a valid [CharGrid] /// - `char_grid` is not written to concurrently /// - the returned instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_char_grid_free`. @@ -96,7 +96,7 @@ pub unsafe extern "C" fn sp_char_grid_clone( NonNull::from(Box::leak(result)) } -/// Deallocates a [SPCharGrid]. +/// Deallocates a [CharGrid]. /// /// # Panics /// @@ -106,11 +106,11 @@ pub unsafe extern "C" fn sp_char_grid_clone( /// /// The caller has to make sure that: /// -/// - `char_grid` points to a valid [SPCharGrid] +/// - `char_grid` points to a valid [CharGrid] /// - `char_grid` is not used concurrently or after char_grid call -/// - `char_grid` was not passed to another consuming function, e.g. to create a [SPCommand] +/// - `char_grid` was not passed to another consuming function, e.g. to create a [TypedCommand] /// -/// [SPCommand]: [crate::SPCommand] +/// [TypedCommand]: [crate::TypedCommand] #[no_mangle] pub unsafe extern "C" fn sp_char_grid_free(char_grid: NonNull) { _ = unsafe { Box::from_raw(char_grid.as_ptr()) }; @@ -132,7 +132,7 @@ pub unsafe extern "C" fn sp_char_grid_free(char_grid: NonNull) { /// /// The caller has to make sure that: /// -/// - `char_grid` points to a valid [SPCharGrid] +/// - `char_grid` points to a valid [CharGrid] /// - `char_grid` is not written to concurrently #[no_mangle] pub unsafe extern "C" fn sp_char_grid_get( @@ -143,7 +143,7 @@ pub unsafe extern "C" fn sp_char_grid_get( unsafe { char_grid.as_ref().get(x, y) as u32 } } -/// Sets the value of the specified position in the [SPCharGrid]. +/// Sets the value of the specified position in the [CharGrid]. /// /// # Arguments /// @@ -176,7 +176,7 @@ pub unsafe extern "C" fn sp_char_grid_set( unsafe { (*char_grid.as_ptr()).set(x, y, char::from_u32(value).unwrap()) }; } -/// Sets the value of all cells in the [SPCharGrid]. +/// Sets the value of all cells in the [CharGrid]. /// /// # Arguments /// @@ -191,7 +191,7 @@ pub unsafe extern "C" fn sp_char_grid_set( /// /// The caller has to make sure that: /// -/// - `char_grid` points to a valid [SPCharGrid] +/// - `char_grid` points to a valid [CharGrid] /// - `char_grid` is not written to or read from concurrently #[no_mangle] pub unsafe extern "C" fn sp_char_grid_fill( @@ -201,7 +201,7 @@ pub unsafe extern "C" fn sp_char_grid_fill( unsafe { (*char_grid.as_ptr()).fill(char::from_u32(value).unwrap()) }; } -/// Gets the width of the [SPCharGrid] instance. +/// Gets the width of the [CharGrid] instance. /// /// # Arguments /// @@ -215,7 +215,7 @@ pub unsafe extern "C" fn sp_char_grid_fill( /// /// The caller has to make sure that: /// -/// - `char_grid` points to a valid [SPCharGrid] +/// - `char_grid` points to a valid [CharGrid] #[no_mangle] pub unsafe extern "C" fn sp_char_grid_width( char_grid: NonNull, @@ -223,7 +223,7 @@ pub unsafe extern "C" fn sp_char_grid_width( unsafe { char_grid.as_ref().width() } } -/// Gets the height of the [SPCharGrid] instance. +/// Gets the height of the [CharGrid] instance. /// /// # Arguments /// @@ -237,7 +237,7 @@ pub unsafe extern "C" fn sp_char_grid_width( /// /// The caller has to make sure that: /// -/// - `char_grid` points to a valid [SPCharGrid] +/// - `char_grid` points to a valid [CharGrid] #[no_mangle] pub unsafe extern "C" fn sp_char_grid_height( char_grid: NonNull, diff --git a/src/command.rs b/src/command.rs index e107c07..2ed7415 100644 --- a/src/command.rs +++ b/src/command.rs @@ -1,4 +1,4 @@ -//! C functions for interacting with [SPCommand]s +//! C functions for interacting with [TypedCommand]s //! //! prefix `sp_command_` @@ -10,7 +10,7 @@ use std::ptr::NonNull; /// /// This struct and associated functions implement the UDP protocol for the display. /// -/// To send a [SPCommand], use a [SPConnection]. +/// To send a [TypedCommand], use a [UdpConnection]. /// /// # Examples /// @@ -18,14 +18,12 @@ use std::ptr::NonNull; /// sp_connection_send_command(connection, sp_command_clear()); /// sp_connection_send_command(connection, sp_command_brightness(5)); /// ``` -/// -/// [SPConnection]: [crate::SPConnection] -/// Tries to turn a [SPPacket] into a [SPCommand]. +/// Tries to turn a [Packet] into a [TypedCommand]. /// /// The packet is deallocated in the process. /// -/// Returns: pointer to new [SPCommand] instance or NULL if parsing failed. +/// Returns: pointer to new [TypedCommand] instance or NULL if parsing failed. /// /// # Panics /// @@ -35,10 +33,10 @@ use std::ptr::NonNull; /// /// The caller has to make sure that: /// -/// - [SPPacket] points to a valid instance of [SPPacket] -/// - [SPPacket] is not used concurrently or after this call +/// - [Packet] points to a valid instance of [Packet] +/// - [Packet] is not used concurrently or after this call /// - the result is checked for NULL -/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or +/// - the returned [TypedCommand] instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_command_free`. #[no_mangle] pub unsafe extern "C" fn sp_command_try_from_packet( @@ -51,9 +49,9 @@ pub unsafe extern "C" fn sp_command_try_from_packet( } } -/// Clones a [SPCommand] instance. +/// Clones a [TypedCommand] instance. /// -/// returns: new [SPCommand] instance. Will never return NULL. +/// returns: new [TypedCommand] instance. Will never return NULL. /// /// # Panics /// @@ -63,9 +61,9 @@ pub unsafe extern "C" fn sp_command_try_from_packet( /// /// The caller has to make sure that: /// -/// - `command` points to a valid instance of [SPCommand] +/// - `command` points to a valid instance of [TypedCommand] /// - `command` is not written to concurrently -/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or +/// - the returned [TypedCommand] instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_command_free`. #[no_mangle] pub unsafe extern "C" fn sp_command_clone( @@ -91,7 +89,7 @@ pub unsafe extern "C" fn sp_command_clone( /// /// The caller has to make sure that: /// -/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or +/// - the returned [TypedCommand] instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_command_free`. #[no_mangle] pub unsafe extern "C" fn sp_command_clear() -> NonNull { @@ -109,7 +107,7 @@ pub unsafe extern "C" fn sp_command_clear() -> NonNull { /// /// The caller has to make sure that: /// -/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or +/// - the returned [TypedCommand] instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_command_free`. #[no_mangle] pub unsafe extern "C" fn sp_command_hard_reset() -> NonNull { @@ -125,7 +123,7 @@ pub unsafe extern "C" fn sp_command_hard_reset() -> NonNull { /// /// The caller has to make sure that: /// -/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or +/// - the returned [TypedCommand] instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_command_free`. #[no_mangle] pub unsafe extern "C" fn sp_command_fade_out() -> NonNull { @@ -145,7 +143,7 @@ pub unsafe extern "C" fn sp_command_fade_out() -> NonNull { /// /// The caller has to make sure that: /// -/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or +/// - the returned [TypedCommand] instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_command_free`. #[no_mangle] pub unsafe extern "C" fn sp_command_brightness( @@ -157,7 +155,7 @@ pub unsafe extern "C" fn sp_command_brightness( /// Set the brightness of individual tiles in a rectangular area of the display. /// -/// The passed [SPBrightnessGrid] gets consumed. +/// The passed [BrightnessGrid] gets consumed. /// /// Returns: a new [servicepoint::Command::CharBrightness] instance. Will never return NULL. /// @@ -169,9 +167,9 @@ pub unsafe extern "C" fn sp_command_brightness( /// /// The caller has to make sure that: /// -/// - `grid` points to a valid instance of [SPBrightnessGrid] +/// - `grid` points to a valid instance of [BrightnessGrid] /// - `grid` is not used concurrently or after this call -/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or +/// - the returned [TypedCommand] instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_command_free`. #[no_mangle] pub unsafe extern "C" fn sp_command_char_brightness( @@ -213,7 +211,7 @@ pub unsafe extern "C" fn sp_command_char_brightness( /// - `bit_vec` points to a valid instance of [SPBitVec] /// - `bit_vec` is not used concurrently or after this call /// - `compression` matches one of the allowed enum values -/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or +/// - the returned [TypedCommand] instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_command_free`. #[no_mangle] pub unsafe extern "C" fn sp_command_bitmap_linear( @@ -254,7 +252,7 @@ pub unsafe extern "C" fn sp_command_bitmap_linear( /// - `bit_vec` points to a valid instance of [SPBitVec] /// - `bit_vec` is not used concurrently or after this call /// - `compression` matches one of the allowed enum values -/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or +/// - the returned [TypedCommand] instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_command_free`. #[no_mangle] pub unsafe extern "C" fn sp_command_bitmap_linear_and( @@ -295,7 +293,7 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_and( /// - `bit_vec` points to a valid instance of [SPBitVec] /// - `bit_vec` is not used concurrently or after this call /// - `compression` matches one of the allowed enum values -/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or +/// - the returned [TypedCommand] instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_command_free`. #[no_mangle] pub unsafe extern "C" fn sp_command_bitmap_linear_or( @@ -336,7 +334,7 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_or( /// - `bit_vec` points to a valid instance of [SPBitVec] /// - `bit_vec` is not used concurrently or after this call /// - `compression` matches one of the allowed enum values -/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or +/// - the returned [TypedCommand] instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_command_free`. #[no_mangle] pub unsafe extern "C" fn sp_command_bitmap_linear_xor( @@ -378,7 +376,7 @@ unsafe fn sp_command_bitmap_linear_internal( /// Show codepage 437 encoded text on the screen. /// -/// The passed [SPCp437Grid] gets consumed. +/// The passed [Cp437Grid] gets consumed. /// /// Returns: a new [servicepoint::Command::Cp437Data] instance. Will never return NULL. /// @@ -390,9 +388,9 @@ unsafe fn sp_command_bitmap_linear_internal( /// /// The caller has to make sure that: /// -/// - `grid` points to a valid instance of [SPCp437Grid] +/// - `grid` points to a valid instance of [Cp437Grid] /// - `grid` is not used concurrently or after this call -/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or +/// - the returned [TypedCommand] instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_command_free`. #[no_mangle] pub unsafe extern "C" fn sp_command_cp437_data( @@ -413,7 +411,7 @@ pub unsafe extern "C" fn sp_command_cp437_data( /// Show UTF-8 encoded text on the screen. /// -/// The passed [SPCharGrid] gets consumed. +/// The passed [CharGrid] gets consumed. /// /// Returns: a new [servicepoint::Command::Utf8Data] instance. Will never return NULL. /// @@ -425,9 +423,9 @@ pub unsafe extern "C" fn sp_command_cp437_data( /// /// The caller has to make sure that: /// -/// - `grid` points to a valid instance of [SPCharGrid] +/// - `grid` points to a valid instance of [CharGrid] /// - `grid` is not used concurrently or after this call -/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or +/// - the returned [TypedCommand] instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_command_free`. #[no_mangle] pub unsafe extern "C" fn sp_command_utf8_data( @@ -448,7 +446,7 @@ pub unsafe extern "C" fn sp_command_utf8_data( /// Sets a window of pixels to the specified values. /// -/// The passed [SPBitmap] gets consumed. +/// The passed [Bitmap] gets consumed. /// /// Returns: a new [servicepoint::Command::BitmapLinearWin] instance. Will never return NULL. /// @@ -461,10 +459,10 @@ pub unsafe extern "C" fn sp_command_utf8_data( /// /// The caller has to make sure that: /// -/// - `bitmap` points to a valid instance of [SPBitmap] +/// - `bitmap` points to a valid instance of [Bitmap] /// - `bitmap` is not used concurrently or after this call /// - `compression` matches one of the allowed enum values -/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or +/// - the returned [TypedCommand] instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_command_free`. #[no_mangle] pub unsafe extern "C" fn sp_command_bitmap_linear_win( @@ -487,12 +485,12 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_win( Box::leak(Box::new(command)) } -/// Deallocates a [SPCommand]. +/// Deallocates a [TypedCommand]. /// /// # Examples /// /// ```C -/// SPCommand c = sp_command_clear(); +/// TypedCommand c = sp_command_clear(); /// sp_command_free(c); /// ``` /// @@ -504,9 +502,9 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_win( /// /// The caller has to make sure that: /// -/// - `command` points to a valid [SPCommand] +/// - `command` points to a valid [TypedCommand] /// - `command` is not used concurrently or after this call -/// - `command` was not passed to another consuming function, e.g. to create a [SPPacket] +/// - `command` was not passed to another consuming function, e.g. to create a [Packet] #[no_mangle] pub unsafe extern "C" fn sp_command_free(command: NonNull) { _ = unsafe { Box::from_raw(command.as_ptr()) }; diff --git a/src/connection.rs b/src/connection.rs index 1705538..79e2e33 100644 --- a/src/connection.rs +++ b/src/connection.rs @@ -1,4 +1,4 @@ -//! C functions for interacting with [SPConnection]s +//! C functions for interacting with [UdpConnection]s //! //! prefix `sp_connection_` //! @@ -16,7 +16,7 @@ use servicepoint::{Connection, Packet, TypedCommand, UdpConnection}; use std::ffi::{c_char, CStr}; use std::ptr::NonNull; -/// Creates a new instance of [SPConnection]. +/// Creates a new instance of [UdpConnection]. /// /// returns: NULL if connection fails, or connected instance /// @@ -48,13 +48,13 @@ pub unsafe extern "C" fn sp_connection_open( //#[no_mangle] //pub unsafe extern "C" fn sp_connection_open_ipv4( // host: SocketAddrV4, -//) -> *mut SPConnection { +//) -> *mut UdpConnection { // let connection = match servicepoint::UdpConnection::open(host) { // Err(_) => return std::ptr::null_mut(), // Ok(value) => value, // }; // -// Box::into_raw(Box::new(SPConnection(connection))) +// Box::into_raw(Box::new(UdpConnection(connection))) //} // /// Creates a new instance of [SPUdpConnection] for testing that does not actually send anything. @@ -73,7 +73,7 @@ pub unsafe extern "C" fn sp_connection_open( // NonNull::from(Box::leak(result)) // } -/// Sends a [SPPacket] to the display using the [SPConnection]. +/// Sends a [Packet] to the display using the [UdpConnection]. /// /// The passed `packet` gets consumed. /// @@ -88,8 +88,8 @@ pub unsafe extern "C" fn sp_connection_open( /// /// The caller has to make sure that: /// -/// - `connection` points to a valid instance of [SPConnection] -/// - `packet` points to a valid instance of [SPPacket] +/// - `connection` points to a valid instance of [UdpConnection] +/// - `packet` points to a valid instance of [Packet] /// - `packet` is not used concurrently or after this call #[no_mangle] pub unsafe extern "C" fn sp_connection_send_packet( @@ -100,7 +100,7 @@ pub unsafe extern "C" fn sp_connection_send_packet( unsafe { connection.as_ref().send(*packet) }.is_ok() } -/// Sends a [SPCommand] to the display using the [SPConnection]. +/// Sends a [TypedCommand] to the display using the [UdpConnection]. /// /// The passed `command` gets consumed. /// @@ -115,8 +115,8 @@ pub unsafe extern "C" fn sp_connection_send_packet( /// /// The caller has to make sure that: /// -/// - `connection` points to a valid instance of [SPConnection] -/// - `command` points to a valid instance of [SPPacket] +/// - `connection` points to a valid instance of [UdpConnection] +/// - `command` points to a valid instance of [Packet] /// - `command` is not used concurrently or after this call #[no_mangle] pub unsafe extern "C" fn sp_connection_send_command( @@ -127,7 +127,7 @@ pub unsafe extern "C" fn sp_connection_send_command( unsafe { connection.as_ref().send(command) }.is_ok() } -/// Closes and deallocates a [SPConnection]. +/// Closes and deallocates a [UdpConnection]. /// /// # Panics /// @@ -137,7 +137,7 @@ pub unsafe extern "C" fn sp_connection_send_command( /// /// The caller has to make sure that: /// -/// - `connection` points to a valid [SPConnection] +/// - `connection` points to a valid [UdpConnection] /// - `connection` is not used concurrently or after this call #[no_mangle] pub unsafe extern "C" fn sp_connection_free( diff --git a/src/cp437_grid.rs b/src/cp437_grid.rs index e635247..96db2db 100644 --- a/src/cp437_grid.rs +++ b/src/cp437_grid.rs @@ -1,4 +1,4 @@ -//! C functions for interacting with [SPCp437Grid]s +//! C functions for interacting with [Cp437Grid]s //! //! prefix `sp_cp437_grid_` //! @@ -20,9 +20,9 @@ use crate::SPByteSlice; use servicepoint::{Cp437Grid, DataRef, Grid}; use std::ptr::NonNull; -/// Creates a new [SPCp437Grid] with the specified dimensions. +/// Creates a new [Cp437Grid] with the specified dimensions. /// -/// returns: [SPCp437Grid] initialized to 0. Will never return NULL. +/// returns: [Cp437Grid] initialized to 0. Will never return NULL. /// /// # Safety /// @@ -39,7 +39,7 @@ pub unsafe extern "C" fn sp_cp437_grid_new( NonNull::from(Box::leak(result)) } -/// Loads a [SPCp437Grid] with the specified dimensions from the provided data. +/// Loads a [Cp437Grid] with the specified dimensions from the provided data. /// /// Will never return NULL. /// @@ -71,7 +71,7 @@ pub unsafe extern "C" fn sp_cp437_grid_load( } } -/// Clones a [SPCp437Grid]. +/// Clones a [Cp437Grid]. /// /// Will never return NULL. /// @@ -83,7 +83,7 @@ pub unsafe extern "C" fn sp_cp437_grid_load( /// /// The caller has to make sure that: /// -/// - `cp437_grid` points to a valid [SPCp437Grid] +/// - `cp437_grid` points to a valid [Cp437Grid] /// - `cp437_grid` is not written to concurrently /// - the returned instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_cp437_grid_free`. @@ -95,7 +95,7 @@ pub unsafe extern "C" fn sp_cp437_grid_clone( NonNull::from(Box::leak(result)) } -/// Deallocates a [SPCp437Grid]. +/// Deallocates a [Cp437Grid]. /// /// # Panics /// @@ -105,11 +105,11 @@ pub unsafe extern "C" fn sp_cp437_grid_clone( /// /// The caller has to make sure that: /// -/// - `cp437_grid` points to a valid [SPCp437Grid] +/// - `cp437_grid` points to a valid [Cp437Grid] /// - `cp437_grid` is not used concurrently or after cp437_grid call -/// - `cp437_grid` was not passed to another consuming function, e.g. to create a [SPCommand] +/// - `cp437_grid` was not passed to another consuming function, e.g. to create a [TypedCommand] /// -/// [SPCommand]: [crate::SPCommand] +/// [TypedCommand]: [crate::TypedCommand] #[no_mangle] pub unsafe extern "C" fn sp_cp437_grid_free(cp437_grid: NonNull) { _ = unsafe { Box::from_raw(cp437_grid.as_ptr()) }; @@ -131,7 +131,7 @@ pub unsafe extern "C" fn sp_cp437_grid_free(cp437_grid: NonNull) { /// /// The caller has to make sure that: /// -/// - `cp437_grid` points to a valid [SPCp437Grid] +/// - `cp437_grid` points to a valid [Cp437Grid] /// - `cp437_grid` is not written to concurrently #[no_mangle] pub unsafe extern "C" fn sp_cp437_grid_get( @@ -142,7 +142,7 @@ pub unsafe extern "C" fn sp_cp437_grid_get( unsafe { cp437_grid.as_ref().get(x, y) } } -/// Sets the value of the specified position in the [SPCp437Grid]. +/// Sets the value of the specified position in the [Cp437Grid]. /// /// # Arguments /// @@ -175,7 +175,7 @@ pub unsafe extern "C" fn sp_cp437_grid_set( unsafe { (*cp437_grid.as_ptr()).set(x, y, value) }; } -/// Sets the value of all cells in the [SPCp437Grid]. +/// Sets the value of all cells in the [Cp437Grid]. /// /// # Arguments /// @@ -190,7 +190,7 @@ pub unsafe extern "C" fn sp_cp437_grid_set( /// /// The caller has to make sure that: /// -/// - `cp437_grid` points to a valid [SPCp437Grid] +/// - `cp437_grid` points to a valid [Cp437Grid] /// - `cp437_grid` is not written to or read from concurrently #[no_mangle] pub unsafe extern "C" fn sp_cp437_grid_fill( @@ -200,7 +200,7 @@ pub unsafe extern "C" fn sp_cp437_grid_fill( unsafe { (*cp437_grid.as_ptr()).fill(value) }; } -/// Gets the width of the [SPCp437Grid] instance. +/// Gets the width of the [Cp437Grid] instance. /// /// # Arguments /// @@ -214,7 +214,7 @@ pub unsafe extern "C" fn sp_cp437_grid_fill( /// /// The caller has to make sure that: /// -/// - `cp437_grid` points to a valid [SPCp437Grid] +/// - `cp437_grid` points to a valid [Cp437Grid] #[no_mangle] pub unsafe extern "C" fn sp_cp437_grid_width( cp437_grid: NonNull, @@ -222,7 +222,7 @@ pub unsafe extern "C" fn sp_cp437_grid_width( unsafe { cp437_grid.as_ref().width() } } -/// Gets the height of the [SPCp437Grid] instance. +/// Gets the height of the [Cp437Grid] instance. /// /// # Arguments /// @@ -236,7 +236,7 @@ pub unsafe extern "C" fn sp_cp437_grid_width( /// /// The caller has to make sure that: /// -/// - `cp437_grid` points to a valid [SPCp437Grid] +/// - `cp437_grid` points to a valid [Cp437Grid] #[no_mangle] pub unsafe extern "C" fn sp_cp437_grid_height( cp437_grid: NonNull, @@ -244,7 +244,7 @@ pub unsafe extern "C" fn sp_cp437_grid_height( unsafe { cp437_grid.as_ref().height() } } -/// Gets an unsafe reference to the data of the [SPCp437Grid] instance. +/// Gets an unsafe reference to the data of the [Cp437Grid] instance. /// /// Will never return NULL. /// @@ -256,9 +256,9 @@ pub unsafe extern "C" fn sp_cp437_grid_height( /// /// The caller has to make sure that: /// -/// - `cp437_grid` points to a valid [SPCp437Grid] -/// - the returned memory range is never accessed after the passed [SPCp437Grid] has been freed -/// - the returned memory range is never accessed concurrently, either via the [SPCp437Grid] or directly +/// - `cp437_grid` points to a valid [Cp437Grid] +/// - the returned memory range is never accessed after the passed [Cp437Grid] has been freed +/// - the returned memory range is never accessed concurrently, either via the [Cp437Grid] or directly #[no_mangle] pub unsafe extern "C" fn sp_cp437_grid_unsafe_data_ref( cp437_grid: NonNull, diff --git a/src/lib.rs b/src/lib.rs index 831daea..4d4e386 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -9,14 +9,14 @@ //! #include "servicepoint.h" //! //! int main(void) { -//! SPConnection *connection = sp_connection_open("172.23.42.29:2342"); +//! UdpConnection *connection = sp_connection_open("172.23.42.29:2342"); //! if (connection == NULL) //! return 1; //! -//! SPBitmap *pixels = sp_bitmap_new(SP_PIXEL_WIDTH, SP_PIXEL_HEIGHT); +//! Bitmap *pixels = sp_bitmap_new(SP_PIXEL_WIDTH, SP_PIXEL_HEIGHT); //! sp_bitmap_fill(pixels, true); //! -//! SPCommand *command = sp_command_bitmap_linear_win(0, 0, pixels, Uncompressed); +//! TypedCommand *command = sp_command_bitmap_linear_win(0, 0, pixels, Uncompressed); //! while (sp_connection_send_command(connection, sp_command_clone(command))); //! //! sp_command_free(command); diff --git a/src/packet.rs b/src/packet.rs index f8235ab..ae37058 100644 --- a/src/packet.rs +++ b/src/packet.rs @@ -1,4 +1,4 @@ -//! C functions for interacting with [SPPacket]s +//! C functions for interacting with [Packet]s //! //! prefix `sp_packet_` //! @@ -9,10 +9,10 @@ use crate::SPByteSlice; use servicepoint::{Header, Packet, TypedCommand}; use std::ptr::NonNull; -/// Turns a [SPCommand] into a [SPPacket]. -/// The [SPCommand] gets consumed. +/// Turns a [TypedCommand] into a [Packet]. +/// The [TypedCommand] gets consumed. /// -/// Will never return NULL. +/// Returns NULL in case of an error. /// /// # Panics /// @@ -22,9 +22,9 @@ use std::ptr::NonNull; /// /// The caller has to make sure that: /// -/// - [SPCommand] points to a valid instance of [SPCommand] -/// - [SPCommand] is not used concurrently or after this call -/// - the returned [SPPacket] instance is freed in some way, either by using a consuming function or +/// - [TypedCommand] points to a valid instance of [TypedCommand] +/// - [TypedCommand] is not used concurrently or after this call +/// - the returned [Packet] instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_packet_free`. #[no_mangle] pub unsafe extern "C" fn sp_packet_from_command( @@ -38,7 +38,7 @@ pub unsafe extern "C" fn sp_packet_from_command( } } -/// Tries to load a [SPPacket] from the passed array with the specified length. +/// Tries to load a [Packet] from the passed array with the specified length. /// /// returns: NULL in case of an error, pointer to the allocated packet otherwise /// @@ -52,7 +52,7 @@ pub unsafe extern "C" fn sp_packet_from_command( /// /// - `data` points to a valid memory region of at least `length` bytes /// - `data` is not written to concurrently -/// - the returned [SPPacket] instance is freed in some way, either by using a consuming function or +/// - the returned [Packet] instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_packet_free`. #[no_mangle] pub unsafe extern "C" fn sp_packet_try_load(data: SPByteSlice) -> *mut Packet { @@ -63,7 +63,7 @@ pub unsafe extern "C" fn sp_packet_try_load(data: SPByteSlice) -> *mut Packet { } } -/// Creates a raw [SPPacket] from parts. +/// Creates a raw [Packet] from parts. /// /// # Arguments /// @@ -85,7 +85,7 @@ pub unsafe extern "C" fn sp_packet_try_load(data: SPByteSlice) -> *mut Packet { /// /// - `payload` points to a valid memory region of at least `payload_len` bytes /// - `payload` is not written to concurrently -/// - the returned [SPPacket] instance is freed in some way, either by using a consuming function or +/// - the returned [Packet] instance is freed in some way, either by using a consuming function or /// by explicitly calling [sp_packet_free]. #[no_mangle] pub unsafe extern "C" fn sp_packet_from_parts( @@ -103,6 +103,9 @@ pub unsafe extern "C" fn sp_packet_from_parts( NonNull::from(Box::leak(packet)) } +/// Returns a pointer to the header field of the provided packet. +/// +/// The returned header can be changed and will be valid for the lifetime of the packet. #[no_mangle] pub unsafe extern "C" fn sp_packet_get_header( packet: NonNull, @@ -110,6 +113,9 @@ pub unsafe extern "C" fn sp_packet_get_header( NonNull::from(&mut unsafe { (*packet.as_ptr()).header }) } +/// Returns a pointer to the current payload of the provided packet. +/// +/// The returned memory can be changed and will be valid until a new payload is set. #[no_mangle] pub unsafe extern "C" fn sp_packet_get_payload( packet: NonNull, @@ -117,6 +123,9 @@ pub unsafe extern "C" fn sp_packet_get_payload( unsafe { SPByteSlice::from_slice(&mut *(*packet.as_ptr()).payload) } } +/// Sets the payload of the provided packet to the provided data. +/// +/// This makes previous payload pointers invalid. #[no_mangle] pub unsafe extern "C" fn sp_packet_set_payload( packet: NonNull, @@ -125,8 +134,13 @@ pub unsafe extern "C" fn sp_packet_set_payload( unsafe { (*packet.as_ptr()).payload = data.as_slice().to_vec() } } +/// Serialize the packet into the provided buffer. +/// +/// # Panics +/// +/// - if the buffer is not big enough to hold header+payload. #[no_mangle] -pub unsafe extern "C" fn sp_packet_write_to( +pub unsafe extern "C" fn sp_packet_serialize_to( packet: NonNull, buffer: SPByteSlice, ) { @@ -135,7 +149,7 @@ pub unsafe extern "C" fn sp_packet_write_to( } } -/// Clones a [SPPacket]. +/// Clones a [Packet]. /// /// Will never return NULL. /// @@ -147,7 +161,7 @@ pub unsafe extern "C" fn sp_packet_write_to( /// /// The caller has to make sure that: /// -/// - `packet` points to a valid [SPPacket] +/// - `packet` points to a valid [Packet] /// - `packet` is not written to concurrently /// - the returned instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_packet_free`. @@ -159,7 +173,7 @@ pub unsafe extern "C" fn sp_packet_clone( NonNull::from(Box::leak(result)) } -/// Deallocates a [SPPacket]. +/// Deallocates a [Packet]. /// /// # Panics /// @@ -169,7 +183,7 @@ pub unsafe extern "C" fn sp_packet_clone( /// /// The caller has to make sure that: /// -/// - `packet` points to a valid [SPPacket] +/// - `packet` points to a valid [Packet] /// - `packet` is not used concurrently or after this call #[no_mangle] pub unsafe extern "C" fn sp_packet_free(packet: NonNull) {