servicepoint-binding-c/examples/lang_c/include/servicepoint.h

/* 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>

/**
 * pixel count on whole screen
 */
#define PIXEL_COUNT (PIXEL_WIDTH * PIXEL_HEIGHT)

/**
 * Display height in pixels
 *
 * # Examples
 *
 * ```rust
 * # use servicepoint::{PIXEL_HEIGHT, PIXEL_WIDTH, Bitmap};
 * let grid = Bitmap::new(PIXEL_WIDTH, PIXEL_HEIGHT);
 * ```
 */
#define PIXEL_HEIGHT (TILE_HEIGHT * TILE_SIZE)

/**
 * Display width in pixels
 *
 * # Examples
 *
 * ```rust
 * # use servicepoint::{PIXEL_HEIGHT, PIXEL_WIDTH, Bitmap};
 * let grid = Bitmap::new(PIXEL_WIDTH, PIXEL_HEIGHT);
 * ```
 */
#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
 *
 * # Examples
 *
 * ```rust
 * # use servicepoint::{Cp437Grid, TILE_HEIGHT, TILE_WIDTH};
 * let grid = Cp437Grid::new(TILE_WIDTH, TILE_HEIGHT);
 * ```
 */
#define TILE_HEIGHT 20

/**
 * size of a single tile in one dimension
 */
#define TILE_SIZE 8

/**
 * Display tile count in the x-direction
 *
 * # Examples
 *
 * ```rust
 * # use servicepoint::{Cp437Grid, TILE_HEIGHT, TILE_WIDTH};
 * let grid = Cp437Grid::new(TILE_WIDTH, TILE_HEIGHT);
 * ```
 */
#define TILE_WIDTH 56

/**
 * Specifies the kind of compression to use. Availability depends on features.
 *
 * # Examples
 *
 * ```rust
 * # use servicepoint::*;
 * // create command without payload compression
 * # let pixels = Bitmap::max_sized();
 * _ = BitmapCommand {
 *     origin: Origin::ZERO,
 *     bitmap: pixels,
 *     compression: CompressionCode::Uncompressed
 * };
 *
 * // create command with payload compressed with lzma and appropriate header flags
 * # let pixels = Bitmap::max_sized();
 * _ = BitmapCommand {
 *     origin: Origin::ZERO,
 *     bitmap: pixels,
 *     compression: CompressionCode::Lzma
 * };
 * ```
 */
enum CompressionCode
#ifdef __cplusplus
  : uint16_t
#endif // __cplusplus
 {
    /**
     * no compression
     */
    COMPRESSION_CODE_UNCOMPRESSED = 0,
    /**
     * compress using flate2 with zlib header
     */
    COMPRESSION_CODE_ZLIB = 26490,
    /**
     * compress using bzip2
     */
    COMPRESSION_CODE_BZIP2 = 25210,
    /**
     * compress using lzma
     */
    COMPRESSION_CODE_LZMA = 27770,
    /**
     * compress using Zstandard
     */
    COMPRESSION_CODE_ZSTD = 31347,
};
#ifndef __cplusplus
typedef uint16_t CompressionCode;
#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
 *
 * # Examples
 * ```C
 * SPBitVec vec = sp_bitvec_new(8);
 * sp_bitvec_set(vec, 5, true);
 * sp_bitvec_free(vec);
 * ```
 */
typedef struct SPBitVec SPBitVec;

/**
 * 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`.
 *
 * Please look at the contained structs for documentation per command.
 */
typedef struct Command Command;

/**
 * A connection using the UDP protocol.
 *
 * Use this when sending commands directly to the display.
 *
 * Requires the feature "`protocol_udp`" which is enabled by default.
 */
typedef struct UdpConnection UdpConnection;

/**
 * A 2D grid of values.
 *
 * The memory layout is the one the display expects in [`crate::Command`]s.
 *
 * 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 ValueGrid_Brightness ValueGrid_Brightness;

/**
 * A 2D grid of values.
 *
 * The memory layout is the one the display expects in [`crate::Command`]s.
 *
 * 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 ValueGrid_char ValueGrid_char;

/**
 * A 2D grid of values.
 *
 * The memory layout is the one the display expects in [`crate::Command`]s.
 *
 * 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 ValueGrid_u8 ValueGrid_u8;

/**
 * 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 */*notnull*/ start;
    /**
     * The amount of memory in bytes
     */
    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 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

/**
 * 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`.
 */
Bitmap */*notnull*/ sp_bitmap_clone(Bitmap */*notnull*/ 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(Bitmap */*notnull*/ 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]
 *
 * [SPCommand]: [crate::SPCommand]
 */
void sp_bitmap_free(Bitmap */*notnull*/ 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(Bitmap */*notnull*/ 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(Bitmap */*notnull*/ 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`.
 */
Bitmap *sp_bitmap_load(size_t width,
                       size_t height,
                       SPByteSlice data);

/**
 * 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`.
 */
Bitmap *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].
 */
Bitmap */*notnull*/ 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(Bitmap */*notnull*/ 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(Bitmap */*notnull*/ 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(Bitmap */*notnull*/ 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 */*notnull*/ sp_bitvec_clone(SPBitVec */*notnull*/ 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 */*notnull*/ 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 */*notnull*/ 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(SPBitVec */*notnull*/ 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(SPBitVec */*notnull*/ 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(SPBitVec */*notnull*/ 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 */*notnull*/ sp_bitvec_load(SPByteSlice data);

/**
 * 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 */*notnull*/ 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 */*notnull*/ 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 */*notnull*/ 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`.
 */
BrightnessGrid */*notnull*/ sp_brightness_grid_clone(BrightnessGrid */*notnull*/ 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(BrightnessGrid */*notnull*/ 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(BrightnessGrid */*notnull*/ 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(BrightnessGrid */*notnull*/ 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(BrightnessGrid */*notnull*/ 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`.
 */
BrightnessGrid *sp_brightness_grid_load(size_t width,
                                        size_t height,
                                        SPByteSlice data);

/**
 * 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`.
 */
BrightnessGrid */*notnull*/ 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(BrightnessGrid */*notnull*/ 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(BrightnessGrid */*notnull*/ 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(BrightnessGrid */*notnull*/ 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`.
 */
CharGrid */*notnull*/ sp_char_grid_clone(CharGrid */*notnull*/ 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(CharGrid */*notnull*/ 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(CharGrid */*notnull*/ 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(CharGrid */*notnull*/ 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(CharGrid */*notnull*/ 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`.
 */
CharGrid */*notnull*/ sp_char_grid_load(size_t width,
                                        size_t height,
                                        SPByteSlice data);

/**
 * 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`.
 */
CharGrid */*notnull*/ 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(CharGrid */*notnull*/ 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(CharGrid */*notnull*/ 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`.
 */
Command *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.
 *
 * 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`.
 */
Command *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.
 *
 * 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`.
 */
Command *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.
 *
 * 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`.
 */
Command *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.
 *
 * 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`.
 */
Command *sp_command_bitmap_linear_xor(size_t offset,
                                      SPBitVec */*notnull*/ bit_vec,
                                      CompressionCode 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`.
 */
Command */*notnull*/ 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`.
 */
Command */*notnull*/ sp_command_char_brightness(size_t x,
                                                size_t y,
                                                BrightnessGrid */*notnull*/ 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`.
 */
Command */*notnull*/ 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`.
 */
Command */*notnull*/ sp_command_clone(Command */*notnull*/ 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`.
 */
Command */*notnull*/ sp_command_cp437_data(size_t x,
                                           size_t y,
                                           Cp437Grid */*notnull*/ 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`.
 */
Command */*notnull*/ 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(Command */*notnull*/ 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`.
 */
Command */*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].
 *
 * # 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.
 *
 * 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`.
 */
Command *sp_command_try_from_packet(Packet */*notnull*/ 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`.
 */
Command */*notnull*/ sp_command_utf8_data(size_t x,
                                          size_t y,
                                          CharGrid */*notnull*/ grid);

/**
 * Closes and deallocates a [SPConnection].
 *
 * # Panics
 *
 * - when `connection` is NULL
 *
 * # Safety
 *
 * The caller has to make sure that:
 *
 * - `connection` points to a valid [SPConnection]
 * - `connection` is not used concurrently or after this call
 */
void sp_connection_free(UdpConnection */*notnull*/ connection);

/**
 * Creates a new instance of [SPConnection].
 *
 * 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`.
 */
UdpConnection *sp_connection_open(char */*notnull*/ host);

/**
 * Sends a [SPCommand] to the display using the [SPConnection].
 *
 * 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 [SPConnection]
 * - `command` points to a valid instance of [SPPacket]
 * - `command` is not used concurrently or after this call
 */
bool sp_connection_send_command(UdpConnection */*notnull*/ connection,
                                Command */*notnull*/ command);

/**
 * Sends a [SPPacket] to the display using the [SPConnection].
 *
 * 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 [SPConnection]
 * - `packet` points to a valid instance of [SPPacket]
 * - `packet` is not used concurrently or after this call
 */
bool sp_connection_send_packet(UdpConnection */*notnull*/ connection,
                               Packet */*notnull*/ 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`.
 */
Cp437Grid */*notnull*/ sp_cp437_grid_clone(Cp437Grid */*notnull*/ 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(Cp437Grid */*notnull*/ 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(Cp437Grid */*notnull*/ 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(Cp437Grid */*notnull*/ 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(Cp437Grid */*notnull*/ 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`.
 */
Cp437Grid *sp_cp437_grid_load(size_t width,
                              size_t height,
                              SPByteSlice data);

/**
 * 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`.
 */
Cp437Grid */*notnull*/ 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(Cp437Grid */*notnull*/ 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(Cp437Grid */*notnull*/ 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(Cp437Grid */*notnull*/ 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`.
 */
Packet */*notnull*/ sp_packet_clone(Packet */*notnull*/ 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(Packet */*notnull*/ 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`.
 */
Packet *sp_packet_from_command(Command */*notnull*/ 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].
 */
Packet */*notnull*/ sp_packet_from_parts(Header header,
                                         const SPByteSlice *payload);

Header */*notnull*/ sp_packet_get_header(Packet */*notnull*/ packet);

SPByteSlice sp_packet_get_payload(Packet */*notnull*/ packet);

void sp_packet_set_payload(Packet */*notnull*/ packet, SPByteSlice data);

/**
 * 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`.
 */
Packet *sp_packet_try_load(SPByteSlice data);

void sp_packet_write_to(Packet */*notnull*/ packet, SPByteSlice buffer);

#ifdef __cplusplus
}  // extern "C"
#endif  // __cplusplus