From d07071246bea9a6574b446dab4fcd3f281c386e9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?joseLu=C3=ADs?= Date: Tue, 15 Jun 2021 19:20:16 +0200 Subject: [PATCH] [rust] update docs - add more NcPlane docs. - minor fixes. --- rust/src/notcurses/methods.rs | 2 +- rust/src/plane/mod.rs | 66 +++++++++++++++++++++++++---------- 2 files changed, 48 insertions(+), 20 deletions(-) diff --git a/rust/src/notcurses/methods.rs b/rust/src/notcurses/methods.rs index a8558c8db..43210bb74 100644 --- a/rust/src/notcurses/methods.rs +++ b/rust/src/notcurses/methods.rs @@ -587,7 +587,7 @@ impl Notcurses { } } - /// Allocates an ncstats object. + /// Allocates an [`NcStats`] object. /// /// Use this rather than allocating your own, since future versions of /// Notcurses might enlarge this structure. diff --git a/rust/src/plane/mod.rs b/rust/src/plane/mod.rs index f2ae74e8d..077b97f7b 100644 --- a/rust/src/plane/mod.rs +++ b/rust/src/plane/mod.rs @@ -194,36 +194,64 @@ pub use reimplemented::*; /// `type in C: ncplane (struct)` /// /// -/// # Piles +/// # About planes and piles /// -/// A single notcurses context is made up of one or more piles. +/// A given notcurses context is made up of one or more piles. /// -/// A pile is a set of one or more ncplanes, including the partial orderings -/// made up of their binding and z-axis pointers. +/// A pile is made up of [`NcPlane`]s, totally ordered on a z-axis. /// -/// A pile has a top and bottom ncplane (this might be a single plane), -/// and one or more root planes (planes which are bound to themselves). +/// You can't manage the piles directly, but only the `NcPlanes`. /// -/// Multiple threads can concurrently operate on distinct piles, even changing -/// one while rendering another. +/// A pile is destroyed when all its planes are destroyed or moved to other +/// piles. /// -/// Each plane is part of one and only one pile. By default, a plane is part of -/// the same pile containing that plane to which it is bound. +/// A pile has a top and bottom plane (this might be a single `NcPlane`), +/// and one or more root planes (`NcPlane`s which are bound to themselves). /// -/// If ncpile_create is used in the place of ncplane_create, the returned plane -/// becomes the root plane, top, and bottom of a new pile. As a root plane, +/// Multiple threads can concurrently operate on distinct piles, rendering or +/// mutating it, while another thread concurrently renders or mutates another. +/// +/// Each `NcPlane` is part of one and only one pile. By default, an `NcPlane` is +/// part of the same pile that contains the `NcPlane` to which it is bound. +/// +/// When an `NcPlane` is created without being bound to another `NcPlane`, then +/// it becomes the root plane, top, and bottom of a new pile. As a root plane, /// it is bound to itself. /// -/// A new pile can also be created by reparenting a plane to itself, +/// A new pile can also be created by reparenting an `NcPlane` to itself, /// though if the plane is already a root plane, this is a no-op. /// -/// When a plane is moved to a different pile (whether new or preexisting), -/// any planes which were bound to it are rebound to its previous parent. -/// If the plane was a root plane of some pile, any bound planes become root -/// planes. The new plane is placed immediately atop its new parent on its new -/// pile's z-axis. When ncplane_reparent_family() is used, all planes bound to -/// the reparented plane are moved along with it. Their relative z-order is maintained. +/// When an `NcPlane` is moved to a different pile (whether new or preexisting), +/// any `NcPlane`s which were bound to it are rebound to its previous parent. +/// If the `NcPlane` was a root plane of some pile, any bound planes become root +/// planes. The new `NcPlane` is placed immediately atop its new parent on its +/// new pile's z-axis. +/// +/// When [`NcPlane::reparent_family`][NcPlane#method.reparent_family] is used, +/// all `NcPlanes` bound to the reparented `NcPlane` are moved along with it. +/// Their relative z-order is maintained. +// +/// Rendering reduces a pile of `NcPlane`s to a single `NcPlane`, proceeding +/// from the top to the bottom along a pile's z-axis. The result is a matrix of +/// [`NcCell`][crate::NcCell]s. Rasterizing takes this matrix, together with the +/// current state of the visual area, and produces a stream of optimized control +/// sequences and [`NcEgc`][crate::NcEgc]s for the terminal. By writing this +/// stream to the terminal, the physical display is synced to some pile's +/// `NcPlane`s. +/// +/// [`NcPlane.render`][crate::NcPlane#method.render] performs the first of these +/// tasks for the pile of which the plane is a part. The output is maintained +/// internally; calling `render` again on the same pile will replace this state +/// with a fresh render. Multiple piles can be concurrently rendered. +/// [`NcPlane.rasterize`][crate::NcPlane#method.rasterize] performs +/// rasterization, and writes the result to the terminal. It is a blocking call, +/// and only one rasterization operation may proceed at a time. /// +/// It is necessary to call `NcPlane.rasterize` to generate any visible output; +/// the various *output calls* only draw to the virtual `NcPlane`s. Most of the +/// notcurses `statistics` are updated as a result of a render, and screen +/// geometry is refreshed (similarly to +/// [`Notcurses.refresh`][crate::Notcurses#method.refresh]) following the render. /// /// # Methods & Associated Functions ///