libnotcurses_sys/blitter/
mod.rs

1//! `NcBlitter`
2
3// functions already exported by bindgen: 4
4// ------------------------------------------
5// (#) test:  0
6// (W) wrap: 4
7// ------------------------------------------
8//W+ ncblit_bgrx
9//W+ ncblit_rgb_loose
10//W+ ncblit_rgb_packed
11//W+ ncblit_rgba
12
13mod methods;
14
15/// The blitter mode to use for rasterizing an [`NcVisual`][crate::NcVisual].
16///
17/// We never blit full blocks, but instead spaces (more efficient) with the
18/// background set to the desired foreground.
19///
20/// # Default
21/// *[`NcBlitter::Default`]*
22///
23/// # Degradation
24///
25/// There is a mechanism of graceful degradation, that works as follows:
26/// - without braille support, [`Braille`] decays to [`Sextant`].
27/// - without bitmap support, [`Pixel`] decays to [`Sextant`].
28/// - without sextant support, [`Sextant`] decays to [`Quadrant`].
29/// - without quadrant support, [`Quadrant`] decays to [`Half`].
30/// - the only viable blitters in ASCII are [`Ascii`] and [`Pixel`].
31///
32/// If you don't want this behaviour you have to set the
33/// *[`NcVisualFlag::NoDegrade`]* on [`NcVisualOptions`] or call
34/// *[`degrade(false)`]* on [`NcVisualOptionsBuilder`].
35///
36/// [`Braille`]: NcBlitter::Braille
37/// [`Pixel`]: NcBlitter::Pixel
38/// [`Ascii`]: NcBlitter::Ascii
39/// [`Half`]: NcBlitter::Half
40/// [`Quadrant`]: NcBlitter::Quadrant
41/// [`Sextant`]: NcBlitter::Sextant
42/// [`NcVisualFlag::noDegrade`]: crate::NcVisualFlag#associatedconstant.noDegrade
43/// [`NcVisualOptions`]: crate::NcVisualOptions
44/// [`degrade(false)`]: crate::NcVisualOptionsBuilder#method.degrade
45/// [`NcVisualOptionsBuilder`]: crate::NcVisualOptionsBuilder
46#[repr(u32)]
47#[non_exhaustive]
48#[derive(Clone, Copy, PartialEq, Eq)]
49pub enum NcBlitter {
50    Default = c_api::NCBLIT_DEFAULT,
51
52    /// Blitter mode using only spaces, compatible with ASCII (1x1).
53    Ascii = c_api::NCBLIT_1x1,
54
55    /// Blitter mode using halves + `Ascii` (2x1).
56    /// ▄▀
57    Half = c_api::NCBLIT_2x1,
58
59    /// Blitter mode using quadrants + `Half` (2x2).
60    /// ▗▐ ▖▀▟▌▙
61    Quadrant = c_api::NCBLIT_2x2,
62
63    /// Blitter mode using sextants + `Quadrant` (3x2).
64    /// 🬀🬁🬂🬃🬄🬅🬆🬇🬈🬉🬊🬋🬌🬍🬎🬏🬐🬑🬒🬓🬔🬕🬖🬗🬘🬙🬚🬛🬜🬝🬞🬟🬠🬡🬢🬣🬤🬥🬦🬧🬨🬩🬪🬫🬬🬭🬮🬯🬰🬱🬲🬳🬴🬵🬶🬷🬸🬹🬺🬻
65    Sextant = c_api::NCBLIT_3x2,
66
67    /// Blitter mode using braille (4x2).
68    /// ⡀⡄⡆⡇⢀⣀⣄⣆⣇⢠⣠⣤⣦⣧⢰⣰⣴⣶⣷⢸⣸⣼⣾⣿
69    Braille = c_api::NCBLIT_BRAILLE,
70
71    /// Blitter mode using Pixels/Sixels.
72    Pixel = c_api::NCBLIT_PIXEL,
73
74    /// NcBlitter mode using: four vertical levels (4x1).
75    /// █▆▄▂
76    _4x1 = c_api::NCBLIT_4x1,
77
78    /// NcBlitter mode using: eight vertical levels (8x1).
79    /// █▇▆▅▄▃▂▁
80    _8x1 = c_api::NCBLIT_8x1,
81}
82
83/// # Aliases
84impl NcBlitter {
85    pub const _1x1: NcBlitter = NcBlitter::Ascii;
86    pub const _2x1: NcBlitter = NcBlitter::Half;
87    pub const _2x2: NcBlitter = NcBlitter::Quadrant;
88    pub const _3x2: NcBlitter = NcBlitter::Sextant;
89}
90
91mod core_impls {
92    use super::{c_api, NcBlitter};
93    use core::fmt;
94
95    impl Default for NcBlitter {
96        fn default() -> Self {
97            Self::Default
98        }
99    }
100
101    impl fmt::Display for NcBlitter {
102        fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
103            use NcBlitter::*;
104            write!(
105                f,
106                "{}",
107                match self {
108                    Default => "Default",
109                    Ascii => "Ascii",
110                    Half => "Half",
111                    Quadrant => "Quadrant",
112                    Sextant => "Sextant",
113                    Braille => "Braille",
114                    Pixel => "Pixel",
115                    _4x1 => "4x1",
116                    _8x1 => "8x1",
117                }
118            )
119        }
120    }
121
122    impl fmt::Debug for NcBlitter {
123        fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
124            write!(f, "NcBlitter::{}", self)
125        }
126    }
127
128    impl From<c_api::NcBlitter_u32> for NcBlitter {
129        fn from(blitter: c_api::NcBlitter_u32) -> Self {
130            use {c_api::*, NcBlitter::*};
131            match blitter {
132                NCBLIT_DEFAULT => Default,
133                NCBLIT_1x1 => Ascii,
134                NCBLIT_2x1 => Half,
135                NCBLIT_2x2 => Quadrant,
136                NCBLIT_3x2 => Sextant,
137                NCBLIT_BRAILLE => Braille,
138                NCBLIT_PIXEL => Pixel,
139                NCBLIT_4x1 => _4x1,
140                NCBLIT_8x1 => _8x1,
141                _ => Self::default(),
142            }
143        }
144    }
145
146    impl From<NcBlitter> for c_api::NcBlitter_u32 {
147        fn from(blitter: NcBlitter) -> Self {
148            use {c_api::*, NcBlitter::*};
149            match blitter {
150                Default => NCBLIT_DEFAULT,
151                Ascii => NCBLIT_1x1,
152                Half => NCBLIT_2x1,
153                Quadrant => NCBLIT_2x2,
154                Sextant => NCBLIT_3x2,
155                Braille => NCBLIT_BRAILLE,
156                Pixel => NCBLIT_PIXEL,
157                _4x1 => NCBLIT_4x1,
158                _8x1 => NCBLIT_8x1,
159            }
160        }
161    }
162}
163
164pub(crate) mod c_api {
165    use crate::c_api::ffi;
166
167    /// The blitter mode to use for rasterizing an [`NcVisual`][crate::NcVisual].
168    ///
169    /// It's recommended to use [`NcBlitter`][crate::NcBlitter] instead.
170    ///
171    /// # Associated `c_api` constants
172    ///
173    /// - [`NCBLIT_DEFAULT`]
174    /// - [`NCBLIT_1x1`]
175    /// - [`NCBLIT_2x1`]
176    /// - [`NCBLIT_2x2`]
177    /// - [`NCBLIT_3x2`]
178    /// - [`NCBLIT_4x1`]
179    /// - [`NCBLIT_8x1`]
180    /// - [`NCBLIT_BRAILLE`]
181    /// - [`NCBLIT_PIXEL`]
182    pub type NcBlitter_u32 = ffi::ncblitter_e;
183
184    /// [`NcBlitter_u32`] mode where the blitter is automatically chosen.
185    pub const NCBLIT_DEFAULT: NcBlitter_u32 = ffi::ncblitter_e_NCBLIT_DEFAULT;
186    /// [`NcBlitter_u32`] mode using: space, compatible with ASCII.
187    pub const NCBLIT_1x1: NcBlitter_u32 = ffi::ncblitter_e_NCBLIT_1x1;
188    /// [`NcBlitter_u32`] mode using: halves + 1x1 (space).
189    /// ▄▀
190    pub const NCBLIT_2x1: NcBlitter_u32 = ffi::ncblitter_e_NCBLIT_2x1;
191    /// [`NcBlitter_u32`] mode using: quadrants + 2x1.
192    /// ▗▐ ▖▀▟▌▙
193    pub const NCBLIT_2x2: NcBlitter_u32 = ffi::ncblitter_e_NCBLIT_2x2;
194    /// [`NcBlitter_u32`] mode using: sextants.
195    /// 🬀🬁🬂🬃🬄🬅🬆🬇🬈🬉🬊🬋🬌🬍🬎🬏🬐🬑🬒🬓🬔🬕🬖🬗🬘🬙🬚🬛🬜🬝🬞🬟🬠🬡🬢🬣🬤🬥🬦🬧🬨🬩🬪🬫🬬🬭🬮🬯🬰🬱🬲🬳🬴🬵🬶🬷🬸🬹🬺🬻
196    pub const NCBLIT_3x2: NcBlitter_u32 = ffi::ncblitter_e_NCBLIT_3x2;
197    /// [`NcBlitter_u32`] mode using: four vertical levels.
198    /// █▆▄▂
199    pub const NCBLIT_4x1: NcBlitter_u32 = ffi::ncblitter_e_NCBLIT_4x1;
200    /// [`NcBlitter_u32`] mode using: eight vertical levels.
201    /// █▇▆▅▄▃▂▁
202    pub const NCBLIT_8x1: NcBlitter_u32 = ffi::ncblitter_e_NCBLIT_8x1;
203    /// [`NcBlitter_u32`] mode using: 4 rows, 2 cols (braille).
204    /// ⡀⡄⡆⡇⢀⣀⣄⣆⣇⢠⣠⣤⣦⣧⢰⣰⣴⣶⣷⢸⣸⣼⣾⣿
205    pub const NCBLIT_BRAILLE: NcBlitter_u32 = ffi::ncblitter_e_NCBLIT_BRAILLE;
206    /// Sixel/Pixel mode.
207    ///
208    /// See [Sixel in Wikipedia](https://en.wikipedia.org/wiki/Sixel).
209    pub const NCBLIT_PIXEL: NcBlitter_u32 = ffi::ncblitter_e_NCBLIT_PIXEL;
210}
libnotcurses_sys/blitter/mod.rs

libnotcurses_sys/blitter/
mod.rs
