[rust] add NCVISUAL_OPTION_CHILDPLANE

- update docs

rust/src/bindings.rs

@@ -678,6 +678,7 @@ pub use ffi::{
 // // constants
 // NCVISUAL_OPTION_ADDALPHA,
 // NCVISUAL_OPTION_BLEND,
+// NCVISUAL_OPTION_CHILDPLANE
 // NCVISUAL_OPTION_HORALIGNED
 // NCVISUAL_OPTION_NODEGRADE,
 // NCVISUAL_OPTION_VERALIGNED

rust/src/visual/methods.rs

@@ -26,7 +26,11 @@ impl NcVisualOptions {
     // y is an ncalign_e if NCVISUAL_OPTION_VERALIGNED is provided.
     // x is an ncalign_e value if NCVISUAL_OPTION_HORALIGNED is provided.
 
-    /// Specify an existing plane
+    /// Specify an existing plane.
+    ///
+    /// If [`NCVISUAL_OPTION_CHILDPLANE`][crate::NCVISUAL_OPTION_CHILDPLANE] is
+    /// used in `flags` then the `plane` is interpreted as the parent [`NcPlane`]
+    /// of the new plane created for this [`NcVisual`].
     pub fn with_plane(
         plane: &mut NcPlane,
         scale: NcScale,

rust/src/visual/mod.rs

@@ -68,7 +68,9 @@ pub type NcVisual = crate::bindings::ffi::ncvisual;
 /// Options struct for [`NcVisual`]
 ///
 /// If a plane is not provided, one will be created, having the exact size
-/// necessary to display the visual.
+/// necessary to display the visual (this might be smaller or larger than
+/// the rendering area). if NCVISUAL_OPTION_CHILDPLANE is provided, this
+/// will be interpreted as the parent.
 ///
 /// A subregion of the visual can be rendered using `begx`, `begy`, `lenx`, and `leny`.
 pub type NcVisualOptions = crate::bindings::ffi::ncvisual_options;
@@ -110,6 +112,9 @@ pub const NCVISUAL_OPTION_ADDALPHA: u32 = crate::bindings::ffi::NCVISUAL_OPTION_
 /// Uses [`NCCELL_ALPHA_BLEND`][crate::NCCELL_ALPHA_BLEND] with visual.
 pub const NCVISUAL_OPTION_BLEND: u32 = crate::bindings::ffi::NCVISUAL_OPTION_BLEND;
 
+/// allows you to indicate that the n field of ncvisual_options refers not to the plane onto which you'd like to blit, but the parent of a new plane. A plane will be created using the other parameters in the ncvisual_options, as a child of this parent. This means things like, say, vertically centering a sprixel relative to the standard plane can be done in one step
+pub const NCVISUAL_OPTION_CHILDPLANE: u32 = crate::bindings::ffi::NCVISUAL_OPTION_CHILDPLANE;
+
 /// Fails rather than gracefully degrade. See [NcBlitter].
 pub const NCVISUAL_OPTION_NODEGRADE: u32 = crate::bindings::ffi::NCVISUAL_OPTION_NODEGRADE;