dymokomi/luce-geocore
Source of release 0.7.5
0.7.5 / src / script / volumes.lucb
# Volumes, Houdini's Volume and VDB primitives: named sparse grids of f32 voxels in the
# set's volume, as the Volume node makes them and the Code node's Voxels mode runs over
# them. A fog grid holds densities; a level set signed distances, negative inside. Voxels
# sit in 8x8x8 leaves; voxel (i, j, k) is centered at the grid's transform of (i, j, k).
#
# `add_volume` is the Volume node: a box of voxels, dense (every voxel in the box active)
# or sparse (no voxels yet; `set` makes leaves where it writes). `voxel_grid` opens a
# grid for reading and writing as a `VoxelGrid`: its voxels in leaf order, 512 a leaf, x
# fastest (the Voxels mode's lanes), by lane or by (i, j, k). A grid is read where it is
# until the first write copies it; the copy becomes the set's grid at the next flush.
# `set_look` is the Volume Visualization node on one grid: how the viewport draws it.
#
# A `VoxelGrid` lives as long as its Geometry. When the set is replaced (a verb, `merge`,
# `transform`, `set_geometry`, a new `add_volume` of its name), the handle finds its grid
# again by name in the new set; when the new set has none of that name it is *gone*: it
# reads as an empty grid and a write fails, naming the grid.
## A grid's class, as the Volume node's Class menu.
pub enum VolumeClass as u8:
fog = 0
level_set = 1
## One grid of a geometry's volume, opened for reading and writing.
pub struct VoxelGrid:
var label: str
var class: GridClass
var background_value: f32
var transform: Matrix4
var inverse: Matrix4
## The published grid it reads until the first write (none once it owns its voxels).
var source: SparseGrid*?
## Its own voxels after the first write: leaf keys in leaf order, 512 values and 8
## active-mask words a leaf, and the leaves' order by key, for finding a leaf.
var keys: Growing[u64]
var values_owned: Growing[f32]
var masks: Growing[u64]
var order: Growing[u32]
## How the viewport draws it (the grid's look, until `set_look`).
var styled: VolumeLook
## Written since the set last took it; part of an input (read-only).
var dirty: bool
var locked: bool
## Its grid left the geometry and no grid of its name came back (see `rebind`).
var gone: bool
## The last leaf found, by key.
var cached_key: u64
var cached_leaf: i64
## `grid` (shared) opened for reading.
static func open(grid: const SparseGrid*, locked: bool) -> VoxelGrid!:
return VoxelGrid(label = try heap_text(grid.name()), class = grid.class, background_value = grid.background, transform = grid.transform,
inverse = grid.inverse, source = share_grid((SparseGrid*)grid), keys = Growing[u64](), values_owned = Growing[f32](),
masks = Growing[u64](), order = Growing[u32](), styled = grid.look, dirty = false, locked = locked, gone = false,
cached_key = 0xFFFFFFFFFFFFFFFF, cached_leaf = -1)
# mark: What it is ================================================================
## The grid's name.
pub func name() -> str:
return self.label
## Whether it is a level set (else fog).
pub func is_level_set() -> bool:
return self.class == GridClass.level_set
## The value outside its voxels.
pub func background() -> f32:
return self.background_value
## The distance between voxel centers (along x).
pub func voxel_size() -> f64:
return self.transform.x.length()
## Lanes: 512 for every leaf, active or not (`values()`'s length).
pub func count() -> i64:
return (i64)self.key_view().length * (i64)leaf_voxels
## Voxels whose active bit is set.
pub func active_count() -> i64:
var total: i64 = 0
for word in self.mask_view(): total += (i64)popcount(word)
return total
# mark: How it looks ===============================================================
## How the viewport draws it: its look's density, smoke, shadow and emission
## numbers, its fields (`density_field()`, `emission_field()`,
## `emission_color_field()`) and emission ramp.
pub func look() -> VolumeLook:
return self.styled
## Draw a fog grid as Volume Visualization does: `density` scales its densities,
## `smoke` is the scattered color, `shadow` scales its self-shadowing; it emits
## `emission` times grid `emission_field`'s values ("" none) in `emission_color`, or
## with an emission ramp the ramp at grid `emission_color_field`'s values ("" the
## emission field's); it shows grid `density_field`'s values as its density ("" its
## own); `step` is the ray-marching step in voxels. The emission ramp stays as it was.
pub func set_look(density: f64 = 1.0, smoke: f32[4] = [1.0, 1.0, 1.0, 0.0], shadow: f64 = 1.0, emission: f64 = 0.0, emission_color: f32[4] = [1.0, 1.0, 1.0, 0.0],
emission_field: str = "", density_field: str = "", step: f64 = 1.0, emission_color_field: str = "") -> !:
if self.locked: error(errors.invalid, "an input is read-only: copy() it to change it")
var look = self.styled
look.density = density
look.smoke = vec3(smoke)
look.shadow = shadow
look.emission = emission
look.emission_color = vec3(emission_color)
look.step = step
try look.set_emission_field(emission_field)
try look.set_density_field(density_field)
try look.set_emission_color_field(emission_color_field)
self.styled = look
self.dirty = true
## Color the emission by `data`, a color ramp in luce-std ramp's form,
## along emission field values `low` to `high`; empty data clears it, back to the
## emission color.
pub func set_emission_ramp(data: const f64[], low: f64 = 0.0, high: f64 = 1.0) -> !:
if self.locked: error(errors.invalid, "an input is read-only: copy() it to change it")
try self.styled.set_emission_ramp(data)
self.styled.emission_low = low
self.styled.emission_high = high
self.dirty = true
# mark: By lane: the Voxels mode's order ===========================================
## Every voxel's value, writable, by lane: valid until `set` adds a leaf.
pub func values() -> f32[]!:
try self.own()
self.dirty = true
return self.values_owned.items[..<self.values_owned.count]
## Every voxel's value, to read.
pub func values_view() -> const f32[]:
if let grid = self.source: return grid.values.view()
return self.values_owned.view()
## Lane `lane`'s voxel index (i, j, k).
pub func index(lane: i64) -> (i64, i64, i64):
let (x, y, z) = key_leaf(self.key_view()[(usize)lane // leaf_voxels])
let local = lane % (i64)leaf_voxels
return (x * 8 + (local & 7), y * 8 + ((local >> 3) & 7), z * 8 + (local >> 6))
## Lane `lane`'s voxel center in world space.
pub func position(lane: i64) -> f32[4]:
let (i, j, k) = self.index(lane)
return self.index_position(i, j, k)
## Whether lane `lane`'s voxel is active.
pub func active(lane: i64) -> bool:
return (self.mask_view()[(usize)lane >> 6] >> (u64)(lane & 63)) & 1 != 0
## Turn lane `lane`'s voxel on or off.
pub func set_active(lane: i64, on: bool) -> !:
try self.own()
self.dirty = true
let bit = (u64)1 << (u64)(lane & 63)
let word = &self.masks.items[(usize)lane >> 6]
*word = (*word | bit) if on else (*word & (bit ^ 0xFFFFFFFFFFFFFFFF))
# mark: By voxel index ==============================================================
## The value at voxel (i, j, k): the background outside the leaves.
pub func get(i: i64, j: i64, k: i64) -> f32:
let leaf = self.leaf(leaf_key(leaf_of(i), leaf_of(j), leaf_of(k)))
if leaf < 0: return self.background_value
return self.values_view()[(usize)leaf * leaf_voxels + local_index(i, j, k)]
## Whether voxel (i, j, k) is active.
pub func active_at(i: i64, j: i64, k: i64) -> bool:
let leaf = self.leaf(leaf_key(leaf_of(i), leaf_of(j), leaf_of(k)))
if leaf < 0: return false
let at = (usize)leaf * leaf_voxels + local_index(i, j, k)
return (self.mask_view()[at >> 6] >> (u64)(at & 63)) & 1 != 0
## Set voxel (i, j, k) to `value` and make it active; its leaf is made when the
## grid has none there (other voxels of a new leaf are inactive, at the background).
pub func set(i: i64, j: i64, k: i64, value: f32) -> !:
try self.own()
self.dirty = true
let key = leaf_key(leaf_of(i), leaf_of(j), leaf_of(k))
var leaf = self.leaf(key)
if leaf < 0: leaf = (i64)(try self.add_leaf(key))
let at = (usize)leaf * leaf_voxels + local_index(i, j, k)
self.values_owned.items[at] = value
self.masks.items[at >> 6] |= (u64)1 << (u64)(at & 63)
# mark: World space =================================================================
## Voxel (i, j, k)'s center in world space.
pub func index_position(i: i64, j: i64, k: i64) -> f32[4]:
return vec4(self.transform.transform_point(Vector3((f64)i, (f64)j, (f64)k)))
## World point `p` in index space (voxel centers at whole numbers).
pub func to_index(p: f32[4]) -> f32[4]:
return vec4(self.inverse.transform_point(vec3(p)))
## The trilinear value at world point `p` (VEX volumesample).
pub func sample(p: f32[4]) -> f32:
let at = self.inverse.transform_point(vec3(p))
let fx = math.floor(at.x)
let fy = math.floor(at.y)
let fz = math.floor(at.z)
let i = (i64)fx
let j = (i64)fy
let k = (i64)fz
let tx = (f32)(at.x - fx)
let ty = (f32)(at.y - fy)
let tz = (f32)(at.z - fz)
let x00 = lerp(self.get(i, j, k), self.get(i + 1, j, k), tx)
let x10 = lerp(self.get(i, j + 1, k), self.get(i + 1, j + 1, k), tx)
let x01 = lerp(self.get(i, j, k + 1), self.get(i + 1, j, k + 1), tx)
let x11 = lerp(self.get(i, j + 1, k + 1), self.get(i + 1, j + 1, k + 1), tx)
return lerp(lerp(x00, x10, ty), lerp(x01, x11, ty), tz)
# mark: Inside ======================================================================
func key_view() -> const u64[]:
if let grid = self.source: return grid.keys.view()
return self.keys.view()
func mask_view() -> const u64[]:
if let grid = self.source: return grid.masks.view()
return self.masks.view()
## The leaf of `key`, or -1.
func leaf(key: u64) -> i64:
if key == self.cached_key: return self.cached_leaf
var found: i64 = -1
if let grid = self.source:
found = grid.find(key)
else:
let at = self.ordered_at(key)
if at < self.order.count and self.keys.items[(usize)self.order.items[at]] == key: found = (i64)self.order.items[at]
self.cached_key = key
self.cached_leaf = found
return found
## Where `key` is, or would go, in the leaves' order by key.
func ordered_at(key: u64) -> usize:
var low: usize = 0
var high = self.order.count
while low < high:
let middle = (low + high) // 2
if self.keys.items[(usize)self.order.items[middle]] < key: low = middle + 1
else: high = middle
return low
## Copy the published grid's voxels to write them (the first write does it).
func own() -> !:
if self.locked: error(errors.invalid, "an input is read-only: copy() it to change it")
if self.gone:
var buffer: u8[160]
error(errors.invalid, strings.format(buffer, f"the grid \"{self.label}\" is no longer in the geometry: open it again with voxel_grid") else "the grid is no longer in the geometry")
let grid = self.source else return
try self.keys.assign(grid.keys.view())
try self.values_owned.assign(grid.values.view())
try self.masks.assign(grid.masks.view())
# Published keys are sorted: the order is the leaves' own.
try self.order.reserve(self.keys.count)
for at in 0..<self.keys.count: self.order.items[at] = (u32)at
self.order.count = self.keys.count
release_grid(grid)
self.source = none
## A new leaf of `key`: every voxel inactive at the background. Its number.
func add_leaf(key: u64) -> usize!:
if self.keys.count >= 4000000: error(errors.limit, "a grid holds at most 4M leaves")
let leaf = self.keys.count
try self.keys.push(key)
try self.values_owned.extend(self.values_owned.count + leaf_voxels, self.background_value)
try self.masks.extend(self.masks.count + mask_words, 0)
try self.order.insert(self.ordered_at(key), (u32)leaf)
self.cached_key = key
self.cached_leaf = (i64)leaf
return leaf
## The grid as a published one, its leaves sorted by key (the caller owns it).
func publish() -> SparseGrid*!:
if let grid = self.source:
# Only the look changed: the voxels are shared.
return share_grid(grid) if self.styled.same(&grid.look) else try restyled(grid, &self.styled)
let leaves = self.keys.count
var keys = try Column[u64].allocate(leaves)
errdefer keys.release()
var values = try Column[f32].allocate(leaves * leaf_voxels)
errdefer values.release()
var masks = try Column[u64].allocate(leaves * mask_words)
errdefer masks.release()
let out_keys = keys.span()
let out_values = values.span()
let out_masks = masks.span()
for at in 0..<leaves:
let leaf = (usize)self.order.items[at]
out_keys[at] = self.keys.items[leaf]
memory.copy(out_values[at * leaf_voxels..<(at + 1) * leaf_voxels], self.values_owned.items[leaf * leaf_voxels..<(leaf + 1) * leaf_voxels], leaf_voxels)
memory.copy(out_masks[at * mask_words..<(at + 1) * mask_words], self.masks.items[leaf * mask_words..<(leaf + 1) * mask_words], mask_words)
let made = try new_grid(self.label, self.class, self.background_value, self.transform, keys.take(), values.take(), masks.take())
made.look = self.styled
return made
## Point the handle at `grid` (shared), the grid of its name in a replaced set, or at
## nothing (gone) without one. Unflushed writes are dropped: callers flush first.
func rebind(grid: const SparseGrid*?):
self.drop_voxels()
self.dirty = false
self.cached_key = 0xFFFFFFFFFFFFFFFF
self.cached_leaf = -1
self.gone = grid == none
if let found = grid:
self.class = found.class
self.background_value = found.background
self.transform = found.transform
self.inverse = found.inverse
self.styled = found.look
self.source = share_grid((SparseGrid*)found)
## Let go of the voxels it reads or owns; it then has no leaves.
func drop_voxels():
if let grid = self.source: release_grid(grid)
self.source = none
self.keys.close()
self.values_owned.close()
self.masks.close()
self.order.close()
func close():
self.drop_voxels()
release_text(self.label)
func lerp(a: f32, b: f32, t: f32) -> f32:
return a + (b - a) * t
extend Geometry:
## A grid of voxels `voxel` apart over the box `size` wide around `center`, named
## `name`, as the Volume node makes it: `dense`, every voxel in the box active at
## `initial`; else none yet (`set` makes them). A grid of that name is replaced.
pub func add_volume(name: str, class: VolumeClass, center: f32[4], size: f32[4], voxel: f64 = 0.05, background: f32 = 0.0, initial: f32 = 0.0, dense: bool = true) -> VoxelGrid*!:
if self.locked: error(errors.invalid, "an input is read-only: copy() it to change it")
if name.length == 0 or name.length > 64: error(errors.invalid, "a grid needs a name of 1..64 bytes")
let half = Vector3((f64)size[0] * 0.5, (f64)size[1] * 0.5, (f64)size[2] * 0.5)
let middle = vec3(center)
let grid = try box_grid(name, GridClass.level_set if class == VolumeClass.level_set else GridClass.fog, middle.subtract(half), middle.add(half), voxel, background, initial, dense)
try put_grid(self.set(), grid)
# A handle already open on that name now reads the new grid.
self.rebind_grid(name)
return try self.voxel_grid(name)
## Grid `name` of the volume, opened for reading and writing ("" the first grid,
## "#2" the third). An input's grids read only.
pub func voxel_grid(name: str) -> VoxelGrid*!:
let volume = set_volume(self.set()) else error(errors.invalid, "the geometry has no volume")
let index = grid_index(volume, name) else error(errors.invalid, "the volume has no grid of that name")
for open in self.grids.view():
if open.name() == volume.grid(index).name(): return open
let made = try new VoxelGrid[1] --- in memory.heap
made[0] = VoxelGrid.open(volume.grid(index), self.locked) catch failure:
free(made) in memory.heap
error(failure.code, failure.message)
self.grids.push(made.data) catch failure:
made[0].close()
free(made) in memory.heap
error(failure.code, failure.message)
return made.data
## How many grids the volume holds.
pub func volume_count() -> i64:
let volume = set_volume(self.set()) else return 0
return (i64)volume.grid_count()
## Grid `index`'s name.
pub func volume_name(index: i64) -> str!:
let volume = set_volume(self.set()) else error(errors.invalid, "the geometry has no volume")
if index < 0 or index >= (i64)volume.grid_count(): error(errors.invalid, "the volume has no such grid")
return volume.grid((usize)index).name()
## Remove grid `name` from the volume, if it is there.
pub func remove_volume(name: str) -> !:
if self.locked: error(errors.invalid, "an input is read-only: copy() it to change it")
defer self.rebind_grid(name)
let volume = set_volume(self.set()) else return
let index = grid_index(volume, name) else return
if volume.grid_count() == 1:
self.set().remove(volume_type())
return
let made = try new_volume()
for at in 0..<volume.grid_count():
if at == index: continue
add_grid(made, share_grid((SparseGrid*)volume.grid(at))) catch failure:
release_volume(made)
error(failure.code, failure.message)
self.set().put(volume_type(), (void*)made) catch failure:
release_volume(made)
error(failure.code, failure.message)
## Put written grids in the set's volume; they stay open.
func flush_grids() -> !:
for at in 0..<self.grids.count:
let open = self.grids.items[at]
if not open.dirty: continue
try put_grid(self.set(), try open.publish())
open.dirty = false
## Point every open grid at the set's grid of its name, or mark it gone: after the
## set was replaced or its volume changed. Handles stay where they are, so a script's
## `VoxelGrid*` never dangles; their unflushed writes are dropped.
func rebind_grids():
for open in self.grids.view(): open.rebind(self.grid_named(open.name()))
## Point the open grid `name`, if there is one, at the set's grid of that name (or
## mark it gone); the other handles keep their writes.
func rebind_grid(name: str):
for open in self.grids.view():
if open.name() == name: open.rebind(self.grid_named(name))
## The set's grid named exactly `name`, or none (also once the set is taken).
func grid_named(name: str) -> const SparseGrid*?:
if self.storage == none: return none
let volume = set_volume(self.set()) else return none
for at in 0..<volume.grid_count():
if volume.grid(at).name() == name: return volume.grid(at)
return none
## Take over `other`'s open grids (a geometry `set_geometry` replaced): they rebind to
## this set's grids by name, after this geometry's own writes are flushed into it.
func adopt_grids(other: Geometry*) -> !:
try self.flush_grids()
# Room first, so no handle is ever in both lists.
try self.grids.reserve(self.grids.count + other.grids.count)
let first = self.grids.count
for open in other.grids.view():
self.grids.items[self.grids.count] = open
self.grids.count += 1
other.grids.clear()
# Only the adopted handles rebind: this geometry's own keep what they
# hold (a script writing a grid, then set_geometry).
for open in self.grids.view()[first..]: open.rebind(self.grid_named(open.name()))
## Close every open grid without keeping its writes (only when the geometry closes).
func close_grids():
for open in self.grids.view():
open.close()
free(VoxelGrid[](open, 1)) in memory.heap
self.grids.clear()
## The grid `name` reaches in `volume` ("" the first, "#2" the third), or none.
func grid_index(volume: const Volume*, name: str) -> usize?:
if name.length == 0: return 0 if volume.grid_count() > 0 else none
for at in 0..<volume.grid_count():
if volume.grid(at).name() == name: return at
if name.length > 1 and name.bytes[0] == '#':
if let at = strings.parse_i64((str)name.bytes[1..]):
if at >= 0 and (usize)at < volume.grid_count(): return (usize)at
return none
## `set`'s volume with `grid` (taken) in place of the grid of its name, or after them.
func put_grid(set: GeometrySet*, grid: SparseGrid*) -> !:
let made = new_volume() catch failure:
release_grid(grid)
error(failure.code, failure.message)
var placed = false
if let volume = set_volume(set):
for at in 0..<volume.grid_count():
let other = volume.grid(at)
let taken = grid if other.name() == grid.name() else share_grid((SparseGrid*)other)
if taken == grid: placed = true
add_grid(made, taken) catch failure:
if not placed: release_grid(grid)
release_volume(made)
error(failure.code, failure.message)
if not placed:
add_grid(made, grid) catch failure:
release_volume(made)
error(failure.code, failure.message)
set.put(volume_type(), (void*)made) catch failure:
release_volume(made)
error(failure.code, failure.message)