Luce packages
LuceLuce BaseLuciaOS

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()