Ductane v1.4.0
Contents

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

ProceduralSkyDaySky
Set bya zenith, a horizon, a ground and a sun, by handthe hour, or a sun placed by hand
Givesradiance by direction, prefiltered into an EnvironmentMapa Lighting: the light's direction and color, the sky's zenith, horizon and ground, and the sky's light
Drawn byyour own sky pass, sampling the cubeSkyPass
Night, moon, stars, cloudsnoneyes

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.

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.