dymokomi/luce-fbx
Source of release 0.12.1
0.12.1 / src / scene / anim.lucb
## Animation: the first AnimationStack, its AnimationLayers, their
## AnimationCurveNodes (an animated property of an object: OP-connected to
## it, with default component values `d|X`, `d|Y`, `d|Z`) and the
## AnimationCurves driving each component (OP-connected to the node).
## Everything follows ufbx: keys and tangents are decoded as
## ufbxi_read_animation_curve decodes them (constant, linear and cubic keys;
## auto, TCB and user tangents with weights), curves evaluate as
## ufbx_evaluate_curve (a cubic Bezier segment solved for its time), with
## pre- and post-extrapolation, and layers combine as ufbxi_evaluate_props:
## the first replaces the rest value, the next add (additive), blend by
## their weight (override passthrough) or replace (override). Rotations and
## scales blend component-wise (ufbx composes them as quaternions and
## products when a layer asks; that is not done here).
pub enum Interpolation as u8:
constant_previous = 0
constant_next = 1
linear = 2
cubic = 3
pub enum Extrapolation as u8:
constant = 0
repeat = 1
mirror = 2
slope = 3
repeat_relative = 4
pub struct Key:
pub var time: f64
pub var value: f64
pub var interpolation: Interpolation
## Tangents: time and value offsets to the Bezier handles.
pub var left_dx: f64
pub var left_dy: f64
pub var right_dx: f64
pub var right_dy: f64
pub struct AnimCurve:
pub var first: usize
pub var count: usize
pub var pre: Extrapolation
pub var pre_repeat: i64
pub var post: Extrapolation
pub var post_repeat: i64
## One animated property on one layer.
pub struct AnimValue:
pub var layer: usize
pub var target: u32
## The property's name, in the document (a string property).
pub var name_node: u32
pub var name_index: usize
pub var curves: u32[3]
pub var defaults: f64[3]
pub struct AnimLayer:
pub var object: u32
pub var weight: f64
pub var additive: bool
pub var blended: bool
## Rotations combine as rotations, scales as products (the layer's
## accumulation modes 0), else component by component.
pub var compose_rotation: bool
pub var compose_scale: bool
pub struct Animation:
## The stack (absent: no animation).
pub var stack: u32
pub var layers: Growing[AnimLayer]
pub var values: Growing[AnimValue]
pub var curves: Growing[AnimCurve]
pub var keys: Growing[Key]
## The stack's time span, in seconds.
pub var start: f64
pub var stop: f64
## KTime ticks per second (Settings.ticks).
pub var ticks: f64
## Value indices sorted by target (stable: layer order kept per target).
var by_target: Growing[u32]
pub func close():
self.layers.close()
self.values.close()
self.curves.close()
self.keys.close()
self.by_target.close()
## The values of `target`: a range of by_target.
func target_range(target: u32) -> (usize, usize):
var low: usize = 0
var high = self.by_target.count
while low < high:
let middle = (low + high) // 2
if self.values.items[(usize)self.by_target.items[middle]].target < target: low = middle + 1
else: high = middle
var end = low
while end < self.by_target.count and self.values.items[(usize)self.by_target.items[end]].target == target: end += 1
return (low, end)
## Whether any property of `target` is animated.
pub func touches(target: u32) -> bool:
let (first, end) = self.target_range(target)
return end > first
## Whether property `name` of `target` is animated.
pub func animates(scene: const Scene*, target: u32, name: str) -> bool:
let (first, end) = self.target_range(target)
for at in first..<end:
if value_name(scene, &self.values.items[(usize)self.by_target.items[at]]) == name: return true
return false
## Property `name` of `target` at `time` over every layer, starting from
## its `rest` value (ufbxi_evaluate_props, ufbxi_combine_anim_layer).
pub func evaluate(scene: const Scene*, target: u32, name: str, time: f64, rest: Vector3) -> Vector3:
var result = rest
let (first, end) = self.target_range(target)
var order: i64 = -1
# The target's values are in layer order.
for at in first..<end:
let value = &self.values.items[(usize)self.by_target.items[at]]
if value_name(scene, value) != name: continue
let layer = self.layers.items[value.layer]
let v = self.value_at(value, time)
if value.layer == 0 or not (layer.additive or layer.blended):
result = v
continue
let weight = self.layer_weight(scene, value.layer, time)
let rotation = layer.compose_rotation and name == "Lcl Rotation"
let scale = layer.compose_scale and name == "Lcl Scaling"
if rotation and order < 0:
order = (i64)self.evaluate_number(scene, target, "RotationOrder", time, (f64)scene.integer(target, "RotationOrder", 0))
if order < 0 or order > 6: order = 0
if layer.additive:
if scale:
result = Vector3(result.x * power(v.x, weight), result.y * power(v.y, weight), result.z * power(v.z, weight))
elif rotation:
let added = slerp(Quat(), euler(v, order), weight)
result = quat_euler(euler(result, order).times(added), order)
else:
result = Vector3(result.x + v.x * weight, result.y + v.y * weight, result.z + v.z * weight)
else:
let keep = 1.0 - weight
if scale:
result = Vector3(power(result.x, keep) * power(v.x, weight), power(result.y, keep) * power(v.y, weight), power(result.z, keep) * power(v.z, weight))
elif rotation:
result = quat_euler(slerp(euler(result, order), euler(v, order), weight), order)
else:
result = Vector3(result.x * keep + v.x * weight, result.y * keep + v.y * weight, result.z * keep + v.z * weight)
return result
## Layer `index`'s weight at `time`: its Weight, animated in its own
## layer when it is blended.
func layer_weight(scene: const Scene*, index: usize, time: f64) -> f64:
let layer = self.layers.items[index]
if not layer.blended: return layer.weight
let (first, end) = self.target_range(layer.object)
for at in first..<end:
let value = &self.values.items[(usize)self.by_target.items[at]]
if value.layer != index or value_name(scene, value) != "Weight": continue
var weight = self.value_at(value, time).x / 100.0
if weight < 0.0: weight = 0.0
if weight > 0.99999: weight = 1.0
return weight
return layer.weight
## A number property at `time` (the first component).
pub func evaluate_number(scene: const Scene*, target: u32, name: str, time: f64, rest: f64) -> f64:
return self.evaluate(scene, target, name, time, Vector3(rest, 0.0, 0.0)).x
## An animated value's components at `time`.
func value_at(value: const AnimValue*, time: f64) -> Vector3:
var out: f64[3] = value.defaults
for component: usize in 0..<3:
let curve = value.curves[component]
if curve != absent: out[component] = self.curve_at((usize)curve, time, out[component])
return Vector3(out[0], out[1], out[2])
## Curve `index` at `time` (ufbx_evaluate_curve).
pub func curve_at(index: usize, time: f64, fallback: f64) -> f64:
return self.curve_value(index, time, fallback, true)
func curve_value(index: usize, time: f64, fallback: f64, extrapolate: bool) -> f64:
let curve = self.curves.items[index]
let keys = self.keys.items[curve.first..<curve.first + curve.count]
if keys.length == 0: return fallback
if keys.length == 1: return keys[0].value
if extrapolate and (time < keys[0].time or time > keys[keys.length - 1].time):
return self.extrapolated(index, time)
# The first key after `time`.
var low: usize = 0
var high = keys.length
while low < high:
let middle = (low + high) // 2
if keys[middle].time <= time: low = middle + 1
else: high = middle
if low == 0: return keys[0].value
if low == keys.length: return keys[keys.length - 1].value
let previous = keys[low - 1]
let next = keys[low]
if previous.time == time: return previous.value
let reciprocal = 1.0 / (next.time - previous.time)
var t = (time - previous.time) * reciprocal
match previous.interpolation:
.constant_previous: return previous.value
.constant_next: return next.value
.linear: return previous.value * (1.0 - t) + next.value * t
_:
let x1 = previous.right_dx * reciprocal
let x2 = 1.0 - next.left_dx * reciprocal
t = bezier_parameter(x1, x2, t)
let u = 1.0 - t
let y0 = previous.value
let y3 = next.value
let y1 = y0 + previous.right_dy
let y2 = y3 - next.left_dy
return u * u * u * y0 + 3.0 * (u * u * t * y1 + u * t * t * y2) + t * t * t * y3
## Outside the keys (ufbxi_extrapolate_curve), in KTime ticks so repeats
## land on frames exactly.
func extrapolated(index: usize, time: f64) -> f64:
let curve = self.curves.items[index]
let keys = self.keys.items[curve.first..<curve.first + curve.count]
let before = time < keys[0].time
let key = keys[0] if before else keys[keys.length - 1]
let mode = curve.pre if before else curve.post
let repeat = curve.pre_repeat if before else curve.post_repeat
if mode == Extrapolation.constant: return key.value
if mode == Extrapolation.slope:
let dx = key.right_dx if before else key.left_dx
let dy = key.right_dy if before else key.left_dy
if dx == 0.0: return key.value
return key.value + dy * ((time - key.time) / dx)
if repeat == 0: return key.value
let low = math.round(keys[0].time * self.ticks)
let high = math.round(keys[keys.length - 1].time * self.ticks)
let ticks = time * self.ticks
let delta = low - ticks if before else ticks - high
let duration = high - low
if not (duration >= 1.0): return key.value
var count = math.floor(delta / duration)
var rest = delta - count * duration
if repeat > 0 and count >= (f64)repeat:
count = (f64)(repeat - 1)
rest = duration
if mode == Extrapolation.mirror:
let parity = count * 0.5 - math.floor(count * 0.5)
if parity <= 0.25: rest = duration - rest
if before: rest = duration - rest
var value = self.curve_value(index, (low + rest) / self.ticks, key.value, false)
if mode == Extrapolation.repeat_relative:
var step = keys[keys.length - 1].value - keys[0].value
if before: step = -step
value += step * (count + 1.0)
return value
func by_target_order(animation: const Animation*, a: u32, b: u32) -> i64:
let x = animation.values.items[(usize)a].target
let y = animation.values.items[(usize)b].target
if x != y: return -1 if x < y else 1
return (i64)a - (i64)b
## |v|^e with v's sign (ufbxi_pow_abs).
func power(v: f64, e: f64) -> f64:
if e <= 0.0: return 1.0
if e >= 1.0: return v
let sign = -1.0 if v < 0.0 else 1.0
return sign * math.pow(v * sign, e)
func value_name(scene: const Scene*, value: const AnimValue*) -> str:
return scene.document.text(value.name_node, value.name_index) else ""
## The parameter of a cubic Bezier's time polynomial at `x` (Newton's
## method, as ufbxi_find_cubic_bezier_t).
func bezier_parameter(p1: f64, p2: f64, x: f64) -> f64:
let a = p1 * 3.0 - p2 * 3.0 + 1.0
let b = p2 * 3.0 - p1 * 6.0
let c = p1 * 3.0
var t = x
for round in 0..<11:
let miss = ((a * t + b) * t + c) * t - x
t -= miss / ((3.0 * a * t + 2.0 * b) * t + c)
if round >= 2 and math.abs(miss) <= 8.881784197001252e-16: break
return t
extend Scene:
## The first AnimationStack's animation (empty when there is none).
pub func animation() -> Animation!:
var result = Animation(absent, Growing[AnimLayer](), Growing[AnimValue](), Growing[AnimCurve](), Growing[Key](), 0.0, 0.0, self.settings.ticks, Growing[u32]())
errdefer result.close()
var stack = absent
for index in 1..<(u32)self.objects.count:
if self.objects.items[(usize)index].kind == Kind.stack:
stack = index
break
if stack == absent: return result
result.stack = stack
result.start = self.number(stack, "LocalStart", 0.0) / result.ticks
result.stop = self.number(stack, "LocalStop", 0.0) / result.ticks
# Its layers, in connection order.
for index in 0..<self.child_count(stack):
let connection = self.child_connection(stack, index)
if connection.property != absent or self.kind(connection.child) != Kind.layer: continue
let layer = connection.child
let mode = self.integer(layer, "BlendMode", 0)
try result.layers.push(AnimLayer(object = layer, weight = math.max(0.0, self.number(layer, "Weight", 100.0) / 100.0), additive = mode == 0, blended = mode == 0 or mode == 2,
compose_rotation = self.integer(layer, "RotationAccumulationMode", 0) == 0, compose_scale = self.integer(layer, "ScaleAccumulationMode", 0) == 0))
var curve_objects = Growing[u32]()
defer curve_objects.close()
for (layer_index, layer) in result.layers.view().indexed():
for index in 0..<self.child_count(layer.object):
let connection = self.child_connection(layer.object, index)
if connection.property != absent or self.kind(connection.child) != Kind.curve_node: continue
try self.read_curve_node(&result, layer_index, connection.child, &curve_objects)
try self.read_curves(&result, curve_objects.view())
for index in 0..<(u32)result.values.count: try result.by_target.push(index)
sort_indices(result.by_target.items[..<result.by_target.count], &result, by_target_order)
return result
## A curve node's animated properties: one value per OP connection to a
## target object, its curves found by component.
func read_curve_node(result: Animation*, layer: usize, node: u32, curve_objects: Growing[u32]*) -> !:
var curves: u32[3] = [absent, absent, absent]
let names: str[3] = ["d|X", "d|Y", "d|Z"]
var defaults: f64[3] = [0.0, 0.0, 0.0]
var single = false
for index in 0..<self.child_count(node):
let connection = self.child_connection(node, index)
if self.kind(connection.child) != Kind.curve: continue
let property = self.connection_property(connection)
var component: usize = 3
for (at, name) in names.indexed():
if property == name: component = at
if component == 3:
# A single-valued property (d|DeformPercent, d|Visibility...).
if not single and curves[0] == absent:
component = 0
single = true
else: continue
curves[component] = (u32)curve_objects.count
try curve_objects.push(connection.child)
for (at, name) in names.indexed(): defaults[at] = self.number(node, name, 0.0)
if single:
# The single value's default: the node's first d| property.
if let list = self.document.child(self.objects.items[(usize)node].node, "Properties70"):
if let first = self.document.first_child(list):
defaults[0] = self.document.real(first, 4) else 0.0
for index in 0..<self.parent_count(node):
let connection = self.parent_connection(node, index)
if connection.property == absent: continue
try result.values.push(AnimValue(layer = layer, target = connection.parent, name_node = connection.node, name_index = 3, curves = curves, defaults = defaults))
## Decode every curve's keys in one batch, then their tangents.
func read_curves(result: Animation*, objects: const u32[]) -> !:
var raw = Growing[RawCurve]()
defer:
for index in 0..<raw.count: raw.items[index].release()
raw.close()
var jobs = Growing[ArrayJob]()
defer jobs.close()
for object in objects:
let node = self.objects.items[(usize)object].node
var curve = RawCurve()
# Until it is in `raw`, the curve's arrays are its own to free.
var kept = false
defer:
if not kept: curve.release()
let source = self.document
# ASCII files from 7.2 on write the attribute floats as their
# bits' integers (some of them are not floats: packed weights).
curve.integer_bits = not source.binary and source.version >= 7200
# FBX 6 curves have none of these arrays and stay empty.
if let times = source.child(node, "KeyTime"):
if let values = source.child(node, "KeyValueFloat"):
try curve.plan(source, times, values, node, &jobs)
try raw.push(curve)
kept = true
try self.document.decode_arrays(jobs.view())
for (index, object) in objects.indexed():
let node = self.objects.items[(usize)object].node
let (pre, pre_repeat) = extrapolation(self.document, node, "Pre-Extrapolation")
let (post, post_repeat) = extrapolation(self.document, node, "Post-Extrapolation")
let first = result.keys.count
try raw.items[index].keys(&result.keys, result.ticks)
try result.curves.push(AnimCurve(first = first, count = result.keys.count - first, pre = pre, pre_repeat = pre_repeat, post = post, post_repeat = post_repeat))