libnotcurses_sys/
scale.rs

1//! `NcScale`
2
3/// Indicates how to scale an [`NcVisual`][crate::NcVisual] during rendering.
4///
5/// # Default
6/// *[`NcScale::None`]*
7///
8/// # Application
9/// The scaling preferences are applied only for the context of
10/// [`NcVisual.render`][crate::NcVisual#method.render].
11///
12/// You can think of it as the following pipeline, where you still have
13/// the original frame:
14/// ```txt
15/// NcVisual::from_file() → frame → NcVisual.render() → scaling → output_frame → blit
16/// ```
17///
18/// Whereas
19/// [`NcVisual.resize`][crate::NcVisual#method.resize] and
20/// [`NcVisual.resize_noninterpolative`][crate::NcVisual#method.resize_noninterpolative]
21/// are changing that original frame.
22///
23#[repr(u32)]
24#[non_exhaustive]
25#[derive(Clone, Copy, PartialEq, Eq)]
26pub enum NcScale {
27    /// Maintains the original size. Will Apply no scaling.
28    None = c_api::NCSCALE_NONE,
29
30    /// Maintains the aspect ratio.
31    ///
32    /// Scales an `NcVisual` to the `NcPlane`'s size without stretching.
33    Scale = c_api::NCSCALE_SCALE,
34
35    /// Like `None`, maintains the original size, while admitting
36    /// high-resolution blitters that don't preserve the aspect ratio.
37    NoneHiRes = c_api::NCSCALE_NONE_HIRES,
38
39    /// Like `Scale`, maintains the aspect ratio, while admitting
40    /// high-resolution blitters that don't preserve the aspect ratio.
41    ScaleHiRes = c_api::NCSCALE_SCALE_HIRES,
42
43    /// Throws away aspect ratio.
44    ///
45    /// Stretches and scales the `NcVisual` in an attempt to fill the entirety
46    /// of the `NcPlane`.
47    Stretch = c_api::NCSCALE_STRETCH,
48}
49
50mod core_impls {
51    use super::{c_api, NcScale};
52    use core::fmt;
53
54    impl Default for NcScale {
55        fn default() -> Self {
56            Self::None
57        }
58    }
59
60    impl fmt::Display for NcScale {
61        fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
62            use NcScale::*;
63            write!(
64                f,
65                "{}",
66                match self {
67                    None => "None",
68                    Scale => "Scale",
69                    NoneHiRes => "NoneHiRes",
70                    ScaleHiRes => "ScaleHiRes",
71                    Stretch => "Stretch",
72                }
73            )
74        }
75    }
76
77    impl fmt::Debug for NcScale {
78        fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
79            write!(f, "NcScale {{ {} }}", self)
80        }
81    }
82
83    impl From<c_api::NcScale_u32> for NcScale {
84        fn from(scale: c_api::NcScale_u32) -> Self {
85            use {c_api::*, NcScale::*};
86            match scale {
87                NCSCALE_NONE => None,
88                NCSCALE_SCALE => Scale,
89                NCSCALE_NONE_HIRES => NoneHiRes,
90                NCSCALE_SCALE_HIRES => ScaleHiRes,
91                NCSCALE_STRETCH => Stretch,
92                _ => Self::default(),
93            }
94        }
95    }
96
97    impl From<NcScale> for c_api::NcScale_u32 {
98        fn from(scale: NcScale) -> Self {
99            use {c_api::*, NcScale::*};
100            match scale {
101                None => NCSCALE_NONE,
102                Scale => NCSCALE_SCALE,
103                NoneHiRes => NCSCALE_NONE_HIRES,
104                ScaleHiRes => NCSCALE_SCALE_HIRES,
105                Stretch => NCSCALE_STRETCH,
106            }
107        }
108    }
109}
110
111pub(crate) mod c_api {
112    use crate::c_api::ffi;
113
114    /// Indicates how to scale an [`NcVisual`][crate::NcVisual] during rendering.
115    ///
116    /// It's recommended to use [`NcScale`][crate::NcScale] instead.
117    ///
118    /// # Associated `c_api` constants
119    ///
120    /// - [`NCSCALE_NONE`] will apply no scaling.
121    /// - [`NCSCALE_SCALE`] scales a visual to the plane's size,
122    ///   maintaining aspect ratio.
123    /// - [`NCSCALE_STRETCH`] stretches and scales the image in an
124    ///   attempt to fill the entirety of the plane.
125    /// - [`NCSCALE_NONE_HIRES`] like `NONE` admitting high-res blitters.
126    /// - [`NCSCALE_SCALE_HIRES`] like `CALE` admitting high-res blitters.
127    ///
128    /// The `NCSCALE_*` preferences are applied only for the context of
129    /// [`NcVisual.render`][crate::NcVisual#method.render].
130    /// You can think of it as a pipeline:
131    ///
132    /// ```txt
133    /// NcVisual::fromfile() → frame → NcVisual.render() → scaling → output frame → blit
134    /// ```
135    ///
136    /// where you still have the original frame. Whereas
137    /// [`NcVisual.resize`][crate::NcVisual#method.resize] and
138    /// [`NcVisual.resize_noninterpolative`][crate::NcVisual#method.resize_noninterpolative]
139    /// are changing that original frame.
140    pub type NcScale_u32 = ffi::ncscale_e;
141
142    /// [`NcScale_u32`] mode that maintains the original size.
143    pub const NCSCALE_NONE: NcScale_u32 = ffi::ncscale_e_NCSCALE_NONE;
144
145    /// [`NcScale_u32`] mode that maintains the aspect ratio.
146    pub const NCSCALE_SCALE: NcScale_u32 = ffi::ncscale_e_NCSCALE_SCALE;
147
148    /// [`NcScale_u32`] mode that throws away the aspect ratio.
149    pub const NCSCALE_STRETCH: NcScale_u32 = ffi::ncscale_e_NCSCALE_STRETCH;
150
151    /// [`NcScale_u32`] mode that maintains the original size, admitting
152    /// high-resolution blitters that don't preserve the aspect ratio.
153    pub const NCSCALE_NONE_HIRES: NcScale_u32 = ffi::ncscale_e_NCSCALE_NONE_HIRES;
154
155    /// [`NcScale_u32`] mode that maintains the aspect ratio, admitting
156    /// high-resolution blitters that don't preserve the aspect ratio.
157    pub const NCSCALE_SCALE_HIRES: NcScale_u32 = ffi::ncscale_e_NCSCALE_SCALE_HIRES;
158}
libnotcurses_sys/scale.rs

libnotcurses_sys/
scale.rs
