From 7d51756a12c084d3d40d318adfdc976e2d2bb820 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?joseLu=C3=ADs?= <joseluis@andamira.net>
Date: Thu, 8 Apr 2021 13:11:06 +0200
Subject: [PATCH] rust: new poc-planebase example; doc improvements

- improve NcVisual.from_rgba documentation.
- fix Notcurses.term_dim_yx documentation.
- new example `poc-planebase` to help find the bug.
- improve full-capabilities example a little.
---
 rust/examples/full-capabilities.rs |  5 ++---
 rust/examples/poc-planebase.rs     | 29 +++++++++++++++++++++++++++++
 rust/src/notcurses/methods.rs      |  2 +-
 rust/src/visual.rs                 | 16 ++++++----------
 4 files changed, 38 insertions(+), 14 deletions(-)
 create mode 100644 rust/examples/poc-planebase.rs

diff --git a/rust/examples/full-capabilities.rs b/rust/examples/full-capabilities.rs
index 52c8a6cc1..7468c33f9 100644
--- a/rust/examples/full-capabilities.rs
+++ b/rust/examples/full-capabilities.rs
@@ -1,7 +1,7 @@
 use libnotcurses_sys::*;
 
 fn main() -> NcResult<()> {
-    let mut nc = FullMode::new()?;
+    let mut nc = FullMode::without_altscreen()?;
 
     let (t_rows, t_cols) = nc.term_dim_yx();
     println!("Terminal rows={0}, cols={1}", t_rows, t_cols);
@@ -24,7 +24,6 @@ Palette size: {6:?}
         nc.palette_size(),
     );
 
-    println!("Done. Waiting for 10 seconds. . .");
-    rsleep![&mut nc, 10];
+    rsleep![&mut nc, 1];
     Ok(())
 }
diff --git a/rust/examples/poc-planebase.rs b/rust/examples/poc-planebase.rs
new file mode 100644
index 000000000..a305561da
--- /dev/null
+++ b/rust/examples/poc-planebase.rs
@@ -0,0 +1,29 @@
+use libnotcurses_sys::*;
+
+fn main() -> NcResult<()> {
+    let mut nc = FullMode::with_debug(NCLOGLEVEL_INFO, 0)?;
+    
+    let (dimy, dimx) = nc.term_dim_yx();
+    let stdn = nc.stdplane();
+
+    let p1 = NcPlane::new_bound(stdn, 0, 0, dimy, dimx)?;
+
+    let mut channels = NcChannelPair::with_rgb8(0, 0xcc, 0, 0, 0x88, 0);
+    p1.set_base(" ", 0, channels)?;
+
+    let p2 = NcPlane::new_bound(stdn, 0, 0, dimy/3, dimx/3)?;
+    p2.set_base(" ", 0, channels.set_bg_rgb8(0x88, 0, 0))?;
+
+    let p3 = NcPlane::new_bound(stdn, 0, 0, dimy/9, dimx/9)?;
+    p3.set_base(" ", 0, channels.set_bg_rgb8(0, 0, 0x88))?;
+
+    rsleep![&mut nc, 1];
+
+    p3.move_yx((dimy - dimy/9) as i32, (dimx - dimx/9) as i32)?;
+    rsleep![&mut nc, 1];
+
+    p2.move_yx((dimy/2) as i32, (dimx/2) as i32)?;
+    rsleep![&mut nc, 1];
+
+    Ok(())
+}
diff --git a/rust/src/notcurses/methods.rs b/rust/src/notcurses/methods.rs
index a52e57ce0..b19620b7c 100644
--- a/rust/src/notcurses/methods.rs
+++ b/rust/src/notcurses/methods.rs
@@ -652,7 +652,7 @@ impl Notcurses {
 
     /// Returns our current idea of the terminal dimensions in rows and cols.
     ///
-    /// *C style function: [notcurses_supported_styles()][crate::notcurses_supported_styles].*
+    /// *C style function: [notcurses_term_dim_yx()][crate::notcurses_term_dim_yx].*
     pub fn term_dim_yx(&self) -> (NcDim, NcDim) {
         crate::notcurses_term_dim_yx(self)
     }
diff --git a/rust/src/visual.rs b/rust/src/visual.rs
index f1015c197..7ff97afea 100644
--- a/rust/src/visual.rs
+++ b/rust/src/visual.rs
@@ -163,9 +163,6 @@ impl NcVisualOptions {
 /// # NcVisual Constructors & destructors
 impl NcVisual {
     /// Like [ncvisual_from_rgba], but 'bgra' is arranged as BGRA.
-    // pub fn ncvisual_from_bgra<'a>(
-    // ) -> NcResult<&'a mut NcVisual> {
-    // }
     ///
     /// *C style function: [ncvisual_from_bgra()][crate::ncvisual_from_bgra].*
     pub fn from_bgra<'a>(
@@ -233,13 +230,12 @@ impl NcVisual {
     /// Prepares an NcVisual, and its underlying NcPlane, based off RGBA content
     /// in memory at `rgba`.
     ///
-    /// `rgba` must be a flat array of 32-bit 8bpc RGBA pixels.
-    //
-    // FIXME:
-    // These must be arranged in 'rowstride' lines, where the first 'cols' * 4b are actual data.
-    // There must be 'rows' lines. The total size of 'rgba' must thus be at least
-    // (rows * rowstride) bytes, of which (rows * cols * 4) bytes are actual data.
-    // Resulting planes are ceil('rows' / 2) x 'cols'.
+    /// `rgba` is laid out as `rows` lines, each of which is `rowstride` bytes in length.
+    /// Each line has `cols` 32-bit 8bpc RGBA pixels followed by possible padding
+    /// (there will be rowstride - cols * 4 bytes of padding).
+    ///
+    /// The total size of `rgba` is thus (rows * rowstride) bytes, of which
+    /// (rows * cols * 4) bytes are actual non-padding data.
     ///
     /// *C style function: [ncvisual_from_rgba()][crate::ncvisual_from_rgba].*
     pub fn from_rgba<'a>(