servicepoint/servicepoint-binding-c
0
2
Fork 0
Code Issues 1 Pull requests 1 Projects Releases 2 Packages Wiki Activity Actions

wip remove newtypes

Browse source
This commit is contained in:
Vinzenz Schroeter 2025-04-12 10:54:47 +02:00
parent 6f5698a95e
commit cf9877ce7b
14 changed files with 497 additions and 430 deletions
Download patch file Download diff file Expand all files Collapse all files

2
examples/lang_c/Makefile
View file

@ -36,7 +36,7 @@ CCFLAGS := -static -Os \
-fvisibility=hidden \
-Bsymbolic \
-Wl,--exclude-libs,ALL \
-fno-ident \
-fno-ident
#-fuse-ld=gold \
-fno-exceptions
#-Wl,--icf=all \

426
examples/lang_c/include/servicepoint.h
View file

@ -86,6 +86,32 @@ enum SPCompressionCode
typedef uint16_t SPCompressionCode;
#endif // __cplusplus
/**
* A fixed-size 2D grid of booleans.
*
* The values are stored in packed bytes (8 values per byte) in the same order as used by the display for storing pixels.
* This means that no conversion is necessary for sending the data to the display.
* The downside is that the width has to be a multiple of 8.
*
* # Examples
*
* ```rust
* use servicepoint::Bitmap;
* let mut bitmap = Bitmap::new(8, 2);
*
* ```
*/
typedef struct Bitmap Bitmap;
/**
* The raw packet.
*
* Contents should probably only be used directly to use features not exposed by the library.
*
* You may want to use [`crate::Command`] or [`crate::TypedCommand`] instead.
*/
typedef struct Packet Packet;
/**
* A vector of bits
*
@ -99,108 +125,51 @@ typedef uint16_t SPCompressionCode;
typedef struct SPBitVec SPBitVec;
/**
* A grid of pixels.
* This enum contains all commands provided by the library.
* This is useful in case you want one data type for all kinds of commands without using `dyn`.
*
* # 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);
* ```
* Please look at the contained structs for documentation per command.
*/
typedef struct SPBitmap SPBitmap;
typedef struct Command Command;
/**
* A grid containing brightness values.
* A connection using the UDP protocol.
*
* # Examples
* ```C
* SPConnection connection = sp_connection_open("127.0.0.1:2342");
* if (connection == NULL)
* return 1;
* Use this when sending commands directly to the display.
*
* SPBrightnessGrid 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);
* sp_connection_free(connection);
* ```
* Requires the feature "`protocol_udp`" which is enabled by default.
*/
typedef struct SPBrightnessGrid SPBrightnessGrid;
typedef struct UdpConnection UdpConnection;
/**
* A C-wrapper for grid containing UTF-8 characters.
* A 2D grid of values.
*
* As the rust [char] type is not FFI-safe, characters are passed in their UTF-32 form as 32bit unsigned integers.
* The memory layout is the one the display expects in [`crate::Command`]s.
*
* The encoding is enforced in most cases by the rust standard library
* and will panic when provided with illegal characters.
*
* # Examples
*
* ```C
* CharGrid grid = sp_char_grid_new(4, 3);
* sp_char_grid_fill(grid, '?');
* sp_char_grid_set(grid, 0, 0, '!');
* sp_char_grid_free(grid);
* ```
* This structure can be used with any type that implements the [Value] trait.
* You can also use the concrete type aliases provided in this crate, e.g. [`crate::CharGrid`] and [`crate::ByteGrid`].
*/
typedef struct SPCharGrid SPCharGrid;
typedef struct ValueGrid_Brightness ValueGrid_Brightness;
/**
* A low-level display command.
* A 2D grid of values.
*
* This struct and associated functions implement the UDP protocol for the display.
* The memory layout is the one the display expects in [`crate::Command`]s.
*
* To send a [SPCommand], use a [SPConnection].
*
* # Examples
*
* ```C
* sp_connection_send_command(connection, sp_command_clear());
* sp_connection_send_command(connection, sp_command_brightness(5));
* ```
*
* [SPConnection]: [crate::SPConnection]
* This structure can be used with any type that implements the [Value] trait.
* You can also use the concrete type aliases provided in this crate, e.g. [`crate::CharGrid`] and [`crate::ByteGrid`].
*/
typedef struct SPCommand SPCommand;
typedef struct ValueGrid_char ValueGrid_char;
/**
* A connection to the display.
* A 2D grid of values.
*
* # Examples
* The memory layout is the one the display expects in [`crate::Command`]s.
*
* ```C
* CConnection connection = sp_connection_open("172.23.42.29:2342");
* if (connection != NULL)
* sp_connection_send_command(connection, sp_command_clear());
* ```
* This structure can be used with any type that implements the [Value] trait.
* You can also use the concrete type aliases provided in this crate, e.g. [`crate::CharGrid`] and [`crate::ByteGrid`].
*/
typedef struct SPConnection SPConnection;
/**
* A C-wrapper for grid containing codepage 437 characters.
*
* The encoding is currently not enforced.
*
* # Examples
*
* ```C
* Cp437Grid grid = sp_cp437_grid_new(4, 3);
* sp_cp437_grid_fill(grid, '?');
* sp_cp437_grid_set(grid, 0, 0, '!');
* sp_cp437_grid_free(grid);
* ```
*/
typedef struct SPCp437Grid SPCp437Grid;
/**
* The raw packet
*/
typedef struct SPPacket SPPacket;
typedef struct ValueGrid_u8 ValueGrid_u8;
/**
* Represents a span of memory (`&mut [u8]` ) as a struct usable by C code.
@ -228,6 +197,105 @@ typedef struct {
size_t length;
} SPByteSlice;
/**
* A grid containing brightness values.
*
* # Examples
*
* ```rust
* # use servicepoint::*;
* let mut grid = BrightnessGrid::new(2,2);
* grid.set(0, 0, Brightness::MIN);
* grid.set(1, 1, Brightness::MIN);
*
* # let connection = FakeConnection;
* connection.send(BrightnessGridCommand {
* origin: Origin::new(3, 7),
* grid
* }).unwrap()
* ```
*/
typedef ValueGrid_Brightness BrightnessGrid;
/**
* A grid containing UTF-8 characters.
*
* To send a `CharGrid` to the display, use a [`crate::CharGridCommand`].
*
* Also see [`ValueGrid`] for the non-specialized operations and examples.
*
* # Examples
*
* ```rust
* # use servicepoint::*;
* let grid = CharGrid::from("You can\nload multiline\nstrings directly");
* assert_eq!(grid.get_row_str(1), Some("load multiline\0\0".to_string()));
*
* # let connection = FakeConnection;
* let command = CharGridCommand { origin: Origin::ZERO, grid };
* connection.send(command).unwrap()
* ```
*/
typedef ValueGrid_char CharGrid;
/**
* A grid containing codepage 437 characters.
*
* The encoding is currently not enforced.
*/
typedef ValueGrid_u8 Cp437Grid;
/**
* A C-wrapper for grid containing codepage 437 characters.
*
* The encoding is currently not enforced.
*
* # Examples
*
* ```C
* Cp437Grid grid = sp_cp437_grid_new(4, 3);
* sp_cp437_grid_fill(grid, '?');
* sp_cp437_grid_set(grid, 0, 0, '!');
* sp_cp437_grid_free(grid);
* ```
*/
typedef Cp437Grid SPCp437Grid;
/**
* A raw header.
*
* The header specifies the kind of command, the size of the payload and where to display the
* payload, where applicable.
*
* Because the meaning of most fields depend on the command, there are no speaking names for them.
*
* The contained values are in platform endian-ness and may need to be converted before sending.
*/
typedef struct {
/**
* The first two bytes specify which command this packet represents.
*/
uint16_t command_code;
/**
* First command-specific value
*/
uint16_t a;
/**
* Second command-specific value
*/
uint16_t b;
/**
* Third command-specific value
*/
uint16_t c;
/**
* Fourth command-specific value
*/
uint16_t d;
} Header;
#ifdef __cplusplus
extern "C" {
#endif // __cplusplus
@ -250,7 +318,7 @@ extern "C" {
* - the returned instance is freed in some way, either by using a consuming function or
* by explicitly calling `sp_bitmap_free`.
*/
SPBitmap *sp_bitmap_clone(const SPBitmap *bitmap);
Bitmap *sp_bitmap_clone(const Bitmap *bitmap);
/**
* Sets the state of all pixels in the [SPBitmap].
@ -271,7 +339,7 @@ SPBitmap *sp_bitmap_clone(const SPBitmap *bitmap);
* - `bitmap` points to a valid [SPBitmap]
* - `bitmap` is not written to or read from concurrently
*/
void sp_bitmap_fill(SPBitmap *bitmap, bool value);
void sp_bitmap_fill(Bitmap *bitmap, bool value);
/**
* Deallocates a [SPBitmap].
@ -290,7 +358,7 @@ void sp_bitmap_fill(SPBitmap *bitmap, bool value);
*
* [SPCommand]: [crate::SPCommand]
*/
void sp_bitmap_free(SPBitmap *bitmap);
void sp_bitmap_free(Bitmap *bitmap);
/**
* Gets the current value at the specified position in the [SPBitmap].
@ -312,7 +380,7 @@ void sp_bitmap_free(SPBitmap *bitmap);
* - `bitmap` points to a valid [SPBitmap]
* - `bitmap` is not written to concurrently
*/
bool sp_bitmap_get(const SPBitmap *bitmap, size_t x, size_t y);
bool sp_bitmap_get(const Bitmap *bitmap, size_t x, size_t y);
/**
* Gets the height in pixels of the [SPBitmap] instance.
@ -331,7 +399,7 @@ bool sp_bitmap_get(const SPBitmap *bitmap, size_t x, size_t y);
*
* - `bitmap` points to a valid [SPBitmap]
*/
size_t sp_bitmap_height(const SPBitmap *bitmap);
size_t sp_bitmap_height(const Bitmap *bitmap);
/**
* Loads a [SPBitmap] with the specified dimensions from the provided data.
@ -362,10 +430,10 @@ size_t sp_bitmap_height(const SPBitmap *bitmap);
* - the returned instance is freed in some way, either by using a consuming function or
* by explicitly calling `sp_bitmap_free`.
*/
SPBitmap *sp_bitmap_load(size_t width,
size_t height,
const uint8_t *data,
size_t data_length);
Bitmap *sp_bitmap_load(size_t width,
size_t height,
const uint8_t *data,
size_t data_length);
/**
* Creates a new [SPBitmap] with the specified dimensions.
@ -390,8 +458,8 @@ SPBitmap *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`.
*/
SPBitmap *sp_bitmap_new(size_t width,
size_t height);
Bitmap *sp_bitmap_new(size_t width,
size_t height);
/**
* Creates a new [SPBitmap] with a size matching the screen.
@ -405,7 +473,7 @@ SPBitmap *sp_bitmap_new(size_t width,
* - the returned instance is freed in some way, either by using a consuming function or
* by explicitly calling [sp_bitmap_free].
*/
SPBitmap *sp_bitmap_new_screen_sized(void);
Bitmap *sp_bitmap_new_screen_sized(void);
/**
* Sets the value of the specified position in the [SPBitmap].
@ -430,7 +498,7 @@ SPBitmap *sp_bitmap_new_screen_sized(void);
* - `bitmap` points to a valid [SPBitmap]
* - `bitmap` is not written to or read from concurrently
*/
void sp_bitmap_set(SPBitmap *bitmap, size_t x, size_t y, bool value);
void sp_bitmap_set(Bitmap *bitmap, size_t x, size_t y, bool value);
/**
* Gets an unsafe reference to the data of the [SPBitmap] instance.
@ -447,7 +515,7 @@ void sp_bitmap_set(SPBitmap *bitmap, size_t x, size_t y, bool value);
* - 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
*/
SPByteSlice sp_bitmap_unsafe_data_ref(SPBitmap *bitmap);
SPByteSlice sp_bitmap_unsafe_data_ref(Bitmap *bitmap);
/**
* Gets the width in pixels of the [SPBitmap] instance.
@ -466,7 +534,7 @@ SPByteSlice sp_bitmap_unsafe_data_ref(SPBitmap *bitmap);
*
* - `bitmap` points to a valid [SPBitmap]
*/
size_t sp_bitmap_width(const SPBitmap *bitmap);
size_t sp_bitmap_width(const Bitmap *bitmap);
/**
* Clones a [SPBitVec].
@ -699,7 +767,7 @@ SPByteSlice sp_bitvec_unsafe_data_ref(SPBitVec *bit_vec);
* - the returned instance is freed in some way, either by using a consuming function or
* by explicitly calling `sp_brightness_grid_free`.
*/
SPBrightnessGrid *sp_brightness_grid_clone(const SPBrightnessGrid *brightness_grid);
BrightnessGrid *sp_brightness_grid_clone(const BrightnessGrid *brightness_grid);
/**
* Sets the value of all cells in the [SPBrightnessGrid].
@ -721,7 +789,7 @@ SPBrightnessGrid *sp_brightness_grid_clone(const SPBrightnessGrid *brightness_gr
* - `brightness_grid` points to a valid [SPBrightnessGrid]
* - `brightness_grid` is not written to or read from concurrently
*/
void sp_brightness_grid_fill(SPBrightnessGrid *brightness_grid, uint8_t value);
void sp_brightness_grid_fill(BrightnessGrid *brightness_grid, uint8_t value);
/**
* Deallocates a [SPBrightnessGrid].
@ -744,7 +812,7 @@ void sp_brightness_grid_fill(SPBrightnessGrid *brightness_grid, uint8_t value);
*
* [SPCommand]: [crate::SPCommand]
*/
void sp_brightness_grid_free(SPBrightnessGrid *brightness_grid);
void sp_brightness_grid_free(BrightnessGrid *brightness_grid);
/**
* Gets the current value at the specified position.
@ -768,7 +836,7 @@ void sp_brightness_grid_free(SPBrightnessGrid *brightness_grid);
* - `brightness_grid` points to a valid [SPBrightnessGrid]
* - `brightness_grid` is not written to concurrently
*/
uint8_t sp_brightness_grid_get(const SPBrightnessGrid *brightness_grid,
uint8_t sp_brightness_grid_get(const BrightnessGrid *brightness_grid,
size_t x,
size_t y);
@ -791,7 +859,7 @@ uint8_t sp_brightness_grid_get(const SPBrightnessGrid *brightness_grid,
*
* - `brightness_grid` points to a valid [SPBrightnessGrid]
*/
size_t sp_brightness_grid_height(const SPBrightnessGrid *brightness_grid);
size_t sp_brightness_grid_height(const BrightnessGrid *brightness_grid);
/**
* Loads a [SPBrightnessGrid] with the specified dimensions from the provided data.
@ -812,10 +880,10 @@ size_t sp_brightness_grid_height(const SPBrightnessGrid *brightness_grid);
* - the returned instance is freed in some way, either by using a consuming function or
* by explicitly calling `sp_brightness_grid_free`.
*/
SPBrightnessGrid *sp_brightness_grid_load(size_t width,
size_t height,
const uint8_t *data,
size_t data_length);
BrightnessGrid *sp_brightness_grid_load(size_t width,
size_t height,
const uint8_t *data,
size_t data_length);
/**
* Creates a new [SPBrightnessGrid] with the specified dimensions.
@ -829,8 +897,8 @@ SPBrightnessGrid *sp_brightness_grid_load(size_t width,
* - the returned instance is freed in some way, either by using a consuming function or
* by explicitly calling `sp_brightness_grid_free`.
*/
SPBrightnessGrid *sp_brightness_grid_new(size_t width,
size_t height);
BrightnessGrid *sp_brightness_grid_new(size_t width,
size_t height);
/**
* Sets the value of the specified position in the [SPBrightnessGrid].
@ -856,7 +924,7 @@ SPBrightnessGrid *sp_brightness_grid_new(size_t width,
* - `brightness_grid` points to a valid [SPBrightnessGrid]
* - `brightness_grid` is not written to or read from concurrently
*/
void sp_brightness_grid_set(SPBrightnessGrid *brightness_grid,
void sp_brightness_grid_set(BrightnessGrid *brightness_grid,
size_t x,
size_t y,
uint8_t value);
@ -882,7 +950,7 @@ void sp_brightness_grid_set(SPBrightnessGrid *brightness_grid,
* - 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
*/
SPByteSlice sp_brightness_grid_unsafe_data_ref(SPBrightnessGrid *brightness_grid);
SPByteSlice sp_brightness_grid_unsafe_data_ref(BrightnessGrid *brightness_grid);
/**
* Gets the width of the [SPBrightnessGrid] instance.
@ -903,7 +971,7 @@ SPByteSlice sp_brightness_grid_unsafe_data_ref(SPBrightnessGrid *brightness_grid
*
* - `brightness_grid` points to a valid [SPBrightnessGrid]
*/
size_t sp_brightness_grid_width(const SPBrightnessGrid *brightness_grid);
size_t sp_brightness_grid_width(const BrightnessGrid *brightness_grid);
/**
* Clones a [SPCharGrid].
@ -923,7 +991,7 @@ size_t sp_brightness_grid_width(const SPBrightnessGrid *brightness_grid);
* - the returned instance is freed in some way, either by using a consuming function or
* by explicitly calling `sp_char_grid_free`.
*/
SPCharGrid *sp_char_grid_clone(const SPCharGrid *char_grid);
CharGrid *sp_char_grid_clone(const CharGrid *char_grid);
/**
* Sets the value of all cells in the [SPCharGrid].
@ -944,7 +1012,7 @@ SPCharGrid *sp_char_grid_clone(const SPCharGrid *char_grid);
* - `char_grid` points to a valid [SPCharGrid]
* - `char_grid` is not written to or read from concurrently
*/
void sp_char_grid_fill(SPCharGrid *char_grid, uint32_t value);
void sp_char_grid_fill(CharGrid *char_grid, uint32_t value);
/**
* Deallocates a [SPCharGrid].
@ -963,7 +1031,7 @@ void sp_char_grid_fill(SPCharGrid *char_grid, uint32_t value);
*
* [SPCommand]: [crate::SPCommand]
*/
void sp_char_grid_free(SPCharGrid *char_grid);
void sp_char_grid_free(CharGrid *char_grid);
/**
* Gets the current value at the specified position.
@ -985,7 +1053,7 @@ void sp_char_grid_free(SPCharGrid *char_grid);
* - `char_grid` points to a valid [SPCharGrid]
* - `char_grid` is not written to concurrently
*/
uint32_t sp_char_grid_get(const SPCharGrid *char_grid, size_t x, size_t y);
uint32_t sp_char_grid_get(const CharGrid *char_grid, size_t x, size_t y);
/**
* Gets the height of the [SPCharGrid] instance.
@ -1004,7 +1072,7 @@ uint32_t sp_char_grid_get(const SPCharGrid *char_grid, size_t x, size_t y);
*
* - `char_grid` points to a valid [SPCharGrid]
*/
size_t sp_char_grid_height(const SPCharGrid *char_grid);
size_t sp_char_grid_height(const CharGrid *char_grid);
/**
* Loads a [SPCharGrid] with the specified dimensions from the provided data.
@ -1026,10 +1094,10 @@ size_t sp_char_grid_height(const SPCharGrid *char_grid);
* - the returned instance is freed in some way, either by using a consuming function or
* by explicitly calling `sp_char_grid_free`.
*/
SPCharGrid *sp_char_grid_load(size_t width,
size_t height,
const uint8_t *data,
size_t data_length);
CharGrid *sp_char_grid_load(size_t width,
size_t height,
const uint8_t *data,
size_t data_length);
/**
* Creates a new [SPCharGrid] with the specified dimensions.
@ -1043,8 +1111,8 @@ SPCharGrid *sp_char_grid_load(size_t width,
* - the returned instance is freed in some way, either by using a consuming function or
* by explicitly calling `sp_char_grid_free`.
*/
SPCharGrid *sp_char_grid_new(size_t width,
size_t height);
CharGrid *sp_char_grid_new(size_t width,
size_t height);
/**
* Sets the value of the specified position in the [SPCharGrid].
@ -1071,10 +1139,7 @@ SPCharGrid *sp_char_grid_new(size_t width,
*
* [SPBitVec]: [crate::SPBitVec]
*/
void sp_char_grid_set(SPCharGrid *char_grid,
size_t x,
size_t y,
uint32_t value);
void sp_char_grid_set(CharGrid *char_grid, size_t x, size_t y, uint32_t value);
/**
* Gets the width of the [SPCharGrid] instance.
@ -1093,7 +1158,7 @@ void sp_char_grid_set(SPCharGrid *char_grid,
*
* - `char_grid` points to a valid [SPCharGrid]
*/
size_t sp_char_grid_width(const SPCharGrid *char_grid);
size_t sp_char_grid_width(const CharGrid *char_grid);
/**
* Set pixel data starting at the pixel offset on screen.
@ -1122,9 +1187,9 @@ size_t sp_char_grid_width(const SPCharGrid *char_grid);
* - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
* by explicitly calling `sp_command_free`.
*/
SPCommand *sp_command_bitmap_linear(size_t offset,
SPBitVec *bit_vec,
SPCompressionCode compression);
Command *sp_command_bitmap_linear(size_t offset,
SPBitVec *bit_vec,
SPCompressionCode compression);
/**
* Set pixel data according to an and-mask starting at the offset.
@ -1153,9 +1218,9 @@ SPCommand *sp_command_bitmap_linear(size_t offset,
* - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
* by explicitly calling `sp_command_free`.
*/
SPCommand *sp_command_bitmap_linear_and(size_t offset,
SPBitVec *bit_vec,
SPCompressionCode compression);
Command *sp_command_bitmap_linear_and(size_t offset,
SPBitVec *bit_vec,
SPCompressionCode compression);
/**
* Set pixel data according to an or-mask starting at the offset.
@ -1184,9 +1249,9 @@ SPCommand *sp_command_bitmap_linear_and(size_t offset,
* - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
* by explicitly calling `sp_command_free`.
*/
SPCommand *sp_command_bitmap_linear_or(size_t offset,
SPBitVec *bit_vec,
SPCompressionCode compression);
Command *sp_command_bitmap_linear_or(size_t offset,
SPBitVec *bit_vec,
SPCompressionCode compression);
/**
* Sets a window of pixels to the specified values.
@ -1210,10 +1275,10 @@ SPCommand *sp_command_bitmap_linear_or(size_t offset,
* - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
* by explicitly calling `sp_command_free`.
*/
SPCommand *sp_command_bitmap_linear_win(size_t x,
size_t y,
SPBitmap *bitmap,
SPCompressionCode compression);
Command *sp_command_bitmap_linear_win(size_t x,
size_t y,
Bitmap *bitmap,
SPCompressionCode compression);
/**
* Set pixel data according to a xor-mask starting at the offset.
@ -1242,9 +1307,9 @@ SPCommand *sp_command_bitmap_linear_win(size_t x,
* - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
* by explicitly calling `sp_command_free`.
*/
SPCommand *sp_command_bitmap_linear_xor(size_t offset,
SPBitVec *bit_vec,
SPCompressionCode compression);
Command *sp_command_bitmap_linear_xor(size_t offset,
SPBitVec *bit_vec,
SPCompressionCode compression);
/**
* Set the brightness of all tiles to the same value.
@ -1262,7 +1327,7 @@ SPCommand *sp_command_bitmap_linear_xor(size_t offset,
* - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
* by explicitly calling `sp_command_free`.
*/
SPCommand *sp_command_brightness(uint8_t brightness);
Command *sp_command_brightness(uint8_t brightness);
/**
* Set the brightness of individual tiles in a rectangular area of the display.
@ -1284,9 +1349,9 @@ SPCommand *sp_command_brightness(uint8_t brightness);
* - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
* by explicitly calling `sp_command_free`.
*/
SPCommand *sp_command_char_brightness(size_t x,
size_t y,
SPBrightnessGrid *grid);
Command *sp_command_char_brightness(size_t x,
size_t y,
BrightnessGrid *grid);
/**
* Set all pixels to the off state.
@ -1308,7 +1373,7 @@ SPCommand *sp_command_char_brightness(size_t x,
* - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
* by explicitly calling `sp_command_free`.
*/
SPCommand *sp_command_clear(void);
Command *sp_command_clear(void);
/**
* Clones a [SPCommand] instance.
@ -1328,7 +1393,7 @@ SPCommand *sp_command_clear(void);
* - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
* by explicitly calling `sp_command_free`.
*/
SPCommand *sp_command_clone(const SPCommand *command);
Command *sp_command_clone(const Command *command);
/**
* Show codepage 437 encoded text on the screen.
@ -1350,9 +1415,9 @@ SPCommand *sp_command_clone(const SPCommand *command);
* - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
* by explicitly calling `sp_command_free`.
*/
SPCommand *sp_command_cp437_data(size_t x,
size_t y,
SPCp437Grid *grid);
Command *sp_command_cp437_data(size_t x,
size_t y,
SPCp437Grid *grid);
/**
* A yet-to-be-tested command.
@ -1366,7 +1431,7 @@ SPCommand *sp_command_cp437_data(size_t x,
* - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
* by explicitly calling `sp_command_free`.
*/
SPCommand *sp_command_fade_out(void);
Command *sp_command_fade_out(void);
/**
* Deallocates a [SPCommand].
@ -1390,7 +1455,7 @@ SPCommand *sp_command_fade_out(void);
* - `command` is not used concurrently or after this call
* - `command` was not passed to another consuming function, e.g. to create a [SPPacket]
*/
void sp_command_free(SPCommand *command);
void sp_command_free(Command *command);
/**
* Kills the udp daemon on the display, which usually results in a restart.
@ -1406,9 +1471,23 @@ void sp_command_free(SPCommand *command);
* - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
* by explicitly calling `sp_command_free`.
*/
SPCommand *sp_command_hard_reset(void);
Command *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].
*
* # Examples
*
* ```C
* 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].
*
* The packet is deallocated in the process.
@ -1429,7 +1508,7 @@ SPCommand *sp_command_hard_reset(void);
* - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
* by explicitly calling `sp_command_free`.
*/
SPCommand *sp_command_try_from_packet(SPPacket *packet);
Command *sp_command_try_from_packet(Packet *packet);
/**
* Show UTF-8 encoded text on the screen.
@ -1451,9 +1530,9 @@ SPCommand *sp_command_try_from_packet(SPPacket *packet);
* - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
* by explicitly calling `sp_command_free`.
*/
SPCommand *sp_command_utf8_data(size_t x,
size_t y,
SPCharGrid *grid);
Command *sp_command_utf8_data(size_t x,
size_t y,
CharGrid *grid);
/**
* Closes and deallocates a [SPConnection].
@ -1469,7 +1548,7 @@ SPCommand *sp_command_utf8_data(size_t x,
* - `connection` points to a valid [SPConnection]
* - `connection` is not used concurrently or after this call
*/
void sp_connection_free(SPConnection *connection);
void sp_connection_free(UdpConnection *connection);
/**
* Creates a new instance of [SPConnection].
@ -1487,7 +1566,7 @@ void sp_connection_free(SPConnection *connection);
* - the returned instance is freed in some way, either by using a consuming function or
* by explicitly calling `sp_connection_free`.
*/
SPConnection *sp_connection_open(const char *host);
UdpConnection *sp_connection_open(const char *host);
/**
* Sends a [SPCommand] to the display using the [SPConnection].
@ -1509,8 +1588,8 @@ SPConnection *sp_connection_open(const char *host);
* - `command` points to a valid instance of [SPPacket]
* - `command` is not used concurrently or after this call
*/
bool sp_connection_send_command(const SPConnection *connection,
SPCommand *command);
bool sp_connection_send_command(const UdpConnection *connection,
Command *command);
/**
* Sends a [SPPacket] to the display using the [SPConnection].
@ -1532,8 +1611,7 @@ bool sp_connection_send_command(const SPConnection *connection,
* - `packet` points to a valid instance of [SPPacket]
* - `packet` is not used concurrently or after this call
*/
bool sp_connection_send_packet(const SPConnection *connection,
SPPacket *packet);
bool sp_connection_send_packet(const UdpConnection *connection, Packet *packet);
/**
* Clones a [SPCp437Grid].
@ -1761,7 +1839,7 @@ size_t sp_cp437_grid_width(const SPCp437Grid *cp437_grid);
* - the returned instance is freed in some way, either by using a consuming function or
* by explicitly calling `sp_packet_free`.
*/
SPPacket *sp_packet_clone(const SPPacket *packet);
Packet *sp_packet_clone(const Packet *packet);
/**
* Deallocates a [SPPacket].
@ -1777,7 +1855,7 @@ SPPacket *sp_packet_clone(const SPPacket *packet);
* - `packet` points to a valid [SPPacket]
* - `packet` is not used concurrently or after this call
*/
void sp_packet_free(SPPacket *packet);
void sp_packet_free(Packet *packet);
/**
* Turns a [SPCommand] into a [SPPacket].
@ -1798,7 +1876,7 @@ void sp_packet_free(SPPacket *packet);
* - the returned [SPPacket] instance is freed in some way, either by using a consuming function or
* by explicitly calling `sp_packet_free`.
*/
SPPacket *sp_packet_from_command(SPCommand *command);
Packet *sp_packet_from_command(Command *command);
/**
* Creates a raw [SPPacket] from parts.
@ -1826,13 +1904,11 @@ SPPacket *sp_packet_from_command(SPCommand *command);
* - the returned [SPPacket] instance is freed in some way, either by using a consuming function or
* by explicitly calling [sp_packet_free].
*/
SPPacket *sp_packet_from_parts(uint16_t command_code,
uint16_t a,
uint16_t b,
uint16_t c,
uint16_t d,
const uint8_t *payload,
size_t payload_len);
Packet *sp_packet_from_parts(Header header,
const uint8_t *payload,
size_t payload_len);
Header sp_packet_get_header(const Packet *packet);
/**
* Tries to load a [SPPacket] from the passed array with the specified length.
@ -1852,8 +1928,8 @@ SPPacket *sp_packet_from_parts(uint16_t command_code,
* - the returned [SPPacket] instance is freed in some way, either by using a consuming function or
* by explicitly calling `sp_packet_free`.
*/
SPPacket *sp_packet_try_load(const uint8_t *data,
size_t length);
Packet *sp_packet_try_load(const uint8_t *data,
size_t length);
#ifdef __cplusplus
} // extern "C"

6
examples/lang_c/src/main.c
View file

@ -2,17 +2,17 @@
#include "servicepoint.h"
int main(void) {
SPConnection *connection = sp_connection_open("localhost:2342");
UdpConnection *connection = sp_connection_open("localhost: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);
if (pixels == NULL)
return 1;
sp_bitmap_fill(pixels, true);
SPCommand *command = sp_command_bitmap_linear_win(0, 0, pixels, SP_COMPRESSION_CODE_UNCOMPRESSED);
Command *command = sp_command_bitmap_linear_win(0, 0, pixels, SP_COMPRESSION_CODE_UNCOMPRESSED);
if (command == NULL)
return 1;