libnotcurses_sys/channel/mod.rs
1//! `NcChannel*`
2
3// -----------------------------------------------------------------------------
4// - The channel components are u8 instead of u32.
5// Because of type enforcing, some runtime checks are now unnecessary.
6//
7// - None of the functions can't fail now. The original checks for dirty bits
8// have been substitued by mask cleaning (bitwise and)
9//
10// - These functions were deemed unnecessary to implement:
11// - `channel_set_rgb_clipped()`
12// - `channels_set_fg_rgb8_clipped()`
13// - `channels_set_bg_rgb8_clipped()`
14// -----------------------------------------------------------------------------
15//
16// functions manually reimplemented: 46
17// ------------------------------------------
18// (X) wont: 9
19// (+) done: 39
20// (#) test: 21
21// (W) wrap: 37
22// ------------------------------------------
23//W# channel_alpha
24//W# channel_b
25//W# channel_default_p
26//W# channel_g
27//W# channel_palindex_p
28//W# channel_r
29// # channel_rgb8 // unneeded method
30//W# channel_set
31//W# channel_set_alpha
32//W# channel_set_default
33//W# channel_set_not_default // not in the original C API
34// # channel_set_rgb8 // unneeded method
35// X channel_set_rgb_clipped // not needed
36//W# channels_bchannel
37//W+ channels_bg_alpha
38//W+ channels_bg_default_p
39//W# channels_bg_palindex_p
40//W+ channels_bg_rgb
41// + channels_bg_rgb8 // unneeded method
42//W+ channels_channels
43//W# channels_combine
44//W# channels_fchannel
45//W+ channels_fg_alpha
46//W+ channels_fg_default_p
47//W# channels_fg_palindex_p
48//W+ channels_fg_rgb
49// + channels_fg_rgb8 // unneeded method
50//W# channels_set_bchannel
51//W+ channels_set_bg_alpha
52//W+ channels_set_bg_default
53//W channels_set_bg_not_default // not in the original C API
54//W# channels_set_bg_palindex
55//W+ channels_set_bg_rgb
56// + channels_set_bg_rgb8 // unneeded method
57// X channels_set_bg_rgb8_clipped // not needed
58//W+ channels_set_channels
59//W channels_set_default // not in the original C API
60//W# channels_set_fchannel
61//W+ channels_set_fg_alpha
62//W+ channels_set_fg_default
63//W channels_set_fg_not_default // not in the original C API
64//W# channels_set_fg_palindex
65//W+ channels_set_fg_rgb
66// + channels_set_fg_rgb8 // unneeded method
67// X channels_set_fg_rgb8_clipped // not needed
68//W channels_set_not_default // not in the original C API
69
70#[cfg(test)]
71mod test;
72
73#[allow(clippy::module_inception)]
74mod channel;
75mod channels;
76pub(crate) mod reimplemented;
77pub use {channel::NcChannel, channels::NcChannels};
78
79pub(crate) mod c_api {
80 use crate::c_api::ffi;
81
82 #[allow(unused_imports)]
83 use crate::{NcAlpha, NcChannel, NcChannels};
84
85 /// 32 bits of context-dependent info containing [`NcRgb_u32`]
86 /// + [`NcAlpha_u32`] + extra
87 ///
88 /// It's recommended to use [`NcChannel`][crate::NcChannel] instead.
89 ///
90 /// It is composed of:
91 /// - a 24-bit [`NcRgb_u32`] value
92 /// - plus 8 bits divided in:
93 /// - 2 bits of [`NcAlpha_u32`]
94 /// - 6 bits of context-dependent info
95 ///
96 /// The context details are documented in [`NcChannels_u64`].
97 ///
98 /// ## Diagram
99 ///
100 /// ```txt
101 /// ~~AA~~~~ RRRRRRRR GGGGGGGG BBBBBBBB
102 /// ```
103 /// `type in C: channel (uint32_t)`
104 ///
105 /// # See also
106 /// - [`NcRgb_u32`]
107 /// - [`NcRgba_u32`]
108 ///
109 /// [`NcRgb_u32`]: crate::c_api::NcRgb_u32
110 /// [`NcRgba_u32`]: crate::c_api::NcRgba_u32
111 /// [`NcAlpha_u32`]: crate::c_api::NcAlpha_u32
112 pub type NcChannel_u32 = u32;
113
114 /// 64 bits containing a foreground and background [`NcChannel_u32`].
115 ///
116 /// It's recommended to use [`NcChannels`][crate::NcChannels] instead.
117 ///
118 /// At render time, both 24-bit [`NcRgb_u32`] values are quantized down to
119 /// terminal capabilities, if necessary. There's a clear path to 10-bit
120 /// support should we one day need it.
121 ///
122 /// ## Default Color
123 ///
124 /// The "default color" is best explained by [color(3NCURSES)][0] and
125 /// [default_colors(3NCURSES)][1]. Ours is the same concept.
126 ///
127 /// [0]: https://manpages.debian.org/stretch/ncurses-doc/color.3ncurses.en.html
128 /// [1]: https://manpages.debian.org/stretch/ncurses-doc/default_colors.3ncurses.en.html
129 ///
130 /// **Until the "not default color" bit is set, any color you load will be ignored.**
131 ///
132 /// ## Diagram
133 ///
134 /// ```txt
135 /// ~~AA~~~~|RRRRRRRR|GGGGGGGG|BBBBBBBB║~~AA~~~~|RRRRRRRR|GGGGGGGG|BBBBBBBB
136 /// ↑↑↑↑↑↑↑↑↑↑↑↑ foreground ↑↑↑↑↑↑↑↑↑↑↑║↑↑↑↑↑↑↑↑↑↑↑↑ background ↑↑↑↑↑↑↑↑↑↑↑
137 /// ```
138 ///
139 /// Detailed info (specially on the context-dependent bits on each
140 /// [`NcChannel_u32`]'s 4th byte):
141 ///
142 /// ```txt
143 /// ~foreground channel~
144 /// reserved, must be 0 ↓bits view↓ ↓hex mask↓
145 /// 0·······|········|········|········║········|········|········|········ = 8·······|········
146 ///
147 /// NcChannels::FG_DEFAULT_MASK: foreground is NOT "default color"
148 /// ·1······|········|········|········║········|········|········|········ = 4·······|········
149 ///
150 /// NcChannels::FG_ALPHA_MASK: foreground alpha (2bits)
151 /// ··11····|········|········|········║········|········|········|········ = 3·······|········
152 ///
153 /// NcChannels::FG_PALETTE: foreground uses palette index
154 /// ····1···|········|········|········║········|········|········|········ = ·8······|········
155 ///
156 /// NcChannels::NOBACKGROUND_MASK: glyph is entirely foreground
157 /// ·····1··|········|········|········║········|········|········|········ = ·4······|········
158 ///
159 /// reserved, must be 0
160 /// ······00|········|········|········║········|········|········|········ = ·3······|········
161 ///
162 /// NcChannels::FG_RGB_MASK: foreground in 3x8 RGB (rrggbb)
163 /// ········|11111111|11111111|11111111║········|········|········|········ = ··FFFFFF|········
164 /// ```
165 ///
166 /// ```txt
167 /// ~background channel~
168 /// reserved, must be 0 ↓bits view↓ ↓hex mask↓
169 /// ········|········|········|········║0·······|········|········|········ = ········|8·······
170 ///
171 /// NcChannels::BGDEFAULT_MASK: background is NOT "default color"
172 /// ········|········|········|········║·1······|········|········|········ = ········|4·······
173 ///
174 /// NcChannels::BG_ALPHA_MASK: background alpha (2 bits)
175 /// ········|········|········|········║··11····|········|········|········ = ········|3·······
176 ///
177 /// NcChannels::BG_PALETTE: background uses palette index
178 /// ········|········|········|········║····1···|········|········|········ = ········|·8······
179 ///
180 /// reserved, must be 0
181 /// ········|········|········|········║·····000|········|········|········ = ········|·7······
182 ///
183 /// NcChannels::BG_RGB_MASK: background in 3x8 RGB (rrggbb)
184 /// ········|········|········|········║········|11111111|11111111|11111111 = ········|··FFFFFF
185 /// ```
186 /// `type in C: channels (uint64_t)`
187 ///
188 /// ## `NcChannels` Mask Flags
189 ///
190 /// - [`NcChannels::BG_DEFAULT_MASK`][NcChannels#associatedconstant.BGDEFAULT_MASK]
191 /// - [`NcChannels::BG_ALPHA_MASK`][NcChannels#associatedconstant.BG_ALPHA_MASK]
192 /// - [`NcChannels::BG_PALETTE`][NcChannels#associatedconstant.BG_PALETTE]
193 /// - [`NcChannels::BG_RGB_MASK`][NcChannels#associatedconstant.BG_RGB_MASK]
194 /// - [`NcChannels::FG_DEFAULT_MASK`][NcChannels#associatedconstant.FGDEFAULT_MASK]
195 /// - [`NcChannels::FG_ALPHA_MASK`][NcChannels#associatedconstant.FG_ALPHA_MASK]
196 /// - [`NcChannels::FG_PALETTE`][NcChannels#associatedconstant.FG_PALETTE]
197 /// - [`NcChannels::FG_RGB_MASK`][NcChannels#associatedconstant.FG_RGB_MASK]
198 ///
199 /// [`NcRgb_u32`]: crate::c_api::NcRgb_u32
200 /// [`NcChannel_u32`]: crate::c_api::NcChannel_u32
201 ///
202 pub type NcChannels_u64 = u64;
203
204 /// If this bit is set, we are *not* using the default background color
205 ///
206 /// Note: This is equivalent to
207 /// [`NcChannel::DEFAULT_MASK`][NcChannel#associatedconstant.DEFAULT_MASK]
208 ///
209 /// See the detailed diagram at [`NcChannels`]
210 pub const NC_BGDEFAULT_MASK: u32 = ffi::NC_BGDEFAULT_MASK;
211
212 /// Extract these bits to get the (background) [`NcAlpha`] mask.
213 ///
214 /// Note: This is equivalent to
215 /// [`NcChannel::ALPHA_MASK`][NcChannel#associatedconstant.ALPHA_MASK]
216 ///
217 /// See the detailed diagram at [`NcChannels`]
218 pub const NC_BG_ALPHA_MASK: u32 = ffi::NC_BG_ALPHA_MASK;
219
220 /// If this bit *and* [`NC_BGDEFAULT_MASK`] are set, we're using a
221 /// palette-indexed background color
222 ///
223 /// Note: This is equivalent to
224 /// [`NcChannel::PALETTE_MASK`][NcChannel#associatedconstant.PALETTE_MASK]
225 ///
226 /// See the detailed diagram at [`NcChannels`]
227 pub const NC_BG_PALETTE: u32 = ffi::NC_BG_PALETTE;
228
229 /// Extract these bits to get the background [`NcRgb`][crate::NcRgb] value
230 ///
231 /// Note: This is equivalent to
232 /// [`NcChannel::RGB_MASK`][NcChannel#associatedconstant.RGB_MASK]
233 ///
234 /// See the detailed diagram at [`NcChannels`]
235 pub const NC_BG_RGB_MASK: u32 = ffi::NC_BG_RGB_MASK;
236
237 /// Does this glyph completely obscure the background?
238 ///
239 /// If so, there's no need to emit a background when rasterizing,
240 /// a small optimization. These are also used to track regions into which
241 /// we must not cellblit.
242 pub const NC_NOBACKGROUND_MASK: u64 = ffi::NC_NOBACKGROUND_MASK as u64;
243}