dymokomi/luce-3d
Source of release 0.9.6
0.9.6 / 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 one fog drawing, made once
## per grid on the CPU (renderers/fog_texels.lucb: dense texels, optical
## depths toward the light and the sky) with 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. A FogScene
## (renderers/fog_scene.lucb) draws them: the first draw of a volume sends its
## texels to the GPU as its atlas and frees them here; later draws (a camera
## drag) send nothing, and a new look sends only the scene's table of numbers
## and emission strips.
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 core.material import Color, check_color
from renderers.fog_texels import FogTexels, fog_texels
## 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 sends them
## as its atlas texture, and its look.
pub struct FogVolume:
var data: FogTexels
var texture: gpu.Texture?
var styled: VolumeLook
## Counts up with each new look, so a scene knows to send its numbers again.
var version: u64
## Whether the emission strip changed since a scene last sent it.
var strip_stale: bool
var uploads: i64
var strip_uploads: i64
## Which drawing this is, never reused (a FogScene keys the atlases it
## stacks for a group on it).
let serial: u64
## 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 texels 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; a scene sends the strips with its
## table).
pub func strip_upload_count() -> i64:
return self.strip_uploads
# What a FogScene reads and notes as it draws it.
## Its texels' layout (their values are freed once sent).
pub func texel_data() -> const FogTexels*:
return &self.data
## The atlas on the GPU: sent on the first draw, when the CPU copy is
## freed; whether this call sent it. Volumes draw on the device they were
## first drawn on.
pub func atlas(device: gpu.Device) -> (gpu.Texture, bool)!:
if let texture = self.texture: return (texture, false)
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, true)
## Its serial: which drawing this is, never reused.
pub func drawing_id() -> u64:
return self.serial
## The whole look it draws with, and its version (new with each look).
pub func styled_look() -> const VolumeLook*:
return &self.styled
pub func look_version() -> u64:
return self.version
## Whether its emission strip changed since a scene last sent it; a scene
## asking is sending it, which this counts.
pub func take_strip() -> bool:
if not self.strip_stale: return false
self.strip_stale = false
self.strip_uploads += 1
return true
## Free the texels and the atlas.
pub func close():
self.data.close()
if let texture = self.texture:
var owned = texture
owned.destroy()
self.texture = 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, show.emission_color, matrix, direction)
errdefer data.close()
return try new FogVolume(data = data, texture = none, styled = clamped(&show.styled.look), version = 1, strip_stale = true, uploads = 0, strip_uploads = 0,
serial = next_fog_serial.add(1, .relaxed) + 1) in memory.heap
## The last FogVolume serial handed out (volumes are made on workers too).
var next_fog_serial: @u64
## 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)
if let field = show.emission_color: 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.
## A look equal to the one drawn changes nothing: its numbers are not sent.
pub func restyle_fog(volume: FogVolume*, look: const VolumeLook*):
let old = volume.styled
let made = clamped(look)
let strip = old.emission_low != made.emission_low or old.emission_high != made.emission_high or old.emission_color != made.emission_color or not same_numbers(old.emission_ramp(), made.emission_ramp())
let numbers = strip or old.density != made.density or old.smoke != made.smoke or old.shadow != made.shadow or old.emission != made.emission or old.step != made.step
volume.styled = made
if numbers: volume.version += 1
if strip: 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
## Corner `index` of the unit box: bit 0 x, bit 1 y, bit 2 z.
pub func corner_of(index: usize) -> Vector3:
return Vector3((f64)(index & 1), (f64)((index >> 1) & 1), (f64)((index >> 2) & 1))