Struct libnotcurses_sys::NcChannels

#[repr(transparent)]
pub struct NcChannels(pub NcChannels_u64);

64 bits containing a foreground and background NcChannel

At render time, both 24-bit NcRgb values are quantized down to terminal capabilities, if necessary. There’s a clear path to 10-bit support should we one day need it.

Default Color

The “default color” is best explained by color(3NCURSES) and default_colors(3NCURSES). Ours is the same concept.

Until the “not default color” bit is set, any color you load will be ignored.

Diagram

~~AA~~~~|RRRRRRRR|GGGGGGGG|BBBBBBBB║~~AA~~~~|RRRRRRRR|GGGGGGGG|BBBBBBBB
↑↑↑↑↑↑↑↑↑↑↑↑ foreground ↑↑↑↑↑↑↑↑↑↑↑║↑↑↑↑↑↑↑↑↑↑↑↑ background ↑↑↑↑↑↑↑↑↑↑↑

Detailed info (specially on the context-dependent bits on each NcChannel’s 4th byte):

                            ~foreground channel~
reserved, must be 0                                  ↓bits view↓               ↓hex mask↓
0·······|········|········|········║········|········|········|········  =  8·······|········

NcChannels::FG_DEFAULT_MASK: foreground is NOT "default color"
·1······|········|········|········║········|········|········|········  =  4·······|········

NcChannels::FG_ALPHA_MASK: foreground alpha (2bits)
··11····|········|········|········║········|········|········|········  =  3·······|········

NcChannels::FG_PALETTE: foreground uses palette index
····1···|········|········|········║········|········|········|········  =  ·8······|········

NcChannels::NOBACKGROUND_MASK: glyph is entirely foreground
·····1··|········|········|········║········|········|········|········  =  ·4······|········

reserved, must be 0
······00|········|········|········║········|········|········|········  =  ·3······|········

NcChannels::FG_RGB_MASK: foreground in 3x8 RGB (rrggbb)
········|11111111|11111111|11111111║········|········|········|········  =  ··FFFFFF|········

                            ~background channel~
reserved, must be 0                                  ↓bits view↓               ↓hex mask↓
········|········|········|········║0·······|········|········|········  =  ········|8·······

NcChannels::BGDEFAULT_MASK: background is NOT "default color"
········|········|········|········║·1······|········|········|········  =  ········|4·······

NcChannels::BG_ALPHA_MASK: background alpha (2 bits)
········|········|········|········║··11····|········|········|········  =  ········|3·······

NcChannels::BG_PALETTE: background uses palette index
········|········|········|········║····1···|········|········|········  =  ········|·8······

reserved, must be 0
········|········|········|········║·····000|········|········|········  =  ········|·7······

NcChannels::BG_RGB_MASK: background in 3x8 RGB (rrggbb)
········|········|········|········║········|11111111|11111111|11111111  =  ········|··FFFFFF

type in C: channels (uint64_t)

NcChannels Mask Flags

• NcChannels::BG_DEFAULT_MASK
• NcChannels::BG_ALPHA_MASK
• NcChannels::BG_PALETTE
• NcChannels::BG_RGB_MASK
• NcChannels::FG_DEFAULT_MASK
• NcChannels::FG_ALPHA_MASK
• NcChannels::FG_PALETTE
• NcChannels::FG_RGB_MASK

Tuple Fields

0: NcChannels_u64

Implementations

impl NcChannels

NcChannels constants

pub const BG_DEFAULT_MASK: u32 = 1_073_741_824u32

If this bit is set, we are not using the default background color.

See the detailed diagram at NcChannels

pub const BG_ALPHA_MASK: u32 = 805_306_368u32

Extract these bits to get the background NcAlpha mask.

See the detailed diagram at NcChannels

pub const BG_PALETTE_MASK: u32 = 134_217_728u32

If this bit and BG_DEFAULT_MASK are set, we’re using a palette-indexed background color.

See the detailed diagram at NcChannels

pub const BG_RGB_MASK: u32 = 16_777_215u32

Extract these bits to get the background NcRgb value.

pub const NOBACKGROUND_MASK: u64 = 9_727_775_195_120_271_360u64

Does this glyph completely obscure the background? If so, there’s no need to emit a background when rasterizing, a small optimization. These are also used to track regions into which we must not cellblit.

impl NcChannels

NcChannels constructors

pub fn new() -> Self

New NcChannels, set to black and NOT using the “default color”.

pub fn with_default() -> Self

New NcChannels, set to black and using the “default color”.

pub fn from_rgb(fg_rgb: impl Into<NcRgb>, bg_rgb: impl Into<NcRgb>) -> Self

New NcChannels, expects two separate NcRgbs for the foreground and background channels.

pub fn from_rgb_both(rgb: impl Into<NcRgb>) -> Self

New NcChannels, expects a single NcRgb for both foreground and background channels.

pub fn from_rgb_alpha(
    fg_rgb: impl Into<NcRgb>,
    fg_alpha: impl Into<NcAlpha>,
    bg_rgb: impl Into<NcRgb>,
    bg_alpha: impl Into<NcAlpha>
) -> Self

New NcChannels, expects two separate NcRgb & NcAlpha for the foreground and background channels.

pub fn from_rgb_alpha_both(
    rgb: impl Into<NcRgb>,
    alpha: impl Into<NcAlpha>
) -> Self

New NcChannels, expects NcRgb & NcAlpha for both channels.

pub fn combine(
    fchannel: impl Into<NcChannel>,
    bchannel: impl Into<NcChannel>
) -> Self

Combines two NcChannels into an NcChannels.

C style function: channels_combine().

pub fn reverse(&mut self) -> Self

Returns the NcChannels with the fore- and background’s color information swapped, but without touching housekeeping bits.

Alpha is retained unless it would lead to an illegal state: HIGHCONTRAST, TRANSPARENT and BLEND are taken to OPAQUE unless the new value is RGB.

HIGHCONTRAST TRANSPARENT BLEND OPAQUE

C style function: ncchannels_reverse().

impl NcChannels

NcChannels methods

pub fn fchannel(&self) -> NcChannel

Gets the foreground alpha and coloring bits as an NcChannel.

C style function: ncchannels_fchannel().

pub fn bchannel(&self) -> NcChannel

Gets the background alpha and coloring bits as an NcChannel.

C style function: ncchannels_bchannel().

pub fn set_fchannel(&mut self, fchannel: impl Into<NcChannel>) -> Self

Sets the foreground alpha and coloring bits from an NcChannel.

C style function: ncchannels_set_fchannel().

pub fn set_bchannel(&mut self, bchannel: impl Into<NcChannel>) -> Self

Sets the background alpha and coloring bits from an NcChannel.

C style function: ncchannels_set_bchannel().

pub fn channels(&self) -> NcChannels

Gets the alpha and coloring bits as an NcChannels.

C style function: ncchannels_bchannel().

pub fn set_channels(&mut self, from_channels: impl Into<NcChannels>) -> Self

Sets the foreground alpha and coloring bits as an NcChannels, from another NcChannels.

C style function: ncchannels_set_fchannel().

pub fn fg_alpha(&self) -> NcAlpha

Gets the foreground NcAlpha.

C style function: ncchannels_fg_alpha().

pub fn bg_alpha(&self) -> NcAlpha

Gets the background NcAlpha.

C style function: ncchannels_bg_alpha().

pub fn set_fg_alpha(&mut self, alpha: impl Into<NcAlpha>) -> NcResult<()>

Sets the foreground NcAlpha.

C style function: ncchannels_set_fg_alpha().

pub fn set_bg_alpha(&mut self, alpha: impl Into<NcAlpha>) -> NcResult<()>

Sets the background NcAlpha.

C style function: ncchannels_set_bg_alpha().

pub fn fg_rgb_p(&self) -> bool

Returns true if the foreground channel is set to RGB color.

C style function: ncchannels_fg_rgb_p().

pub fn bg_rgb_p(&self) -> bool

Returns true if the background channel is set to RGB color.

C style function: ncchannels_bg_rgb_p().

pub fn fg_rgb(&self) -> NcRgb

Gets the foreground NcRgb.

C style function: ncchannels_fg_rgb().

pub fn bg_rgb(&self) -> NcRgb

Gets the background NcRgb.

C style function: ncchannels_bg_rgb().

pub fn set_fg_rgb(&mut self, rgb: impl Into<NcRgb>) -> Self

Sets the foreground NcRgb.

C style function: channels_set_fg_rgb().

pub fn set_bg_rgb(&mut self, rgb: impl Into<NcRgb>) -> Self

Sets the background NcRgb.

C style function: channels_set_bg_rgb().

pub fn fg_r(&self) -> u8

Gets the foreground red component.

(No equivalent C style function)

pub fn fg_g(&self) -> u8

Gets the foreground green component.

(No equivalent C style function)

pub fn fg_b(&self) -> u8

Gets the foreground blue component.

(No equivalent C style function)

pub fn bg_r(&self) -> u8

Gets the background red component.

(No equivalent C style function)

pub fn bg_g(&self) -> u8

Gets the background green component.

(No equivalent C style function)

pub fn bg_b(&self) -> u8

Gets the background blue component.

(No equivalent C style function)

pub fn fg_set_r(&mut self, r: impl Into<u8>) -> Self

Sets the foreground red component, and returns the new NcChannels.

(No equivalent C style function)

pub fn fg_set_g(&mut self, g: impl Into<u8>) -> Self

Sets the foreground green component, and returns the new NcChannels.

(No equivalent C style function)

pub fn fg_set_b(&mut self, b: impl Into<u8>) -> Self

Sets the foreground blue component, and returns the new NcChannels.

(No equivalent C style function)

pub fn bg_set_r(&mut self, r: impl Into<u8>) -> Self

Sets the background red component, and returns the new NcChannels.

(No equivalent C style function)

pub fn bg_set_g(&mut self, g: impl Into<u8>) -> Self

Sets the background green component, and returns the new NcChannels.

(No equivalent C style function)

pub fn bg_set_b(&mut self, b: impl Into<u8>) -> Self

Sets the background blue component, and returns the new NcChannels.

(No equivalent C style function)

pub fn fg_default_p(&self) -> bool

Is the background using the “default background color”?

C style function: channels_fg_default_p().

pub fn bg_default_p(&self) -> bool

Is the background using the “default background color”?

The “default background color” must generally be used to take advantage of terminal-effected transparency.

C style function: channels_bg_default_p().

pub fn set_fg_default(&mut self) -> Self

Marks the foreground as using its “default color”, and returns the new NcChannels.

C style function: channels_set_fg_default().

pub fn set_bg_default(&mut self) -> Self

Marks the background as using its “default color”, and returns the new NcChannels.

C style function: channels_set_bg_default().

pub fn set_fg_not_default(&mut self) -> Self

Marks the foreground as NOT using its “default color”, and returns the new NcChannels.

C style function: channels_set_fg_default().

pub fn set_bg_not_default(&mut self) -> Self

Marks the background as NOT using its “default color”, and returns the new NcChannels.

C style function: channels_set_bg_not_default().

pub fn set_default(&mut self) -> Self

Marks both the foreground and background as using its “default color”, and returns the new NcChannels.

pub fn set_not_default(&mut self) -> Self

Marks both the foreground and background as NOT using its “default color”, and returns the new NcChannels.

pub fn fg_palindex(&self) -> NcPaletteIndex

Gets the NcPaletteIndex from the foreground NcChannel.

C style function: channels_fg_palindex().

pub fn bg_palindex(&self) -> NcPaletteIndex

Gets the NcPaletteIndex from the background NcChannel.

C style function: channels_bg_palindex().

pub fn fg_palindex_p(&self) -> bool

Is the foreground of using an indexed NcPalette color?

C style function: channels_fg_palindex_p().

pub fn bg_palindex_p(&self) -> bool

Is the background of using an indexed NcPalette color?

C style function: channels_bg_palindex_p().

pub fn set_fg_palindex(&mut self, index: impl Into<NcPaletteIndex>) -> Self

Sets the foreground of an NcChannels as using an indexed NcPalette color.

C style function: channels_set_fg_palindex().

pub fn set_bg_palindex(&mut self, index: impl Into<NcPaletteIndex>) -> Self

Sets the background of an NcChannels as using an indexed NcPalette color.

C style function: channels_set_bg_palindex().

Trait Implementations

impl Binary for NcChannels

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Clone for NcChannels

fn clone(&self) -> NcChannels

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for NcChannels

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for NcChannels

fn default() -> Self

Returns the “default value” for a type.

impl Display for NcChannels

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<&'_ NcChannels> for *const NcChannels_u64

fn from(s: &NcChannels) -> Self

Converts to this type from the input type.

impl From<&'_ mut NcChannels> for *mut NcChannels_u64

fn from(s: &mut NcChannels) -> Self

Converts to this type from the input type.

impl<'a> From<&'a NcChannels> for &'a NcChannels_u64

fn from(s: &'a NcChannels) -> Self

Converts to this type from the input type.

impl<'a> From<&'a mut NcChannels> for &'a mut NcChannels_u64

fn from(s: &'a mut NcChannels) -> Self

Converts to this type from the input type.

impl<'a> From<&'a mut u64> for NcChannels

fn from(p: &'a mut NcChannels_u64) -> Self

Converts to this type from the input type.

impl<'a> From<&'a u64> for NcChannels

fn from(p: &'a NcChannels_u64) -> Self

Converts to this type from the input type.

impl From<[u8; 6]> for NcChannels

fn from(a: [u8; 6]) -> Self

Converts to this type from the input type.

impl From<(u8, u8, u8, u8, u8, u8)> for NcChannels

fn from(t: (u8, u8, u8, u8, u8, u8)) -> Self

Converts to this type from the input type.

impl From<NcChannels> for NcChannels_u64

fn from(s: NcChannels) -> Self

Converts to this type from the input type.

impl From<NcChannels> for [u8; 6]

fn from(rgb: NcChannels) -> Self

Converts to this type from the input type.

impl From<NcChannels> for (u8, u8, u8, u8, u8, u8)

fn from(rgb: NcChannels) -> Self

Converts to this type from the input type.

impl From<u64> for NcChannels

fn from(p: NcChannels_u64) -> Self

Converts to this type from the input type.

impl LowerHex for NcChannels

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Octal for NcChannels

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq<NcChannels> for NcChannels

fn eq(&self, other: &NcChannels) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &NcChannels) -> bool

This method tests for !=.

impl UpperHex for NcChannels

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Copy for NcChannels

impl StructuralPartialEq for NcChannels