Log inGet started
Package

volumetricSky.module

Newest version

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 a preset sub-table; every VolumetricSky component field (weatherRegions, maxSteps, taaBlendAlpha, …) by its own name; name names 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. Returns false when 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 resource spawn created.
  • 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 to cloud_noise's files; the weather map is filled when the coverage, cloud type, weatherVariation, weatherExtent, seed or weatherRegions in weather change. 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), which M.enqueueCloudPasses hands the renderer for every view it draws. renderParams is the flat table from snapshotRenderParams().
  • M.find() -> id? — return the id of the entity carrying the scene's VolumetricSky, whatever the entity is named, or nil when no entity carries one.
  • M.despawn() -> () — despawn the entity M.find names. 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's public fields. The clouds are lit by the scene's sun, so setSun's direction moves the scene's sun; its colour and intensity are the preset's sunColor and sunIntensity, 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 declares atmospherics, 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.create with history = 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 by renderScale, 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. Set taaBlendAlpha = 1.0 to disable while still going through the same code path (useful for benchmarking).
  • All public setters write through to VolumetricSky.component's public fields, which means they replicate as Sync if the component is sync-enabled. Tweaks survive scene reloads as long as the same entity is alive.
  • SkyPreset and its defaults are declared here, and the component declares its preset field from them. M.spawn / M.configure read 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.