diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index df2ba75..7a41a35 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -498,8 +498,8 @@ its 8 x 8 px flow grid: per-pixel choice between the frames was tried and read as patches. Both are measured with the local contrast an in-between keeps against the real frame, not PSNR or LPIPS, which reward -the blend that reads as fog. Video mode keeps the plain render. `FH_STILL=0` and `FH_NEAR=0` turn them off for -comparisons. +the blend that reads as fog. Video mode keeps the plain render. The nearest-source regions are an option (`nearest_source`, off by default); +`FH_STILL=0` turns the still test off for comparisons. ## Cadence (video mode) diff --git a/CHANGELOG.md b/CHANGELOG.md index 10c20bc..aa5f941 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,26 @@ follow semantic versioning as described in [CONTRIBUTING.md](CONTRIBUTING.md). ## [Unreleased] +## [0.4.1] - 2026-11-17 + +### Changed + +- Static protection is on by default (frames 8, tolerance 4) in every API: `SessionOptions`, `Options`, the C + defaults and the browser module, where `staticProtection: false` turns it off. A still overlay over a moving world + (HUD text, a crosshair, a bar) was painted over by the world the flow brought from both sides: the opaque overlay of + a synthetic 1080p HUD clip scored 14 to 16 dB and scores 24.5 to 29.5 dB once the protection has its history. + Captured 120 fps video without overlays (UVG, 14 clips) is unchanged (-0.00 dB). +- Nearest-source regions are off by default and became an option: `SessionOptions::nearest_source`, `nearestSource` + in the browser module, `FH_NEAR=1` in the environment for the C API. On the same 14 clips they cost 0.53 dB and + gained no sharpness (0.772 against 0.775 of the ground truth's local contrast); on ground-truth triplets the + realtime defaults now score ATD 31.66, CS2 29.32, natural 38.18 dB (0.3.7: 30.62, 28.83, 37.32). + +### Fixed + +- `VideoSource` (browser adapters) works in a browser without `importExternalTexture` (Firefox 141 and 142): the + frame goes through a 2D canvas there instead of failing with "importExternalTexture is not a function". That path + costs a CPU copy per frame; `VideoSource.path` tells a host which one is in use (`copy`, `external`, `canvas`). + ## [0.4.0] - 2026-11-16 ### Added diff --git a/Cargo.lock b/Cargo.lock index edbd23e..29337fa 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -548,7 +548,7 @@ dependencies = [ [[package]] name = "flyhigh-capi" -version = "0.4.0" +version = "0.4.1" dependencies = [ "anyhow", "flyhigh-engine", @@ -558,7 +558,7 @@ dependencies = [ [[package]] name = "flyhigh-cli" -version = "0.4.0" +version = "0.4.1" dependencies = [ "anyhow", "bytemuck", @@ -573,7 +573,7 @@ dependencies = [ [[package]] name = "flyhigh-engine" -version = "0.4.0" +version = "0.4.1" dependencies = [ "anyhow", "ash", @@ -590,7 +590,7 @@ dependencies = [ [[package]] name = "flyhigh-options" -version = "0.4.0" +version = "0.4.1" dependencies = [ "proc-macro2", "quote", @@ -599,7 +599,7 @@ dependencies = [ [[package]] name = "flyhigh-player" -version = "0.4.0" +version = "0.4.1" dependencies = [ "anyhow", "flyhigh-engine", @@ -610,7 +610,7 @@ dependencies = [ [[package]] name = "flyhigh-web" -version = "0.4.0" +version = "0.4.1" dependencies = [ "console_error_panic_hook", "flyhigh-engine", diff --git a/Cargo.toml b/Cargo.toml index 8c71b16..b1fe96f 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -5,7 +5,7 @@ members = ["crates/flyhigh-options", "crates/flyhigh-engine", "crates/flyhigh-ca default-members = ["crates/flyhigh-options", "crates/flyhigh-engine", "crates/flyhigh-capi", "crates/flyhigh-cli", "examples/player"] [workspace.package] -version = "0.4.0" +version = "0.4.1" edition = "2021" license = "Apache-2.0" repository = "https://github.com/getflyhigh/flyhigh-engine" diff --git a/bindings/python/flyhigh.py b/bindings/python/flyhigh.py index 5fa9edc..d7fc0d4 100644 --- a/bindings/python/flyhigh.py +++ b/bindings/python/flyhigh.py @@ -327,7 +327,9 @@ def _session_options(width: int, height: int, internal=None, k: int = 1, repair: o.k = k o.repair = repair o.render = _RENDER[render] - if static_protection: + if static_protection is False: + o.keep_static = 0 + elif static_protection: o.keep_static = 1 if isinstance(static_protection, dict): o.static_frames = int(static_protection.get("frames", o.static_frames)) @@ -343,7 +345,7 @@ def _session_options(width: int, height: int, internal=None, k: int = 1, repair: class Session: """The plans of a model for one frame size: Session(engine, model, width, height, internal="auto"|"frame"|(w, h), - k=1, repair=1, render="model"|"bilinear"|"bicubic", static_protection=None|True|{"frames", "tolerance"}, + k=1, repair=1, render="model"|"bilinear"|"bicubic", static_protection=None|True|False|{"frames", "tolerance"}, fast_render=False, linear_t=False, keep_maps=False, protection_mask=False, tune=None).""" def __init__(self, engine: Engine, model: Model, width: int, height: int, **options): diff --git a/crates/flyhigh-capi/src/lib.rs b/crates/flyhigh-capi/src/lib.rs index ca469d6..a6537ac 100644 --- a/crates/flyhigh-capi/src/lib.rs +++ b/crates/flyhigh-capi/src/lib.rs @@ -111,7 +111,7 @@ pub extern "C" fn fh_options_default(width: u32, height: u32) -> FhOptions { repair: o.repair, cadence: 0, render_sampling: 0, - keep_static: 0, + keep_static: 1, static_frames: o.static_frames, static_tolerance: o.static_tolerance, fast_render: 0, diff --git a/crates/flyhigh-capi/tests/defaults.rs b/crates/flyhigh-capi/tests/defaults.rs index cd0e33f..c7d4e3c 100644 --- a/crates/flyhigh-capi/tests/defaults.rs +++ b/crates/flyhigh-capi/tests/defaults.rs @@ -16,7 +16,7 @@ fn options_default_matches_rust() { (c.width, c.height, c.k, c.internal_w, c.internal_h, c.mode, c.repair, c.cadence, c.render_sampling), (1920, 1080, 1, 856, 480, 0, DEFAULT_REPAIR, 0, 0) ); - assert_eq!((c.keep_static, c.fast_render, c.linear_t), (0, 0, 0)); + assert_eq!((c.keep_static, c.fast_render, c.linear_t), (1, 0, 0)); let s = fh_options_default(640, 480); assert_eq!((s.internal_w, s.internal_h), (0, 0)); // 0, 0 = the frame size } diff --git a/crates/flyhigh-engine/src/api.rs b/crates/flyhigh-engine/src/api.rs index a5f2e64..e313668 100644 --- a/crates/flyhigh-engine/src/api.rs +++ b/crates/flyhigh-engine/src/api.rs @@ -94,7 +94,7 @@ pub struct Options { /// render source sampler: None = the model's (manifest), Some(true) bicubic, Some(false) bilinear pub cubic: Option, /// static protection: pixels equal in both source frames (HUD, burnt-in subtitles, logos) are kept as they are - /// instead of being warped with the motion behind them (default off) + /// instead of being warped with the motion behind them (default on) pub keep_static: bool, /// static protection: unchanged source frames before a pixel is protected (default 8) pub static_frames: u32, @@ -121,7 +121,7 @@ impl Options { repair: DEFAULT_REPAIR, cadence: false, cubic: None, - keep_static: false, + keep_static: true, static_frames: crate::DEFAULT_STATIC_FRAMES, static_tolerance: crate::DEFAULT_STATIC_TOLERANCE, fast_render: false, @@ -147,6 +147,7 @@ impl Options { fast_render: self.fast_render, linear_t: self.linear_t, protection_mask: false, + near: crate::options::near_default(), } } } diff --git a/crates/flyhigh-engine/src/gen_tex.rs b/crates/flyhigh-engine/src/gen_tex.rs index d67b753..2015dfd 100644 --- a/crates/flyhigh-engine/src/gen_tex.rs +++ b/crates/flyhigh-engine/src/gen_tex.rs @@ -62,6 +62,8 @@ pub struct TexOptions { pub fast_render: bool, pub linear_t: bool, pub protection_mask: bool, + /// nearest-source regions (`NetOpts::near`, realtime mode) + pub near: bool, } impl TexOptions { /// defaults: k 1, internal size `default_internal`, realtime, repair `DEFAULT_REPAIR`, no cadence, model sampler, no static protection @@ -77,12 +79,13 @@ impl TexOptions { repair: crate::DEFAULT_REPAIR, cadence: false, cubic: None, - keep_static: false, + keep_static: true, static_frames: crate::DEFAULT_STATIC_FRAMES, static_tolerance: crate::DEFAULT_STATIC_TOLERANCE, fast_render: false, linear_t: false, protection_mask: false, + near: crate::options::near_default(), } } } @@ -211,7 +214,7 @@ impl GenTex { // games (realtime); video and anime keep the soft blend until it is measured there decisive: crate::options::decisive_default() && opts.mode == TexMode::Realtime, still: crate::options::still_default() && opts.mode == TexMode::Realtime, - near: crate::options::near_default() && opts.mode == TexMode::Realtime, + near: opts.near && opts.mode == TexMode::Realtime, }; let mut sess = Vec::new(); for _ in 0..n_sess { diff --git a/crates/flyhigh-engine/src/options.rs b/crates/flyhigh-engine/src/options.rs index 8af0d5c..07603a5 100644 --- a/crates/flyhigh-engine/src/options.rs +++ b/crates/flyhigh-engine/src/options.rs @@ -236,11 +236,12 @@ pub struct NetOpts { pub fn decisive_default() -> bool { std::env::var("FH_BLEND").is_ok_and(|v| v.trim() == "decisive") } -/// Nearest-source regions for hosts (Session, Stream realtime); FH_NEAR=0 turns them off for comparisons. On a flick the -/// network cannot follow, the blend of two misplaced copies reads as fog: the nearer frame, warped, reads as a short -/// hold. +/// The default of `SessionOptions::nearest_source`: off, FH_NEAR=1 turns it on. On a flick +/// the network cannot follow, the blend of two misplaced copies reads as fog and the nearer frame, warped, reads as a +/// short hold; measured on captured 120 fps video (FlyHigh-Bench, UVG, 14 clips) the regions cost 0.53 dB and gain no +/// sharpness, so they wait for a test that separates the flicks they help from the motion they hurt. pub fn near_default() -> bool { - std::env::var("FH_NEAR").map_or(true, |v| v.trim() != "0") + std::env::var("FH_NEAR").is_ok_and(|v| v.trim() == "1") } /// The still test for hosts (Session, Stream realtime); FH_STILL=0 turns it off for comparisons. The model's reference /// render (`NetOpts::new`, the parity fixtures) has none. @@ -324,7 +325,10 @@ mod tests { } let session = &groups[1].options; assert_eq!(session.iter().find(|o| o.name == "k").map(|o| o.default.as_str()), Some("1")); - assert_eq!(session.iter().find(|o| o.name == "static_protection").map(|o| o.default.as_str()), Some("off")); + assert_eq!( + session.iter().find(|o| o.name == "static_protection").map(|o| o.default.as_str()), + Some("frames 8, tolerance 4") + ); } #[test] diff --git a/crates/flyhigh-engine/src/session.rs b/crates/flyhigh-engine/src/session.rs index 281f7fe..80ec11b 100644 --- a/crates/flyhigh-engine/src/session.rs +++ b/crates/flyhigh-engine/src/session.rs @@ -114,6 +114,12 @@ pub struct SessionOptions { /// Works with or without `static_protection`; a rewritten mask applies from the next pair. #[option(values = "on, off", c = "protection_mask (0, 1)")] pub protection_mask: bool, + /// Where the two warped frames disagree over a whole region (a flick the network could not follow), the + /// in-between takes the nearer source frame alone there: a short hold instead of the fog of two misplaced + /// copies. Off by default: on captured 120 fps video it costs 0.53 dB and gains no sharpness; a host whose + /// viewers prefer the hold on fast turns turns it on. The environment variable `FH_NEAR=1` sets the default to on. + #[option(default = "off", values = "on, off", c = "none (FH_NEAR=1 in the environment)")] + pub nearest_source: bool, /// Kernel choices from an earlier autotune on this device at this size (the text of a `TuneTable`); without one /// the engine tunes at the first build, or uses the fixed routing when the autotune is off. #[option(default = "none", values = "an autotune table", c = "tune (text, NULL = none)")] @@ -129,11 +135,12 @@ impl SessionOptions { k: 1, repair: crate::DEFAULT_REPAIR, render: RenderSampling::Model, - static_protection: None, + static_protection: Some(StaticProtection::default()), fast_render: false, linear_t: false, keep_maps: false, protection_mask: false, + nearest_source: crate::options::near_default(), tune: None, } } @@ -192,7 +199,7 @@ impl SessionOptions { protection_mask: self.protection_mask, decisive: crate::options::decisive_default(), still: crate::options::still_default(), - near: crate::options::near_default(), + near: self.nearest_source, } } @@ -220,6 +227,7 @@ impl SessionOptions { fast_render: self.fast_render, linear_t: self.linear_t, protection_mask: self.protection_mask, + near: self.nearest_source, } } } diff --git a/crates/flyhigh-engine/tests/defaults.rs b/crates/flyhigh-engine/tests/defaults.rs index a0bc298..be881cc 100644 --- a/crates/flyhigh-engine/tests/defaults.rs +++ b/crates/flyhigh-engine/tests/defaults.rs @@ -18,7 +18,7 @@ fn generator_defaults() { let o = Options::new(1920, 1080); assert_eq!((o.k, o.repair, o.mode, o.cadence, o.cubic), (1, DEFAULT_REPAIR, Mode::Realtime, false, None)); assert_eq!(o.internal, Some((856, 480))); - assert!(!o.keep_static && !o.tex_options().keep_static && !TexOptions::new(64, 64).keep_static); + assert!(o.keep_static && o.tex_options().keep_static && TexOptions::new(64, 64).keep_static); assert_eq!(Options::new(800, 600).internal, None); let t = o.tex_options(); assert_eq!((t.w, t.h, t.iw, t.ih, t.k, t.repair), (1920, 1080, 856, 480, 1, 1)); diff --git a/crates/flyhigh-engine/tests/golden_plans.rs b/crates/flyhigh-engine/tests/golden_plans.rs index 310fadd..63b2124 100644 --- a/crates/flyhigh-engine/tests/golden_plans.rs +++ b/crates/flyhigh-engine/tests/golden_plans.rs @@ -81,6 +81,7 @@ fn dump_video(e: &Engine) -> String { let mut o = TexOptions::new(1280, 720); o.mode = TexMode::Video; o.cadence = true; + o.keep_static = false; let g = GenTex::new(&e.gpu, &e.blob, &e.ops, o, None).expect("video session"); let d = |s: &SessionExt| format!("# pair\n{}# mid\n{}", plan_dump(&s.plan_pair), plan_dump(&s.plan_mid)); assert_eq!(g.sess.len(), 3); diff --git a/crates/flyhigh-web/js/adapters.js b/crates/flyhigh-web/js/adapters.js index 366340b..eedb063 100644 --- a/crates/flyhigh-web/js/adapters.js +++ b/crates/flyhigh-web/js/adapters.js @@ -71,10 +71,14 @@ function draw(device, pipe, bindGroup, view) { /** Writes a