- rename EGC to Egc, EGCBackstop to EgcBackstop and ChannelPair to Channels.
- make the original type aliased structs non-public (e.g. ncdirect, ncalign…)
- fix and improve documentation for several types.
- revert renaming crate to nc on use.
- directly import the used types at the beginning of the module.
Now the rustdoc generated documentation is much cleaner.
/// A Cell corresponds to a single character cell on some plane, which can be occupied by a single grapheme cluster (some root spacing glyph, along with possible combining characters, which might span multiple columns). At any cell, we can have a theoretically arbitrarily long UTF-8 string, a foreground color, a background color, and an attribute set. Valid grapheme cluster contents include:
///
/// - A NUL terminator,
/// - A single control character, followed by a NUL terminator,
/// - At most one spacing character, followed by zero or more nonspacing
/// characters, followed by a NUL terminator.
///
/// Multi-column characters can only have a single style/color throughout.
/// wcwidth() is not reliable. It's just quoting whether or not the Egc
/// contains a "Wide Asian" double-width character.
/// This is set for some things, like most emoji, and not set for
/// other things, like cuneiform.
///
/// Each cell occupies 16 static bytes (128 bits). The surface is thus ~1.6MB
/// for a (pretty large) 500x200 terminal. At 80x43, it's less than 64KB.
/// Dynamic requirements (the egcpool) can add up to 16MB to an ncplane, but
/// such large pools are unlikely in common use.
///
/// We implement some small alpha compositing. Foreground and background both
/// have two bits of inverted alpha. The actual grapheme written to a cell is
/// the topmost non-zero grapheme. If its alpha is 00, its foreground color is
/// used unchanged. If its alpha is 10, its foreground color is derived entirely
/// from cells underneath it. Otherwise, the result will be a composite.
/// Likewise for the background. If the bottom of a coordinate's zbuffer is
/// reached with a cumulative alpha of zero, the default is used. In this way,
/// a terminal configured with transparent background can be supported through
/// multiple occluding ncplanes. A foreground alpha of 11 requests high-contrast
/// text (relative to the computed background). A background alpha of 11 is
/// currently forbidden.
///
/// Default color takes precedence over palette or RGB, and cannot be used with
/// transparency. Indexed palette takes precedence over RGB. It cannot
/// meaningfully set transparency, but it can be mixed into a cascading color.
/// RGB is used if neither default terminal colors nor palette indexing are in
/// play, and fully supports all transparency options.
///
/// `type in C: cell (struct)`
///
pubtypeCell=crate::cell;
// Egc
//
// type in C: cell (struct)
pubtypeCell=nc::cell;
/// EGC (Extended Grapheme Cluster)
/// 32-bit Char, Extended Grapheme Cluster
///
/// This 32 bit char, together with the associated plane's associated egcpool,
/// completely define this cell's EGC. Unless the EGC requires more than four
/// bytes to encode as UTF-8, it will be inlined here:
/// completely define this cell's `Egc`. Unless the `Egc` requires more than
/// four bytes to encode as UTF-8, it will be inlined here:
///
/// ```txt
/// UUUUUUUU UUUUUUUU UUUUUUUU UUUUUUUU
/// extended grapheme cluster <= 4bytes
/// ```
///
/// If more than four bytes are required, it will be spilled into the egcpool.
/// In either case, there's a NUL-terminated string available without copying,
@ -160,64 +228,90 @@ pub type Cell = nc::cell;
/// byte of this struct (the GClusterBackStop field, see below) is
/// guaranteed to be zero, as are any unused bytes in gcluster.
///
/// A spilled EGC is indicated by the value 0x01iiiiii. This cannot alias a
/// true supra-ASCII EGC, because UTF-8 only encodes bytes <= 0x80 when they
/// are single-byte ASCII-derived values. The iiiiii is interpreted as a 24-bit
/// A spilled Egc is indicated by the value `0x01iiiiii`. This cannot alias a
/// true supra-ASCII Egc, because UTF-8 only encodes bytes <= 0x80 when they
/// are single-byte ASCII-derived values. The `iiiiii` is interpreted as a 24-bit
/// index into the egcpool (which may thus be up to 16MB):
///
/// ```txt
/// 00000001 iiiiiiii iiiiiiii iiiiiiii
/// sign 24bit index to egpool
/// sign 24bit index to egcpool
/// ```
///
/// The cost of this scheme is that the character 0x01 (SOH) cannot be encoded
/// in a cell, and therefore it must not be allowed through the API.
///
/// -----
/// NOTE that even if the EGC is <= 4 bytes and inlined, is still interpreted a
/// NOTE that even if the `Egc` is <= 4 bytes and inlined, is still interpreted
/// a NUL-terminated char * (technically, &cell->gcluster is treated as a char*).
/// If it is more than 4 bytes, cell->gcluster has a first byte of 0x01,
/// and the remaining 24 bits are an index into the plane's egcpool,
/// which is carved into NUL-terminated chunks of arbitrary length.
///
/// type in C: gcluster (uint32_t)
/// `type in C: gcluster (uint32_t)`
///
// WIP towards a safe abstraction for Cell & functions receiving
pubtypeEGC=char;
// pub type EGCPool<'a> = &'a[u8];
pubtypeEgc=char;
// pub type EgcPool<'a> = &'a[u8];
pubtypeCellGcluster=u32;// the type cell.gcluster expects the EGB to be
/// EGC BackStop
/// Egc BackStop
///
/// `type in C: cell.gcluster_backstop`
///
/// type in C: cell.gcluster_backstop
pubtypeEGCBackstop=u8;
pubtypeEgcBackstop=u8;
/// StyleMask
// StyleMask
///
/// 16 bits NCSTYLE_* of boolean styling attributes:
/// 16 bits `NCSTYLE_*` of boolean styling attributes:
///
/// ```txt
/// 11111111 11111111
/// ```
///
/// type in C: stylemask (uint16_t)
/// `type in C: stylemask (uint16_t)`
///
pubtypeStyleMask=u16;
/// Type alias of ncplane
// Plane: fundamental drawing surface. unites a:
//
// - CellMatrix
// - EGCPool
//
// type in C: ncplane (struct)
pubtypeNcPlane=nc::ncplane;
// NcPlane
/// Fundamental drawing surface.
///
/// Unites a:
///
/// - CellMatrix
/// - EgcPool
///
/// `type in C: ncplane (struct)`
pubtypeNcPlane=crate::ncplane;
/// I/O wrapper to dump file descriptor to [`NcPlane`](type.NcPlane.html)
pubtypeNcFdPlane=crate::ncfdplane;
// EGCPool: contiguous region chopped up into NUL-terminated UTF8 EGCs, one per plane
/// Options struct for [`NcFdPlane`](type.NcFdPlane.html)
///
/// `type in C: ncplane_options (struct)`
pubtypeNcFdPlaneOptions=crate::ncfdplane_options;
// EGCPool:
//
// type in C: egcpool (struct)
// Contiguous region chopped up into NUL-terminated UTF8 EGCs, one per plane
//
// `type in C: egcpool (struct)`
// TODO
// CellMatrix: rectilinear array of Cells
// one -- fb per plane, and transients show up ?
/// Typle alias of palette256
pubtypePalette=nc::palette256;
/// Palette structure consisting of an array of 256 [`Channel`](type.Channel.html)s
///
/// Some terminals only support 256 colors, but allow the full
/// palette to be specified with arbitrary RGB colors. In all cases, it's more
/// performant to use indexed colors, since it's much less data to write to the
/// terminal. If you can limit yourself to 256 colors, that's probably best.
joseLuís
4 years ago