You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
230 lines
8.5 KiB
Rust
230 lines
8.5 KiB
Rust
//! The notcurses types are defined and/or explained here
|
|
//!
|
|
use crate as nc;
|
|
|
|
/// RGB: 24 bits broken into 3x 8bpp channels.
|
|
///
|
|
/// -------- RRRRRRRR GGGGGGGG BBBBBBBB
|
|
///
|
|
/// type in C: no data type
|
|
///
|
|
pub type Rgb = u32;
|
|
|
|
/// 8 bpp channel
|
|
///
|
|
/// CCCCCCCC (1 Byte)
|
|
///
|
|
/// Used both for R/G/B color and 8 bit alpha
|
|
///
|
|
/// type in C: no data type
|
|
///
|
|
pub type Color = u8;
|
|
|
|
/// Channel: 32 bits of context-dependent info
|
|
/// containing RGB + 2 bits of alpha + crap
|
|
///
|
|
/// ~~AA~~~~ RRRRRRRR GGGGGGGG BBBBBBBB
|
|
///
|
|
/// It is:
|
|
/// - an RGB value
|
|
/// - plus 2 bits of alpha
|
|
/// - plus context-dependent info
|
|
///
|
|
/// The context details are documented in ChannelPair,
|
|
///
|
|
/// type in C: channel (uint32_t)
|
|
///
|
|
pub type Channel = u32;
|
|
|
|
/// 2 bits of alpha (surrounded by context dependent bits).
|
|
/// It is part of a Channel.
|
|
///
|
|
/// ~~AA~~~~ -------- -------- --------
|
|
///
|
|
/// type in C: no data type
|
|
///
|
|
pub type AlphaBits = u32;
|
|
|
|
/// Channels: 64 bits containing a foreground and background channel
|
|
///
|
|
/// ~~AA~~~~|RRRRRRRR|GGGGGGGG|BBBBBBBB|~~AA~~~~|RRRRRRRR|GGGGGGGG|BBBBBBBB
|
|
/// ↑↑↑↑↑↑↑↑↑↑↑↑ foreground ↑↑↑↑↑↑↑↑↑↑↑|↑↑↑↑↑↑↑↑↑↑↑↑ background ↑↑↑↑↑↑↑↑↑↑↑
|
|
///
|
|
/// Detailed info (specially on the context-dependent bits on the 4th byte;
|
|
///
|
|
/// ~foreground channel~
|
|
/// part of a wide glyph: ↓bits view↓ ↓hex view↓
|
|
/// 1······· ········ ········ ········ ········ ········ ········ ········ = 8······· ········
|
|
///
|
|
/// foreground is *not* "default color":
|
|
/// ·1······ ········ ········ ········ ········ ········ ········ ········ = 4······· ········
|
|
///
|
|
/// foreground alpha (2bits):
|
|
/// ··11···· ········ ········ ········ ········ ········ ········ ········ = 3······· ········
|
|
///
|
|
/// foreground uses palette index:
|
|
/// ····1··· ········ ········ ········ ········ ········ ········ ········ = ·8······ ········
|
|
///
|
|
/// glyph is entirely foreground:
|
|
/// ·····1·· ········ ········ ········ ········ ········ ········ ········ = ·4······ ········
|
|
///
|
|
/// reserved, must be 0:
|
|
/// ······00 ········ ········ ········ ········ ········ ········ ········ = ·3······ ········
|
|
///
|
|
/// foreground in 3x8 RGB (rrggbb):
|
|
/// ········ 11111111 11111111 11111111 ········ ········ ········ ········ = ··FFFFFF ········
|
|
///
|
|
/// ~background channel~
|
|
/// reserved, must be 0: ↓bits view↓ ↓hex view↓
|
|
/// ········ ········ ········ ········ 0······· ········ ········ ········ = ········ 8·······
|
|
///
|
|
/// background is *not* "default color":
|
|
/// ········ ········ ········ ········ ·1······ ········ ········ ········ = ········ 4·······
|
|
///
|
|
/// background alpha (2 bits):
|
|
/// ········ ········ ········ ········ ··11···· ········ ········ ········ = ········ 3·······
|
|
///
|
|
/// background uses palette index:
|
|
/// ········ ········ ········ ········ ····1··· ········ ········ ········ = ········ ·8······
|
|
///
|
|
/// reserved, must be 0:
|
|
/// ········ ········ ········ ········ ·····000 ········ ········ ········ = ········ ·7······
|
|
///
|
|
/// background in 3x8 RGB (rrggbb):
|
|
/// 0········ ········ ········ ········ ········11111111 11111111 11111111 = ········ ··FFFFFF
|
|
///
|
|
///
|
|
/// At render time, these 24-bit values are quantized down to terminal
|
|
/// capabilities, if necessary. There's a clear path to 10-bit support should
|
|
/// we one day need it, but keep things cagey for now. "default color" is
|
|
/// best explained by color(3NCURSES). ours is the same concept. until the
|
|
/// "not default color" bit is set, any color you load will be ignored.
|
|
///
|
|
/// type in C: channels (uint64_t)
|
|
///
|
|
pub type ChannelPair = u64;
|
|
|
|
/// Pixel (RGBA): 32 bits broken into RGB + 8-bit alpha
|
|
///
|
|
/// AAAAAAAA GGGGGGGG BBBBBBBB RRRRRRRR
|
|
///
|
|
/// 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
|
|
///
|
|
/// type in C: ncpixel (uint32_t)
|
|
///
|
|
// NOTE: the order of the colors is different than channel. Why.
|
|
pub type Pixel = u32;
|
|
|
|
// Cell: 128 bits tying together a:
|
|
//
|
|
// 1. GCluster, 32b, either or:
|
|
// UUUUUUUU UUUUUUUU UUUUUUUU UUUUUUUU
|
|
// 00000001 IIIIIIII IIIIIIII IIIIIIII
|
|
//
|
|
// 2. GCluster backstop, 8b, (zero)
|
|
// 00000000
|
|
//
|
|
// 3. reserved, 8b (ought to be zero)
|
|
// ~~~~~~~~
|
|
//
|
|
// 4. Stylemask, 16b
|
|
// 11111111 11111111
|
|
//
|
|
// 5. Channels (64b)
|
|
// ~~AA~~~~|RRRRRRRR|GGGGGGGG|BBBBBBBB|~~AA~~~~|RRRRRRRR|GGGGGGGG|BBBBBBBB
|
|
//
|
|
// type in C: cell (struct)
|
|
pub type Cell = nc::cell;
|
|
|
|
/// EGC (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:
|
|
///
|
|
/// 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,
|
|
/// because (1) the egcpool is all NUL-terminated sequences and (2) the fifth
|
|
/// 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
|
|
/// index into the egcpool (which may thus be up to 16MB):
|
|
///
|
|
/// 00000001 iiiiiiii iiiiiiii iiiiiiii
|
|
/// sign 24bit index to egpool
|
|
///
|
|
/// 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
|
|
/// 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)
|
|
///
|
|
// WIP towards a safe abstraction for Cell & functions receiving
|
|
pub type EGC = char;
|
|
// pub type EGCPool<'a> = &'a[u8];
|
|
pub type CellGcluster = u32; // the type cell.gcluster expects the EGB to be
|
|
|
|
/// EGC BackStop
|
|
///
|
|
/// type in C: cell.gcluster_backstop
|
|
pub type EGCBackstop = u8;
|
|
|
|
/// StyleMask
|
|
///
|
|
/// 16 bits NCSTYLE_* of boolean styling attributes:
|
|
///
|
|
/// 11111111 11111111
|
|
///
|
|
/// type in C: stylemask (uint16_t)
|
|
///
|
|
pub type StyleMask = u16;
|
|
|
|
// Plane: fundamental drawing surface. unites a:
|
|
//
|
|
// - CellMatrix
|
|
// - EGCPool
|
|
//
|
|
// type in C: ncplane (struct)
|
|
pub type Plane = nc::ncplane;
|
|
|
|
// EGCPool: contiguous region chopped up into NUL-terminated UTF8 EGCs, one per plane
|
|
//
|
|
// type in C: egcpool (struct)
|
|
|
|
// CellMatrix: rectilinear array of Cells
|
|
// one -- fb per plane, and transients show up ?
|
|
|
|
/// 8-bit value used for indexing into a palette
|
|
///
|
|
pub type PaletteIndex = u8;
|
|
pub type Palette = nc::palette256;
|
|
|
|
/// 32-bit signed value used to return errors, when value < 0, (usually -1)
|
|
///
|
|
pub type IntResult = i32;
|
|
|
|
///
|
|
pub type Align = nc::ncalign_e;
|
|
pub const ALIGN_LEFT: Align = nc::ncalign_e_NCALIGN_LEFT;
|
|
pub const ALIGN_RIGHT: Align = nc::ncalign_e_NCALIGN_RIGHT;
|
|
pub const ALIGN_CENTER: Align = nc::ncalign_e_NCALIGN_CENTER;
|
|
|
|
///
|
|
pub type DirectMode = nc::ncdirect;
|