Merge branch 'master' of github.com:dankamongmen/notcurses

rust/src/bindings.rs

@@ -659,6 +659,8 @@ pub use ffi::{
     notcurses_lex_blitter,
     notcurses_lex_margins,
     notcurses_lex_scalemode,
+    notcurses_linesigs_disable,
+    notcurses_linesigs_enable,
     notcurses_mouse_disable,
     notcurses_mouse_enable,
     notcurses_palette_size,

rust/src/cells/methods.rs

@@ -16,7 +16,7 @@ impl NcCell {
         channels: NcChannelPair,
     ) -> Self {
         NcCell {
-            gcluster: ch as u32,
+            gcluster: (ch as u32).to_le(),
             gcluster_backstop: 0 as NcEgcBackstop,
             width,
             stylemask,

rust/src/notcurses/methods.rs

@@ -131,6 +131,18 @@ impl Notcurses {
         crate::notcurses_getc_nblocking(self, input)
     }
 
+    /// Disables signals originating from the terminal's line discipline, i.e.
+    /// SIGINT (^C), SIGQUIT (^), and SIGTSTP (^Z). They are enabled by default.
+    pub fn linesigs_disable(&mut self) -> NcResult {
+        unsafe { crate::notcurses_linesigs_disable(self) }
+    }
+
+    /// Restores signals originating from the terminal's line discipline, i.e.
+    /// SIGINT (^C), SIGQUIT (^), and SIGTSTP (^Z), if disabled.
+    pub fn linesigs_enable(&mut self) -> NcResult {
+        unsafe { crate::notcurses_linesigs_enable(self) }
+    }
+
     ///
     pub fn render(&mut self) -> NcResult {
         unsafe { crate::notcurses_render(self) }

rust/src/notcurses/mod.rs

@@ -1,8 +1,9 @@
 //! `Notcurses`
 
-// functions already exported by bindgen : 39
+// functions already exported by bindgen : 41
 // ------------------------------------------
-// (#) unit tests: 10 / 29
+// (#) test: 10
+// (W) wrap:  8
 // ------------------------------------------
 //   notcurses_at_yx
 //   notcurses_bottom
@@ -17,25 +18,27 @@
 //   notcurses_cursor_enable
 // # notcurses_debug
 // # notcurses_drop_planes
-//   notcurses_getc
-// # notcurses_init
+//W  notcurses_getc
+//W# notcurses_init
 //   notcurses_inputready_fd
 //   notcurses_lex_blitter
 //   notcurses_lex_margins
 //   notcurses_lex_scalemode
+//W  notcurses_linesigs_disable
+//W  notcurses_linesigs_enable
 //   notcurses_mouse_disable
 //   notcurses_mouse_enable
 //   notcurses_palette_size
 //   notcurses_refresh
-//   notcurses_render
+//W  notcurses_render
 //   notcurses_render_to_buffer
 //   notcurses_render_to_file
 //   notcurses_stats
 //   notcurses_stats_alloc
 //   notcurses_stats_reset
-//   notcurses_stdplane
-//   notcurses_stdplane_const
-// # notcurses_stop
+//W  notcurses_stdplane
+//W  notcurses_stdplane_const
+//W# notcurses_stop
 //   notcurses_str_blitter
 //   notcurses_str_scalemode
 //   notcurses_supported_styles
@@ -46,12 +49,13 @@
 //
 // functions manually reimplemented: 6
 // -----------------------------------------
-// (+) implement : 6 / 0
-// (#) unit tests: 0 / 6
+// (+) done: 6 / 0
+// (#) test: 0
+// (W) wrap: 2
 // -----------------------------------------
 // # notcurses_align
-// + notcurses_getc_blocking
-// + notcurses_getc_nblock
+//W+ notcurses_getc_blocking
+//W+ notcurses_getc_nblock
 // + notcurses_stddim_yx
 // + notcurses_stddim_yx_const
 // + notcurses_term_dim_yx

rust/src/pixel.rs

@@ -9,89 +9,178 @@
 //
 // functions manually reimplemented: 10
 // ------------------------------------------
-// (+) implement : 10 /  0
-// (#) unit tests:  0 / 10
+// (+) done: 10 /  0
+// (#) test:  0
+// (W) wrap: 10
 // ------------------------------------------
-// + ncpixel
-// + ncpixel_a
-// + ncpixel_b
-// + ncpixel_g
-// + ncpixel_r
-// + ncpixel_set_a
-// + ncpixel_set_b
-// + ncpixel_set_g
-// + ncpixel_set_r
-// + ncpixel_set_rgb
+//W+ ncpixel
+//W+ ncpixel_a
+//W+ ncpixel_b
+//W+ ncpixel_g
+//W+ ncpixel_r
+//W+ ncpixel_set_a
+//W+ ncpixel_set_b
+//W+ ncpixel_set_g
+//W+ ncpixel_set_r
+//W+ ncpixel_set_rgb8
 
 use crate::NcColor;
 
 // NcPixel (RGBA)
-/// 32 bits broken into RGB + 8-bit alpha
-///
-/// NcPixel has 8 bits of alpha,  more or less linear, contributing
-/// directly to the usual alpha blending equation.
-///
-/// We map the 8 bits of alpha to 2 bits of alpha via a level function:
-/// https://nick-black.com/dankwiki/index.php?title=Notcurses#Transparency.2FContrasting
+/// An ABGR pixel.
 ///
 /// ## Diagram
 ///
 /// ```txt
 /// AAAAAAAA GGGGGGGG BBBBBBBB RRRRRRRR
 /// ```
+///
 /// `type in C: ncpixel (uint32_t)`
 ///
-// NOTE: the order of the colors is different than in NcChannel.
+/// NcPixel has 8 bits of alpha,  more or less linear, contributing
+/// directly to the usual alpha blending equation.
+///
+/// We map the 8 bits of alpha to 2 bits of alpha via a [level
+/// function](https://nick-black.com/dankwiki/index.php?title=Notcurses#Transparency.2FContrasting)
+///
+/// The ncpixel API facilitates direct management of the pixels within an
+/// ncvisual (ncvisuals keep a backing store of 32-bit RGBA pixels, and render
+/// them down to terminal graphics in ncvisual_render()).
+///
+/// Per libav, we "store as BGRA on little-endian, and ARGB on big-endian".
+/// This is an RGBA *byte-order* scheme. libav emits bytes, not words. Those
+/// bytes are R-G-B-A. When read as words, on little endian this will be ABGR,
+/// and on big-endian this will be RGBA. force everything to LE ABGR.
+///
 pub type NcPixel = u32;
 
-/// Get an RGB pixel from RGB values
-pub fn ncpixel(r: NcColor, g: NcColor, b: NcColor) -> NcPixel {
-    0xff000000 as NcPixel | r as NcPixel | (b as NcPixel) << 8 | (g as NcPixel) << 16
+/// Constructs a libav-compatible ABGR pixel from [NcColor] RGB components.
+#[inline]
+pub const fn ncpixel(red: NcColor, green: NcColor, blue: NcColor) -> NcPixel {
+    0xff000000 as NcPixel | red as NcPixel | (blue as NcPixel) << 8 | (green as NcPixel) << 16
 }
 
-/// Extract the 8-bit alpha component from a pixel
-pub fn ncpixel_a(pixel: NcPixel) -> NcColor {
-    ((pixel & 0xff000000) >> 24) as NcColor
+/// Extracts the 8-bit alpha component from an ABGR pixel.
+#[inline]
+pub const fn ncpixel_a(pixel: NcPixel) -> NcColor {
+    ((pixel.to_le() & 0xff000000) >> 24) as NcColor
 }
 
-/// Extract the 8 bit green component from a pixel
-pub fn ncpixel_g(pixel: NcPixel) -> NcColor {
-    ((pixel & 0x00ff0000) >> 16) as NcColor
+/// Extracts the 8 bit blue component from an ABGR pixel.
+#[inline]
+pub const fn ncpixel_b(pixel: NcPixel) -> NcColor {
+    ((pixel.to_le() & 0x00ff0000) >> 16) as NcColor
 }
 
-/// Extract the 8 bit blue component from a pixel
-pub fn ncpixel_b(pixel: NcPixel) -> NcColor {
-    ((pixel & 0x0000ff00) >> 8) as NcColor
+/// Extracts the 8 bit green component from an ABGR pixel.
+#[inline]
+pub const fn ncpixel_g(pixel: NcPixel) -> NcColor {
+    ((pixel.to_le() & 0x0000ff00) >> 8) as NcColor
 }
 
-/// Extract the 8 bit red component from a pixel
-pub fn ncpixel_r(pixel: NcPixel) -> NcColor {
-    (pixel & 0x000000ff) as NcColor
+/// Extracts the 8 bit red component from an ABGR pixel.
+#[inline]
+pub const fn ncpixel_r(pixel: NcPixel) -> NcColor {
+    (pixel.to_le() & 0x000000ff) as NcColor
 }
 
-/// Set the 8-bit alpha component of a pixel
+/// Sets the 8-bit alpha component of an ABGR pixel.
+#[inline]
 pub fn ncpixel_set_a(pixel: &mut NcPixel, alpha: NcColor) {
-    *pixel = (*pixel & 0x00ffffff) | ((alpha as NcPixel) << 24);
+    *pixel = (((*pixel).to_le() & 0x00ffffff) | ((alpha as NcPixel) << 24)).to_le();
 }
 
-/// Set the 8-bit green component of a pixel
-pub fn ncpixel_set_g(pixel: &mut NcPixel, green: NcColor) {
-    *pixel = (*pixel & 0xff00ffff) | ((green as NcPixel) << 16);
+/// Sets the 8-bit blue component of an ABGR pixel.
+#[inline]
+pub fn ncpixel_set_b(pixel: &mut NcPixel, blue: NcColor) {
+    *pixel = (((*pixel).to_le() & 0xffff00ff) | ((blue as NcPixel) << 8)).to_le();
 }
 
-/// Set the 8-bit blue component of a pixel
-pub fn ncpixel_set_b(pixel: &mut NcPixel, blue: NcColor) {
-    *pixel = (*pixel & 0xffff00ff) | ((blue as NcPixel) << 8);
+/// Sets the 8-bit green component of an ABGR pixel.
+#[inline]
+pub fn ncpixel_set_g(pixel: &mut NcPixel, green: NcColor) {
+    *pixel = (((*pixel).to_le() & 0xff00ffff) | ((green as NcPixel) << 16)).to_le();
 }
 
-/// Set the 8-bit red component of a pixel
+/// Sets the 8-bit red component of an ABGR pixel.
+#[inline]
 pub fn ncpixel_set_r(pixel: &mut NcPixel, red: NcColor) {
-    *pixel = (*pixel & 0xffffff00) | red as NcPixel;
+    *pixel = (((*pixel).to_le() & 0xffffff00) | red as NcPixel).to_le();
 }
 
-/// set the RGB values of an RGB pixel
-pub fn ncpixel_set_rgb(pixel: &mut NcPixel, red: NcColor, green: NcColor, blue: NcColor) {
+/// Sets the [NcColor] RGB components of an ABGR pixel.
+#[inline]
+pub fn ncpixel_set_rgb8(pixel: &mut NcPixel, red: NcColor, green: NcColor, blue: NcColor) {
     ncpixel_set_r(pixel, red);
     ncpixel_set_g(pixel, green);
     ncpixel_set_b(pixel, blue);
 }
+
+/// Enables the [NcPixel] methods.
+//
+// NOTE: waiting for: https://github.com/rust-lang/rust/issues/56546
+// to move doc comments to the trait and appear unhidden at the implementation.
+pub trait NcPixelMethods {
+    fn new(r: NcColor, g: NcColor, b: NcColor) -> NcPixel;
+    fn a(self) -> NcColor;
+    fn b(self) -> NcColor;
+    fn g(self) -> NcColor;
+    fn r(self) -> NcColor;
+    fn set_a(&mut self, green: NcColor);
+    fn set_b(&mut self, blue: NcColor);
+    fn set_g(&mut self, green: NcColor);
+    fn set_r(&mut self, red: NcColor);
+    fn set_rgb8(&mut self, red: NcColor, green: NcColor, blue: NcColor);
+}
+
+impl NcPixelMethods for NcPixel {
+    /// Constructs a libav-compatible ABGR pixel from [NcColor] RGB components.
+    fn new(red: NcColor, green: NcColor, blue: NcColor) -> NcPixel {
+        ncpixel(red, green, blue)
+    }
+
+    /// Extracts the 8-bit alpha component from an ABGR pixel.
+    fn a(self) -> NcColor {
+        ncpixel_a(self)
+    }
+
+    /// Extracts the 8 bit blue component from an ABGR pixel.
+    fn b(self) -> NcColor {
+        ncpixel_b(self)
+    }
+
+    /// Extracts the 8 bit green component from an ABGR pixel.
+    fn g(self) -> NcColor {
+        ncpixel_g(self)
+    }
+
+    /// Extracts the 8 bit red component from an ABGR pixel.
+    fn r(self) -> NcColor {
+        ncpixel_r(self)
+    }
+
+    /// Sets the 8-bit alpha component of an ABGR pixel.
+    fn set_a(&mut self, alpha: NcColor) {
+        ncpixel_set_a(self, alpha)
+    }
+
+    /// Sets the 8-bit green component of an ABGR pixel.
+    fn set_g(&mut self, green: NcColor) {
+        ncpixel_set_b(self, green)
+    }
+
+    /// Sets the 8-bit blue component of an ABGR pixel.
+    fn set_b(&mut self, blue: NcColor) {
+        ncpixel_set_b(self, blue)
+    }
+
+    /// Sets the 8-bit red component of an ABGR pixel.
+    fn set_r(&mut self, red: NcColor) {
+        ncpixel_set_r(self, red)
+    }
+
+    /// Sets the [NcColor] RGB components of an ABGR pixel.
+    fn set_rgb8(&mut self, red: NcColor, green: NcColor, blue: NcColor) {
+        ncpixel_set_rgb8(self, red, green, blue);
+    }
+}

rust/src/plane/mod.rs

@@ -218,7 +218,6 @@ pub use reimplemented::*;
 /// - [`NcColor`, `NcRgb` & default color](#ncplane-methods-nccolor-ncrgb--default-color)
 /// - [`NcStyleMask` & `NcPaletteIndex`](#ncplane-methods-ncstylemask--paletteindex)
 /// - [`NcCell` & `NcEgc`](#ncplane-methods-nccell--ncegc)
-/// - [writing](#ncplane-methods-writing)
 /// - [cursor](#ncplane-methods-cursor)
 /// - [`NcPlane` & `Notcurses`](#ncplane-methods-ncplane--notcurses)
 /// - [boxes & perimeters](#ncplane-methods-boxes--perimeters)