volumetricSky.module
This package holds more than this page lists. See all of its files in its world.
README.md
volumetricSky
Orchestration backend for the VolumetricSky.component. Owns the
GPU resources the cloud layer needs (the tiling shape and detail noise,
the weather map, the raymarch render target, the per-view accumulation
history, the composite) and exposes a small public surface the component
drives every frame.
The layer is a shell around the planet between two altitudes over the
ground (the planet PhysicalAtmosphere integrates over), so it reaches the
horizon. Its clouds are formed where they stand in the world: a weather map
states coverage, cloud type and density per place, and two tiling noise
textures placed in world units form the clouds. One raymarcher,
cloud_raymarch, draws every sky.
Exports
M.spawn(opts?) -> id— spawn the singleton sky entity, or configure the one already standing, and return its id. Every weather parameter (coverage,sunColor,sunIntensity,windSpeed, …) is settable at the top level or inside apresetsub-table; everyVolumetricSkycomponent field (weatherRegions,maxSteps,taaBlendAlpha, …) by its own name;namenames the entity. Parameters left out keep their current values. An option that names neither raises, listing both sets, and leaves no entity behind. A weather parameter takes the shape its default carries — a number, or an array of that many numbers — and a value of another shape raises naming the parameter. A preset key an earlier cloud layer read (M.RETIRED_PRESET_KEYS:noiseScale,horizExtent, …) is accepted and read by nothing.M.configure(opts) -> boolean— apply those same weather parameters and component fields to the sky already standing. Returnsfalsewhen none has been spawned.M.defaultPreset() -> table— a fresh copy of the weather configuration a sky spawned with no options carries. The copy is the caller's to edit.M.destroy() -> ()— release every resourcespawncreated.M.fillClouds(weather) -> boolean: fill what the clouds are formed from where it does not hold what it should, and return whether this call dispatched a fill. The tiling noise holds no weather, wind or extent, so it is filled once per render device and again after an edit tocloud_noise's files; the weather map is filled when the coverage, cloud type,weatherVariation,weatherExtent, seed orweatherRegionsinweatherchange. Each fill waits until its shader's program is resident.M.volumeBakes() -> number: how many times the tiling noise has been filled since the module loaded.M.weatherBakes() -> number: how many times the weather map has been filled since the module loaded.M.weatherRegionsFault(regions) -> string?: what is wrong with a list of weather regions, or nil.M.setWeatherRegions(regions) -> boolean: author the weather over places in the world on the active sky.M.layerShell() -> table?: where the layer stood for the last dispatch: the planet's centre and radius, the ground level, the base and top altitudes and the march's reach.M.layerTarget() -> string?: the render target holding the layer the frame's last view drew.M.getShaderHandles() -> table: the compute shaders the layer runs (noise,weather,raymarch,taa,surfaces), resolved and compiled.M.dispatchRaymarch(renderParams, viewport) -> ()— pack the frame the layer's passes draw (the raymarch's and the accumulation's uniforms, the layer's targets), whichM.enqueueCloudPasseshands the renderer for every view it draws.renderParamsis the flat table fromsnapshotRenderParams().M.find() -> id?— return the id of the entity carrying the scene'sVolumetricSky, whatever the entity is named, ornilwhen no entity carries one.M.despawn() -> ()— despawn the entityM.findnames. Its component lets go of the cloud layer as it goes, and the last sky to let go releases the layer's GPU resources.M.setCoverage(c) / M.setDensity(g) / M.setSun(dir, color, intensity?) / M.setWind(v)— convenience setters that route through the active component'spublicfields. The clouds are lit by the scene's sun, sosetSun's direction moves the scene's sun; its colour and intensity are the preset'ssunColorandsunIntensity, how brightly and in what tint that sun lights the clouds.M.enqueueCloudPasses(ctx) -> ()— enqueue the layer's passes for the frame; the renderer runs them for every view it draws. Every pass declaresatmospherics, so a camera stating an isolated environment draws no clouds.
Usage
-- The component drives this module automatically. Direct M.* use is
-- rare; the canonical entry point is attaching VolumetricSky to an
-- entity (or loading a preset and passing it to component.add):
local sky = entity.spawn("sky")
sky.component.add("VolumetricSky", {})
-- Driving the layer by hand instead, a frame at a time. Each call creates
-- the resources it needs: the noise and the weather map on the first fill,
-- the render targets at the size the viewport names:
local Sky = require("@builtin::systems.volumetrics.volumetricSky")
Sky.fillClouds({ coverage = 0.5, cloudType = 0.5 })
Sky.dispatchRaymarch(renderParams, { width = 1280, height = 720 })
Notes
- The shape noise is 128^3 RGBA8 (8 MiB), the detail noise 64^3 RGBA8 (1 MiB) and the weather map 256x256 RGBA16F (0.5 MiB), whatever the layer reaches.
- The accumulation is a history target (
renderer.texture.createwithhistory = true): each view the frame draws (the viewport, every camera rendering into a texture, every capture) keeps its own pair of RGBA16F images at its own size scaled byrenderScale, and the pass reprojects them through that view's own camera (@frame.camera). A view's first render, and its first after a cut or a change of size, starts from its own raymarch. SettaaBlendAlpha = 1.0to disable while still going through the same code path (useful for benchmarking). - All public setters write through to
VolumetricSky.component'spublicfields, which means they replicate as Sync if the component is sync-enabled. Tweaks survive scene reloads as long as the same entity is alive. SkyPresetand its defaults are declared here, and the component declares itspresetfield from them.M.spawn/M.configureread that same key set to tell a weather parameter from a component field, so a parameter added to the preset reaches the schema and the option routing in one edit.