libnotcurses_sys/pixel/
mod.rs

1//! The `NcPixel` API facilitates direct management of the pixels within an
2//! [`NcVisual`] (`NcVisuals` keep a backing store of 32-bit RGBA pixels,
3//! and render them down to terminal graphics in [`NcVisual.blit`].
4//!
5//! [`NcVisual`]: crate::NcVisual
6//! [`NcVisual.blit`]: crate::NcVisual#method.blit
7//
8// - NOTE: The pixel color & alpha components are u8 instead of u32.
9//   Because of type enforcing, some runtime checks are now unnecessary.
10//
11// - NOTE: no functions can fail anymore and therefore none returns errors.
12//
13// functions manually reimplemented: 10
14// ------------------------------------------
15// (+) done:  9
16// (#) test:  0
17// (W) wrap: 10
18// ------------------------------------------
19//W+ ncpixel
20//W+ ncpixel_a
21//W+ ncpixel_b
22//W+ ncpixel_g
23//W+ ncpixel_r
24//W+ ncpixel_set_a
25//W+ ncpixel_set_b
26//W+ ncpixel_set_g
27//W+ ncpixel_set_r
28//X  ncpixel_set_rgb8
29
30mod methods;
31pub(crate) mod reimplemented;
32
33mod pixel_impl;
34pub use pixel_impl::NcPixelImpl;
35
36/// An ABGR pixel.
37///
38/// ## Diagram
39///
40/// ```txt
41/// AAAAAAAA BBBBBBBB GGGGGGGG RRRRRRRR
42/// ```
43///
44/// `NcPixel` has 8 bits of alpha,  more or less linear, contributing
45/// directly to the usual alpha blending equation.
46///
47/// We map the 8 bits of alpha to 2 bits of alpha via a [level function][0]
48///
49/// [0]: https://nick-black.com/dankwiki/index.php?title=Notcurses#Transparency.2FContrasting
50///
51/// The `NcPixel` API facilitates direct management of the pixels within an
52/// [`NcVisual`] (`NcVisuals` keep a backing store of 32-bit RGBA pixels,
53/// and render them down to terminal graphics in `NcVisual.render`).
54///
55/// Per libav, we "store as BGRA on little-endian, and ARGB on big-endian".
56/// This is an RGBA *byte-order* scheme. libav emits bytes, not words. Those
57/// bytes are R-G-B-A. When read as words, on little endian this will be ABGR,
58/// and on big-endian this will be RGBA. force everything to LE ABGR, a no-op
59/// on (and thus favoring) little-endian, which is the dominant ordering for
60/// processor architectures (x86, most ARM implementations, base RISC-V
61/// implementations) and their associated memory.
62///
63/// [`NcVisual`]: crate::NcVisual
64#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
65pub struct NcPixel(pub c_api::NcPixel_u32);
66
67mod core_impls {
68    use super::{c_api::NcPixel_u32, NcPixel};
69    use crate::{NcRgb, NcRgba};
70
71    crate::from_primitive![NcPixel, NcPixel_u32];
72    crate::unit_impl_from![NcPixel, NcPixel_u32];
73    crate::unit_impl_fmt![bases+display; NcPixel];
74
75    impl From<NcRgb> for NcPixel {
76        fn from(rgb: NcRgb) -> Self {
77            Self::from_rgb(rgb)
78        }
79    }
80    impl From<NcPixel> for NcRgb {
81        fn from(bgra: NcPixel) -> Self {
82            bgra.to_rgb()
83        }
84    }
85    impl From<NcRgba> for NcPixel {
86        fn from(rgba: NcRgba) -> Self {
87            Self::from_rgba(rgba)
88        }
89    }
90    impl From<NcPixel> for NcRgba {
91        fn from(bgra: NcPixel) -> Self {
92            bgra.to_rgba()
93        }
94    }
95}
96
97/// Contains the pixel geometry information as returned by the
98/// `NcPlane.`[`pixel_geom`][crate::NcPlane#method.pixel_geom] method.
99///
100/// If bitmaps are not supported, the fields `max_bitmap_*` will be 0.
101///
102/// See also [`NcVisualGeometry`][crate::NcVisualGeometry].
103#[derive(Clone, Debug)]
104pub struct NcPixelGeometry {
105    /// The height in pixels of the display region.
106    pub term_y: u32,
107
108    /// The width in pixels of the display region.
109    pub term_x: u32,
110
111    /// The height in pixels of a single cell.
112    pub cell_y: u32,
113
114    /// The width in pixels of a single cell.
115    pub cell_x: u32,
116
117    /// The height in pixels of the maximum displayable bitmap (0 if not supported).
118    pub max_bitmap_y: u32,
119
120    /// The width in pixels of the maximum displayable bitmap (0 if not supported).
121    pub max_bitmap_x: u32,
122}
123
124pub(crate) mod c_api {
125    pub use super::pixel_impl::c_api::*;
126
127    /// An ABGR pixel.
128    ///
129    /// It's recommended to use [`NcPixel`][crate::NcPixel] instead.
130    ///
131    /// ## Diagram
132    ///
133    /// ```txt
134    /// AAAAAAAA BBBBBBBB GGGGGGGG RRRRRRRR
135    /// ```
136    ///
137    /// `type in C: ncpixel (uint32_t)`
138    ///
139    /// `NcPixel` has 8 bits of alpha,  more or less linear, contributing
140    /// directly to the usual alpha blending equation.
141    ///
142    /// We map the 8 bits of alpha to 2 bits of alpha via a [level function][0]
143    ///
144    /// [0]: https://nick-black.com/dankwiki/index.php?title=Notcurses#Transparency.2FContrasting
145    ///
146    /// The `NcPixel` API facilitates direct management of the pixels within an
147    /// [`NcVisual`] (`NcVisuals` keep a backing store of 32-bit RGBA pixels,
148    /// and render them down to terminal graphics in `NcVisual.render`).
149    ///
150    /// Per libav, we "store as BGRA on little-endian, and ARGB on big-endian".
151    /// This is an RGBA *byte-order* scheme. libav emits bytes, not words. Those
152    /// bytes are R-G-B-A. When read as words, on little endian this will be ABGR,
153    /// and on big-endian this will be RGBA. force everything to LE ABGR, a no-op
154    /// on (and thus favoring) little-endian, which is the dominant ordering for
155    /// processor architectures (x86, most ARM implementations, base RISC-V
156    /// implementations) and their associated memory.
157    ///
158    /// [`NcVisual`]: crate::NcVisual
159    pub type NcPixel_u32 = u32;
160}
libnotcurses_sys/pixel/mod.rs

libnotcurses_sys/pixel/
mod.rs
