Docs / Rendering
The sky by the hour
DaySky is a sky set by one number, the time of day. The sun's direction, its light, the sky's colors, the moon by night and the eye's adjustment to the dark all follow from that number. SkyPass draws the result behind a scene, with the stars, the moon's phase and the clouds. Use it for a world whose light changes through the day. For a fixed sky prefiltered for reflections, see sky and environment.
How it differs from ProceduralSky
ProceduralSky | DaySky | |
|---|---|---|
| Set by | a zenith, a horizon, a ground and a sun, by hand | the hour, or a sun placed by hand |
| Gives | radiance by direction, prefiltered into an EnvironmentMap | a Lighting: the light's direction and color, the sky's zenith, horizon and ground, and the sky's light |
| Drawn by | your own sky pass, sampling the cube | SkyPass |
| Night, moon, stars, clouds | none | yes |
DaySky builds no cube map. A game that lights with a DaySky takes its ambient from Lighting.skyLight, zenith, horizon and ground.
DaySky
public init(timeOfDay: Float = 15, sun: Sun? = nil, fogDensity: Float = 0, saturation: Float = 1, zenithBrightness: Float = 1, latitude: Float? = nil, yearPosition: Double = 1, moonAge: Double? = nil)
timeOfDay is hours since midnight and wraps around the clock. Without a latitude, the day is an equinox day, the same everywhere. The sun rises in the east (+x) at six, passes south (+z) at noon at 62°, and sets in the west at eighteen. The noon sun isn't straight overhead on purpose: a sun that casts no shadow direction makes every scene look flat. By night, the light comes from the moon, which is always kept above the horizon so that a scene can still be judged.
lighting returns a DaySky.Lighting, in linear radiance for the HDR scene target. A high sun is about 3. direction points toward the light (the sun by day, the moon by night), colour is its radiance, and elevation is the sun's height in radians, below zero at night. exposureStops opens the exposure by up to three stops as the light falls. Hand it to ToneMapping.exposureStops and night reads as dark rather than black. See tone mapping.
sunplaces the sun by hand:DaySky.Sun(heading:height:colour:brightness:), where the heading is a compass bearing in degrees and the height is in degrees above the horizon. The sky's colors still follow the sun's height, so a low sun set by hand still gets a dusk sky.fogDensityis exponential-squared distance fog toward the horizon color. At 0.008, half of a thing is gone at about 100 m.fog(atDistance:)gives the share.saturationandzenithBrightnesschange the sky that is drawn, but not the light it casts, so a deeper blue sky doesn't darken the world's shadows.latitudeandyearPosition(0 is the middle of the northern winter, 2 the middle of summer) make the sun move as it really does: short, low days in winter and long, high ones in summer.DaySky.daylight(latitude:yearPosition:)gives sunrise and sunset, ornilfor polar day or night. A world clock sets both.moonAge, 0…1, is how far through its month the moon is: 0 new, 0.5 full. The moon follows the sun's path, trailing it by its age, and lights the night as brightly as its phase, so a new moon's night is darker. Withnil, the moon is full and opposite the sun.
SkyPass
public func encode(into encoder: MTL4RenderCommandEncoder, frameSlot: Int, viewProjection: simd_float4x4, eye: SIMD3<Float>, lighting: DaySky.Lighting, night: NightSky? = nil, clouds: Clouds? = nil, time: Float = 0, rainbow: Float = 0)
SkyPass(device:sampleCount:) draws a full-screen triangle at the far plane. Draw it first in the scene pass. It neither writes nor tests depth, so everything drawn after it covers it. It sets its own pipeline, depth state and argument table, so set yours again after it. Add its allocations to your residency set. time, in seconds, makes the stars twinkle.
// your game, first in the scene pass let night = sky.night skyPass.encode(into: encoder, frameSlot: frameSlot, viewProjection: viewProjection, eye: eye, lighting: lighting, night: night, clouds: SkyPass.Clouds(layer: layer, picture: cloudPicture), rainbow: weather.rainbow(sunElevation: lighting.elevation))
NightSky comes from DaySky.night. It holds stars and the Milky Way turned about the pole for the latitude, by the hour and the year, fading out at dawn. It also holds the moon, lit on the side that faces the sun, and tonight's aurora. A rainbow needs night. Without a night sky, the pass draws none, whatever rainbow says.
Aurora
DaySky.auroraStrength is tonight's aurora, from 0 to 1. Like the real thing, it shows on most nights near the poles, about one night in twelve at 45°, and never below 35°. Each night's showing is fixed by nightNumber, which a world clock counts, so every player sees the same sky that night. Without a clock there is no natural aurora, because one night repeated forever would mean an aurora in every scene or in none. DaySky.aurora scales it: 0 for none, 1 as the latitude gives it, and up to 2 for every clear night.
Rainbows
Weather.rainbow(sunElevation:) puts a rainbow where physics puts one. It needs rain falling, the sun out through broken cloud, and the sun up but lower than 42°, because the bow sits 42° from the point opposite the sun. A shower clearing on a weather schedule makes one as its rain thins.
Clouds
Weather.clouds(at:) returns the CloudLayer overhead at a moment. The weather sets coverage and darkness. Even a clear sky keeps CloudLayer.fairWeather (0.22), so it is never an empty dome. A storm's towers rise half as tall again. A world's own CloudShape sets the base height (300–4,000 m), the thickness, and the speed, where 1 is CloudLayer.speedAloft, 8 m/s.
Clouds travel steadily along the world's prevailing wind, never at the wind of the moment. Their place is how far they have traveled since the clock began, so a wind that changed would move them that whole distance at once. The pattern repeats every 61,440 m (CloudLayer.period), which keeps a clock of years precise.
CloudPass(device:) raymarches the layer before the scene pass. It returns a picture that SkyPass lays over the sky:
// your game, in encodePrePasses let layer = weather.clouds(at: now) cloudPicture = cloudPass.encode(into: commandBuffer, frameSlot: frameSlot, viewProjection: viewProjection, eye: eye, lighting: lighting, layer: layer, quality: settings.clouds, width: width, height: height)
GraphicsSettings.clouds picks the quality. .high draws at half the screen's width and height, and .medium at a quarter, with fewer steps. .flat returns nil, and SkyPass draws a flat, lit, drifting layer from the same coverage. The Low preset (GraphicsSettings.Preset.low) picks .flat. Each frame's picture is blended with the previous one, because a single frame's steps leave grain at every cloud edge that shimmers like static. Add allocations again whenever picturesChanged is set.
The clouds' shadows come from the same coverage map. CloudLayer.shadow(at:light:) gives the share of sun that gets through on the CPU, and duCloudShadow in DuctaneWeather.h does the same in your shaders, reading CloudPass.coverageMap. Under broken cloud the shadows fall in patches. Under a sky that's nearly covered they fade out, because the weather has already dimmed the sun. See weather.
Related: shadows, the world's clock.