Type Alias libnotcurses_sys::NcCell
source · pub type NcCell = nccell;
Expand description
A coordinate on an NcPlane
storing 128 bits of data.
§Methods & Associated Functions
§Description
An NcCell
corresponds to a single character cell on some NcPlane
,
which can be occupied by a single EGC
grapheme cluster (some root
spacing glyph, along with possible combining characters, which might span
multiple columns).
An NcCell
is bounded to an NcPlane
, but the cell doesn’t store anything
about the plane.
At any NcCell
, we can have a theoretically arbitrarily long UTF-8 string,
a foreground color, a background color, and an NcStyle
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.
§Diagram
`NcCell`: 128 bits structure comprised of the following 5 elements:
GCLUSTER|GCLUSTER|GCLUSTER|GCLUSTER 1. `EGC`
00000000║WWWWWWWW║11111111|11111111 2. backstop + 3. width + 4. `NcStyle`
~~AA~~~~|RRRRRRRR|GGGGGGGG|BBBBBBBB 5. `NcChannels`
~~AA~~~~|RRRRRRRR|GGGGGGGG|BBBBBBBB "
1. (32b) Extended Grapheme Cluster, presented either as:
1.1. An EGC of up to 4 bytes:
UUUUUUUU|UUUUUUUU|UUUUUUUU|UUUUUUUU
1.2. A `0x01` in the first byte, plus 3 bytes with a 24b address to an egcpool:
00000001|IIIIIIII|IIIIIIII|IIIIIIII
2. (8b) backstop (zero)
00000000
3. (8b) column width
WWWWWWWW
4. (16b) `NcStyle`
11111111 11111111
5. (64b) `NcChannels`
~~AA~~~~|RRRRRRRR|GGGGGGGG|BBBBBBBB║~~AA~~~~|RRRRRRRR|GGGGGGGG|BBBBBBBB
type in C: cell (struct)
§More NcCell
Information
§Size
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.
§Alpha Compositing
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 (
NcAlpha::OPAQUE
) its foreground color is used unchanged. -
If its alpha is 10 (
NcAlpha::TRANSPARENT
) its foreground color is derived entirely from cells underneath it. -
If its alpha is 01 (
NcAlpha::BLEND
) 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
(NcAlpha::HIGHCONTRAST
)
requests high-contrast text (relative to the computed background).
A background alpha of 11 is currently forbidden.
§Precedence
- 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.
§Column width (WIP)
See USAGE.md
We store the column width in this field. for a multicolumn EGC of N columns, there will be N nccells, and each has a width of N…for now. eventually, such an EGC will set more than one subsequent cell to WIDE_RIGHT, and this won’t be necessary. it can then be used as a bytecount. see #1203. FIXME iff width >= 2, the cell is part of a multicolumn glyph. whether a cell is the left or right side of the glyph can be determined by checking whether ->gcluster is zero.
Aliased Type§
struct NcCell {
pub gcluster: u32,
pub gcluster_backstop: u8,
pub width: u8,
pub stylemask: u16,
pub channels: u64,
}
Fields§
§gcluster: u32
4B → 4B little endian EGC
gcluster_backstop: u8
1B → 5B (8 bits of zero)
width: u8
1B → 6B (8 bits of EGC column width)
stylemask: u16
2B → 8B (16 bits of NCSTYLE_* attributes)
channels: u64
- 8B == 16B
Implementations§
source§impl NcCell
impl NcCell
§NcCell constructors
sourcepub fn from_char7b(ch: char) -> NcResult<Self>
pub fn from_char7b(ch: char) -> NcResult<Self>
New NcCell
, expects a 7-bit char
.
sourcepub fn from_char(plane: &mut NcPlane, ch: char) -> NcResult<Self>
pub fn from_char(plane: &mut NcPlane, ch: char) -> NcResult<Self>
New NcCell
, from a char
.
Expects a plane where to save the extra data if it’s greater than 4 bytes.
sourcepub fn from_str(plane: &mut NcPlane, string: &str) -> NcResult<Self>
pub fn from_str(plane: &mut NcPlane, string: &str) -> NcResult<Self>
New NcCell
, from a &str
.
Expects a plane where to save the extra data if it’s greater than 4 bytes.
sourcepub fn load(plane: &mut NcPlane, cell: &mut NcCell, egc: &str) -> NcResult<u32>
pub fn load(plane: &mut NcPlane, cell: &mut NcCell, egc: &str) -> NcResult<u32>
Breaks the UTF-8 string in egc
down, setting up this NcCell
,
and returns the number of bytes copied out of egc
.
The styling of the cell is left untouched, but any resources are released. C style function: nccell_load().
sourcepub fn prime(
plane: &mut NcPlane,
cell: &mut NcCell,
gcluster: &str,
style: impl Into<NcStyle>,
channels: impl Into<NcChannels>
) -> NcResult<u32>
pub fn prime( plane: &mut NcPlane, cell: &mut NcCell, gcluster: &str, style: impl Into<NcStyle>, channels: impl Into<NcChannels> ) -> NcResult<u32>
Same as load, plus blasts the styling with
style
and channels
.
- Breaks the UTF-8 string in
gcluster
down, setting up this NcCell. - Returns the number of bytes copied out of
gcluster
. - Any resources are released.
- Blasts the styling with
style
andchannels
.
C style function: nccell_prime().
sourcepub fn duplicate(&self, common_plane: &mut NcPlane) -> NcResult<NcCell>
pub fn duplicate(&self, common_plane: &mut NcPlane) -> NcResult<NcCell>
Duplicate this NcCell
into another one.
Both must be or will be bound to common_plane
.
C style function: nccell_duplicate().
sourcepub fn init(&mut self)
pub fn init(&mut self)
Initializes (zeroes out) this NcCell
.
C style function: nccell_init().
sourcepub fn release(&mut self, plane: &mut NcPlane)
pub fn release(&mut self, plane: &mut NcPlane)
Releases resources held by the current cell in the NcPlane plane
.
C style function: nccell_release().
source§impl NcCell
impl NcCell
§NcCell methods: bg|fg NcChannel
s manipulation.
sourcepub fn bchannel(&self) -> NcChannel
pub fn bchannel(&self) -> NcChannel
Gets the background alpha and coloring bits from the cell NcChannels
as an NcChannel
.
C style function: nccell_bchannel().
sourcepub fn fchannel(&self) -> NcChannel
pub fn fchannel(&self) -> NcChannel
Gets the foreground alpha and coloring bits from the cell NcChannels
as an NcChannel
.
C style function: nccell_fchannel().
sourcepub fn channels(&self) -> NcChannels
pub fn channels(&self) -> NcChannels
Gets the alpha and coloring bits from the cell NcChannels
.
C style function: nccell_channels().
sourcepub fn set_bchannel(&mut self, from: impl Into<NcChannel>) -> NcChannels
pub fn set_bchannel(&mut self, from: impl Into<NcChannel>) -> NcChannels
Sets the background alpha and coloring bits of the cell NcChannels
,
returning the new NcChannels_u64
.
C style function: nccell_bchannel().
sourcepub fn set_fchannel(&mut self, from: impl Into<NcChannel>) -> NcChannels
pub fn set_fchannel(&mut self, from: impl Into<NcChannel>) -> NcChannels
Sets the foreground alpha and coloring bits from the cell NcChannels
,
returning the new NcChannels_u64
.
C style function: nccell_set_fchannel().
sourcepub fn set_channels(&mut self, from: impl Into<NcChannels>) -> NcChannels
pub fn set_channels(&mut self, from: impl Into<NcChannels>) -> NcChannels
Sets the alpha and coloring bits of the cell NcChannels
from another NcChannels
, returning the new NcChannels
.
C style function: nccell_set_channels().
sourcepub fn bg_alpha(&self) -> NcAlpha
pub fn bg_alpha(&self) -> NcAlpha
Gets the background NcAlpha
(shifted to LSBs).
C style function: nccell_bg_alpha().
sourcepub fn bg_default_p(&self) -> bool
pub fn bg_default_p(&self) -> bool
Is the background NcChannel
using the “default background color”?
C style function: nccell_bg_default_p().
sourcepub fn bg_palindex(&self) -> NcPaletteIndex
pub fn bg_palindex(&self) -> NcPaletteIndex
Gets the NcPaletteIndex
of the background NcChannel
.
C style function: nccell_bg_palindex().
sourcepub fn bg_palindex_p(&self) -> bool
pub fn bg_palindex_p(&self) -> bool
Is the background NcChannel
using an NcPaletteIndex
indexed
NcPalette
color?
C style function: nccell_bg_palindex_p().
sourcepub fn bg_rgb(&self) -> NcRgb
pub fn bg_rgb(&self) -> NcRgb
Gets the background NcRgb
(shifted to LSBs).
C style function: nccell_bg_rgb().
sourcepub fn fg_alpha(&self) -> NcAlpha
pub fn fg_alpha(&self) -> NcAlpha
Gets the foreground NcAlpha
(shifted to LSBs).
C style function: nccell_fg_alpha().
sourcepub fn fg_default_p(&self) -> bool
pub fn fg_default_p(&self) -> bool
Is the foreground NcChannel
using the “default foreground color”?
C style function: nccell_fg_default_p().
sourcepub fn fg_palindex(&self) -> NcPaletteIndex
pub fn fg_palindex(&self) -> NcPaletteIndex
Gets the NcPaletteIndex
of the foreground NcChannel
.
C style function: nccell_fg_palindex().
sourcepub fn fg_palindex_p(&self) -> bool
pub fn fg_palindex_p(&self) -> bool
Is the foreground NcChannel
using an NcPaletteIndex
indexed
NcPalette
color?
C style function: nccell_fg_palindex_p().
sourcepub fn fg_rgb(&self) -> NcRgb
pub fn fg_rgb(&self) -> NcRgb
Gets the foreground NcRgb
(shifted to LSBs).
C style function: nccell_fg_rgb().
sourcepub fn set_bg_alpha(&mut self, alpha: impl Into<NcAlpha>)
pub fn set_bg_alpha(&mut self, alpha: impl Into<NcAlpha>)
Sets the background NcAlpha
.
C style function: nccell_set_bg_alpha().
sourcepub fn set_bg_default(&mut self)
pub fn set_bg_default(&mut self)
Indicates to use the “default color” for the background NcChannel
.
C style function: nccell_set_bg_default().
sourcepub fn set_bg_palindex(&mut self, index: impl Into<NcPaletteIndex>)
pub fn set_bg_palindex(&mut self, index: impl Into<NcPaletteIndex>)
Sets the background NcPaletteIndex
.
Also sets
NcChannels::BG_PALETTE_MASK
and
NcAlpha::OPAQUE
, and clears out
NcChannels::BG_DEFAULT_MASK
.
C style function: nccell_set_bg_palindex().
sourcepub fn set_bg_rgb(&mut self, rgb: impl Into<NcRgb>)
pub fn set_bg_rgb(&mut self, rgb: impl Into<NcRgb>)
Sets the background NcRgb
and marks it as not using the default color.
C style function: nccell_set_bg_rgb().
sourcepub fn set_fg_alpha(&mut self, alpha: impl Into<NcAlpha>)
pub fn set_fg_alpha(&mut self, alpha: impl Into<NcAlpha>)
Sets the foreground NcAlpha
.
C style function: nccell_set_fg_alpha().
sourcepub fn set_fg_default(&mut self)
pub fn set_fg_default(&mut self)
Indicates to use the “default color” for the foreground NcChannel
.
C style function: nccell_set_fg_default().
sourcepub fn set_fg_palindex(&mut self, index: impl Into<NcPaletteIndex>)
pub fn set_fg_palindex(&mut self, index: impl Into<NcPaletteIndex>)
Sets the foreground NcPaletteIndex
.
Also sets
NcChannels::FG_PALETTE_MASK
and
NcAlpha::OPAQUE
, and clears out
NcChannels::FG_DEFAULT_MASK
.
C style function: nccell_set_fg_palindex().
sourcepub fn set_fg_rgb(&mut self, rgb: impl Into<NcRgb>)
pub fn set_fg_rgb(&mut self, rgb: impl Into<NcRgb>)
Sets the foreground NcRgb
and marks it as not using the default color.
C style function: nccell_set_fg_rgb().
source§impl NcCell
impl NcCell
§NcCell
methods: other components
sourcepub fn compare(
plane1: &NcPlane,
cell1: &NcCell,
plane2: &NcPlane,
cell2: &NcCell
) -> bool
Available on crate feature libc
only.
pub fn compare( plane1: &NcPlane, cell1: &NcCell, plane2: &NcPlane, cell2: &NcCell ) -> bool
libc
only.Returns true if the two cells have distinct EGC
s, attributes,
or NcChannel
s.
The actual egcpool index needn’t be the same–indeed, the planes
needn’t even be the same. Only the expanded EGC
must be bit-equal.
C style function: nccellcmp().
sourcepub fn extract(
&self,
plane: &mut NcPlane,
styles: &mut NcStyle,
channels: &mut NcChannels
) -> String
Available on crate feature libc
only.
pub fn extract( &self, plane: &mut NcPlane, styles: &mut NcStyle, channels: &mut NcChannels ) -> String
libc
only.Saves the NcStyle
and the NcChannels
, and returns the duplicatd EGC
.
C style function: nccell_fg_alpha().
sourcepub fn styles(&self) -> NcStyle
pub fn styles(&self) -> NcStyle
Returns the NcStyle
bits.
C style function: nccell_styles().
sourcepub fn styles_off(&mut self, stylebits: impl Into<NcStyle>)
pub fn styles_off(&mut self, stylebits: impl Into<NcStyle>)
Removes the specified NcStyle
bits.
C style function: nccell_off_styles().
sourcepub fn styles_on(&mut self, stylebits: impl Into<NcStyle>)
pub fn styles_on(&mut self, stylebits: impl Into<NcStyle>)
Adds the specified NcStyle
bits.
C style function: nccell_on_styles().
sourcepub fn styles_set(&mut self, stylebits: impl Into<NcStyle>)
pub fn styles_set(&mut self, stylebits: impl Into<NcStyle>)
Sets just the specified NcStyle
bits.
C style function: nccell_set_styles().
source§impl NcCell
impl NcCell
§NcCell
methods: text
sourcepub const fn cols(&self) -> u8
pub const fn cols(&self) -> u8
Returns the number of columns occupied by the cell.
See ncstrwidth
for an equivalent for multiple EGCs.
C style function: nccell_cols().
sourcepub fn egc(&self, plane: &NcPlane) -> &str
pub fn egc(&self, plane: &NcPlane) -> &str
Returns a pointer to the EGC
of this NcCell in the plane
.
This pointer can be invalidated by any further operation on the referred plane, so… watch out!
C style function: nccell_extended_gcluster().
sourcepub fn strdup(&self, plane: &NcPlane) -> String
Available on crate feature libc
only.
pub fn strdup(&self, plane: &NcPlane) -> String
libc
only.Copies the UTF8-encoded EGC
out of this NcCell,
whether simple or complex.
The result is not tied to the NcPlane, and persists across erases and destruction.
C style function: nccell_strdup().
sourcepub fn double_wide_p(&self) -> bool
pub fn double_wide_p(&self) -> bool
Does this NcCell contain a wide codepoint?
C style function: nccell_double_wide_p().
sourcepub fn wide_left_p(&self) -> bool
pub fn wide_left_p(&self) -> bool
Is this the left half of a wide character?
C style function: nccell_wide_left_p().
sourcepub fn wide_right_p(&self) -> bool
pub fn wide_right_p(&self) -> bool
Is this the right side of a wide character?
C style function: nccell_wide_right_p().
source§impl NcCell
impl NcCell
§NcCell
methods: boxes
sourcepub fn load_box(
plane: &mut NcPlane,
style: impl Into<NcStyle>,
channels: impl Into<NcChannels>,
ul: &mut NcCell,
ur: &mut NcCell,
ll: &mut NcCell,
lr: &mut NcCell,
hl: &mut NcCell,
vl: &mut NcCell,
gcluster: &str
) -> NcResult<()>
pub fn load_box( plane: &mut NcPlane, style: impl Into<NcStyle>, channels: impl Into<NcChannels>, ul: &mut NcCell, ur: &mut NcCell, ll: &mut NcCell, lr: &mut NcCell, hl: &mut NcCell, vl: &mut NcCell, gcluster: &str ) -> NcResult<()>
Loads up six cells with the EGC
s necessary to draw a box.
On error, any NcCell
s this function might have loaded before the error
are released.
There must be at least six EGC
s in gcluster
.
C style function: nccells_load_box().
sourcepub fn double_box(
plane: &mut NcPlane,
style: impl Into<NcStyle>,
channels: impl Into<NcChannels>,
ul: &mut NcCell,
ur: &mut NcCell,
ll: &mut NcCell,
lr: &mut NcCell,
hl: &mut NcCell,
vl: &mut NcCell
) -> NcResult<()>
pub fn double_box( plane: &mut NcPlane, style: impl Into<NcStyle>, channels: impl Into<NcChannels>, ul: &mut NcCell, ur: &mut NcCell, ll: &mut NcCell, lr: &mut NcCell, hl: &mut NcCell, vl: &mut NcCell ) -> NcResult<()>
NcCell.load_box() with the double box-drawing characters.
C style function: nccells_double_box().
sourcepub fn rounded_box(
plane: &mut NcPlane,
style: impl Into<NcStyle>,
channels: impl Into<NcChannels>,
ul: &mut NcCell,
ur: &mut NcCell,
ll: &mut NcCell,
lr: &mut NcCell,
hl: &mut NcCell,
vl: &mut NcCell
) -> NcResult<()>
pub fn rounded_box( plane: &mut NcPlane, style: impl Into<NcStyle>, channels: impl Into<NcChannels>, ul: &mut NcCell, ur: &mut NcCell, ll: &mut NcCell, lr: &mut NcCell, hl: &mut NcCell, vl: &mut NcCell ) -> NcResult<()>
NcCell.load_box() with the rounded box-drawing characters.
C style function: nccells_rounded_box().
sourcepub fn ascii_box(
plane: &mut NcPlane,
style: impl Into<NcStyle>,
channels: impl Into<NcChannels>,
ul: &mut NcCell,
ur: &mut NcCell,
ll: &mut NcCell,
lr: &mut NcCell,
hl: &mut NcCell,
vl: &mut NcCell
) -> NcResult<()>
pub fn ascii_box( plane: &mut NcPlane, style: impl Into<NcStyle>, channels: impl Into<NcChannels>, ul: &mut NcCell, ur: &mut NcCell, ll: &mut NcCell, lr: &mut NcCell, hl: &mut NcCell, vl: &mut NcCell ) -> NcResult<()>
NcCell.load_box() with ASCII characters.
C style function: nccells_ascii_box().
sourcepub fn heavy_box(
plane: &mut NcPlane,
style: impl Into<NcStyle>,
channels: impl Into<NcChannels>,
ul: &mut NcCell,
ur: &mut NcCell,
ll: &mut NcCell,
lr: &mut NcCell,
hl: &mut NcCell,
vl: &mut NcCell
) -> NcResult<()>
pub fn heavy_box( plane: &mut NcPlane, style: impl Into<NcStyle>, channels: impl Into<NcChannels>, ul: &mut NcCell, ur: &mut NcCell, ll: &mut NcCell, lr: &mut NcCell, hl: &mut NcCell, vl: &mut NcCell ) -> NcResult<()>
NcCell.load_box() with the heavy line box-drawing characters.
C style function: nccells_heavy_box().
sourcepub fn light_box(
plane: &mut NcPlane,
style: impl Into<NcStyle>,
channels: impl Into<NcChannels>,
ul: &mut NcCell,
ur: &mut NcCell,
ll: &mut NcCell,
lr: &mut NcCell,
hl: &mut NcCell,
vl: &mut NcCell
) -> NcResult<()>
pub fn light_box( plane: &mut NcPlane, style: impl Into<NcStyle>, channels: impl Into<NcChannels>, ul: &mut NcCell, ur: &mut NcCell, ll: &mut NcCell, lr: &mut NcCell, hl: &mut NcCell, vl: &mut NcCell ) -> NcResult<()>
NcCell.load_box() with the light line box-drawing characters.
C style function: nccells_light_box().