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

add NULL checks - command

Browse source
This commit is contained in:
Vinzenz Schroeter 2024-10-13 18:56:29 +02:00
parent bcb73999da
commit 2e1cb6f681
5 changed files with 186 additions and 105 deletions
Download patch file Download diff file Expand all files Collapse all files

165
crates/servicepoint_binding_c/src/command.rs
View file

@ -4,7 +4,7 @@
use std::ptr::null_mut;
use servicepoint::{Brightness, Origin};
use servicepoint::{Brightness, Command, Origin};
use crate::{
SPBitVec, SPBrightnessGrid, SPCompressionCode, SPCp437Grid, SPPacket,
@ -15,7 +15,7 @@ use crate::{
///
/// This struct and associated functions implement the UDP protocol for the display.
///
/// To send a [SPCommand], use a `SPConnection`.
/// To send a [SPCommand], use a [SPConnection].
///
/// # Examples
///
@ -31,18 +31,22 @@ impl Clone for SPCommand {
}
}
/// Tries to turn a `SPPacket` into a [SPCommand].
/// Tries to turn a [SPPacket] into a [SPCommand].
///
/// The packet is deallocated in the process.
///
/// Returns: pointer to new [SPCommand] instance or NULL
/// 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
/// - [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`.
@ -59,6 +63,12 @@ pub unsafe extern "C" fn sp_command_try_from_packet(
/// 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:
@ -71,14 +81,17 @@ pub unsafe extern "C" fn sp_command_try_from_packet(
pub unsafe extern "C" fn sp_command_clone(
command: *const SPCommand,
) -> *mut SPCommand {
Box::into_raw(Box::new((*command).clone()))
assert!(!command.is_null());
let result = Box::into_raw(Box::new((*command).clone()));
assert!(!result.is_null());
result
}
/// Set all pixels to the off state.
///
/// Does not affect brightness.
///
/// Returns: a new `Command::Clear` instance. Will never return NULL.
/// Returns: a new [Command::Clear] instance. Will never return NULL.
///
/// # Examples
///
@ -94,14 +107,16 @@ pub unsafe extern "C" fn sp_command_clone(
/// by explicitly calling `sp_command_free`.
#[no_mangle]
pub unsafe extern "C" fn sp_command_clear() -> *mut SPCommand {
Box::into_raw(Box::new(SPCommand(servicepoint::Command::Clear)))
let result = Box::into_raw(Box::new(SPCommand(servicepoint::Command::Clear)));
assert!(!result.is_null());
result
}
/// 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 `Command::HardReset` instance. Will never return NULL.
/// Returns: a new [Command::HardReset] instance. Will never return NULL.
///
/// # Safety
///
@ -111,7 +126,9 @@ pub unsafe extern "C" fn sp_command_clear() -> *mut SPCommand {
/// by explicitly calling `sp_command_free`.
#[no_mangle]
pub unsafe extern "C" fn sp_command_hard_reset() -> *mut SPCommand {
Box::into_raw(Box::new(SPCommand(servicepoint::Command::HardReset)))
let result = Box::into_raw(Box::new(SPCommand(servicepoint::Command::HardReset)));
assert!(!result.is_null());
result
}
/// A yet-to-be-tested command.
@ -126,12 +143,14 @@ pub unsafe extern "C" fn sp_command_hard_reset() -> *mut SPCommand {
/// by explicitly calling `sp_command_free`.
#[no_mangle]
pub unsafe extern "C" fn sp_command_fade_out() -> *mut SPCommand {
Box::into_raw(Box::new(SPCommand(servicepoint::Command::FadeOut)))
let result = Box::into_raw(Box::new(SPCommand(servicepoint::Command::FadeOut)));
assert!(!result.is_null());
result
}
/// Set the brightness of all tiles to the same value.
///
/// Returns: a new `Command::Brightness` instance. Will never return NULL.
/// Returns: a new [Command::Brightness] instance. Will never return NULL.
///
/// # Panics
///
@ -149,16 +168,22 @@ pub unsafe extern "C" fn sp_command_brightness(
) -> *mut SPCommand {
let brightness =
Brightness::try_from(brightness).expect("invalid brightness");
Box::into_raw(Box::new(SPCommand(servicepoint::Command::Brightness(
let result = Box::into_raw(Box::new(SPCommand(servicepoint::Command::Brightness(
brightness,
))))
))));
assert!(!result.is_null());
result
}
/// Set the brightness of individual tiles in a rectangular area of the display.
///
/// The passed [SPBrightnessGrid] gets consumed.
///
/// Returns: a new `Command::CharBrightness` instance. Will never return NULL.
/// Returns: a new [Command::CharBrightness] instance. Will never return NULL.
///
/// # Panics
///
/// - when `grid` is NULL
///
/// # Safety
///
@ -174,11 +199,14 @@ pub unsafe extern "C" fn sp_command_char_brightness(
y: usize,
grid: *mut SPBrightnessGrid,
) -> *mut SPCommand {
assert!(!grid.is_null());
let byte_grid = *Box::from_raw(grid);
Box::into_raw(Box::new(SPCommand(servicepoint::Command::CharBrightness(
let result = Box::into_raw(Box::new(SPCommand(servicepoint::Command::CharBrightness(
Origin::new(x, y),
byte_grid.0,
))))
))));
assert!(!result.is_null());
result
}
/// Set pixel data starting at the pixel offset on screen.
@ -190,7 +218,12 @@ pub unsafe extern "C" fn sp_command_char_brightness(
///
/// The passed [SPBitVec] gets consumed.
///
/// Returns: a new `Command::BitmapLinear` instance. Will never return NULL.
/// Returns: a new [Command::BitmapLinear] instance. Will never return NULL.
///
/// # Panics
///
/// - when `bit_vec` is null
/// - when `compression_code` is not a valid value
///
/// # Safety
///
@ -207,12 +240,15 @@ pub unsafe extern "C" fn sp_command_bitmap_linear(
bit_vec: *mut SPBitVec,
compression: SPCompressionCode,
) -> *mut SPCommand {
assert!(!bit_vec.is_null());
let bit_vec = *Box::from_raw(bit_vec);
Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinear(
let result = Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinear(
offset,
bit_vec.into(),
compression.try_into().expect("invalid compression code"),
))))
))));
assert!(!result.is_null());
result
}
/// Set pixel data according to an and-mask starting at the offset.
@ -224,7 +260,12 @@ pub unsafe extern "C" fn sp_command_bitmap_linear(
///
/// The passed [SPBitVec] gets consumed.
///
/// Returns: a new `Command::BitmapLinearAnd` instance. Will never return NULL.
/// Returns: a new [Command::BitmapLinearAnd] instance. Will never return NULL.
///
/// # Panics
///
/// - when `bit_vec` is null
/// - when `compression_code` is not a valid value
///
/// # Safety
///
@ -241,12 +282,15 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_and(
bit_vec: *mut SPBitVec,
compression: SPCompressionCode,
) -> *mut SPCommand {
assert!(!bit_vec.is_null());
let bit_vec = *Box::from_raw(bit_vec);
Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinearAnd(
let result = Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinearAnd(
offset,
bit_vec.into(),
compression.try_into().expect("invalid compression code"),
))))
))));
assert!(!result.is_null());
result
}
/// Set pixel data according to an or-mask starting at the offset.
@ -258,7 +302,12 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_and(
///
/// The passed [SPBitVec] gets consumed.
///
/// Returns: a new `Command::BitmapLinearOr` instance. Will never return NULL.
/// Returns: a new [Command::BitmapLinearOr] instance. Will never return NULL.
///
/// # Panics
///
/// - when `bit_vec` is null
/// - when `compression_code` is not a valid value
///
/// # Safety
///
@ -275,12 +324,15 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_or(
bit_vec: *mut SPBitVec,
compression: SPCompressionCode,
) -> *mut SPCommand {
assert!(!bit_vec.is_null());
let bit_vec = *Box::from_raw(bit_vec);
Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinearOr(
let result = Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinearOr(
offset,
bit_vec.into(),
compression.try_into().expect("invalid compression code"),
))))
))));
assert!(!result.is_null());
result
}
/// Set pixel data according to a xor-mask starting at the offset.
@ -292,7 +344,12 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_or(
///
/// The passed [SPBitVec] gets consumed.
///
/// Returns: a new `Command::BitmapLinearXor` instance. Will never return NULL.
/// Returns: a new [Command::BitmapLinearXor] instance. Will never return NULL.
///
/// # Panics
///
/// - when `bit_vec` is null
/// - when `compression_code` is not a valid value
///
/// # Safety
///
@ -309,30 +366,32 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_xor(
bit_vec: *mut SPBitVec,
compression: SPCompressionCode,
) -> *mut SPCommand {
assert!(!bit_vec.is_null());
let bit_vec = *Box::from_raw(bit_vec);
Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinearXor(
let result = Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinearXor(
offset,
bit_vec.into(),
compression.try_into().expect("invalid compression code"),
))))
))));
assert!(!result.is_null());
result
}
/// Show text on the screen.
///
/// <div class="warning">
/// The library does not currently convert between UTF-8 and CP-437.
/// Because Rust expects UTF-8 strings, it might be necessary to only send ASCII for now.
/// </div>
/// The passed [SPCp437Grid] gets consumed.
///
/// The passed `SPCp437Grid` gets consumed.///
/// Returns: a new [Command::Cp437Data] instance. Will never return NULL.
///
/// Returns: a new `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` 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`.
@ -342,24 +401,32 @@ pub unsafe extern "C" fn sp_command_cp437_data(
y: usize,
grid: *mut SPCp437Grid,
) -> *mut SPCommand {
assert!(!grid.is_null());
let grid = *Box::from_raw(grid);
Box::into_raw(Box::new(SPCommand(servicepoint::Command::Cp437Data(
let result = Box::into_raw(Box::new(SPCommand(servicepoint::Command::Cp437Data(
Origin::new(x, y),
grid.0,
))))
))));
assert!(!result.is_null());
result
}
/// Sets a window of pixels to the specified values.
///
/// The passed `SPPixelGrid` gets consumed.
/// The passed [SPPixelGrid] gets consumed.
///
/// Returns: a new `Command::BitmapLinearWin` instance. Will never return NULL.
/// Returns: a new [Command::BitmapLinearWin] instance. Will never return NULL.
///
/// # Panics
///
/// - when `pixel_grid` is null
/// - when `compression_code` is not a valid value
///
/// # Safety
///
/// The caller has to make sure that:
///
/// - `pixel_grid` points to a valid instance of `SPPixelGrid`
/// - `pixel_grid` points to a valid instance of [SPPixelGrid]
/// - `pixel_grid` 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
@ -371,14 +438,17 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_win(
pixel_grid: *mut SPPixelGrid,
compression_code: SPCompressionCode,
) -> *mut SPCommand {
assert!(!pixel_grid.is_null());
let byte_grid = (*Box::from_raw(pixel_grid)).0;
Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinearWin(
let result = Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinearWin(
Origin::new(x, y),
byte_grid,
compression_code
.try_into()
.expect("invalid compression code"),
))))
))));
assert!(!result.is_null());
result
}
/// Deallocates a [SPCommand].
@ -390,14 +460,19 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_win(
/// 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`
/// - `command` was not passed to another consuming function, e.g. to create a [SPPacket]
#[no_mangle]
pub unsafe extern "C" fn sp_command_free(command: *mut SPCommand) {
assert!(!command.is_null());
_ = Box::from_raw(command);
}

22
crates/servicepoint_binding_c/src/connection.rs
View file

@ -18,7 +18,7 @@ use crate::{SPCommand, SPPacket};
/// ```
pub struct SPConnection(pub(crate) servicepoint::Connection);
/// Creates a new instance of `SPConnection`.
/// Creates a new instance of [SPConnection].
///
/// returns: NULL if connection fails, or connected instance
///
@ -45,7 +45,7 @@ pub unsafe extern "C" fn sp_connection_open(
Box::into_raw(Box::new(SPConnection(connection)))
}
/// Sends a `SPPacket` to the display using the `SPConnection`.
/// Sends a [SPPacket] to the display using the [SPConnection].
///
/// The passed `packet` gets consumed.
///
@ -55,8 +55,8 @@ pub unsafe extern "C" fn sp_connection_open(
///
/// The caller has to make sure that:
///
/// - `connection` points to a valid instance of `SPConnection`
/// - `packet` points to a valid instance of `SPPacket`
/// - `connection` points to a valid instance of [SPConnection]
/// - `packet` points to a valid instance of [SPPacket]
/// - `packet` is not used concurrently or after this call
#[no_mangle]
pub unsafe extern "C" fn sp_connection_send_packet(
@ -77,8 +77,8 @@ pub unsafe extern "C" fn sp_connection_send_packet(
///
/// The caller has to make sure that:
///
/// - `connection` points to a valid instance of `SPConnection`
/// - `command` points to a valid instance of `SPPacket`
/// - `connection` points to a valid instance of [SPConnection]
/// - `command` points to a valid instance of [SPPacket]
/// - `command` is not used concurrently or after this call
#[no_mangle]
pub unsafe extern "C" fn sp_connection_send_command(
@ -89,13 +89,19 @@ pub unsafe extern "C" fn sp_connection_send_command(
(*connection).0.send(command).is_ok()
}
/// Closes and deallocates a `SPConnection`.
/// Closes and deallocates a [SPConnection].
///
/// # Panics
///
/// # Panics
///
/// - when `connection` is NULL
///
/// # Safety
///
/// The caller has to make sure that:
///
/// - `connection` points to a valid `SPConnection`
/// - `connection` points to a valid [SPConnection]
/// - `connection` is not used concurrently or after this call
#[no_mangle]
pub unsafe extern "C" fn sp_connection_free(connection: *mut SPConnection) {

40
crates/servicepoint_binding_c/src/cp437_grid.rs
View file

@ -1,4 +1,4 @@
//! C functions for interacting with `SPCp437Grid`s
//! C functions for interacting with [SPCp437Grid]s
//!
//! prefix `sp_cp437_grid_`
@ -25,9 +25,9 @@ impl Clone for SPCp437Grid {
}
}
/// Creates a new `SPCp437Grid` with the specified dimensions.
/// Creates a new [SPCp437Grid] with the specified dimensions.
///
/// returns: `SPCp437Grid` initialized to 0.
/// returns: [SPCp437Grid] initialized to 0.
///
/// # Safety
///
@ -45,7 +45,7 @@ pub unsafe extern "C" fn sp_cp437_grid_new(
))))
}
/// Loads a `SPCp437Grid` with the specified dimensions from the provided data.
/// Loads a [SPCp437Grid] with the specified dimensions from the provided data.
///
/// Will never return NULL.
///
@ -74,7 +74,7 @@ pub unsafe extern "C" fn sp_cp437_grid_load(
))))
}
/// Clones a `SPCp437Grid`.
/// Clones a [SPCp437Grid].
///
/// Will never return NULL.
///
@ -82,7 +82,7 @@ pub unsafe extern "C" fn sp_cp437_grid_load(
///
/// The caller has to make sure that:
///
/// - `cp437_grid` points to a valid `SPCp437Grid`
/// - `cp437_grid` points to a valid [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`.
@ -93,13 +93,13 @@ pub unsafe extern "C" fn sp_cp437_grid_clone(
Box::into_raw(Box::new((*cp437_grid).clone()))
}
/// Deallocates a `SPCp437Grid`.
/// Deallocates a [SPCp437Grid].
///
/// # Safety
///
/// The caller has to make sure that:
///
/// - `cp437_grid` points to a valid `SPCp437Grid`
/// - `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]
#[no_mangle]
@ -122,7 +122,7 @@ pub unsafe extern "C" fn sp_cp437_grid_free(cp437_grid: *mut SPCp437Grid) {
///
/// The caller has to make sure that:
///
/// - `cp437_grid` points to a valid `SPCp437Grid`
/// - `cp437_grid` points to a valid [SPCp437Grid]
/// - `cp437_grid` is not written to concurrently
#[no_mangle]
pub unsafe extern "C" fn sp_cp437_grid_get(
@ -133,7 +133,7 @@ pub unsafe extern "C" fn sp_cp437_grid_get(
(*cp437_grid).0.get(x, y)
}
/// Sets the value of the specified position in the `SPCp437Grid`.
/// Sets the value of the specified position in the [SPCp437Grid].
///
/// # Arguments
///
@ -163,7 +163,7 @@ pub unsafe extern "C" fn sp_cp437_grid_set(
(*cp437_grid).0.set(x, y, value);
}
/// Sets the value of all cells in the `SPCp437Grid`.
/// Sets the value of all cells in the [SPCp437Grid].
///
/// # Arguments
///
@ -174,7 +174,7 @@ pub unsafe extern "C" fn sp_cp437_grid_set(
///
/// The caller has to make sure that:
///
/// - `cp437_grid` points to a valid `SPCp437Grid`
/// - `cp437_grid` points to a valid [SPCp437Grid]
/// - `cp437_grid` is not written to or read from concurrently
#[no_mangle]
pub unsafe extern "C" fn sp_cp437_grid_fill(
@ -184,7 +184,7 @@ pub unsafe extern "C" fn sp_cp437_grid_fill(
(*cp437_grid).0.fill(value);
}
/// Gets the width of the `SPCp437Grid` instance.
/// Gets the width of the [SPCp437Grid] instance.
///
/// # Arguments
///
@ -194,7 +194,7 @@ pub unsafe extern "C" fn sp_cp437_grid_fill(
///
/// The caller has to make sure that:
///
/// - `cp437_grid` points to a valid `SPCp437Grid`
/// - `cp437_grid` points to a valid [SPCp437Grid]
#[no_mangle]
pub unsafe extern "C" fn sp_cp437_grid_width(
cp437_grid: *const SPCp437Grid,
@ -202,7 +202,7 @@ pub unsafe extern "C" fn sp_cp437_grid_width(
(*cp437_grid).0.width()
}
/// Gets the height of the `SPCp437Grid` instance.
/// Gets the height of the [SPCp437Grid] instance.
///
/// # Arguments
///
@ -212,7 +212,7 @@ pub unsafe extern "C" fn sp_cp437_grid_width(
///
/// The caller has to make sure that:
///
/// - `cp437_grid` points to a valid `SPCp437Grid`
/// - `cp437_grid` points to a valid [SPCp437Grid]
#[no_mangle]
pub unsafe extern "C" fn sp_cp437_grid_height(
cp437_grid: *const SPCp437Grid,
@ -220,7 +220,7 @@ pub unsafe extern "C" fn sp_cp437_grid_height(
(*cp437_grid).0.height()
}
/// Gets an unsafe reference to the data of the `SPCp437Grid` instance.
/// Gets an unsafe reference to the data of the [SPCp437Grid] instance.
///
/// Will never return NULL.
///
@ -228,9 +228,9 @@ pub unsafe extern "C" fn sp_cp437_grid_height(
///
/// The caller has to make sure that:
///
/// - `cp437_grid` points to a valid `SPCp437Grid`
/// - the returned memory range is never accessed after the passed `SPCp437Grid` has been freed
/// - the returned memory range is never accessed concurrently, either via the `SPCp437Grid` or directly
/// - `cp437_grid` points to a valid [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
#[no_mangle]
pub unsafe extern "C" fn sp_cp437_grid_unsafe_data_ref(
cp437_grid: *mut SPCp437Grid,

18
crates/servicepoint_binding_c/src/packet.rs
View file

@ -1,4 +1,4 @@
//! C functions for interacting with `SPPacket`s
//! C functions for interacting with [SPPacket]s
//!
//! prefix `sp_packet_`
@ -9,7 +9,7 @@ use crate::SPCommand;
/// The raw packet
pub struct SPPacket(pub(crate) servicepoint::packet::Packet);
/// Turns a [SPCommand] into a `SPPacket`.
/// Turns a [SPCommand] into a [SPPacket].
/// The [SPCommand] gets consumed.
///
/// Will never return NULL.
@ -20,7 +20,7 @@ pub struct SPPacket(pub(crate) servicepoint::packet::Packet);
///
/// - [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
/// - the returned [SPPacket] instance is freed in some way, either by using a consuming function or
/// by explicitly calling `sp_packet_free`.
#[no_mangle]
pub unsafe extern "C" fn sp_packet_from_command(
@ -31,7 +31,7 @@ pub unsafe extern "C" fn sp_packet_from_command(
Box::into_raw(Box::new(packet))
}
/// Tries to load a `SPPacket` from the passed array with the specified length.
/// 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
///
@ -41,7 +41,7 @@ pub unsafe extern "C" fn sp_packet_from_command(
///
/// - `data` points to a valid memory region of at least `length` bytes
/// - `data` is not written to concurrently
/// - the returned `SPPacket` instance is freed in some way, either by using a consuming function or
/// - the returned [SPPacket] instance is freed in some way, either by using a consuming function or
/// by explicitly calling `sp_packet_free`.
#[no_mangle]
pub unsafe extern "C" fn sp_packet_try_load(
@ -55,7 +55,7 @@ pub unsafe extern "C" fn sp_packet_try_load(
}
}
/// Clones a `SPPacket`.
/// Clones a [SPPacket].
///
/// Will never return NULL.
///
@ -63,7 +63,7 @@ pub unsafe extern "C" fn sp_packet_try_load(
///
/// The caller has to make sure that:
///
/// - `packet` points to a valid `SPPacket`
/// - `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`.
@ -74,13 +74,13 @@ pub unsafe extern "C" fn sp_packet_clone(
Box::into_raw(Box::new(SPPacket((*packet).0.clone())))
}
/// Deallocates a `SPPacket`.
/// Deallocates a [SPPacket].
///
/// # Safety
///
/// The caller has to make sure that:
///
/// - `packet` points to a valid `SPPacket`
/// - `packet` points to a valid [SPPacket]
/// - `packet` is not used concurrently or after this call
#[no_mangle]
pub unsafe extern "C" fn sp_packet_free(packet: *mut SPPacket) {

46
crates/servicepoint_binding_c/src/pixel_grid.rs
View file

@ -1,4 +1,4 @@
//! C functions for interacting with `SPPixelGrid`s
//! C functions for interacting with [SPPixelGrid]s
//!
//! prefix `sp_pixel_grid_`
@ -18,14 +18,14 @@ use crate::byte_slice::SPByteSlice;
/// ```
pub struct SPPixelGrid(pub(crate) servicepoint::PixelGrid);
/// Creates a new `SPPixelGrid` with the specified dimensions.
/// Creates a new [SPPixelGrid] with the specified dimensions.
///
/// # Arguments
///
/// - `width`: size in pixels in x-direction
/// - `height`: size in pixels in y-direction
///
/// returns: `SPPixelGrid` initialized to all pixels off. Will never return NULL.
/// returns: [SPPixelGrid] initialized to all pixels off. Will never return NULL.
///
/// # Panics
///
@ -47,14 +47,14 @@ pub unsafe extern "C" fn sp_pixel_grid_new(
))))
}
/// Loads a `SPPixelGrid` with the specified dimensions from the provided data.
/// Loads a [SPPixelGrid] with the specified dimensions from the provided data.
///
/// # Arguments
///
/// - `width`: size in pixels in x-direction
/// - `height`: size in pixels in y-direction
///
/// returns: `SPPixelGrid` that contains a copy of the provided data. Will never return NULL.
/// returns: [SPPixelGrid] that contains a copy of the provided data. Will never return NULL.
///
/// # Panics
///
@ -81,7 +81,7 @@ pub unsafe extern "C" fn sp_pixel_grid_load(
))))
}
/// Clones a `SPPixelGrid`.
/// Clones a [SPPixelGrid].
///
/// Will never return NULL.
///
@ -89,7 +89,7 @@ pub unsafe extern "C" fn sp_pixel_grid_load(
///
/// The caller has to make sure that:
///
/// - `pixel_grid` points to a valid `SPPixelGrid`
/// - `pixel_grid` points to a valid [SPPixelGrid]
/// - `pixel_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_pixel_grid_free`.
@ -100,13 +100,13 @@ pub unsafe extern "C" fn sp_pixel_grid_clone(
Box::into_raw(Box::new(SPPixelGrid((*pixel_grid).0.clone())))
}
/// Deallocates a `SPPixelGrid`.
/// Deallocates a [SPPixelGrid].
///
/// # Safety
///
/// The caller has to make sure that:
///
/// - `pixel_grid` points to a valid `SPPixelGrid`
/// - `pixel_grid` points to a valid [SPPixelGrid]
/// - `pixel_grid` is not used concurrently or after pixel_grid call
/// - `pixel_grid` was not passed to another consuming function, e.g. to create a [SPCommand]
#[no_mangle]
@ -114,7 +114,7 @@ pub unsafe extern "C" fn sp_pixel_grid_free(pixel_grid: *mut SPPixelGrid) {
_ = Box::from_raw(pixel_grid);
}
/// Gets the current value at the specified position in the `SPPixelGrid`.
/// Gets the current value at the specified position in the [SPPixelGrid].
///
/// # Arguments
///
@ -129,7 +129,7 @@ pub unsafe extern "C" fn sp_pixel_grid_free(pixel_grid: *mut SPPixelGrid) {
///
/// The caller has to make sure that:
///
/// - `pixel_grid` points to a valid `SPPixelGrid`
/// - `pixel_grid` points to a valid [SPPixelGrid]
/// - `pixel_grid` is not written to concurrently
#[no_mangle]
pub unsafe extern "C" fn sp_pixel_grid_get(
@ -140,7 +140,7 @@ pub unsafe extern "C" fn sp_pixel_grid_get(
(*pixel_grid).0.get(x, y)
}
/// Sets the value of the specified position in the `SPPixelGrid`.
/// Sets the value of the specified position in the [SPPixelGrid].
///
/// # Arguments
///
@ -158,7 +158,7 @@ pub unsafe extern "C" fn sp_pixel_grid_get(
///
/// The caller has to make sure that:
///
/// - `pixel_grid` points to a valid `SPPixelGrid`
/// - `pixel_grid` points to a valid [SPPixelGrid]
/// - `pixel_grid` is not written to or read from concurrently
#[no_mangle]
pub unsafe extern "C" fn sp_pixel_grid_set(
@ -170,7 +170,7 @@ pub unsafe extern "C" fn sp_pixel_grid_set(
(*pixel_grid).0.set(x, y, value);
}
/// Sets the state of all pixels in the `SPPixelGrid`.
/// Sets the state of all pixels in the [SPPixelGrid].
///
/// # Arguments
///
@ -181,7 +181,7 @@ pub unsafe extern "C" fn sp_pixel_grid_set(
///
/// The caller has to make sure that:
///
/// - `pixel_grid` points to a valid `SPPixelGrid`
/// - `pixel_grid` points to a valid [SPPixelGrid]
/// - `pixel_grid` is not written to or read from concurrently
#[no_mangle]
pub unsafe extern "C" fn sp_pixel_grid_fill(
@ -191,7 +191,7 @@ pub unsafe extern "C" fn sp_pixel_grid_fill(
(*pixel_grid).0.fill(value);
}
/// Gets the width in pixels of the `SPPixelGrid` instance.
/// Gets the width in pixels of the [SPPixelGrid] instance.
///
/// # Arguments
///
@ -201,7 +201,7 @@ pub unsafe extern "C" fn sp_pixel_grid_fill(
///
/// The caller has to make sure that:
///
/// - `pixel_grid` points to a valid `SPPixelGrid`
/// - `pixel_grid` points to a valid [SPPixelGrid]
#[no_mangle]
pub unsafe extern "C" fn sp_pixel_grid_width(
pixel_grid: *const SPPixelGrid,
@ -209,7 +209,7 @@ pub unsafe extern "C" fn sp_pixel_grid_width(
(*pixel_grid).0.width()
}
/// Gets the height in pixels of the `SPPixelGrid` instance.
/// Gets the height in pixels of the [SPPixelGrid] instance.
///
/// # Arguments
///
@ -219,7 +219,7 @@ pub unsafe extern "C" fn sp_pixel_grid_width(
///
/// The caller has to make sure that:
///
/// - `pixel_grid` points to a valid `SPPixelGrid`
/// - `pixel_grid` points to a valid [SPPixelGrid]
#[no_mangle]
pub unsafe extern "C" fn sp_pixel_grid_height(
pixel_grid: *const SPPixelGrid,
@ -227,15 +227,15 @@ pub unsafe extern "C" fn sp_pixel_grid_height(
(*pixel_grid).0.height()
}
/// Gets an unsafe reference to the data of the `SPPixelGrid` instance.
/// Gets an unsafe reference to the data of the [SPPixelGrid] instance.
///
/// ## Safety
///
/// The caller has to make sure that:
///
/// - `pixel_grid` points to a valid `SPPixelGrid`
/// - the returned memory range is never accessed after the passed `SPPixelGrid` has been freed
/// - the returned memory range is never accessed concurrently, either via the `SPPixelGrid` or directly
/// - `pixel_grid` points to a valid [SPPixelGrid]
/// - the returned memory range is never accessed after the passed [SPPixelGrid] has been freed
/// - the returned memory range is never accessed concurrently, either via the [SPPixelGrid] or directly
#[no_mangle]
pub unsafe extern "C" fn sp_pixel_grid_unsafe_data_ref(
pixel_grid: *mut SPPixelGrid,