dymokomi/luce-3d
Source of release 0.9.2
0.9.2 / src / renderers / fog_volume.lucb
## Fog volumes (density grids) in the viewport, ray-marched on the GPU as
## Houdini's viewport shows smoke. A FogVolume is made once per grid on the CPU
## (renderers/fog_texels.lucb: dense texels, optical depths toward the light and
## the sky) and uploads its atlas on its first draw; later draws (a camera drag)
## upload nothing. A draw cuts the volume's box into view-aligned slabs, back to
## front, and shades them in one draw with shaders/fog.frag: each fragment
## marches its stretch of the eye ray, jittered per pixel, with Beer–Lambert
## absorption, single scattering of the key light and the sky, and emission
## from a second grid colored through a strip of 256 texels (renderers/
## fog_ramp.lucb). Each drawing takes its grid's own look (luce-geocore's
## VolumeLook, which Volume Visualization sets per grid); which grids draw, and
## from which values, is luce-geocore's fog_show. The slabs are depth tested
## without writing depth, so meshes in front hide the fog and fog in front
## veils meshes behind it, to within one slab (four steps).
from luce_gpu import gpu
import interop
import memory
from luce_std import math
import errors
from luce_geocore.geocore import Vector3, Matrix4, GeometrySet, Bounds
from luce_geocore.kernel import SparseGrid, VolumeLook, FogShow, set_volume, fog_show, fog_show_count
from cameras.perspective import PerspectiveCamera, Projection
from core.material import Color, check_color
from renderers.fog_texels import FogTexels, fog_texels
from renderers.fog_shaders import fog_frag_words, fog_frag_msl, fog_frag_fast_math
from renderers.fog_ramp import strip_texels, emission_strip, emission_fit
## Ray-marching steps in one slab: how finely meshes inside the fog cut it.
let slab_steps: f64 = 4.0
## The most slabs a draw makes; past it, slabs (and steps) grow longer.
let most_slabs: usize = 1024
## The key light's direction luced-3d's viewport uses, toward the light.
let default_light: Vector3 = Vector3(3.0, 5.0, 2.0)
## How a fog volume looks, its numbers: what `look` reads and `set_look`
## overrides (the emission ramp and fields stay the grid's).
pub struct FogLook:
## Extinction per world unit at density 1: multiplies every density.
pub var density: f64 = 1.0
## The smoke's scattering color (white smoke).
pub var color: Color = Color(1.0, 1.0, 1.0)
## Multiplies the optical depth toward the key light: 0 unshadowed.
pub var shadow: f64 = 1.0
## Light emitted per world unit at emission field value 1, and its color
## where no emission ramp colors it.
pub var emission: f64 = 0.0
pub var emission_color: Color = Color(1.0, 1.0, 1.0)
## The ray-marching step, in voxels (0.25..8).
pub var step: f64 = 1.0
## One fog drawing ready to draw: its texels until the first draw uploads
## them, then its atlas texture; and its emission strip, sent again when its
## look changes it.
pub struct FogVolume:
var data: FogTexels
var styled: VolumeLook
var texture: gpu.Texture?
var strip: gpu.Texture?
var strip_stale: bool
var uploads: i64
var strip_uploads: i64
## Fog drawing `index` of `geometry`'s own volume (see `count`), placed by
## `matrix`, lit from `light` (a world direction toward the key light),
## drawn with its grid's look.
pub static func of(geometry: interop.Reference[GeometrySet], index: i64, matrix: Matrix4 = Matrix4(), light: Vector3 = default_light) -> interop.Reference[FogVolume]!:
let made = try fog_volume(try geometry.get(), index, matrix, light)
return try interop.Reference[FogVolume].adopt(made, fog_volume_type, memory.heap)
## How many fog drawings `geometry`'s own volume makes: its fog grids with
## voxels but those lending their values to another's (emission and
## density fields; luce-geocore's fog_show). Level sets keep their surface
## preview; instances are counted by their own sets.
pub static func count(geometry: interop.Reference[GeometrySet]) -> i64!:
return (i64)fog_grid_count(try geometry.get())
## What `of` would make drawing `index`'s texels from (its density grid's
## contents, its emission field's, the placement and the light): equal
## keys make equal volumes, so a held volume is reused. A changed look
## keeps the key unless it names other fields.
pub static func key(geometry: interop.Reference[GeometrySet], index: i64, matrix: Matrix4 = Matrix4(), light: Vector3 = default_light) -> i64!:
return try fog_volume_key(try geometry.get(), index, matrix, light)
## The numbers of drawing `index`'s look (its grid's, the defaults where
## Volume Visualization set none).
pub static func look_of(geometry: interop.Reference[GeometrySet], index: i64) -> FogLook!:
let look = fog_look(try geometry.get(), index) else error(errors.invalid, "the geometry has no such fog drawing")
return numbers_of(&look)
## Draw with drawing `index` of `geometry`'s look from now on (a new look
## of the same grids): the atlas stays; the emission strip is sent again
## if it changed.
pub func restyle(geometry: interop.Reference[GeometrySet], index: i64) -> !:
let look = fog_look(try geometry.get(), index) else error(errors.invalid, "the geometry has no such fog drawing")
restyle_fog(&self, &look)
## The numbers of the look it draws with.
pub func look() -> FogLook:
return numbers_of(&self.styled)
## Whether an emission color ramp colors its emission.
pub func ramped() -> bool:
return self.styled.emission_ramp().length > 0
## Draw with `look`'s numbers from now on (its emission ramp and fields
## stay): the atlas stays.
pub func set_look(look: FogLook) -> !:
try check_color(look.color)
try check_color(look.emission_color)
if not (look.density >= 0.0 and look.density <= 1.0e6) or not (look.step >= 0.25 and look.step <= 8.0):
error(errors.invalid, "a fog look needs a density scale in 0..1e6 and a step of 0.25..8 voxels")
if not (look.shadow >= 0.0 and look.shadow <= 100.0) or not (look.emission >= 0.0 and look.emission <= 1.0e6):
error(errors.invalid, "a fog look needs a shadow scale in 0..100 and an emission scale in 0..1e6")
var styled = self.styled
styled.density = look.density
styled.smoke = Vector3(look.color.red, look.color.green, look.color.blue)
styled.shadow = look.shadow
styled.emission = look.emission
styled.emission_color = Vector3(look.emission_color.red, look.emission_color.green, look.emission_color.blue)
styled.step = look.step
restyle_fog(&self, &styled)
## The highest density.
pub func peak() -> f64:
return self.data.peak
## The world box around its texel box (for framing).
pub func bounds() -> Bounds:
var low = self.data.box.transform_point(corner_of(0))
var high = low
for corner in 1..<(usize)8:
let p = self.data.box.transform_point(corner_of(corner))
low = Vector3(math.min(low.x, p.x), math.min(low.y, p.y), math.min(low.z, p.z))
high = Vector3(math.max(high.x, p.x), math.max(high.y, p.y), math.max(high.z, p.z))
return Bounds(low, high)
## Texels across the box along `axis` (0 x, 1 y, 2 z).
pub func texels(axis: i64) -> i64:
return (i64)self.data.counts[(usize)axis % 3]
## How many times its atlas went to the GPU (once, on its first draw).
pub func upload_count() -> i64:
return self.uploads
## How many times its emission strip went to the GPU (on its first draw,
## and after each look that changed it).
pub func strip_upload_count() -> i64:
return self.strip_uploads
## Draw over what `target` holds, through `camera`: the key light colored
## `key` (intensity folded in) and a sky light of `ambient`. A standalone
## frame (no device) draws nothing.
pub func draw(camera: interop.Reference[PerspectiveCamera], target: interop.View[gpu.RenderTarget], key: Color = Color(0.85, 0.85, 0.85), ambient: f64 = 0.35) -> !:
try check_color(key)
if not (ambient >= 0.0 and ambient <= 100.0): error(errors.invalid, "ambient light must be in 0..100")
let native = try target.get()
var device = gpu.device_of(native) catch failure:
if failure.code != gpu.unavailable: error(failure.code, failure.message)
recover gpu.Device()
defer device.destroy()
let size = try native.size()
if not device.is_open() or size.width <= 0.0 or size.height <= 0.0: return
let texture = try self.upload(device)
let strip = try self.upload_strip(device)
let projection = try camera.value().projection(size.width / size.height)
let plan = self.plan(projection) else return
let vertices = try self.slabs(projection, plan)
defer free(vertices) in memory.heap
if vertices.length == 0: return
let pipeline = try fog_pipeline(device, try native.pixel_format())
var uniforms = self.uniforms(projection, plan, key, ambient)
try gpu.shade_triangles(native, pipeline, vertices, u8[]((u8*)&uniforms[0], 128), [texture, strip], gpu.Filter.linear)
## The atlas on the GPU: sent on the first draw, when the CPU copy is
## freed. Volumes draw on the device they were first drawn on.
func upload(device: gpu.Device) -> gpu.Texture!:
if let texture = self.texture: return texture
var texture = try gpu.Texture.create(device, (u32)self.data.width, (u32)self.data.height, gpu.Format.rgba16_float)
errdefer texture.destroy()
try texture.upload(u8[]((u8*)self.data.texels.data, self.data.texels.length * 2))
self.texture = texture
self.uploads += 1
self.data.close()
return texture
## The emission strip on the GPU, made on the first draw and filled again
## when the look changed it.
func upload_strip(device: gpu.Device) -> gpu.Texture!:
if let strip = self.strip:
if not self.strip_stale: return strip
if self.strip == none:
self.strip = try gpu.Texture.create(device, (u32)strip_texels, 1, gpu.Format.rgba16_float)
let strip = self.strip else trap("fog strip")
var texels: f16[1024]
emission_strip(&self.styled, texels)
try strip.upload(u8[]((u8*)&texels[0], 2048))
self.strip_stale = false
self.strip_uploads += 1
return strip
## Where the slabs lie along the view axis through `projection`: from the
## box's near side (or the near plane) to its far side, `slab_steps` steps
## apart, or farther apart when that would take more than `most_slabs`.
## None when the box is behind the eye or past the far plane.
func plan(projection: Projection) -> SlabPlan?:
let forward = projection.backward.multiply_scalar(-1.0)
var nearest = 1.0e300
var farthest = -1.0e300
for corner in 0..<(usize)8:
let depth = self.data.box.transform_point(corner_of(corner)).subtract(projection.position).dot(forward)
nearest = math.min(nearest, depth)
farthest = math.max(farthest, depth)
var thickness = slab_steps * self.styled.step * self.data.voxel
let start = math.max(nearest + thickness * 0.001, projection.near * 1.001)
let finish = math.min(farthest, projection.far * 0.999)
if finish <= start: return none
var count = (usize)math.ceil((finish - start) / thickness)
if count > most_slabs:
count = most_slabs
thickness = (finish - start) / (f64)most_slabs
return SlabPlan(start, thickness, count)
## The slab polygons of `plan` from back to front as clip-space triangles,
## each vertex colored with its box coordinates. Heap storage, owned by
## the caller.
func slabs(projection: Projection, plan: SlabPlan) -> gpu.Vertex[]!:
let forward = projection.backward.multiply_scalar(-1.0)
# A slab is at most a hexagon: four triangles.
let out = try new gpu.Vertex[plan.count * 12] --- in memory.heap
var written: usize = 0
var index = plan.count
while index > 0:
index -= 1
written += cut(self.data.box, projection, forward, plan.start + (f64)index * plan.thickness, out[written..])
return out[..<written]
## The fragment stage's uniforms (shaders/fog.frag's Params).
func uniforms(projection: Projection, plan: SlabPlan, key: Color, ambient: f64) -> f32[32]:
let box = self.data.box
let inverse = box.inverse() catch failure: trap(failure.message)
let eye = inverse.transform_point(projection.position)
let forward = projection.backward.multiply_scalar(-1.0)
let look = &self.styled
let counts = self.data.counts
let (low, scale) = emission_fit(look)
return [(f32)eye.x, (f32)eye.y, (f32)eye.z, (f32)plan.thickness,
(f32)box.x.dot(forward), (f32)box.y.dot(forward), (f32)box.z.dot(forward), (f32)slab_steps,
(f32)box.x.length(), (f32)box.y.length(), (f32)box.z.length(), (f32)look.density,
(f32)key.red, (f32)key.green, (f32)key.blue, (f32)ambient,
(f32)look.smoke.x, (f32)look.smoke.y, (f32)look.smoke.z, (f32)look.shadow,
(f32)look.emission, (f32)low, (f32)scale, 0.0,
(f32)counts[0], (f32)counts[1], (f32)counts[2], (f32)self.data.columns,
(f32)self.data.width, (f32)self.data.height, 0.0, 0.0]
## Free the texels and the textures.
pub func close():
self.data.close()
if let texture = self.texture:
var owned = texture
owned.destroy()
self.texture = none
if let strip = self.strip:
var owned = strip
owned.destroy()
self.strip = none
pub let fog_volume_type: interop.Type[FogVolume] = interop.Type[FogVolume]("FogVolume", FogVolume.close, closeable = true, main_thread = true)
## A heap FogVolume of fog drawing `index` of `set`'s own volume, drawn with
## its grid's look (Base callers, such as a worker handing it to the UI
## thread: adopt it with `fog_volume_type` there). Fails when there is no
## such drawing.
pub func fog_volume(set: const GeometrySet*, index: i64, matrix: Matrix4, light: Vector3) -> FogVolume*!:
let show = shown(set, index) else error(errors.invalid, "the geometry has no such fog drawing")
let direction = try light.normalized()
var data = try fog_texels(show.density, show.emission, matrix, direction)
errdefer data.close()
return try new FogVolume(data = data, styled = clamped(&show.styled.look), texture = none, strip = none, strip_stale = true, uploads = 0, strip_uploads = 0) in memory.heap
## How many fog drawings `set`'s own volume makes (see FogVolume.count).
pub func fog_grid_count(set: const GeometrySet*) -> usize:
let volume = set_volume(set) else return 0
return fog_show_count(volume)
## The content key of fog drawing `index` of `set` placed by `matrix` and lit
## from `light` (see FogVolume.key); fails when there is no such drawing.
pub func fog_volume_key(set: const GeometrySet*, index: i64, matrix: Matrix4, light: Vector3) -> i64!:
let show = shown(set, index) else error(errors.invalid, "the geometry has no such fog drawing")
var key = mix_grid(0xCBF29CE484222325, show.density)
if let field = show.emission: key = mix_grid(key, field)
let placed = matrix.multiply(show.density.transform)
for value in [placed.x, placed.y, placed.z, placed.translation, try light.normalized()]:
key = mix(mix(mix(key, value.x), value.y), value.z)
return (i64)(key >> 1)
## The look fog drawing `index` of `set` draws with: its grid's, clamped to
## what a FogVolume draws (colors to 0..1, the step to 0.25..8, scales to
## their ranges); none past the drawings.
pub func fog_look(set: const GeometrySet*, index: i64) -> VolumeLook?:
let show = shown(set, index) else return none
return clamped(&show.styled.look)
## The numbers of fog drawing `index` of `set`'s look (FogVolume.look_of).
pub func fog_look_of(set: const GeometrySet*, index: i64) -> FogLook!:
let look = fog_look(set, index) else error(errors.invalid, "the geometry has no such fog drawing")
return numbers_of(&look)
## Draw `volume` with `look` from now on: the atlas stays; the emission strip
## is sent again on the next draw if `look` changes it.
pub func restyle_fog(volume: FogVolume*, look: const VolumeLook*):
let old = volume.styled
volume.styled = clamped(look)
if old.emission_low != look.emission_low or old.emission_high != look.emission_high or old.emission_color != volume.styled.emission_color or not same_numbers(old.emission_ramp(), look.emission_ramp()):
volume.strip_stale = true
func same_numbers(a: const f64[], b: const f64[]) -> bool:
if a.length != b.length: return false
for at in 0..<a.length:
if a[at] != b[at]: return false
return true
## `look` with its numbers in the ranges a FogVolume draws.
func clamped(look: const VolumeLook*) -> VolumeLook:
var made = *look
made.density = math.clamp(look.density, 0.0, 1.0e6)
made.smoke = unit_vector(look.smoke)
made.shadow = math.clamp(look.shadow, 0.0, 100.0)
made.emission = math.clamp(look.emission, 0.0, 1.0e6)
made.emission_color = unit_vector(look.emission_color)
made.step = math.clamp(look.step, 0.25, 8.0)
return made
## A look's numbers as a FogLook.
func numbers_of(look: const VolumeLook*) -> FogLook:
return FogLook(density = look.density, color = Color(look.smoke.x, look.smoke.y, look.smoke.z), shadow = look.shadow, emission = look.emission,
emission_color = Color(look.emission_color.x, look.emission_color.y, look.emission_color.z), step = look.step)
func unit_vector(value: Vector3) -> Vector3:
return Vector3(math.clamp(value.x, 0.0, 1.0), math.clamp(value.y, 0.0, 1.0), math.clamp(value.z, 0.0, 1.0))
## Fog drawing `index` of `set`'s own volume, if it makes one.
func shown(set: const GeometrySet*, index: i64) -> FogShow?:
if index < 0: return none
let volume = set_volume(set) else return none
return fog_show(volume, (usize)index)
## `key` with a grid's columns (their ids change with their contents).
func mix_grid(key: u64, grid: const SparseGrid*) -> u64:
return (((key ^ grid.keys.id()) *% 0x100000001B3) ^ grid.values.id()) *% 0x100000001B3
func mix(key: u64, value: f64) -> u64:
var bits = value
return (key ^ memory.read[u64]((void*)&bits)) *% 0x100000001B3
# mark: Slabs
## Where a draw's slabs lie along the view axis: the first plane's depth, the
## world distance between planes, and how many.
struct SlabPlan:
let start: f64
let thickness: f64
let count: usize
## Corner `index` of the unit box: bit 0 x, bit 1 y, bit 2 z.
func corner_of(index: usize) -> Vector3:
return Vector3((f64)(index & 1), (f64)((index >> 1) & 1), (f64)((index >> 2) & 1))
## The box's twelve edges as corner pairs.
let edges: usize[24] = [0, 1, 2, 3, 4, 5, 6, 7, 0, 2, 1, 3, 4, 6, 5, 7, 0, 4, 1, 5, 2, 6, 3, 7]
## Write the polygon where the plane at view depth `depth` cuts `box`, as a
## triangle fan, into `out`; how many vertices it wrote (0 when it misses).
func cut(box: Matrix4, projection: Projection, forward: Vector3, depth: f64, out: gpu.Vertex[]) -> usize:
let origin = Vector3()
var points: Vector3[6] = [origin, origin, origin, origin, origin, origin]
var coordinates = points
var count: usize = 0
for edge in 0..<(usize)12:
let a = corner_of(edges[edge * 2])
let b = corner_of(edges[edge * 2 + 1])
let pa = box.transform_point(a)
let pb = box.transform_point(b)
let da = pa.subtract(projection.position).dot(forward) - depth
let db = pb.subtract(projection.position).dot(forward) - depth
if (da < 0.0) == (db < 0.0) or count == 6: continue
let t = da / (da - db)
points[count] = pa.add(pb.subtract(pa).multiply_scalar(t))
coordinates[count] = a.add(b.subtract(a).multiply_scalar(t))
count += 1
if count < 3: return 0
# Order the points around their center, in the view plane.
var center = Vector3()
for at in 0..<count: center = center.add(points[at])
center = center.multiply_scalar(1.0 / (f64)count)
var angles: f64[6]
for at in 0..<count:
let offset = points[at].subtract(center)
angles[at] = math.atan2(offset.dot(projection.up), offset.dot(projection.right))
for at in 1..<count:
var probe = at
while probe > 0 and angles[probe - 1] > angles[probe]:
let angle = angles[probe]
angles[probe] = angles[probe - 1]
angles[probe - 1] = angle
let point = points[probe]
points[probe] = points[probe - 1]
points[probe - 1] = point
let coordinate = coordinates[probe]
coordinates[probe] = coordinates[probe - 1]
coordinates[probe - 1] = coordinate
probe -= 1
var written: usize = 0
for at in 1..<count - 1:
for corner in [(usize)0, at, at + 1]:
out[written] = clip_vertex(points[corner], coordinates[corner], projection)
written += 1
return written
## `point` in clip space (as WireRenderer projects), colored with its box
## coordinates.
func clip_vertex(point: Vector3, coordinate: Vector3, projection: Projection) -> gpu.Vertex:
let relative = point.subtract(projection.position)
let distance = -relative.dot(projection.backward)
return gpu.Vertex(x = (f32)(relative.dot(projection.right) * projection.focal / projection.aspect),
y = (f32)(relative.dot(projection.up) * projection.focal),
z = (f32)(projection.far * (distance - projection.near) / (projection.far - projection.near)),
w = (f32)distance, red = (f32)math.clamp(coordinate.x, 0.0, 1.0), green = (f32)math.clamp(coordinate.y, 0.0, 1.0),
blue = (f32)math.clamp(coordinate.z, 0.0, 1.0))
# mark: The shared pipeline
## The fog shader and its pipelines on one device, per target format (slot 0
## for presentation surfaces, 1 + the format otherwise): made on first use and
## kept, so a new volume compiles nothing. Main thread only, as drawing is.
struct FogPipelines:
var device: gpu.Device
var shader: gpu.Shader
var pipelines: (gpu.Pipeline?)[9]
var shared: FogPipelines? = none
## The fog pipeline drawing into targets of `pixel_format` on `device`.
func fog_pipeline(device: gpu.Device, pixel_format: gpu.Format?) -> gpu.Pipeline!:
var wanted = device
if let held = shared:
if not held.device.same(&wanted): release_fog_pipelines()
if shared == none:
var shader = try gpu.Shader.create(device, fog_frag_words, fog_frag_msl, fog_frag_fast_math)
errdefer shader.destroy()
shared = FogPipelines(device = try device.share(), shader = shader)
var held = shared else trap("fog pipelines")
var slot: usize = 0
if let format = pixel_format: slot = (usize)(u8)format + 1
if let made = held.pipelines[slot]: return made
let made = try gpu.Pipeline.create(device, held.shader, gpu.Blend.over, pixel_format, depth_test = true)
held.pipelines[slot] = made
shared = held
return made
## Release the shared fog shader and pipelines (they are made again on the
## next draw): for a clean shutdown, or before closing the device.
pub func release_fog_pipelines():
let held = shared else return
shared = none
for pipeline in held.pipelines:
if let made = pipeline:
var owned = made
owned.destroy()
var shader = held.shader
shader.destroy()
var device = held.device
device.destroy()