servicepoint-binding-c/src/command.rs

//! C functions for interacting with [SPCommand]s
//!
//! prefix `sp_command_`

use crate::SPBitVec;
use servicepoint::{
    BinaryOperation, Bitmap, BrightnessGrid, CharGrid, CompressionCode,
    Cp437Grid, GlobalBrightnessCommand, Packet, TypedCommand,
};
use std::ptr::NonNull;

/// 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`.
#[no_mangle]
pub unsafe extern "C" fn sp_command_try_from_packet(
    packet: NonNull<Packet>,
) -> *mut TypedCommand {
    let packet = *unsafe { Box::from_raw(packet.as_ptr()) };
    match servicepoint::TypedCommand::try_from(packet) {
        Err(_) => std::ptr::null_mut(),
        Ok(command) => Box::into_raw(Box::new(command)),
    }
}

/// 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`.
#[no_mangle]
pub unsafe extern "C" fn sp_command_clone(
    command: NonNull<TypedCommand>,
) -> NonNull<TypedCommand> {
    let result = Box::new(unsafe { command.as_ref().clone() });
    NonNull::from(Box::leak(result))
}

/// 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`.
#[no_mangle]
pub unsafe extern "C" fn sp_command_clear() -> NonNull<TypedCommand> {
    let result = Box::new(servicepoint::ClearCommand.into());
    NonNull::from(Box::leak(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 [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`.
#[no_mangle]
pub unsafe extern "C" fn sp_command_hard_reset() -> NonNull<TypedCommand> {
    let result = Box::new(servicepoint::HardResetCommand.into());
    NonNull::from(Box::leak(result))
}

/// 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`.
#[no_mangle]
pub unsafe extern "C" fn sp_command_fade_out() -> NonNull<TypedCommand> {
    let result = Box::new(servicepoint::FadeOutCommand.into());
    NonNull::from(Box::leak(result))
}

/// 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`.
#[no_mangle]
pub unsafe extern "C" fn sp_command_brightness(
    brightness: u8,
) -> NonNull<TypedCommand> {
    let brightness = servicepoint::Brightness::try_from(brightness)
        .expect("invalid brightness");
    let result = Box::new(GlobalBrightnessCommand::from(brightness).into());
    NonNull::from(Box::leak(result))
}

/// 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`.
#[no_mangle]
pub unsafe extern "C" fn sp_command_char_brightness(
    x: usize,
    y: usize,
    grid: NonNull<BrightnessGrid>,
) -> NonNull<TypedCommand> {
    let grid = unsafe { *Box::from_raw(grid.as_ptr()) };
    let result = Box::new(
        servicepoint::BrightnessGridCommand {
            origin: servicepoint::Origin::new(x, y),
            grid,
        }
        .into(),
    );
    NonNull::from(Box::leak(result))
}

/// 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`.
#[no_mangle]
pub unsafe extern "C" fn sp_command_bitmap_linear(
    offset: usize,
    bit_vec: NonNull<SPBitVec>,
    compression: CompressionCode,
) -> *mut TypedCommand {
    unsafe {
        sp_command_bitmap_linear_internal(
            offset,
            bit_vec,
            compression,
            BinaryOperation::Overwrite,
        )
    }
}

/// 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`.
#[no_mangle]
pub unsafe extern "C" fn sp_command_bitmap_linear_and(
    offset: usize,
    bit_vec: NonNull<SPBitVec>,
    compression: CompressionCode,
) -> *mut TypedCommand {
    unsafe {
        sp_command_bitmap_linear_internal(
            offset,
            bit_vec,
            compression,
            BinaryOperation::Xor,
        )
    }
}

/// 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`.
#[no_mangle]
pub unsafe extern "C" fn sp_command_bitmap_linear_or(
    offset: usize,
    bit_vec: NonNull<SPBitVec>,
    compression: CompressionCode,
) -> *mut TypedCommand {
    unsafe {
        sp_command_bitmap_linear_internal(
            offset,
            bit_vec,
            compression,
            BinaryOperation::Or,
        )
    }
}

/// 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`.
#[no_mangle]
pub unsafe extern "C" fn sp_command_bitmap_linear_xor(
    offset: usize,
    bit_vec: NonNull<SPBitVec>,
    compression: CompressionCode,
) -> *mut TypedCommand {
    unsafe {
        sp_command_bitmap_linear_internal(
            offset,
            bit_vec,
            compression,
            BinaryOperation::Xor,
        )
    }
}

#[inline]
unsafe fn sp_command_bitmap_linear_internal(
    offset: usize,
    bit_vec: NonNull<SPBitVec>,
    compression: CompressionCode,
    operation: BinaryOperation,
) -> *mut TypedCommand {
    let bit_vec = unsafe { *Box::from_raw(bit_vec.as_ptr()) };
    let compression = match compression.try_into() {
        Ok(compression) => compression,
        Err(_) => return std::ptr::null_mut(),
    };
    let command = servicepoint::BitVecCommand {
        offset,
        operation,
        bitvec: bit_vec.0,
        compression,
    }
    .into();
    Box::leak(Box::new(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`.
#[no_mangle]
pub unsafe extern "C" fn sp_command_cp437_data(
    x: usize,
    y: usize,
    grid: NonNull<Cp437Grid>,
) -> NonNull<TypedCommand> {
    let grid = *unsafe { Box::from_raw(grid.as_ptr()) };
    let result = Box::new(
        servicepoint::Cp437GridCommand {
            origin: servicepoint::Origin::new(x, y),
            grid,
        }
        .into(),
    );
    NonNull::from(Box::leak(result))
}

/// 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`.
#[no_mangle]
pub unsafe extern "C" fn sp_command_utf8_data(
    x: usize,
    y: usize,
    grid: NonNull<CharGrid>,
) -> NonNull<TypedCommand> {
    let grid = unsafe { *Box::from_raw(grid.as_ptr()) };
    let result = Box::new(
        servicepoint::CharGridCommand {
            origin: servicepoint::Origin::new(x, y),
            grid,
        }
        .into(),
    );
    NonNull::from(Box::leak(result))
}

/// 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`.
#[no_mangle]
pub unsafe extern "C" fn sp_command_bitmap_linear_win(
    x: usize,
    y: usize,
    bitmap: NonNull<Bitmap>,
    compression: CompressionCode,
) -> *mut TypedCommand {
    let bitmap = unsafe { *Box::from_raw(bitmap.as_ptr()) };
    let compression = match compression.try_into() {
        Ok(compression) => compression,
        Err(_) => return std::ptr::null_mut(),
    };
    let command = servicepoint::BitmapCommand {
        origin: servicepoint::Origin::new(x, y),
        bitmap,
        compression,
    }
    .into();
    Box::leak(Box::new(command))
}

/// 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]
#[no_mangle]
pub unsafe extern "C" fn sp_command_free(command: NonNull<TypedCommand>) {
    _ = unsafe { Box::from_raw(command.as_ptr()) };
}