/* Generated with cbindgen:0.28.0 */
/* Warning, this file is autogenerated by cbindgen. Don't modify this manually. */
#include <stdarg.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <stdlib.h>
/**
* 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
/**
* pixel count on whole screen
*/
#define SP_PIXEL_COUNT (SP_PIXEL_WIDTH * SP_PIXEL_HEIGHT)
/**
* Display height in pixels
*/
#define SP_PIXEL_HEIGHT (SP_TILE_HEIGHT * SP_TILE_SIZE)
/**
* Display width in pixels
*/
#define SP_PIXEL_WIDTH (SP_TILE_WIDTH * SP_TILE_SIZE)
/**
* Display tile count in the y-direction
*/
#define SP_TILE_HEIGHT 20
/**
* size of a single tile in one dimension
*/
#define SP_TILE_SIZE 8
/**
* Display tile count in the x-direction
*/
#define SP_TILE_WIDTH 56
/**
* Specifies the kind of compression to use.
*/
enum SPCompressionCode
#ifdef __cplusplus
: uint16_t
#endif // __cplusplus
{
/**
* no compression
*/
SP_COMPRESSION_CODE_UNCOMPRESSED = 0,
/**
* compress using flate2 with zlib header
*/
SP_COMPRESSION_CODE_ZLIB = 26490,
/**
* compress using bzip2
*/
SP_COMPRESSION_CODE_BZIP2 = 25210,
/**
* compress using lzma
*/
SP_COMPRESSION_CODE_LZMA = 27770,
/**
* compress using Zstandard
*/
SP_COMPRESSION_CODE_ZSTD = 31347,
};
#ifndef __cplusplus
typedef uint16_t SPCompressionCode;
#endif // __cplusplus
/**
* A vector of bits
*
* # Examples
* ```C
* SPBitVec vec = sp_bitvec_new(8);
* sp_bitvec_set(vec, 5, true);
* sp_bitvec_free(vec);
* ```
*/
typedef struct SPBitVec SPBitVec;
/**
* 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);
* ```
*/
typedef struct SPBitmap SPBitmap;
/**
* A grid containing brightness values.
*
* # Examples
* ```C
* SPConnection connection = sp_connection_open("127.0.0.1:2342");
* if (connection == NULL)
* return 1;
*
* 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);
* ```
*/
typedef struct SPBrightnessGrid SPBrightnessGrid;
/**
* A C-wrapper for grid containing UTF-8 characters.
*
* As the rust [char] type is not FFI-safe, characters are passed in their UTF-32 form as 32bit unsigned integers.
*
* 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);
* ```
*/
typedef struct SPCharGrid SPCharGrid;
/**
* 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]
*/
typedef struct SPCommand SPCommand;
/**
* 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;
/**
* A connection to the display.
*
* # Examples
*
* ```C
* CConnection connection = sp_connection_open("172.23.42.29:2342");
* if (connection != NULL)
* sp_connection_send_command(connection, sp_command_clear());
* ```
*/
typedef struct SPUdpConnection SPUdpConnection;
/**
* Represents a span of memory (`&mut [u8]` ) as a struct usable by C code.
*
* You should not create an instance of this type in your C code.
*
* # Safety
*
* The caller has to make sure that:
*
* - accesses to the memory pointed to with `start` is never accessed outside `length`
* - the lifetime of the `CByteSlice` does not outlive the memory it points to, as described in
* the function returning this type.
* - an instance of this created from C is never passed to a consuming function, as the rust code
* will try to free the memory of a potentially separate allocator.
*/
typedef struct {
/**
* The start address of the memory
*/
uint8_t *start;
/**
* The amount of memory in bytes
*/
size_t length;
} SPByteSlice;
#ifdef __cplusplus
extern "C" {
#endif // __cplusplus
/**
* Clones a [SPBitmap].
*
* Will never return NULL.
*
* # Panics
*
* - when `bitmap` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `bitmap` points to a valid [SPBitmap]
* - `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`.
*/
SPBitmap *sp_bitmap_clone(const SPBitmap *bitmap);
/**
* Sets the state of all pixels in the [SPBitmap].
*
* # Arguments
*
* - `bitmap`: instance to write to
* - `value`: the value to set all pixels to
*
* # Panics
*
* - when `bitmap` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `bitmap` points to a valid [SPBitmap]
* - `bitmap` is not written to or read from concurrently
*/
void sp_bitmap_fill(SPBitmap *bitmap, bool value);
/**
* Deallocates a [SPBitmap].
*
* # Panics
*
* - when `bitmap` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `bitmap` points to a valid [SPBitmap]
* - `bitmap` is not used concurrently or after bitmap call
* - `bitmap` was not passed to another consuming function, e.g. to create a [SPCommand]
*
* [SPCommand]: [crate::SPCommand]
*/
void sp_bitmap_free(SPBitmap **bitmap);
/**
* Gets the current value at the specified position in the [SPBitmap].
*
* # Arguments
*
* - `bitmap`: instance to read from
* - `x` and `y`: position of the cell to read
*
* # Panics
*
* - when `bitmap` is NULL
* - when accessing `x` or `y` out of bounds
*
* # Safety
*
* The caller has to make sure that:
*
* - `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);
/**
* Gets the height in pixels of the [SPBitmap] instance.
*
* # Arguments
*
* - `bitmap`: instance to read from
*
* # Panics
*
* - when `bitmap` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `bitmap` points to a valid [SPBitmap]
*/
size_t sp_bitmap_height(const SPBitmap *bitmap);
/**
* Loads a [SPBitmap] 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.
*
* # Errors
*
* In the following cases, this function will return NULL:
*
* - when the dimensions and data size do not match exactly.
* - when the width is not dividable by 8
*
* # Panics
*
* - when `data` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `data` points to a valid memory location of at least `data_length` bytes in size.
* - 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);
/**
* Creates a new [SPBitmap] 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.
*
* # Errors
*
* In the following cases, this function will return NULL:
*
* - when the width is not dividable by 8
*
* # Safety
*
* The caller has to make sure that:
*
* - 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);
/**
* Creates a new [SPBitmap] with a size matching the screen.
*
* returns: [SPBitmap] initialized to all pixels off. Will never return NULL.
*
* # Safety
*
* The caller has to make sure that:
*
* - 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);
/**
* Sets the value of the specified position in the [SPBitmap].
*
* # Arguments
*
* - `bitmap`: instance to write to
* - `x` and `y`: position of the cell
* - `value`: the value to write to the cell
*
* returns: old value of the cell
*
* # Panics
*
* - when `bitmap` is NULL
* - when accessing `x` or `y` out of bounds
*
* # Safety
*
* The caller has to make sure that:
*
* - `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);
/**
* Gets an unsafe reference to the data of the [SPBitmap] instance.
*
* # Panics
*
* - when `bitmap` is NULL
*
* # Safety
*
* 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
*/
SPByteSlice sp_bitmap_unsafe_data_ref(SPBitmap *bitmap);
/**
* Gets the width in pixels of the [SPBitmap] instance.
*
* # Arguments
*
* - `bitmap`: instance to read from
*
* # Panics
*
* - when `bitmap` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `bitmap` points to a valid [SPBitmap]
*/
size_t sp_bitmap_width(const SPBitmap *bitmap);
/**
* Clones a [SPBitVec].
*
* returns: new [SPBitVec] instance. Will never return NULL.
*
* # Panics
*
* - when `bit_vec` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `bit_vec` points to a valid [SPBitVec]
* - `bit_vec` is not written to concurrently
* - the returned instance is freed in some way, either by using a consuming function or
* by explicitly calling `sp_bitvec_free`.
*/
SPBitVec *sp_bitvec_clone(const SPBitVec *bit_vec);
/**
* Sets the value of all bits in the [SPBitVec].
*
* # Arguments
*
* - `bit_vec`: instance to write to
* - `value`: the value to set all bits to
*
* # Panics
*
* - when `bit_vec` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `bit_vec` points to a valid [SPBitVec]
* - `bit_vec` is not written to or read from concurrently
*/
void sp_bitvec_fill(SPBitVec *bit_vec, bool value);
/**
* Deallocates a [SPBitVec].
*
* # Panics
*
* - when `but_vec` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `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]
*
* [SPCommand]: [crate::SPCommand]
*/
void sp_bitvec_free(SPBitVec *bit_vec);
/**
* Gets the value of a bit from the [SPBitVec].
*
* # Arguments
*
* - `bit_vec`: instance to read from
* - `index`: the bit index to read
*
* returns: value of the bit
*
* # Panics
*
* - when `bit_vec` is NULL
* - when accessing `index` out of bounds
*
* # Safety
*
* The caller has to make sure that:
*
* - `bit_vec` points to a valid [SPBitVec]
* - `bit_vec` is not written to concurrently
*/
bool sp_bitvec_get(const SPBitVec *bit_vec, size_t index);
/**
* Returns true if length is 0.
*
* # Arguments
*
* - `bit_vec`: instance to write to
*
* # Panics
*
* - when `bit_vec` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `bit_vec` points to a valid [SPBitVec]
*/
bool sp_bitvec_is_empty(const SPBitVec *bit_vec);
/**
* Gets the length of the [SPBitVec] in bits.
*
* # Arguments
*
* - `bit_vec`: instance to write to
*
* # Panics
*
* - when `bit_vec` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `bit_vec` points to a valid [SPBitVec]
*/
size_t sp_bitvec_len(const SPBitVec *bit_vec);
/**
* Interpret the data as a series of bits and load then into a new [SPBitVec] instance.
*
* returns: [SPBitVec] instance containing data. Will never return NULL.
*
* # Panics
*
* - when `data` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `data` points to a valid memory location of at least `data_length`
* bytes in size.
* - the returned instance is freed in some way, either by using a consuming function or
* by explicitly calling `sp_bitvec_free`.
*/
SPBitVec *sp_bitvec_load(const uint8_t *data,
size_t data_length);
/**
* Creates a new [SPBitVec] instance.
*
* # Arguments
*
* - `size`: size in bits.
*
* returns: [SPBitVec] with all bits set to false. Will never return NULL.
*
* # Panics
*
* - when `size` is not divisible by 8.
*
* # Safety
*
* The caller has to make sure that:
*
* - the returned instance is freed in some way, either by using a consuming function or
* by explicitly calling `sp_bitvec_free`.
*/
SPBitVec *sp_bitvec_new(size_t size);
/**
* Sets the value of a bit in the [SPBitVec].
*
* # Arguments
*
* - `bit_vec`: instance to write to
* - `index`: the bit index to edit
* - `value`: the value to set the bit to
*
* # Panics
*
* - when `bit_vec` is NULL
* - when accessing `index` out of bounds
*
* # Safety
*
* The caller has to make sure that:
*
* - `bit_vec` points to a valid [SPBitVec]
* - `bit_vec` is not written to or read from concurrently
*/
void sp_bitvec_set(SPBitVec *bit_vec, size_t index, bool value);
/**
* Gets an unsafe reference to the data of the [SPBitVec] instance.
*
* # Arguments
*
* - `bit_vec`: instance to write to
*
* # Panics
*
* - when `bit_vec` is NULL
*
* ## Safety
*
* The caller has to make sure that:
*
* - `bit_vec` points to a valid [SPBitVec]
* - the returned memory range is never accessed after the passed [SPBitVec] has been freed
* - the returned memory range is never accessed concurrently, either via the [SPBitVec] or directly
*/
SPByteSlice sp_bitvec_unsafe_data_ref(SPBitVec *bit_vec);
/**
* Clones a [SPBrightnessGrid].
*
* # Arguments
*
* - `brightness_grid`: instance to read from
*
* returns: new [SPBrightnessGrid] instance. Will never return NULL.
*
* # Panics
*
* - when `brightness_grid` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `brightness_grid` points to a valid [SPBrightnessGrid]
* - `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`.
*/
SPBrightnessGrid *sp_brightness_grid_clone(const SPBrightnessGrid *brightness_grid);
/**
* Sets the value of all cells in the [SPBrightnessGrid].
*
* # Arguments
*
* - `brightness_grid`: instance to write to
* - `value`: the value to set all cells to
*
* # Panics
*
* - when `brightness_grid` is NULL
* - When providing an invalid brightness value
*
* # Safety
*
* The caller has to make sure that:
*
* - `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);
/**
* Deallocates a [SPBrightnessGrid].
*
* # Arguments
*
* - `brightness_grid`: instance to read from
*
* # Panics
*
* - when `brightness_grid` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `brightness_grid` points to a valid [SPBrightnessGrid]
* - `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]
*
* [SPCommand]: [crate::SPCommand]
*/
void sp_brightness_grid_free(SPBrightnessGrid *brightness_grid);
/**
* Gets the current value at the specified position.
*
* # Arguments
*
* - `brightness_grid`: instance to read from
* - `x` and `y`: position of the cell to read
*
* returns: value at position
*
* # Panics
*
* - when `brightness_grid` is NULL
* - When accessing `x` or `y` out of bounds.
*
* # Safety
*
* The caller has to make sure that:
*
* - `brightness_grid` points to a valid [SPBrightnessGrid]
* - `brightness_grid` is not written to concurrently
*/
uint8_t sp_brightness_grid_get(const SPBrightnessGrid *brightness_grid,
size_t x,
size_t y);
/**
* Gets the height of the [SPBrightnessGrid] instance.
*
* # Arguments
*
* - `brightness_grid`: instance to read from
*
* returns: height
*
* # Panics
*
* - when `brightness_grid` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `brightness_grid` points to a valid [SPBrightnessGrid]
*/
size_t sp_brightness_grid_height(const SPBrightnessGrid *brightness_grid);
/**
* Loads a [SPBrightnessGrid] with the specified dimensions from the provided data.
*
* returns: new [SPBrightnessGrid] instance. Will never return NULL.
*
* # Panics
*
* - when `data` is NULL
* - when the provided `data_length` does not match `height` and `width`
*
* # Safety
*
* The caller has to make sure that:
*
* - `data` points to a valid memory location of at least `data_length`
* bytes in size.
* - 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);
/**
* Creates a new [SPBrightnessGrid] with the specified dimensions.
*
* returns: [SPBrightnessGrid] initialized to 0. Will never return NULL.
*
* # Safety
*
* The caller has to make sure that:
*
* - 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);
/**
* Sets the value of the specified position in the [SPBrightnessGrid].
*
* # Arguments
*
* - `brightness_grid`: instance to write to
* - `x` and `y`: position of the cell
* - `value`: the value to write to the cell
*
* returns: old value of the cell
*
* # Panics
*
* - when `brightness_grid` is NULL
* - When accessing `x` or `y` out of bounds.
* - When providing an invalid brightness value
*
* # Safety
*
* The caller has to make sure that:
*
* - `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,
size_t x,
size_t y,
uint8_t value);
/**
* Gets an unsafe reference to the data of the [SPBrightnessGrid] instance.
*
* # Arguments
*
* - `brightness_grid`: instance to read from
*
* returns: slice of bytes underlying the `brightness_grid`.
*
* # Panics
*
* - when `brightness_grid` is NULL
*
* # Safety
*
* 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
*/
SPByteSlice sp_brightness_grid_unsafe_data_ref(SPBrightnessGrid *brightness_grid);
/**
* Gets the width of the [SPBrightnessGrid] instance.
*
* # Arguments
*
* - `brightness_grid`: instance to read from
*
* returns: width
*
* # Panics
*
* - when `brightness_grid` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `brightness_grid` points to a valid [SPBrightnessGrid]
*/
size_t sp_brightness_grid_width(const SPBrightnessGrid *brightness_grid);
/**
* Clones a [SPCharGrid].
*
* Will never return NULL.
*
* # Panics
*
* - when `char_grid` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `char_grid` points to a valid [SPCharGrid]
* - `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`.
*/
SPCharGrid *sp_char_grid_clone(const SPCharGrid *char_grid);
/**
* Sets the value of all cells in the [SPCharGrid].
*
* # Arguments
*
* - `char_grid`: instance to write to
* - `value`: the value to set all cells to
*
* # Panics
*
* - when `char_grid` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `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);
/**
* Deallocates a [SPCharGrid].
*
* # Panics
*
* - when `char_grid` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `char_grid` points to a valid [SPCharGrid]
* - `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]
*
* [SPCommand]: [crate::SPCommand]
*/
void sp_char_grid_free(SPCharGrid *char_grid);
/**
* Gets the current value at the specified position.
*
* # Arguments
*
* - `char_grid`: instance to read from
* - `x` and `y`: position of the cell to read
*
* # Panics
*
* - when `char_grid` is NULL
* - when accessing `x` or `y` out of bounds
*
* # Safety
*
* The caller has to make sure that:
*
* - `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);
/**
* Gets the height of the [SPCharGrid] instance.
*
* # Arguments
*
* - `char_grid`: instance to read from
*
* # Panics
*
* - when `char_grid` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `char_grid` points to a valid [SPCharGrid]
*/
size_t sp_char_grid_height(const SPCharGrid *char_grid);
/**
* Loads a [SPCharGrid] with the specified dimensions from the provided data.
*
* Will never return NULL.
*
* # Panics
*
* - when `data` is NULL
* - when the provided `data_length` does not match `height` and `width`
* - when `data` is not valid UTF-8
*
* # Safety
*
* The caller has to make sure that:
*
* - `data` points to a valid memory location of at least `data_length`
* bytes in size.
* - 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);
/**
* Creates a new [SPCharGrid] with the specified dimensions.
*
* returns: [SPCharGrid] initialized to 0. Will never return NULL.
*
* # Safety
*
* The caller has to make sure that:
*
* - 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);
/**
* Sets the value of the specified position in the [SPCharGrid].
*
* # Arguments
*
* - `char_grid`: instance to write to
* - `x` and `y`: position of the cell
* - `value`: the value to write to the cell
*
* returns: old value of the cell
*
* # Panics
*
* - when `char_grid` is NULL
* - when accessing `x` or `y` out of bounds
*
* # Safety
*
* The caller has to make sure that:
*
* - `char_grid` points to a valid [SPBitVec]
* - `char_grid` is not written to or read from concurrently
*
* [SPBitVec]: [crate::SPBitVec]
*/
void sp_char_grid_set(SPCharGrid *char_grid,
size_t x,
size_t y,
uint32_t value);
/**
* Gets the width of the [SPCharGrid] instance.
*
* # Arguments
*
* - `char_grid`: instance to read from
*
* # Panics
*
* - when `char_grid` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `char_grid` points to a valid [SPCharGrid]
*/
size_t sp_char_grid_width(const SPCharGrid *char_grid);
/**
* Set pixel data starting at the pixel offset on screen.
*
* The screen will continuously overwrite more pixel data without regarding the offset, meaning
* once the starting row is full, overwriting will continue on column 0.
*
* The contained [SPBitVec] is always uncompressed.
*
* The passed [SPBitVec] gets consumed.
*
* Returns: a new [servicepoint::Command::BitmapLinear] instance. Will never return NULL.
*
* # Panics
*
* - when `bit_vec` is null
* - when `compression_code` is not a valid value
*
* # Safety
*
* The caller has to make sure that:
*
* - `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
* by explicitly calling `sp_command_free`.
*/
SPCommand *sp_command_bitmap_linear(size_t offset,
SPBitVec *bit_vec,
SPCompressionCode compression);
/**
* Set pixel data according to an and-mask starting at the offset.
*
* The screen will continuously overwrite more pixel data without regarding the offset, meaning
* once the starting row is full, overwriting will continue on column 0.
*
* The contained [SPBitVec] is always uncompressed.
*
* The passed [SPBitVec] gets consumed.
*
* Returns: a new [servicepoint::Command::BitmapLinearAnd] instance. Will never return NULL.
*
* # Panics
*
* - when `bit_vec` is null
* - when `compression_code` is not a valid value
*
* # Safety
*
* The caller has to make sure that:
*
* - `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
* by explicitly calling `sp_command_free`.
*/
SPCommand *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.
*
* The screen will continuously overwrite more pixel data without regarding the offset, meaning
* once the starting row is full, overwriting will continue on column 0.
*
* The contained [SPBitVec] is always uncompressed.
*
* The passed [SPBitVec] gets consumed.
*
* Returns: a new [servicepoint::Command::BitmapLinearOr] instance. Will never return NULL.
*
* # Panics
*
* - when `bit_vec` is null
* - when `compression_code` is not a valid value
*
* # Safety
*
* The caller has to make sure that:
*
* - `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
* by explicitly calling `sp_command_free`.
*/
SPCommand *sp_command_bitmap_linear_or(size_t offset,
SPBitVec *bit_vec,
SPCompressionCode compression);
/**
* Sets a window of pixels to the specified values.
*
* The passed [SPBitmap] gets consumed.
*
* Returns: a new [servicepoint::Command::BitmapLinearWin] instance. Will never return NULL.
*
* # Panics
*
* - when `bitmap` is null
* - when `compression_code` is not a valid value
*
* # Safety
*
* The caller has to make sure that:
*
* - `bitmap` points to a valid instance of [SPBitmap]
* - `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
* by explicitly calling `sp_command_free`.
*/
SPCommand *sp_command_bitmap_linear_win(size_t x,
size_t y,
SPBitmap *bitmap,
SPCompressionCode compression);
/**
* Set pixel data according to a xor-mask starting at the offset.
*
* The screen will continuously overwrite more pixel data without regarding the offset, meaning
* once the starting row is full, overwriting will continue on column 0.
*
* The contained [SPBitVec] is always uncompressed.
*
* The passed [SPBitVec] gets consumed.
*
* Returns: a new [servicepoint::Command::BitmapLinearXor] instance. Will never return NULL.
*
* # Panics
*
* - when `bit_vec` is null
* - when `compression_code` is not a valid value
*
* # Safety
*
* The caller has to make sure that:
*
* - `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
* by explicitly calling `sp_command_free`.
*/
SPCommand *sp_command_bitmap_linear_xor(size_t offset,
SPBitVec *bit_vec,
SPCompressionCode compression);
/**
* Set the brightness of all tiles to the same value.
*
* Returns: a new [servicepoint::Command::Brightness] instance. Will never return NULL.
*
* # Panics
*
* - When the provided brightness value is out of range (0-11).
*
* # Safety
*
* The caller has to make sure that:
*
* - 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);
/**
* Set the brightness of individual tiles in a rectangular area of the display.
*
* The passed [SPBrightnessGrid] gets consumed.
*
* Returns: a new [servicepoint::Command::CharBrightness] instance. Will never return NULL.
*
* # Panics
*
* - when `grid` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `grid` points to a valid instance of [SPBrightnessGrid]
* - `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
* by explicitly calling `sp_command_free`.
*/
SPCommand *sp_command_char_brightness(size_t x,
size_t y,
SPBrightnessGrid *grid);
/**
* Set all pixels to the off state.
*
* Does not affect brightness.
*
* Returns: a new [servicepoint::Command::Clear] instance. Will never return NULL.
*
* # Examples
*
* ```C
* sp_connection_send_command(connection, sp_command_clear());
* ```
*
* # Safety
*
* The caller has to make sure that:
*
* - 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);
/**
* Clones a [SPCommand] instance.
*
* returns: new [SPCommand] instance. Will never return NULL.
*
* # Panics
*
* - when `command` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `command` points to a valid instance of [SPCommand]
* - `command` is not written to concurrently
* - 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);
/**
* Show codepage 437 encoded text on the screen.
*
* The passed [SPCp437Grid] gets consumed.
*
* Returns: a new [servicepoint::Command::Cp437Data] instance. Will never return NULL.
*
* # Panics
*
* - when `grid` is null
*
* # Safety
*
* The caller has to make sure that:
*
* - `grid` points to a valid instance of [SPCp437Grid]
* - `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
* by explicitly calling `sp_command_free`.
*/
SPCommand *sp_command_cp437_data(size_t x,
size_t y,
SPCp437Grid *grid);
/**
* A yet-to-be-tested command.
*
* Returns: a new [servicepoint::Command::FadeOut] instance. Will never return NULL.
*
* # Safety
*
* The caller has to make sure that:
*
* - 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);
/**
* Deallocates a [SPCommand].
*
* # Examples
*
* ```C
* SPCommand c = sp_command_clear();
* sp_command_free(c);
* ```
*
* # Panics
*
* - when `command` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `command` points to a valid [SPCommand]
* - `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);
/**
* Kills the udp daemon on the display, which usually results in a restart.
*
* Please do not send this in your normal program flow.
*
* Returns: a new [servicepoint::Command::HardReset] instance. Will never return NULL.
*
* # Safety
*
* The caller has to make sure that:
*
* - 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);
/**
* Tries to turn a [SPPacket] into a [SPCommand].
*
* The packet is deallocated in the process.
*
* Returns: pointer to new [SPCommand] instance or NULL if parsing failed.
*
* # Panics
*
* - when `packet` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - [SPPacket] points to a valid instance of [SPPacket]
* - [SPPacket] 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
* by explicitly calling `sp_command_free`.
*/
SPCommand *sp_command_try_from_packet(SPPacket *packet);
/**
* Show UTF-8 encoded text on the screen.
*
* The passed [SPCharGrid] gets consumed.
*
* Returns: a new [servicepoint::Command::Utf8Data] instance. Will never return NULL.
*
* # Panics
*
* - when `grid` is null
*
* # Safety
*
* The caller has to make sure that:
*
* - `grid` points to a valid instance of [SPCharGrid]
* - `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
* by explicitly calling `sp_command_free`.
*/
SPCommand *sp_command_utf8_data(size_t x,
size_t y,
SPCharGrid *grid);
/**
* Closes and deallocates a [SPUdpConnection].
*
* # Panics
*
* - when `connection` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `connection` points to a valid [SPUdpConnection]
* - `connection` is not used concurrently or after this call
*/
void sp_connection_free(SPUdpConnection *connection);
/**
* Creates a new instance of [SPUdpConnection].
*
* returns: NULL if connection fails, or connected instance
*
* # Panics
*
* - when `host` is null or an invalid host
*
* # Safety
*
* The caller has to make sure that:
*
* - the returned instance is freed in some way, either by using a consuming function or
* by explicitly calling `sp_connection_free`.
*/
SPUdpConnection *sp_connection_open(const char *host);
/**
* Sends a [SPCommand] to the display using the [SPUdpConnection].
*
* The passed `command` gets consumed.
*
* returns: true in case of success
*
* # Panics
*
* - when `connection` is NULL
* - when `command` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `connection` points to a valid instance of [SPUdpConnection]
* - `command` points to a valid instance of [SPPacket]
* - `command` is not used concurrently or after this call
*/
bool sp_connection_send_command(const SPUdpConnection *connection,
SPCommand *command);
/**
* Sends a [SPPacket] to the display using the [SPUdpConnection].
*
* The passed `packet` gets consumed.
*
* returns: true in case of success
*
* # Panics
*
* - when `connection` is NULL
* - when `packet` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `connection` points to a valid instance of [SPUdpConnection]
* - `packet` points to a valid instance of [SPPacket]
* - `packet` is not used concurrently or after this call
*/
bool sp_connection_send_packet(const SPUdpConnection *connection,
SPPacket *packet);
/**
* Clones a [SPCp437Grid].
*
* Will never return NULL.
*
* # Panics
*
* - when `cp437_grid` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `cp437_grid` points to a valid [SPCp437Grid]
* - `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`.
*/
SPCp437Grid *sp_cp437_grid_clone(const SPCp437Grid *cp437_grid);
/**
* Sets the value of all cells in the [SPCp437Grid].
*
* # Arguments
*
* - `cp437_grid`: instance to write to
* - `value`: the value to set all cells to
*
* # Panics
*
* - when `cp437_grid` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `cp437_grid` points to a valid [SPCp437Grid]
* - `cp437_grid` is not written to or read from concurrently
*/
void sp_cp437_grid_fill(SPCp437Grid *cp437_grid, uint8_t value);
/**
* Deallocates a [SPCp437Grid].
*
* # Panics
*
* - when `cp437_grid` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `cp437_grid` points to a valid [SPCp437Grid]
* - `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]
*
* [SPCommand]: [crate::SPCommand]
*/
void sp_cp437_grid_free(SPCp437Grid *cp437_grid);
/**
* Gets the current value at the specified position.
*
* # Arguments
*
* - `cp437_grid`: instance to read from
* - `x` and `y`: position of the cell to read
*
* # Panics
*
* - when `cp437_grid` is NULL
* - when accessing `x` or `y` out of bounds
*
* # Safety
*
* The caller has to make sure that:
*
* - `cp437_grid` points to a valid [SPCp437Grid]
* - `cp437_grid` is not written to concurrently
*/
uint8_t sp_cp437_grid_get(const SPCp437Grid *cp437_grid, size_t x, size_t y);
/**
* Gets the height of the [SPCp437Grid] instance.
*
* # Arguments
*
* - `cp437_grid`: instance to read from
*
* # Panics
*
* - when `cp437_grid` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `cp437_grid` points to a valid [SPCp437Grid]
*/
size_t sp_cp437_grid_height(const SPCp437Grid *cp437_grid);
/**
* Loads a [SPCp437Grid] with the specified dimensions from the provided data.
*
* Will never return NULL.
*
* # Panics
*
* - when `data` is NULL
* - when the provided `data_length` does not match `height` and `width`
*
* # Safety
*
* The caller has to make sure that:
*
* - `data` points to a valid memory location of at least `data_length`
* bytes in size.
* - the returned instance is freed in some way, either by using a consuming function or
* by explicitly calling `sp_cp437_grid_free`.
*/
SPCp437Grid *sp_cp437_grid_load(size_t width,
size_t height,
const uint8_t *data,
size_t data_length);
/**
* Creates a new [SPCp437Grid] with the specified dimensions.
*
* returns: [SPCp437Grid] initialized to 0. Will never return NULL.
*
* # Safety
*
* The caller has to make sure that:
*
* - the returned instance is freed in some way, either by using a consuming function or
* by explicitly calling `sp_cp437_grid_free`.
*/
SPCp437Grid *sp_cp437_grid_new(size_t width,
size_t height);
/**
* Sets the value of the specified position in the [SPCp437Grid].
*
* # Arguments
*
* - `cp437_grid`: instance to write to
* - `x` and `y`: position of the cell
* - `value`: the value to write to the cell
*
* returns: old value of the cell
*
* # Panics
*
* - when `cp437_grid` is NULL
* - when accessing `x` or `y` out of bounds
*
* # Safety
*
* The caller has to make sure that:
*
* - `cp437_grid` points to a valid [SPBitVec]
* - `cp437_grid` is not written to or read from concurrently
*
* [SPBitVec]: [crate::SPBitVec]
*/
void sp_cp437_grid_set(SPCp437Grid *cp437_grid,
size_t x,
size_t y,
uint8_t value);
/**
* Gets an unsafe reference to the data of the [SPCp437Grid] instance.
*
* Will never return NULL.
*
* # Panics
*
* - when `cp437_grid` is NULL
*
* ## Safety
*
* 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
*/
SPByteSlice sp_cp437_grid_unsafe_data_ref(SPCp437Grid *cp437_grid);
/**
* Gets the width of the [SPCp437Grid] instance.
*
* # Arguments
*
* - `cp437_grid`: instance to read from
*
* # Panics
*
* - when `cp437_grid` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `cp437_grid` points to a valid [SPCp437Grid]
*/
size_t sp_cp437_grid_width(const SPCp437Grid *cp437_grid);
/**
* Clones a [SPPacket].
*
* Will never return NULL.
*
* # Panics
*
* - when `packet` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `packet` points to a valid [SPPacket]
* - `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`.
*/
SPPacket *sp_packet_clone(const SPPacket *packet);
/**
* Deallocates a [SPPacket].
*
* # Panics
*
* - when `packet` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `packet` points to a valid [SPPacket]
* - `packet` is not used concurrently or after this call
*/
void sp_packet_free(SPPacket *packet);
/**
* Turns a [SPCommand] into a [SPPacket].
* The [SPCommand] gets consumed.
*
* Will never return NULL.
*
* # Panics
*
* - when `command` is NULL
*
* # Safety
*
* 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
* by explicitly calling `sp_packet_free`.
*/
SPPacket *sp_packet_from_command(SPCommand *command);
/**
* Creates a raw [SPPacket] from parts.
*
* # Arguments
*
* - `command_code` specifies which command this packet contains
* - `a`, `b`, `c` and `d` are command-specific header values
* - `payload` is the optional data that is part of the command
* - `payload_len` is the size of the payload
*
* returns: new instance. Will never return null.
*
* # Panics
*
* - when `payload` is null, but `payload_len` is not zero
* - when `payload_len` is zero, but `payload` is nonnull
*
* # Safety
*
* The caller has to make sure that:
*
* - `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
* 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);
/**
* Tries to load a [SPPacket] from the passed array with the specified length.
*
* returns: NULL in case of an error, pointer to the allocated packet otherwise
*
* # Panics
*
* - when `data` is NULL
*
* # Safety
*
* The caller has to make sure that:
*
* - `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
* by explicitly calling `sp_packet_free`.
*/
SPPacket *sp_packet_try_load(const uint8_t *data,
size_t length);
#ifdef __cplusplus
} // extern "C"
#endif // __cplusplus