nightshade_api/
environment.rs

1//! Background, grid, fog, bloom, time of day, and other scene wide settings.
2
3use crate::runner::{SUN_NAME, lookup_named};
4use nightshade::ecs::graphics::resources::DepthOfField;
5use nightshade::prelude::*;
6use serde::{Deserialize, Serialize};
7
8/// The tonemapping curve that maps HDR color to the display. `Aces` is the
9/// filmic default; `Reinhard`, `Uncharted2`, `AgX`, `Neutral`, and `None` are
10/// the alternatives.
11pub use nightshade::ecs::graphics::resources::TonemapAlgorithm as Tonemap;
12
13/// What fills the space behind your scene.
14#[derive(Clone, Debug, Serialize, Deserialize, enum2schema::Schema)]
15pub enum Background {
16    /// The procedural sky gradient. The default.
17    Sky,
18    /// The sky with volumetric clouds.
19    CloudySky,
20    /// A procedural starfield.
21    Space,
22    /// A procedural nebula with stars.
23    Nebula,
24    /// A procedural sunset gradient.
25    Sunset,
26    /// A solid color, linear RGBA.
27    Color([f32; 4]),
28    /// An equirectangular hdr image used as a skybox.
29    Hdr(Vec<u8>),
30}
31
32/// Sets the background. [`Background::Color`] switches the atmosphere off and
33/// sets the clear color together, which is the pairing the engine needs. The
34/// procedural skies also recapture image based lighting so reflective
35/// surfaces pick up the new sky.
36pub fn set_background(world: &mut World, background: Background) {
37    match background {
38        Background::Sky => set_atmosphere(world, Atmosphere::Sky),
39        Background::CloudySky => set_atmosphere(world, Atmosphere::CloudySky),
40        Background::Space => set_atmosphere(world, Atmosphere::Space),
41        Background::Nebula => set_atmosphere(world, Atmosphere::Nebula),
42        Background::Sunset => set_atmosphere(world, Atmosphere::Sunset),
43        Background::Color(color) => {
44            world.resources.render_settings.atmosphere = Atmosphere::None;
45            world.resources.render_settings.clear_color = color;
46        }
47        Background::Hdr(bytes) => {
48            load_hdr_skybox(world, bytes);
49        }
50    }
51}
52
53fn set_atmosphere(world: &mut World, atmosphere: Atmosphere) {
54    world.resources.render_settings.atmosphere = atmosphere;
55    capture_procedural_atmosphere_ibl(world, atmosphere, 0.0);
56}
57
58/// Shows or hides the reference grid. On by default.
59#[inline]
60pub fn show_grid(world: &mut World, enabled: bool) {
61    world.resources.debug_draw.show_grid = enabled;
62}
63
64/// Sets the ambient light color, linear RGBA.
65#[inline]
66pub fn set_ambient(world: &mut World, color: [f32; 4]) {
67    world.resources.render_settings.ambient_light = color;
68}
69
70/// Enables distance fog between `Fog::start` and `Fog::end`, or disables it
71/// with `None`.
72#[inline]
73pub fn set_fog(world: &mut World, fog: Option<Fog>) {
74    world.resources.render_settings.fog = fog;
75}
76
77/// Toggles bloom. Emissive materials glow when this is on.
78#[inline]
79pub fn set_bloom(world: &mut World, enabled: bool) {
80    world.resources.render_settings.bloom_enabled = enabled;
81}
82
83/// Sets the bloom strength. The default is 0.5: lower keeps the glow subtle,
84/// higher blooms hard. Has no visible effect unless [`set_bloom`] is on.
85#[inline]
86pub fn set_bloom_intensity(world: &mut World, intensity: f32) {
87    world.resources.render_settings.bloom_intensity = intensity;
88}
89
90/// Sets the hour of the day from 0.0 to 24.0. Switches the sky to the day
91/// and night atmosphere and puts the default sun under its control, so the
92/// sun arcs and the light warms and cools with the hour. The hour you pass is
93/// authoritative, so call this every frame to animate time.
94pub fn set_time_of_day(world: &mut World, hour: f32) {
95    if world
96        .resources
97        .renderer_state
98        .day_night
99        .sun_entity
100        .is_none()
101    {
102        world.resources.renderer_state.day_night.sun_entity = lookup_named(world, SUN_NAME);
103    }
104    world.resources.render_settings.atmosphere = Atmosphere::DayNight;
105    world.resources.renderer_state.day_night.auto_cycle = true;
106    world.resources.renderer_state.day_night.speed = 0.0;
107    world.resources.renderer_state.day_night.hour = hour;
108}
109
110/// Sets the manual exposure multiplier. 1.0 is neutral, above brightens,
111/// below darkens.
112#[inline]
113pub fn set_exposure(world: &mut World, exposure: f32) {
114    world.resources.render_settings.color_grading.exposure = exposure;
115}
116
117/// Sets depth of field. The engine ships presets: `DepthOfField::portrait()`,
118/// `cinematic()`, `macro_shot()`, `landscape()`, and `tilt_shift()`. Disable
119/// it by passing a default with `enabled` false.
120#[inline]
121pub fn set_depth_of_field(world: &mut World, depth_of_field: DepthOfField) {
122    world.resources.render_settings.depth_of_field = depth_of_field;
123}
124
125/// Toggles screen-space ambient occlusion, the contact shadowing that darkens
126/// creases and where objects meet.
127#[inline]
128pub fn set_ssao(world: &mut World, enabled: bool) {
129    world.resources.render_settings.ssao_enabled = enabled;
130}
131
132/// Toggles screen-space reflections on glossy surfaces.
133#[inline]
134pub fn set_ssr(world: &mut World, enabled: bool) {
135    world.resources.render_settings.ssr_enabled = enabled;
136}
137
138/// Toggles screen-space global illumination, one screen-space bounce of indirect
139/// light between surfaces.
140#[inline]
141pub fn set_ssgi(world: &mut World, enabled: bool) {
142    world.resources.render_settings.ssgi_enabled = enabled;
143}
144
145/// Toggles temporal antialiasing. On by default.
146#[inline]
147pub fn set_taa(world: &mut World, enabled: bool) {
148    world.resources.render_settings.taa_enabled = enabled;
149}
150
151/// Sets the tonemapping curve that maps HDR to the display.
152#[inline]
153pub fn set_tonemap(world: &mut World, tonemap: Tonemap) {
154    world
155        .resources
156        .render_settings
157        .color_grading
158        .tonemap_algorithm = tonemap;
159}
160
161/// Sets color grading. `saturation` and `contrast` are multipliers where 1.0 is
162/// neutral, `brightness` is an offset where 0.0 is neutral.
163#[inline]
164pub fn set_color_grading(world: &mut World, saturation: f32, contrast: f32, brightness: f32) {
165    let grading = &mut world.resources.render_settings.color_grading;
166    grading.saturation = saturation;
167    grading.contrast = contrast;
168    grading.brightness = brightness;
169}
170
171/// Sets the window title.
172#[inline]
173pub fn set_title(world: &mut World, title: &str) {
174    world.resources.window.title = title.to_string();
175}
176
177/// Saves a screenshot of the next rendered frame to `path` as a png.
178pub fn screenshot(world: &mut World, path: std::path::PathBuf) {
179    queue_render_command(
180        world,
181        RenderCommand::CaptureScreenshot {
182            path: Some(path),
183            max_dimension: None,
184        },
185    );
186}
nightshade_api/environment.rs

nightshade_api/
environment.rs
