Log inGet started
World

Builtin Library

Branchmain
Branchesmainpublish
Commit15ce14a4c1

readme.md

skyVisibility

How much of the sky each point of the scene sees, so the sky lights only what can see it.

The sky is light arriving from infinity. Without knowing where the geometry stands, every surface is lit as if it stood under the open sky: a sealed room, a cave or a vehicle cabin is nearly as bright as the ground outside, and a mirror inside reflects the open sky. This package builds a grid over the scene's static geometry that states, for each point, the share of the sky it sees in each direction. The renderer scales the sky light every surface receives by it, on both lobes: the diffuse light along the surface's normal and the reflection along its reflection vector. A sealed room goes dark, a window lets in the sky it opens on, and a mirror indoors reflects the room.

A baked lightmap or probe volume carries the sky light the bake found, bounces included, and stays the quality path. This is the term for everything no bake covers, and it needs no authoring.

It keeps itself

A scene's sky (ProceduralSky or Skybox) claims the field while it stands, so every scene with a sky has one. The field is built from the scene's static geometry (Model.mobility resolving to static): movable things are left out, as a moving mesh would leave its occlusion behind where it stood. An authored edit that moves, adds or removes a static surface rebuilds it once the edits settle, and so does a scene loading or unloading.

local skyVisibility = require("@builtin::systems.skyVisibility.skyVisibility")

skyVisibility.settings()    --> { ready, res, boundsMin, boundsMax, cellSize, cells, ... }
skyVisibility.refresh()     -- rebuild on the next tick: static geometry a script placed in play
skyVisibility.build({ cellSize = 0.5 })  -- build now, from a task
skyVisibility.clear()       -- the sky lights everything again

renderer.reflectionEnvironment().skyVisibility reports the field the renderer holds.

How it is built

compute.buildBvhSliced puts the static triangles on the GPU a slice per frame. Every cell of the grid then runs sky_visibility, which casts 64 rays spread over the sphere and keeps, per axis, the cosine-weighted share of the hemisphere whose rays escape every surface, plus how far its rays along each axis and each diagonal reach before a surface stops them. The dispatches go through the bake's GPU scheduler, a bounded number of rays per frame. The cells reach the renderer GPU to GPU through environment.setSkyVisibility, with no read back.

The grid holds at most 65536 cells over the geometry's extent, with cubic cells no smaller than cellSize (0.25 by default). A large world takes larger cells, which resolve smaller rooms less well; a bake resolves them exactly.

A fragment blends the eight cells around it, each only as far as the fragment is within that cell's reach on every axis and along the diagonal toward it, so a cell outside a wall, or past the edge where two walls meet, does not light the room behind them.

What stands over the air

The field holds the static geometry, at cells sized to the scene. A pass lighting the air (fog, haze, a participating medium) also asks what stands directly over each point this frame, whatever it is: a tree's crown, an awning, a vehicle, an instanced forest. overheadCover draws that as a map: every opaque mesh the renderer holds, entity-owned and instanced alike, seen from straight above into a 256 by 256 square of 1-unit texels centred on the camera, each texel holding the height of the highest surface over it. The draw is a depth-tested pass at the map's size with no shading, run each render ahead of the passes that read it, so a crown that moved or a door that closed is in the map the frame it happens.

local OverheadCover = require("@builtin::systems.skyVisibility.overheadCover")

-- in a render feature's render(ctx):
OverheadCover.enqueue(ctx)                      -- draws the map at afterLighting
ctx.enqueue {
    kind = "compute", program = myPass,
    inputs = { overhead_map = OverheadCover.target(), frame_cam = "@frame.camera" },
    stage = "medium",
}

A pass declares overhead_map as a texture2d in its bindings.yaml, #include "@builtin::systems.skyVisibility.overhead_openness", and calls zero_overhead_openness(p, eye) for the share of the sky a point sees past what stands over it: straight up, and two rings of directions around it. A point under a crown reads near 0, one in a clearing near 1, one off the map 1.

Files

skyVisibility.package/
  skyVisibility.module/          -- builds, publishes and maintains the field
  sky_visibility.computeShader/  -- traces one cell's visibility
  overheadCover.module/          -- draws the overhead cover map
  overhead_cover.shader/         -- the map's draw: each surface's height, from above
  overhead_cover.shaderModule/   -- the map's layout
  overhead_openness.shaderModule/ -- how much sky a point sees past what stands over it