effectcraft/crates/expr/src/lib.rs

//! After Effects-compatible expressions on the boa JavaScript engine.
//!
//! [`Expressions`] implements [`ExprHost`] so the renderer can evaluate property expressions:
//!
//! ```text
//! let host = effectcraft_expr::Expressions;
//! let mut r = Renderer::new(&project, &NoFootage, RenderOpts::default());
//! r.expr = Some(&host);
//! ```
//!
//! * **Language**: JavaScript plus AE's legacy array maths (`value + [10, 0]`, `[1, 2] * 2`),
//!   implemented by rewriting `+ - * /` into helper calls ([`rewrite`]). The last evaluated
//!   statement is the result (`var x = …; x`, `if/else` blocks).
//! * **Object model** (`prelude.js`): `time`, `value`, `thisComp`, `thisLayer`, `thisProperty`,
//!   `comp(name)`, layer attributes (`index`, `inPoint`, `width`, `transform`, `effect(…)(…)`,
//!   `mask`, `content`, `text.sourceText`, `marker`, `toComp`/`fromComp`/`toWorld`/`fromWorld`,
//!   `sourceRectAtTime`), property methods (`valueAtTime`, `velocityAtTime`, `speedAtTime`, `key`,
//!   `nearestKey`, `numKeys`, `wiggle`, `temporalWiggle`, `smooth`, `loopIn/Out[Duration]`) and the
//!   global helpers (`linear`/`ease`/`easeIn`/`easeOut`, `random`/`gaussRandom`/`seedRandom`/
//!   `noise`, vector maths, `clamp`, `lookAt`, time and colour conversions, `posterizeTime`).
//! * **Determinism**: `wiggle` and `random` are seeded by layer index, property uid (and time /
//!   `seedRandom`), so frames render identically on every thread and platform.
//! * **Runtime**: one boa `Context` per thread with compiled scripts cached by text. Scripts read
//!   the project through memoized host requests (see [`host`]), so nothing borrowed ever enters
//!   the JS heap. Expressions reading each other nest up to [`MAX_DEPTH`] levels.

pub mod host;
mod noise;
pub mod rewrite;
mod runtime;

use effectcraft_keyframe::Value;
use effectcraft_project::{ItemId, Layer, LayerId, Project, Property};
use effectcraft_render::{EvalCtx, ExprHost};
use effectcraft_time::Tick;

use host::{Own, Req, Resolver, prop_dims, value_resp};
use runtime::{Begin, FRAMES, Frame, Run};

/// Maximum nesting of expressions that read other expressions (cycles stop here).
pub const MAX_DEPTH: usize = 16;
/// Maximum script re-runs while answering host requests.
const MAX_PASSES: usize = 2000;

/// The expression engine (stateless; runtimes are per thread).
#[derive(Clone, Copy, Debug, Default)]
pub struct Expressions;

impl ExprHost for Expressions {
    fn eval(&self, ctx: &EvalCtx, layer: &Layer, prop: &Property, value: &Value) -> Result<Value, String> {
        match &prop.expr {
            Some(e) => evaluate(self, ctx, layer, prop, value, &e.text),
            None => Ok(value.clone()),
        }
    }
}

/// Pops the evaluation frame on every exit path.
struct FrameGuard;
impl Drop for FrameGuard {
    fn drop(&mut self) {
        FRAMES.with(|f| f.borrow_mut().pop());
    }
}

/// Evaluate `text` as the expression of `prop` on `layer` at `ctx.time`, given its keyframed
/// `value`. Other properties' expressions are evaluated through `host`.
pub fn evaluate(host: &dyn ExprHost, ctx: &EvalCtx, layer: &Layer, prop: &Property, value: &Value, text: &str) -> Result<Value, String> {
    let depth = FRAMES.with(|f| f.borrow().len());
    if depth >= MAX_DEPTH {
        return Err("Error: expressions reference each other too deeply (circular reference?)".into());
    }
    let ctx = EvalCtx { project: ctx.project, comp_id: ctx.comp_id, comp: ctx.comp, time: ctx.time, expr: Some(host) };
    let comp = ctx.comp_id.0;
    let path = layer.props.path_of(prop.uid).unwrap_or_else(|| format!("@{}", prop.uid));
    let resolver = Resolver { ctx, own: Own { comp, layer, prop, path: path.clone() } };
    let current = value_resp(value, prop_dims(layer, prop));
    let begin = Begin {
        time: ctx.time.seconds(),
        value: &current,
        comp,
        layer: layer.id.0,
        path: &path,
        uid: prop.uid,
        index: ctx.comp.index_of(layer.id).unwrap_or(0) as f64,
        frame_duration: ctx.comp.frame_duration().seconds(),
    };
    // Answer the requests nearly every expression makes up front.
    let mut frame = Frame::default();
    for req in [Req::CompInfo { comp }, Req::LayerInfo { comp, layer: layer.id.0 }, Req::PropInfo { comp, layer: layer.id.0, path: path.clone() }] {
        let r = resolver.resolve(&req);
        frame.memo.insert(req, r);
    }
    FRAMES.with(|f| f.borrow_mut().push(frame));
    let _guard = FrameGuard;
    for _ in 0..MAX_PASSES {
        match runtime::run(text, &begin) {
            Run::Done(r) => return r.and_then(|o| runtime::to_value(&o, value)),
            Run::Pending => {
                let misses = FRAMES.with(|f| f.borrow_mut().get_mut(depth).map(|fr| std::mem::take(&mut fr.misses)).unwrap_or_default());
                for m in misses {
                    // May evaluate other expressions (nested frames above ours).
                    let r = resolver.resolve(&m);
                    FRAMES.with(|f| f.borrow_mut().get_mut(depth).map(|fr| fr.memo.insert(m, r)));
                }
            }
        }
    }
    Err("Error: expression needs too many property reads".into())
}

/// Evaluate `text` as if it were the expression on the property at `path` (e.g.
/// `transform/rotation`) of `layer` in `comp`, at comp time `t` seconds. Other properties'
/// expressions are evaluated too.
pub fn eval_standalone(project: &Project, comp: ItemId, layer: LayerId, path: &str, text: &str, t: f64) -> Result<Value, String> {
    let c = project.comp(comp).ok_or("no such comp")?;
    let l = c.layer(layer).ok_or("no such layer")?;
    let prop = l.props.prop(path).ok_or_else(|| format!("no property at {path}"))?;
    let ctx = EvalCtx::new(project, comp, c, Tick::from_seconds_f64(t));
    let value = prop.value_at(l.layer_time(ctx.time));
    evaluate(&Expressions, &ctx, l, prop, &value, text)
}

/// Evaluate the expression stored on the property at `path`, reporting errors (the renderer
/// silently falls back to the keyframed value instead).
pub fn eval_property(project: &Project, comp: ItemId, layer: LayerId, path: &str, t: f64) -> Result<Value, String> {
    let c = project.comp(comp).ok_or("no such comp")?;
    let l = c.layer(layer).ok_or("no such layer")?;
    let prop = l.props.prop(path).ok_or_else(|| format!("no property at {path}"))?;
    let ctx = EvalCtx::new(project, comp, c, Tick::from_seconds_f64(t));
    let value = prop.value_at(l.layer_time(ctx.time));
    match &prop.expr {
        Some(e) if prop.has_expression() => evaluate(&Expressions, &ctx, l, prop, &value, &e.text),
        _ => Ok(value),
    }
}

/// Syntax-check an expression (after the array-maths rewrite) without evaluating it.
pub fn check_syntax(text: &str) -> Result<(), String> {
    runtime::check(text)
}

#[cfg(test)]
mod tests;