include/servicepoint.h

@@ -266,6 +266,31 @@ typedef struct {
  */
 typedef ValueGrid_Brightness BrightnessGrid;
 
+/**
+ * A display brightness value, checked for correct value range
+ *
+ * # Examples
+ *
+ * ```
+ * # use servicepoint::*;
+ * let b = Brightness::MAX;
+ * let val: u8 = b.into();
+ *
+ * let b = Brightness::try_from(7).unwrap();
+ * # let connection = FakeConnection;
+ * let result = connection.send(GlobalBrightnessCommand::from(b));
+ * ```
+ */
+typedef uint8_t Brightness;
+/**
+ * highest possible brightness value, 11
+ */
+#define Brightness_MAX 11
+/**
+ * lowest possible brightness value, 0
+ */
+#define Brightness_MIN 0
+
 /**
  * A grid containing UTF-8 characters.
  *
@@ -819,7 +844,7 @@ BrightnessGrid */*notnull*/ sp_brightness_grid_clone(BrightnessGrid */*notnull*/
  * - `brightness_grid` is not written to or read from concurrently
  */
 void sp_brightness_grid_fill(BrightnessGrid */*notnull*/ brightness_grid,
-                             uint8_t value);
+                             Brightness value);
 
 /**
  * Deallocates a [SPBrightnessGrid].
@@ -866,7 +891,7 @@ void sp_brightness_grid_free(BrightnessGrid */*notnull*/ brightness_grid);
  * - `brightness_grid` points to a valid [SPBrightnessGrid]
  * - `brightness_grid` is not written to concurrently
  */
-uint8_t sp_brightness_grid_get(BrightnessGrid */*notnull*/ brightness_grid,
+Brightness sp_brightness_grid_get(BrightnessGrid */*notnull*/ brightness_grid,
                                   size_t x,
                                   size_t y);
 
@@ -956,7 +981,7 @@ BrightnessGrid */*notnull*/ sp_brightness_grid_new(size_t width,
 void sp_brightness_grid_set(BrightnessGrid */*notnull*/ brightness_grid,
                             size_t x,
                             size_t y,
-                            uint8_t value);
+                            Brightness value);
 
 /**
  * Gets an unsafe reference to the data of the [SPBrightnessGrid] instance.
@@ -1358,7 +1383,7 @@ Command *sp_command_bitmap_linear_xor(size_t offset,
  * - 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);
+Command */*notnull*/ sp_command_brightness(Brightness brightness);
 
 /**
  * Set the brightness of individual tiles in a rectangular area of the display.

src/brightness_grid.rs

@@ -20,18 +20,10 @@
 //! ```
 
 use crate::SPByteSlice;
-use servicepoint::{BrightnessGrid, DataRef, Grid};
-use std::convert::Into;
+use servicepoint::{Brightness, BrightnessGrid, DataRef, Grid};
 use std::mem::transmute;
 use std::ptr::NonNull;
 
-/// see [servicepoint::Brightness::MIN]
-pub const SP_BRIGHTNESS_MIN: u8 = 0;
-/// see [servicepoint::Brightness::MAX]
-pub const SP_BRIGHTNESS_MAX: u8 = 11;
-/// Count of possible brightness values
-pub const SP_BRIGHTNESS_LEVELS: u8 = 12;
-
 /// Creates a new [SPBrightnessGrid] with the specified dimensions.
 ///
 /// returns: [SPBrightnessGrid] initialized to 0. Will never return NULL.
@@ -165,8 +157,8 @@ pub unsafe extern "C" fn sp_brightness_grid_get(
     brightness_grid: NonNull<BrightnessGrid>,
     x: usize,
     y: usize,
-) -> u8 {
-    unsafe { brightness_grid.as_ref().get(x, y) }.into()
+) -> Brightness {
+    unsafe { brightness_grid.as_ref().get(x, y) }
 }
 
 /// Sets the value of the specified position in the [SPBrightnessGrid].
@@ -196,11 +188,9 @@ pub unsafe extern "C" fn sp_brightness_grid_set(
     brightness_grid: NonNull<BrightnessGrid>,
     x: usize,
     y: usize,
-    value: u8,
+    value: Brightness,
 ) {
-    let brightness = servicepoint::Brightness::try_from(value)
-        .expect("invalid brightness value");
-    unsafe { (*brightness_grid.as_ptr()).set(x, y, brightness) };
+    unsafe { (*brightness_grid.as_ptr()).set(x, y, value) };
 }
 
 /// Sets the value of all cells in the [SPBrightnessGrid].
@@ -224,11 +214,9 @@ pub unsafe extern "C" fn sp_brightness_grid_set(
 #[no_mangle]
 pub unsafe extern "C" fn sp_brightness_grid_fill(
     brightness_grid: NonNull<BrightnessGrid>,
-    value: u8,
+    value: Brightness,
 ) {
-    let brightness = servicepoint::Brightness::try_from(value)
-        .expect("invalid brightness value");
-    unsafe { (*brightness_grid.as_ptr()).fill(brightness) };
+    unsafe { (*brightness_grid.as_ptr()).fill(value) };
 }
 
 /// Gets the width of the [SPBrightnessGrid] instance.
@@ -302,8 +290,9 @@ pub unsafe extern "C" fn sp_brightness_grid_height(
 pub unsafe extern "C" fn sp_brightness_grid_unsafe_data_ref(
     brightness_grid: NonNull<BrightnessGrid>,
 ) -> SPByteSlice {
-    assert_eq!(size_of::<servicepoint::Brightness>(), 1);
+    //noinspection RsAssertEqual
+    const _: () = assert!(size_of::<Brightness>() == 1);
+
     let data = unsafe { (*brightness_grid.as_ptr()).data_ref_mut() };
-    // this assumes more about the memory layout than rust guarantees. yikes!
     unsafe { SPByteSlice::from_slice(transmute(data)) }
 }

src/command.rs

@@ -3,10 +3,7 @@
 //! prefix `sp_command_`
 
 use crate::SPBitVec;
-use servicepoint::{
-    BinaryOperation, Bitmap, BrightnessGrid, CharGrid, CompressionCode,
-    Cp437Grid, GlobalBrightnessCommand, Packet, TypedCommand,
-};
+use servicepoint::{BinaryOperation, Bitmap, Brightness, BrightnessGrid, CharGrid, CompressionCode, Cp437Grid, GlobalBrightnessCommand, Packet, TypedCommand};
 use std::ptr::NonNull;
 
 /// A low-level display command.
@@ -152,10 +149,8 @@ pub unsafe extern "C" fn sp_command_fade_out() -> NonNull<TypedCommand> {
 ///   by explicitly calling `sp_command_free`.
 #[no_mangle]
 pub unsafe extern "C" fn sp_command_brightness(
-    brightness: u8,
+    brightness: Brightness,
 ) -> 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))
 }