Skip to main content

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}