Luce packages
LuceLuce BaseLuciaOS

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