three_d/core/
render_states.rs

1//!
2//! Definitions of the input state needed for any draw call.
3//!
4
5///
6/// A set of render specific states that has to be specified at each render call.
7///
8#[derive(Debug, Copy, Clone, Default)]
9pub struct RenderStates {
10    ///
11    /// Defines which channels (red, green, blue, alpha and depth) to write to in a render call.
12    ///
13    pub write_mask: WriteMask,
14
15    ///
16    /// Defines the depth test in a render call.
17    /// The depth test determines whether or not a fragment from the current render call should be discarded
18    /// when comparing its depth with the depth of the current fragment.
19    ///
20    pub depth_test: DepthTest,
21
22    ///
23    /// Defines which type of blending to use for a render call.
24    /// Blending allows combining each color channel of a render call with the color already in the
25    /// color channels of the render target.
26    /// This is usually used to simulate transparency.
27    ///
28    pub blend: Blend,
29
30    ///
31    /// Defines whether the triangles that are backfacing, frontfacing or both should be skipped in a render call.
32    ///
33    pub cull: Cull,
34}
35
36///
37/// Defines whether the triangles that are backfacing, frontfacing, both or none should be rendered in a render call.
38///
39#[derive(Debug, Copy, Clone, PartialEq)]
40pub enum Cull {
41    /// Render both front- and backfacing triangles.
42    None,
43    /// Render only frontfacing triangles.
44    Back,
45    /// Render only backfacing triangles.
46    Front,
47    /// Render nothing.
48    FrontAndBack,
49}
50
51impl Default for Cull {
52    fn default() -> Self {
53        Self::None
54    }
55}
56
57///
58/// Determines whether or not a fragment/pixel from the current render call should be discarded
59/// when comparing its depth with the depth of the current fragment/pixel.
60///
61/// **Note:** Depth test is disabled if the render call is not writing to a depth texture.
62///
63#[allow(missing_docs)]
64#[derive(Debug, Copy, Clone, PartialEq)]
65pub enum DepthTest {
66    Never,
67    Less,
68    Equal,
69    LessOrEqual,
70    Greater,
71    NotEqual,
72    GreaterOrEqual,
73    Always,
74}
75
76impl Default for DepthTest {
77    fn default() -> Self {
78        Self::Less
79    }
80}
81
82///
83/// Defines which channels (red, green, blue, alpha and depth) to write to in a render call.
84///
85#[allow(missing_docs)]
86#[derive(Debug, Copy, Clone, PartialEq)]
87pub struct WriteMask {
88    pub red: bool,
89    pub green: bool,
90    pub blue: bool,
91    pub alpha: bool,
92    pub depth: bool,
93}
94
95impl WriteMask {
96    ///
97    /// Writes to all channels (red, green, blue, alpha and depth).
98    ///
99    pub const COLOR_AND_DEPTH: Self = Self {
100        red: true,
101        green: true,
102        blue: true,
103        alpha: true,
104        depth: true,
105    };
106
107    ///
108    /// Writes to all color channels (red, green, blue and alpha).
109    ///
110    pub const COLOR: Self = Self {
111        red: true,
112        green: true,
113        blue: true,
114        alpha: true,
115        depth: false,
116    };
117
118    ///
119    /// Writes to the depth channel only.
120    ///
121    pub const DEPTH: Self = Self {
122        red: false,
123        green: false,
124        blue: false,
125        alpha: false,
126        depth: true,
127    };
128
129    ///
130    /// Do not write to any channels.
131    ///
132    pub const NONE: Self = Self {
133        red: false,
134        green: false,
135        blue: false,
136        alpha: false,
137        depth: false,
138    };
139}
140
141impl Default for WriteMask {
142    fn default() -> Self {
143        Self::COLOR_AND_DEPTH
144    }
145}
146
147///
148/// Defines which type of blending to use for a render call.
149/// Blending allows combining each color channel of a render call with the color already in the
150/// color channels of the render target.
151/// This is usually used to simulate transparency.
152///
153#[allow(missing_docs)]
154#[derive(Debug, Copy, Clone, PartialEq)]
155pub enum Blend {
156    Enabled {
157        source_rgb_multiplier: BlendMultiplierType,
158        source_alpha_multiplier: BlendMultiplierType,
159        destination_rgb_multiplier: BlendMultiplierType,
160        destination_alpha_multiplier: BlendMultiplierType,
161        rgb_equation: BlendEquationType,
162        alpha_equation: BlendEquationType,
163    },
164    Disabled,
165}
166
167impl Blend {
168    ///
169    /// Standard OpenGL transparency blending parameters which, for the usual case of being able to see through objects, does not work on web.
170    /// In that case, use [Blend::TRANSPARENCY] instead which works the same way on desktop and web.
171    ///
172    pub const STANDARD_TRANSPARENCY: Self = Self::Enabled {
173        source_rgb_multiplier: BlendMultiplierType::SrcAlpha,
174        source_alpha_multiplier: BlendMultiplierType::One,
175        destination_rgb_multiplier: BlendMultiplierType::OneMinusSrcAlpha,
176        destination_alpha_multiplier: BlendMultiplierType::Zero,
177        rgb_equation: BlendEquationType::Add,
178        alpha_equation: BlendEquationType::Add,
179    };
180
181    ///
182    /// Transparency blending parameters that works on both desktop and web. For the standard OpenGL parameters, see [Blend::STANDARD_TRANSPARENCY].
183    ///
184    pub const TRANSPARENCY: Self = Self::Enabled {
185        source_rgb_multiplier: BlendMultiplierType::SrcAlpha,
186        source_alpha_multiplier: BlendMultiplierType::Zero,
187        destination_rgb_multiplier: BlendMultiplierType::OneMinusSrcAlpha,
188        destination_alpha_multiplier: BlendMultiplierType::One,
189        rgb_equation: BlendEquationType::Add,
190        alpha_equation: BlendEquationType::Add,
191    };
192
193    ///
194    /// Adds the color of the render target with the output color of the render call.
195    ///
196    pub const ADD: Self = Self::Enabled {
197        source_rgb_multiplier: BlendMultiplierType::One,
198        source_alpha_multiplier: BlendMultiplierType::One,
199        destination_rgb_multiplier: BlendMultiplierType::One,
200        destination_alpha_multiplier: BlendMultiplierType::One,
201        rgb_equation: BlendEquationType::Add,
202        alpha_equation: BlendEquationType::Add,
203    };
204}
205
206impl Default for Blend {
207    fn default() -> Self {
208        Self::Disabled
209    }
210}
211
212///
213/// Value multiplied with the source or target color or alpha value in [Blend].
214///
215#[allow(missing_docs)]
216#[derive(Debug, Copy, Clone, PartialEq)]
217pub enum BlendMultiplierType {
218    Zero,
219    One,
220    SrcColor,
221    OneMinusSrcColor,
222    DstColor,
223    OneMinusDstColor,
224    SrcAlpha,
225    OneMinusSrcAlpha,
226    DstAlpha,
227    OneMinusDstAlpha,
228    SrcAlphaSaturate,
229}
230
231///
232/// How the source and target color or alpha value are combined in [Blend].
233///
234#[allow(missing_docs)]
235#[derive(Debug, Copy, Clone, PartialEq)]
236pub enum BlendEquationType {
237    Add,
238    Subtract,
239    ReverseSubtract,
240    Max,
241    Min,
242}
three_d/core/render_states.rs

three_d/core/
render_states.rs
