sgl_3d/frame_input.rs
1//! What the caller supplies for one frame: the camera, the authored look and
2//! per-frame state. Linear colours and metres. No simulation clock is
3//! advanced here; rendering settings are `settings::Settings`, and point and
4//! spot lights are scene content (`Scene::add_light`).
5mod look;
6
7pub use look::{
8 AgxLook, AutoExposure, BloomParameters, ColorGrading, ColorGradingGlobal, ColorGradingSection,
9 CompensationCurve, CompensationCurveError, Exposure, LocalExposure, MeteringMask,
10 MotionBlurParameters,
11};
12
13use crate::content::lighting::{
14 Backdrop, DirectionalLight, EnvironmentLight, FrameEnvironment, HemisphereLight, Mist,
15};
16use glam::camera;
17use glam::{Mat4, Vec3};
18
19/// Reversed-Z, infinite-far, right-handed perspective. Device depth is
20/// `near / distance`: 1 at the near plane, approaching 0 at infinity.
21pub fn perspective(fov_y_radians: f32, aspect: f32, near: f32) -> Mat4 {
22 camera::rh::proj::directx::perspective_infinite_reverse(fov_y_radians, aspect, near)
23}
24
25/// A render camera. Projection uses reversed-Z device depth (1 near, 0 far),
26/// normally from [`perspective`], in Y-up world space.
27#[derive(Clone, Copy, Debug)]
28pub struct Camera {
29 pub view: Mat4,
30 pub projection: Mat4,
31 pub eye: Vec3,
32}
33
34/// The frame's participating medium, which the volumetric fog lights with
35/// the frame's directional lights and their cascades, the scene's point, spot
36/// and rectangle lights with their shadows, and the frame's ambient light.
37/// The fields are Godot's volumetric fog (`Environment` and `FogMaterial`):
38/// the medium's density falls off above `height` as Godot's fog material's
39/// does, and the camera's froxel volume reaches `length` metres. The scene's
40/// fog volumes (`Scene::update_fog_volumes`) add medium where they lie.
41#[derive(Clone, Copy, Debug, PartialEq)]
42pub struct Fog {
43 /// Extinction per metre at and below `height`; zero is no medium, and
44 /// with no fog volumes either the fog does not run.
45 pub density: f32,
46 /// Linear RGB single-scattering albedo: the share of extinction that
47 /// scatters light rather than absorbing it.
48 pub albedo: [f32; 3],
49 /// Henyey–Greenstein asymmetry, -0.9..0.9: positive scatters forward,
50 /// so light shafts brighten looking toward their light.
51 pub anisotropy: f32,
52 /// The share of the frame's ambient light (the hemisphere fill and
53 /// environment diffuse) the medium and fog volumes scatter, as Godot's
54 /// `volumetric_fog_ambient_inject`. By default 0, as Godot's, so only
55 /// lights light the medium; up to 1 lets the sky's light glow in the
56 /// fog, less where the sky does not reach, such as inside a tunnel.
57 pub ambient: f32,
58 /// World Y below which the density is whole.
59 pub height: f32,
60 /// How fast the density halves above `height`, per metre (Godot's
61 /// `height_falloff`: density × 2^(-falloff × metres above)); zero is
62 /// uniform.
63 pub height_falloff: f32,
64 /// The view depth in metres the froxel volume covers; anything farther
65 /// takes the fog as far as it, the sky by `sky_affect`.
66 pub length: f32,
67 /// How far from the camera the medium begins, metres along the view
68 /// ray: nearer, it is absent (no extinction, no scattered light), and
69 /// beyond, it builds as from the camera, so far-only fog leaves the
70 /// foreground untouched. Fog volumes are not affected. 0 (the default)
71 /// starts it at the camera; NaN, infinite and negative values are 0. The
72 /// volume covers `length` of view depth, which is `length` metres away
73 /// at the frame's centre and farther toward its edges: a start at
74 /// `length` leaves the medium only toward the edges, and one at or
75 /// beyond the corners' distance leaves it out of the volume.
76 pub start: f32,
77 /// How much of its fog the sky takes, 0..=1 (Godot's
78 /// `volumetric_fog_sky_affect`): 1 fogs it as if at `length`, 0 leaves
79 /// it clear. Fog volumes in front of the sky are part of its fog.
80 pub sky_affect: f32,
81}
82
83impl Default for Fog {
84 /// No medium, with Godot's defaults: albedo white, anisotropy 0.2, no
85 /// ambient light, uniform, a 64 m volume starting at the camera and the
86 /// whole fog on the sky.
87 fn default() -> Self {
88 Self {
89 density: 0.,
90 albedo: [1.; 3],
91 anisotropy: 0.2,
92 ambient: 0.,
93 height: 0.,
94 height_falloff: 0.,
95 length: 64.,
96 start: 0.,
97 sky_affect: 1.,
98 }
99 }
100}
101
102impl Fog {
103 /// `start` as the fog takes it: NaN, infinite and negative values are 0.
104 pub(crate) fn effective_start(&self) -> f32 {
105 if self.start.is_finite() && self.start > 0. {
106 self.start
107 } else {
108 0.
109 }
110 }
111}
112
113/// One frame's camera, authored look and per-frame state.
114#[derive(Clone, Copy)]
115pub struct FrameInput {
116 pub camera: Camera,
117 /// The camera jumped (a cut, teleport or discontinuous time): history
118 /// restarts. A target-changing resize and another scene restart it
119 /// without this.
120 pub camera_cut: bool,
121 /// Presentation seconds, which place materials' scrolling normal layers
122 /// and the mist's drift. Double precision, so sessions hours long keep
123 /// their animation smooth.
124 pub elapsed_seconds: f64,
125 /// Milliseconds since the previous frame: FSR's `frameTimeDelta` and
126 /// auto exposure's time step.
127 pub frame_time_ms: f32,
128 /// Enabled material visibility groups: a material draws while every bit
129 /// of its `visibility_group` is set here.
130 pub visibility_mask: u32,
131 /// What surrounds the frame: one of the scene's environment maps,
132 /// which lights the frame, draws its sky and backs its reflections, or
133 /// a procedural sky lit by `directional_lights`; with `None`, or a map
134 /// the scene no longer has, no environment does.
135 pub environment: FrameEnvironment,
136 /// Up to two directional lights; `None` is no light. Under a
137 /// procedural sky (`FrameEnvironment::Sky`) each is its light above the
138 /// air, which reaches the scene through it.
139 pub directional_lights: [Option<DirectionalLight>; 2],
140 pub hemisphere_light: HemisphereLight,
141 /// How `environment` lights surfaces' diffuse lobe. Their specular
142 /// lobe takes `reflection_environment`.
143 pub diffuse_environment: EnvironmentLight,
144 pub backdrop: Backdrop,
145 /// Baked (fixed) lighting: lightmaps, irradiance atlases, instances'
146 /// baked irradiance and the irradiance volume.
147 pub baked_lighting: bool,
148 /// The volumetric fog and mist, while `Settings::atmosphere` is on too.
149 /// Off by default, as Godot's `volumetric_fog_enabled` and
150 /// `fog_enabled`: a game turns it on where it wants fog or mist.
151 pub atmosphere: bool,
152 pub fog: Fog,
153 pub mist: Mist,
154 /// How `environment` lights surfaces' specular lobe where no baked
155 /// probe does: source completion beyond the probes, probe captures' and
156 /// ray hits' environment specular, and the sky probe captures record.
157 pub reflection_environment: EnvironmentLight,
158 pub exposure: Exposure,
159 /// Off (1, 1) by default.
160 pub local_exposure: LocalExposure,
161 pub bloom: BloomParameters,
162 /// While `Settings::motion_blur` is on.
163 pub motion_blur: MotionBlurParameters,
164 pub color_grading: ColorGrading,
165 /// XeGTAO's search radius in world metres, clamped to 0.01..=10000
166 /// (NaN to 0.01). `Settings::ambient_occlusion` turns ambient occlusion
167 /// off.
168 pub ambient_occlusion_radius: f32,
169 /// How far screen-space indirect light reaches, in world metres,
170 /// clamped to 1..=25 (NaN to 5). `Settings::screen_space_indirect`
171 /// turns it on.
172 pub screen_space_indirect_radius: f32,
173}
174
175impl FrameInput {
176 /// `camera` with no lights, fog medium, mist, visibility groups
177 /// or environment; the environment's diffuse lighting, reflections and
178 /// backdrop unturned at intensity 1; baked lighting on and atmosphere
179 /// off; a 60 Hz frame time; a fixed exposure of 0 stops and no local
180 /// exposure; and the default bloom, motion blur and colour grading, an
181 /// ambient occlusion radius of 0.5 m and a screen-space indirect light
182 /// radius of 5 m.
183 pub fn new(camera: Camera) -> Self {
184 Self {
185 camera,
186 camera_cut: false,
187 elapsed_seconds: 0.,
188 frame_time_ms: 1000. / 60.,
189 visibility_mask: 0,
190 environment: FrameEnvironment::None,
191 directional_lights: [None; 2],
192 hemisphere_light: HemisphereLight::default(),
193 diffuse_environment: EnvironmentLight::default(),
194 backdrop: Backdrop::Environment {
195 yaw: 0.,
196 brightness: 1.,
197 },
198 baked_lighting: true,
199 atmosphere: false,
200 fog: Fog::default(),
201 mist: Mist::default(),
202 reflection_environment: EnvironmentLight::default(),
203 exposure: Exposure::default(),
204 local_exposure: LocalExposure::default(),
205 bloom: BloomParameters::default(),
206 motion_blur: MotionBlurParameters::default(),
207 color_grading: ColorGrading::default(),
208 ambient_occlusion_radius: 0.5,
209 screen_space_indirect_radius: 5.,
210 }
211 }
212}