diff --git a/crates/servicepoint_binding_c/src/command.rs b/crates/servicepoint_binding_c/src/command.rs index 4e5b45b..d273437 100644 --- a/crates/servicepoint_binding_c/src/command.rs +++ b/crates/servicepoint_binding_c/src/command.rs @@ -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. /// -///
-/// 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. -///
+/// 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); } diff --git a/crates/servicepoint_binding_c/src/connection.rs b/crates/servicepoint_binding_c/src/connection.rs index ee630a9..95940f8 100644 --- a/crates/servicepoint_binding_c/src/connection.rs +++ b/crates/servicepoint_binding_c/src/connection.rs @@ -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) { diff --git a/crates/servicepoint_binding_c/src/cp437_grid.rs b/crates/servicepoint_binding_c/src/cp437_grid.rs index 38d4af0..98b1927 100644 --- a/crates/servicepoint_binding_c/src/cp437_grid.rs +++ b/crates/servicepoint_binding_c/src/cp437_grid.rs @@ -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, diff --git a/crates/servicepoint_binding_c/src/packet.rs b/crates/servicepoint_binding_c/src/packet.rs index d8a0302..ac27747 100644 --- a/crates/servicepoint_binding_c/src/packet.rs +++ b/crates/servicepoint_binding_c/src/packet.rs @@ -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) { diff --git a/crates/servicepoint_binding_c/src/pixel_grid.rs b/crates/servicepoint_binding_c/src/pixel_grid.rs index e032d50..6592ae5 100644 --- a/crates/servicepoint_binding_c/src/pixel_grid.rs +++ b/crates/servicepoint_binding_c/src/pixel_grid.rs @@ -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,