Skip to content

The truly free, open-source, local-first, cross-platform CapCut replacement. Scriptable through a JSON-RPC API & MCP.

feat(effects): package format 2 - effects drawn in light, checked by probes on the GPU

Jareer3598eb07d8c0
diff --git a/src/Cargo.lock b/src/Cargo.lock
index cc7488de..3b3ac788 100644
--- a/src/Cargo.lock
+++ b/src/Cargo.lock
@@ -1289,6 +1289,7 @@ version = "0.2.4"
dependencies = [
"concat-core",
"concat-effects",
+ "half",
"log",
"pollster",
"wgpu",
diff --git a/src/crates/concat-cli/src/main.rs b/src/crates/concat-cli/src/main.rs
index f4457e3d..2edc9099 100644
--- a/src/crates/concat-cli/src/main.rs
+++ b/src/crates/concat-cli/src/main.rs
@@ -11,8 +11,8 @@
//! is the same API on a socket, for callers that are other processes.
//! `preview` is how the window's effect cards get their pictures: one still
//! through one package at its defaults. `check` is what an author runs on
-//! an effect package before sharing it: the same load the window does, and
-//! its fixtures, with every fault named.
+//! an effect package before sharing it: the same load the window does, its
+//! fixtures, and its probes on the GPU, with every fault named.
use std::error::Error;
use std::io::{BufRead, Write};
@@ -114,7 +114,7 @@ enum Command {
/// Check effect packages before sharing them: load each folder the way
/// the window does, hold its id against the built-ins, run its
- /// fixtures, and name every fault. `path` is one package folder - the
+ /// fixtures and its probes, and name every fault. `path` is one package folder - the
/// one with `effect.toml` in it - or a folder of them, such as the
/// app's own effects folder. Exits non-zero when any package fails.
Check {
@@ -303,8 +303,12 @@ fn check(path: &Path) -> Result<(), Box<dyn Error>> {
};
let taken = concat_effects::Catalogue::builtin();
let mut failed = 0;
+ let mut gpu = None;
for folder in &folders {
- let problems = concat_effects::Package::check_folder(folder, taken);
+ let mut problems = concat_effects::Package::check_folder(folder, taken);
+ if problems.is_empty() {
+ problems = check_probes(folder, &mut gpu);
+ }
if problems.is_empty() {
println!("ok {}", folder.display());
} else {
@@ -324,6 +328,45 @@ fn check(path: &Path) -> Result<(), Box<dyn Error>> {
Ok(())
}
+/// The probes of the package in `folder`, each run on the GPU, one line
+/// per probe that does not hold. The compositor is made on the first
+/// package that has any, and a machine that cannot make one says so as a
+/// fault: a probe that did not run has not passed.
+fn check_probes(folder: &Path, gpu: &mut Option<WgpuCompositor>) -> Vec<String> {
+ // A folder that does not load was reported by `check_folder`.
+ let Ok(package) = concat_effects::Package::from_folder(folder) else {
+ return Vec::new();
+ };
+ if package.probes.is_empty() {
+ return Vec::new();
+ }
+ if gpu.is_none() {
+ *gpu = WgpuCompositor::new();
+ }
+ let Some(gpu) = gpu.as_mut() else {
+ return vec![format!(
+ "{}: no GPU or software renderer is available to run its probes on",
+ package.id()
+ )];
+ };
+ let mut problems = Vec::new();
+ for (n, probe) in package.probes.iter().enumerate() {
+ let Some(pass) = package.probe_pass(probe) else {
+ continue;
+ };
+ let label = probe.label(n);
+ match gpu.probe(&[pass], probe.input, 8, 0.0) {
+ Some(got) => {
+ if let Err(error) = probe.check(got) {
+ problems.push(format!("{}: {label}\n {error}", package.id()));
+ }
+ }
+ None => problems.push(format!("{}: {label}: the GPU did not answer", package.id())),
+ }
+ }
+ problems
+}
+
fn probe(path: &PathBuf) -> Result<(), Box<dyn Error>> {
let info = concat_media::probe(path)?;
diff --git a/src/crates/concat-effects/packages/concat.exposure/effect.toml b/src/crates/concat-effects/packages/concat.exposure/effect.toml
new file mode 100644
index 00000000..0cfea71f
--- /dev/null
+++ b/src/crates/concat-effects/packages/concat.exposure/effect.toml
@@ -0,0 +1,23 @@
+format = 2
+
+[effect]
+id = "concat.exposure"
+name = "Exposure"
+kind = "effect"
+category = "Color"
+order = 10
+intensity = "stops"
+description = "Brighter or darker by stops of light, as the lens would make it, highlights kept."
+
+[[param]]
+key = "stops"
+label = "Exposure"
+min = -4
+max = 4
+default = 0
+step = 0.05
+unit = "EV"
+animate = true
+
+[wgsl]
+entry = "effect.wgsl"
diff --git a/src/crates/concat-effects/packages/concat.exposure/effect.wgsl b/src/crates/concat-effects/packages/concat.exposure/effect.wgsl
new file mode 100644
index 00000000..29b3ae1f
--- /dev/null
+++ b/src/crates/concat-effects/packages/concat.exposure/effect.wgsl
@@ -0,0 +1,9 @@
+struct Params { stops: f32 }
+
+// The light scaled by two to the stops: what opening or closing the lens
+// does. Nothing is clipped, so a highlight pushed past white and brought
+// back down by a later effect is the highlight it was.
+fn effect(uv: vec2<f32>) -> vec4<f32> {
+ let c = sample(uv);
+ return vec4<f32>(exposure(c.rgb, params.stops), c.a);
+}
diff --git a/src/crates/concat-effects/packages/concat.exposure/fixtures.toml b/src/crates/concat-effects/packages/concat.exposure/fixtures.toml
new file mode 100644
index 00000000..0a1ab3d6
--- /dev/null
+++ b/src/crates/concat-effects/packages/concat.exposure/fixtures.toml
@@ -0,0 +1,37 @@
+# Colours in the working space: linear light, 1.0 the white of an SDR
+# picture, 0.18 middle grey. Checked on the GPU by concat-render's suite.
+
+[[probe]]
+name = "default"
+input = [0.18, 0.18, 0.18, 1.0]
+expect = [0.18, 0.18, 0.18, 1.0]
+
+[[probe]]
+name = "minimum"
+at = "min"
+input = [0.8, 0.4, 0.2, 1.0]
+expect = [0.05, 0.025, 0.0125, 1.0]
+
+[[probe]]
+name = "maximum"
+at = "max"
+input = [0.1, 0.05, 0.02, 1.0]
+expect = [1.6, 0.8, 0.32, 1.0]
+
+[[probe]]
+name = "a highlight above white comes down unclipped"
+params = { stops = -1.5 }
+input = [4.0, 2.0, 0.5, 1.0]
+expect = [1.4142, 0.7071, 0.1768, 1.0]
+
+[[probe]]
+name = "a colour outside Rec. 709 keeps its negative channel"
+params = { stops = 1 }
+input = [0.5, 0.2, -0.05, 1.0]
+expect = [1.0, 0.4, -0.1, 1.0]
+
+[[probe]]
+name = "alpha is left alone"
+params = { stops = 2 }
+input = [0.2, 0.1, 0.05, 0.5]
+expect = [0.8, 0.4, 0.2, 0.5]
diff --git a/src/crates/concat-effects/src/catalogue.rs b/src/crates/concat-effects/src/catalogue.rs
index 1bfd5de2..b07f601c 100644
--- a/src/crates/concat-effects/src/catalogue.rs
+++ b/src/crates/concat-effects/src/catalogue.rs
@@ -82,6 +82,9 @@ pub struct Package {
transition: Option<TransitionShader>,
/// The pinned outputs shipped with the package.
pub fixtures: Vec<Fixture>,
+ /// The pinned colours shipped with the package: what its shader makes
+ /// of a picture, checked on a GPU.
+ pub probes: Vec<Probe>,
/// The folder the package was loaded from; None for a built-in.
pub folder: Option<std::path::PathBuf>,
/// The table the manifest's `[lut]` names, read at load.
@@ -122,11 +125,77 @@ pub struct Fixture {
pub chain: String,
}
+/// One pinned colour from `fixtures.toml`'s `[[probe]]`s: a picture of one
+/// colour through the package's shader at these parameters comes out as
+/// this colour. Both are in the compositor's working space - linear light,
+/// 1.0 the white of an SDR picture - and the check is made on a GPU, where
+/// the shader runs: concat-render's suite for the built-ins, `concat-cli
+/// check` for anyone's.
+#[derive(Deserialize, Clone, PartialEq, Debug)]
+#[serde(deny_unknown_fields)]
+pub struct Probe {
+ /// A name for the failure message.
+ #[serde(default)]
+ pub name: String,
+ /// The starting point every parameter takes.
+ #[serde(default)]
+ pub at: At,
+ /// Parameters set on top of `at`, a filter's `intensity` among them.
+ #[serde(default)]
+ pub params: BTreeMap<String, f64>,
+ /// The colour of every pixel going in, straight RGBA.
+ pub input: [f32; 4],
+ /// The colour the middle pixel must come out as.
+ pub expect: [f32; 4],
+ /// How far a channel may land from `expect`, as a fraction of the
+ /// expected value (of 0.01, for a value nearer zero than that). Half
+ /// floats keep about three significant digits; the default allows a
+ /// few steps of them.
+ #[serde(default = "Probe::default_tolerance")]
+ pub tolerance: f32,
+}
+
+impl Probe {
+ fn default_tolerance() -> f32 {
+ 0.004
+ }
+
+ /// What a failure message calls the probe, the `n`th in its file.
+ pub fn label(&self, n: usize) -> String {
+ case_label(&self.name, n)
+ }
+
+ /// Whether `got` is the colour the probe expects, to its tolerance; the
+ /// failure shows both.
+ pub fn check(&self, got: [f32; 4]) -> Result<(), String> {
+ let close = self.expect.iter().zip(got).all(|(want, got)| {
+ let allowed = self.tolerance * want.abs().max(0.01);
+ (got - want).abs() <= allowed
+ });
+ if close {
+ Ok(())
+ } else {
+ Err(format!("expected {:?}\n rendered {got:?}", self.expect))
+ }
+ }
+}
+
+/// What a failure message calls the `n`th case of a fixtures file.
+fn case_label(name: &str, n: usize) -> String {
+ if name.is_empty() {
+ format!("case {}", n + 1)
+ } else {
+ name.to_owned()
+ }
+}
+
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct FixtureFile {
#[serde(default, rename = "case")]
cases: Vec<Fixture>,
+ #[serde(default, rename = "probe")]
+ probes: Vec<Probe>,
}
impl Package {
@@ -268,14 +337,33 @@ impl Package {
}
};
- let fixtures = match fixtures {
- None => Vec::new(),
+ let (fixtures, probes) = match fixtures {
+ None => (Vec::new(), Vec::new()),
Some(source) => {
let file: FixtureFile = toml::from_str(source)
.map_err(|error| invalid(format!("fixtures: {error}")))?;
- file.cases
+ (file.cases, file.probes)
}
};
+ if !probes.is_empty() && shader.is_none() {
+ return Err(invalid(
+ "fixtures: a [[probe]] pins what a [wgsl] shader draws, and the package has none"
+ .to_owned(),
+ ));
+ }
+ for (n, probe) in probes.iter().enumerate() {
+ let filter = manifest.effect.kind == Kind::Filter;
+ if let Some(key) = probe
+ .params
+ .keys()
+ .find(|key| manifest.param(key).is_none() && !(filter && key.as_str() == INTENSITY))
+ {
+ return Err(invalid(format!(
+ "fixtures: probe `{}` sets `{key}`, which is not a parameter",
+ probe.label(n)
+ )));
+ }
+ }
if manifest.lut.is_some() && table.is_none() {
// The table is a file beside the manifest, and only a folder
@@ -294,6 +382,7 @@ impl Package {
shader,
transition,
fixtures,
+ probes,
folder,
lut,
};
@@ -445,9 +534,38 @@ impl Package {
/// runs once before the package is offered. None for a package with
/// no shader.
pub fn trial_pass(&self) -> Option<ShaderPass> {
+ self.pass(&BTreeMap::new(), None)
+ }
+
+ /// The pass this package's shader makes with the parameters in `set`,
+ /// or None for a package with no shader. Keys the manifest does not
+ /// declare are dropped, but for a filter's intensity, which mixes the
+ /// look over the untouched picture; an effect is always whole.
+ pub fn pass(
+ &self,
+ set: &BTreeMap<String, f64>,
+ reveal_map: Option<Arc<RevealMap>>,
+ ) -> Option<ShaderPass> {
let shader = self.shader.as_ref()?;
- let values = self.resolve(&BTreeMap::new());
- Some(shader.pass(&values, &self.manifest.params, 1.0, self.lut.clone(), None))
+ let intensity = if self.kind() == Kind::Filter {
+ (set.get(INTENSITY).copied().unwrap_or(100.0) / 100.0).clamp(0.0, 1.0) as f32
+ } else {
+ 1.0
+ };
+ let values = self.resolve(set);
+ Some(shader.pass(
+ &values,
+ &self.manifest.params,
+ intensity,
+ self.lut.clone(),
+ reveal_map,
+ ))
+ }
+
+ /// The pass a probe checks: the parameters at its starting point with
+ /// its own set on top. None for a package with no shader.
+ pub fn probe_pass(&self, probe: &Probe) -> Option<ShaderPass> {
+ self.pass(&self.set_at(probe.at, &probe.params), None)
}
/// The shader, when the package renders on the GPU.
@@ -504,6 +622,13 @@ impl Package {
.collect()
}
+ /// Every declared parameter at `at`, with `set` on top.
+ fn set_at(&self, at: At, set: &BTreeMap<String, f64>) -> BTreeMap<String, f64> {
+ let mut params = self.params_at(at);
+ params.extend(set.iter().map(|(key, value)| (key.clone(), *value)));
+ params
+ }
+
/// Every declared parameter: the value in `set`, or the default. Keys
/// the manifest does not declare are dropped.
pub fn resolve(&self, set: &BTreeMap<String, f64>) -> BTreeMap<String, f64> {
@@ -622,15 +747,8 @@ impl Package {
pub fn check_fixtures(&self) -> Vec<String> {
let mut failures = Vec::new();
for (n, case) in self.fixtures.iter().enumerate() {
- let mut params = self.params_at(case.at);
- for (key, value) in &case.params {
- params.insert(key.clone(), *value);
- }
- let label = if case.name.is_empty() {
- format!("case {}", n + 1)
- } else {
- case.name.clone()
- };
+ let params = self.set_at(case.at, &case.params);
+ let label = case_label(&case.name, n);
match self.ffmpeg_fragment(&params, case.index) {
Ok(Some(chain)) if chain == case.chain => {}
Ok(Some(chain)) => failures.push(format!(
@@ -1020,22 +1138,8 @@ impl Catalogue {
.iter()
.filter(|applied| applied.enabled)
.filter_map(|applied| {
- let package = self.get(&applied.id)?;
- let shader = package.shader()?;
- let set = params_of(applied);
- let intensity = if package.kind() == Kind::Filter {
- (set.get(INTENSITY).copied().unwrap_or(100.0) / 100.0).clamp(0.0, 1.0) as f32
- } else {
- 1.0
- };
- let values = package.resolve(&set);
- Some(shader.pass(
- &values,
- &package.manifest.params,
- intensity,
- package.lut.clone(),
- reveal_map.clone(),
- ))
+ self.get(&applied.id)?
+ .pass(&params_of(applied), reveal_map.clone())
})
.collect()
}
diff --git a/src/crates/concat-effects/src/lib.rs b/src/crates/concat-effects/src/lib.rs
index b0324c81..217edd1f 100644
--- a/src/crates/concat-effects/src/lib.rs
+++ b/src/crates/concat-effects/src/lib.rs
@@ -14,6 +14,12 @@
//! filtergraph where the chains have always run. `[wgsl]` is a shader,
//! declared here and run by the compositor.
//!
+//! From package format 2 a package that draws the picture is a shader
+//! alone, sampling the compositor's linear working space as it is (see
+//! [`shader`]), and what its `fixtures.toml` pins is colours - `[[probe]]`,
+//! a colour in and the colour out, checked on a GPU - where a chain's pins
+//! strings (`[[case]]`). Sound stays FFmpeg's.
+//!
//! The document is untouched by any of this: a clip still stores
//! `{ id, params, enabled }`, and an id the catalogue does not know is
//! skipped at render time.
@@ -30,9 +36,9 @@ mod builtins {
include!(concat!(env!("OUT_DIR"), "/builtins.rs"));
}
-pub use catalogue::{At, Catalogue, Fixture, Package, package_folders, package_stamp};
+pub use catalogue::{At, Catalogue, Fixture, Package, Probe, package_folders, package_stamp};
pub use manifest::{FORMAT, Kind, Manifest, Param, ParamType};
-pub use shader::{Shader, TransitionShader};
+pub use shader::{Contract, Shader, TransitionShader};
/// Why a package could not be loaded.
#[derive(thiserror::Error, Debug)]
@@ -188,6 +194,104 @@ mod tests {
assert!(gaps.is_empty(), "\n{}", gaps.join("\n"));
}
+ /// The same rule for a package drawn in light, whose pinned outputs
+ /// are colours rather than chains.
+ #[test]
+ fn every_scene_linear_package_probes_its_default_and_every_slider_bound() {
+ let mut gaps = Vec::new();
+ let mut linear = 0;
+ for package in Catalogue::builtin().packages() {
+ if !package.manifest.scene_linear() || package.shader().is_none() {
+ continue;
+ }
+ linear += 1;
+ let has = |at: At| {
+ package
+ .probes
+ .iter()
+ .any(|probe| probe.at == at && probe.params.is_empty())
+ };
+ if !has(At::Default) {
+ gaps.push(format!("{}: no default probe", package.id()));
+ }
+ if !package.manifest.params.is_empty() {
+ if !has(At::Min) {
+ gaps.push(format!("{}: no min probe", package.id()));
+ }
+ if !has(At::Max) {
+ gaps.push(format!("{}: no max probe", package.id()));
+ }
+ }
+ }
+ assert!(linear >= 1, "no package is drawn in light yet");
+ assert!(gaps.is_empty(), "\n{}", gaps.join("\n"));
+ }
+
+ const EXPOSED: &str = "format = 2\n[effect]\nid = \"a.lift\"\nname = \"Lift\"\nkind = \"effect\"\n\
+ [[param]]\nkey = \"stops\"\nlabel = \"Stops\"\nmin = -2\nmax = 2\n\
+ [wgsl]\nentry = \"effect.wgsl\"\n";
+ const EXPOSE: &str = "struct Params { stops: f32 }\nfn effect(uv: vec2<f32>) -> vec4<f32> { let c = sample(uv); return vec4<f32>(exposure(c.rgb, params.stops), c.a); }";
+
+ /// A probe pins what a shader draws, so it needs a shader, and may set
+ /// only what the package declares.
+ #[test]
+ fn a_probe_sets_only_declared_knobs_of_a_shader() {
+ let probe = |params: &str| {
+ format!(
+ "[[probe]]\nname = \"up\"\nparams = {{ {params} }}\ninput = [0.25, 0.25, 0.25, 1]\nexpect = [0.5, 0.5, 0.5, 1]\n"
+ )
+ };
+ let package = Package::from_sources(EXPOSED, Some(&probe("stops = 1")), Some(EXPOSE))
+ .expect("a probe on a shader loads");
+ let pass = package
+ .probe_pass(&package.probes[0])
+ .expect("a shader's pass");
+ assert_eq!(pass.values.get("stops"), Some(&1.0));
+ assert_eq!(pass.intensity, 1.0);
+
+ let error = Package::from_sources(EXPOSED, Some(&probe("gain = 1")), Some(EXPOSE))
+ .expect_err("an undeclared knob")
+ .to_string();
+ assert!(error.contains("`gain`"), "{error}");
+ let error = Package::from_sources(EXPOSED, Some(&probe("intensity = 50")), Some(EXPOSE))
+ .expect_err("an effect has no intensity")
+ .to_string();
+ assert!(error.contains("`intensity`"), "{error}");
+ let filter = EXPOSED.replace("kind = \"effect\"", "kind = \"filter\"");
+ let package = Package::from_sources(&filter, Some(&probe("intensity = 50")), Some(EXPOSE))
+ .expect("a filter's intensity is its mix");
+ assert_eq!(
+ package.probe_pass(&package.probes[0]).map(|p| p.intensity),
+ Some(0.5)
+ );
+
+ let error = Package::from_sources(TINT, Some(&probe("hue = 1")), None)
+ .expect_err("a chain has no shader to probe")
+ .to_string();
+ assert!(error.contains("[wgsl]"), "{error}");
+ }
+
+ /// A probe allows a fraction of the expected value, with a floor near
+ /// zero, and nothing that is not a number.
+ #[test]
+ fn a_probe_holds_to_its_tolerance() {
+ let probe = Probe {
+ name: String::new(),
+ at: At::Default,
+ params: BTreeMap::new(),
+ input: [0.0; 4],
+ expect: [2.0, 0.5, 0.0, 1.0],
+ tolerance: 0.01,
+ };
+ assert!(probe.check([2.019, 0.4951, 0.0000999, 1.0]).is_ok());
+ assert!(probe.check([2.03, 0.5, 0.0, 1.0]).is_err(), "1.5 % off");
+ assert!(probe.check([2.0, 0.5, 0.0002, 1.0]).is_err(), "off zero");
+ let error = probe
+ .check([2.0, f32::NAN, 0.0, 1.0])
+ .expect_err("not a number");
+ assert!(error.contains("NaN"), "{error}");
+ }
+
#[test]
fn built_in_ids_are_namespaced_and_bare_aliases_still_resolve() {
let catalogue = Catalogue::builtin();
diff --git a/src/crates/concat-effects/src/manifest.rs b/src/crates/concat-effects/src/manifest.rs
index 9aee1cb5..ec60f198 100644
--- a/src/crates/concat-effects/src/manifest.rs
+++ b/src/crates/concat-effects/src/manifest.rs
@@ -18,7 +18,17 @@ use crate::Error;
/// compositor. Bumped when any of those changes in a way an older build
/// could not read, so a package written for a newer Concat says so rather
/// than failing in the shader compiler.
-pub const FORMAT: u32 = 1;
+///
+/// Format 2 is the scene-linear contract: the shader samples the working
+/// space as it is - linear light, unclipped, 1.0 the white of an SDR
+/// picture - and a package that draws the picture runs on the GPU alone,
+/// with no `[ffmpeg]` chain. Format 1 packages still load, and their
+/// shaders are handed the gamma-encoded `0..1` picture they were written
+/// for (see `concat-effects/src/shader.rs`).
+pub const FORMAT: u32 = 2;
+
+/// The first format whose shaders sample the working space as it is.
+pub const SCENE_LINEAR: u32 = 2;
/// A parsed `effect.toml`.
#[derive(Deserialize, Clone, PartialEq, Debug)]
@@ -471,10 +481,24 @@ impl Manifest {
if self.wgsl.is_some() && self.effect.kind == Kind::Audio {
return Err(self.invalid("a [wgsl] package cannot be audio"));
}
+ // The picture is drawn on the GPU, in light, and nowhere else:
+ // a chain would run on eight bits the shader never sees.
+ if self.scene_linear() && self.effect.kind.is_visual() && self.ffmpeg.is_some() {
+ return Err(self.invalid(format!(
+ "a format {SCENE_LINEAR} package draws the picture on the GPU alone: \
+ drop the [ffmpeg] table"
+ )));
+ }
}
Ok(())
}
+ /// Whether the package's shader samples the working space as it is,
+ /// rather than the gamma-encoded `0..1` a format 1 shader is given.
+ pub fn scene_linear(&self) -> bool {
+ self.format >= SCENE_LINEAR
+ }
+
/// The declared parameter with this key.
pub fn param(&self, key: &str) -> Option<&Param> {
self.params.iter().find(|param| param.key == key)
@@ -572,17 +596,34 @@ mod tests {
#[test]
fn the_format_is_the_first_thing_read() {
assert_eq!(Manifest::parse(GOOD).expect("parses").format, 1);
- assert_eq!(
- Manifest::parse(&format!("format = {FORMAT}\n{GOOD}"))
- .expect("parses")
- .format,
- FORMAT
+ assert!(!Manifest::parse(GOOD).expect("parses").scene_linear());
+ let shader = GOOD.replace(
+ "[ffmpeg]\n chain = \"gblur=sigma={fixed(radius, 1)}\"",
+ "[wgsl]\n entry = \"effect.wgsl\"",
);
+ let current = Manifest::parse(&format!("format = {FORMAT}\n{shader}")).expect("parses");
+ assert_eq!(current.format, FORMAT);
+ assert!(current.scene_linear());
rejects(&format!("format = {}\n{GOOD}", FORMAT + 1), "newer Concat");
rejects(&format!("format = 0\n{GOOD}"), "format is 0");
rejects(&format!("format = \"1\"\n{GOOD}"), "format");
}
+ /// From format 2 a picture is drawn on the GPU alone, so a chain beside
+ /// the shader is refused; sound is FFmpeg's, and keeps its chain.
+ #[test]
+ fn a_scene_linear_package_draws_without_a_chain() {
+ let both = GOOD.replace(
+ "[ffmpeg]",
+ "[wgsl]\n entry = \"effect.wgsl\"\n\n [ffmpeg]",
+ );
+ Manifest::parse(&format!("format = 1\n{both}")).expect("format 1 may carry both");
+ rejects(&format!("format = 2\n{both}"), "drop the [ffmpeg] table");
+ rejects(&format!("format = 2\n{GOOD}"), "drop the [ffmpeg] table");
+ let audio = GOOD.replace("kind = \"effect\"", "kind = \"audio\"");
+ Manifest::parse(&format!("format = 2\n{audio}")).expect("audio keeps its chain");
+ }
+
#[test]
fn a_transition_manifest_parses() {
let manifest = Manifest::parse(GOOD_TRANSITION).expect("parses");
diff --git a/src/crates/concat-effects/src/shader.rs b/src/crates/concat-effects/src/shader.rs
index 62127215..9b55dc66 100644
--- a/src/crates/concat-effects/src/shader.rs
+++ b/src/crates/concat-effects/src/shader.rs
@@ -11,6 +11,16 @@
//! and is stitched on here so every package shares one contract and no
//! package can bind things differently.
//!
+//! The contract has two editions, chosen by the manifest's `format`
+//! ([`Contract`]). From format 2 a shader samples the compositor's working
+//! space as it is - linear light, unclipped, 1.0 the white of an SDR
+//! picture - and is given the scene-linear library: exposure in stops, a
+//! log space for what the eye judges, contrast and saturation that never
+//! clip. A format 1 shader, written before the working space was linear,
+//! is handed the gamma-encoded `0..1` picture it expects and the
+//! display-referred grading library it was written against, and its
+//! result is taken back into light, so it looks as it always did.
+//!
//! The stitched module is parsed and validated when the package loads, the
//! same way a chain template is, so a broken shader is a load error and not
//! a black frame. Its `Params` struct is read back through naga for the
@@ -25,9 +35,10 @@ use concat_core::{Lut, RevealMap, ShaderPass, TransitionPass};
use crate::manifest::{Manifest, Param, ParamType};
-/// What every package's shader can see. Group 0 is the layer, group 1 the
-/// host's frame block and the package's own parameters.
-pub const PRELUDE: &str = r#"// ── the host's half of the contract; see concat-effects/src/shader.rs ──
+/// What an effect's shader binds: the layer at group 0, the host's frame
+/// block and the package's own parameters at group 1, its table at group 2
+/// and a title's reveal map at group 3.
+const EFFECT_HEAD: &str = r#"// ── the host's half of the contract; see concat-effects/src/shader.rs ──
struct Frame {
/// The layer's size in pixels.
size: vec2<f32>,
@@ -55,24 +66,109 @@ struct Frame {
@group(3) @binding(0) var reveal_texture: texture_2d<f32>;
@group(3) @binding(1) var reveal_sampler: sampler;
+/// A title's per-word reveal order at `uv`, 0..1 - the word painted there,
+/// 0 for the first and 1 for the last, and 0 wherever no word was. A
+/// pass over anything but a title reads the identity map here, which is
+/// 0 everywhere: `reveal_order(uv) <= progress` is then always true, so a
+/// package built on it is a no-op off a title with no special casing.
+fn reveal_order(uv: vec2<f32>) -> f32 {
+ return textureSampleLevel(reveal_texture, reveal_sampler, uv, 0.0).r;
+}
+"#;
+
+/// An effect's `sample` under the format 1 contract.
+const EFFECT_SAMPLE_LEGACY: &str = r#"
/// The layer's colour at `uv`, straight alpha, in the gamma-encoded Rec. 709
-/// `0..1` today's packages were written for (see `legacy_in`).
+/// `0..1` format 1 packages were written for (see `legacy_in`).
fn sample(uv: vec2<f32>) -> vec4<f32> {
return legacy_in(textureSample(source, source_sampler, uv));
}
+"#;
+
+/// An effect's `sample` under the scene-linear contract.
+const EFFECT_SAMPLE_LINEAR: &str = r#"
+/// The layer's colour at `uv`, straight alpha, in the working space as it
+/// is: linear light on Rec. 709 primaries, extended - negative in a channel
+/// outside Rec. 709's gamut, above 1.0 in a highlight - with 1.0 the white
+/// of an SDR picture (203 nits).
+fn sample(uv: vec2<f32>) -> vec4<f32> {
+ return textureSample(source, source_sampler, uv);
+}
+"#;
+
+/// What a transition's shader binds: the outgoing picture and the incoming
+/// one at group 0, the frame block - its spare slot the progress - and the
+/// parameters at group 1, the table at group 2, and no reveal map.
+const TRANSITION_HEAD: &str = r#"// ── the host's half of a transition; see concat-effects/src/shader.rs ──
+struct Frame {
+ /// The layer's size in pixels.
+ size: vec2<f32>,
+ /// Seconds into the timeline.
+ time: f32,
+ /// How far through the cut, 0 the outgoing picture, 1 the incoming one.
+ progress: f32,
+}
+
+@group(0) @binding(0) var from_texture: texture_2d<f32>;
+@group(0) @binding(1) var from_sampler: sampler;
+@group(0) @binding(2) var to_texture: texture_2d<f32>;
+@group(0) @binding(3) var to_sampler: sampler;
+@group(1) @binding(0) var<uniform> frame: Frame;
+@group(1) @binding(1) var<uniform> params: Params;
+@group(2) @binding(0) var lut_texture: texture_3d<f32>;
+@group(2) @binding(1) var lut_sampler: sampler;
+
+/// What the shared helpers read: the outgoing picture, so `soften` and its
+/// like work on the from-side with no wiring by the author.
+fn sample(uv: vec2<f32>) -> vec4<f32> {
+ return from_at(uv);
+}
+"#;
+
+/// A transition's two pictures under the format 1 contract.
+const TRANSITION_SAMPLE_LEGACY: &str = r#"
+/// The outgoing picture's colour at `uv`, straight alpha, gamma-encoded
+/// Rec. 709 as format 1 packages were written for (see `legacy_in`).
+fn from_at(uv: vec2<f32>) -> vec4<f32> {
+ return legacy_in(textureSample(from_texture, from_sampler, uv));
+}
+
+/// The incoming picture's colour at `uv`, likewise.
+fn to_at(uv: vec2<f32>) -> vec4<f32> {
+ return legacy_in(textureSample(to_texture, to_sampler, uv));
+}
+"#;
+
+/// A transition's two pictures under the scene-linear contract.
+const TRANSITION_SAMPLE_LINEAR: &str = r#"
+/// The outgoing picture's colour at `uv`, straight alpha, in the working
+/// space as it is (see an effect's `sample`).
+fn from_at(uv: vec2<f32>) -> vec4<f32> {
+ return textureSample(from_texture, from_sampler, uv);
+}
+
+/// The incoming picture's colour at `uv`, likewise.
+fn to_at(uv: vec2<f32>) -> vec4<f32> {
+ return textureSample(to_texture, to_sampler, uv);
+}
+"#;
+/// What every shader is given whatever it is and whichever contract it
+/// keeps: they read only the frame's size and the table, which both heads
+/// declare.
+const BASICS: &str = r#"
/// One pixel, as a fraction of the layer.
fn texel() -> vec2<f32> {
return vec2<f32>(1.0, 1.0) / frame.size;
}
-/// Luminance, Rec. 709.
+/// Luminance, by Rec. 709's weights: the primaries the working space is on.
fn luma(rgb: vec3<f32>) -> f32 {
return dot(rgb, vec3<f32>(0.2126, 0.7152, 0.0722));
}
-/// The package's look-up table applied to a colour - the identity when
-/// the package ships none, so the call is always safe. Sampled at the
+/// The package's look-up table applied to a colour in `0..1` - the identity
+/// when the package ships none, so the call is always safe. Sampled at the
/// texel centres, so the table's ends land on black and white exactly.
fn lut(rgb: vec3<f32>) -> vec3<f32> {
let n = f32(textureDimensions(lut_texture).x);
@@ -85,17 +181,13 @@ fn hash(p: vec2<f32>, seed: f32) -> f32 {
let q = vec3<f32>(p, seed);
return fract(sin(dot(q, vec3<f32>(12.9898, 78.233, 37.719))) * 43758.5453);
}
+"#;
-/// A title's per-word reveal order at `uv`, 0..1 - the word painted there,
-/// 0 for the first and 1 for the last, and 0 wherever no word was. A
-/// pass over anything but a title reads the identity map here, which is
-/// 0 everywhere: `reveal_order(uv) <= progress` is then always true, so a
-/// package built on it is a no-op off a title with no special casing.
-fn reveal_order(uv: vec2<f32>) -> f32 {
- return textureSampleLevel(reveal_texture, reveal_sampler, uv, 0.0).r;
-}
-
-// ── the grading library ──
+/// The format 1 library: the way into and out of the gamma-encoded picture
+/// those packages were written for, and the display-referred grading
+/// helpers they are built from.
+const LEGACY_LIBRARY: &str = r#"
+// ── the grading library (format 1) ──
/// The compositor's working space - linear light on Rec. 709 primaries,
/// extended past `0..1`, with 1.0 the white of an SDR picture - brought into
@@ -377,9 +469,62 @@ fn edge_at(uv: vec2<f32>) -> f32 {
}
"#;
-/// The stages the host draws with: a full-screen triangle, and a fragment
-/// that mixes the package's colour over the untouched layer by intensity.
-pub const POSTLUDE: &str = r#"
+/// The format 2 library: helpers that hold for any level of light.
+const LINEAR_LIBRARY: &str = r#"
+// ── the scene-linear library (format 2) ──
+//
+// A format 2 shader samples the working space as it is, and nothing here
+// clips it. A multiply - exposure, a white balance, a gain - belongs in
+// light, where it is what a lens or a lamp would do. A judgement of the
+// eye - contrast, a curve, a look - belongs in log, where a stop is the
+// same distance at every level, so one setting reads the same on an SDR
+// timeline and an HDR one.
+
+/// Middle grey: 18 % of SDR white, the level a contrast turns about.
+const MID_GREY: f32 = 0.18;
+
+/// Light scaled by `stops`: 1 is twice the light, -1 half, 0 as shot.
+fn exposure(rgb: vec3<f32>, stops: f32) -> vec3<f32> {
+ return rgb * exp2(stops);
+}
+
+/// Light into log, on ACEScct's curve (Academy S-2016-001): above its toe a
+/// stop is 1/17.52 of the scale at every level, middle grey sits at 0.414
+/// and SDR white at 0.555; below 2^-7 a straight toe carries black, and the
+/// negative channel of a colour outside Rec. 709, through without a pole.
+fn to_log(rgb: vec3<f32>) -> vec3<f32> {
+ let toe = rgb * 10.5402377416545 + vec3<f32>(0.0729055341958355);
+ let curve = (log2(max(rgb, vec3<f32>(0.0078125))) + vec3<f32>(9.72)) / 17.52;
+ return select(curve, toe, rgb <= vec3<f32>(0.0078125));
+}
+
+/// Log back into light: `to_log` undone, held to the largest value the
+/// compositor's half floats store.
+fn from_log(log: vec3<f32>) -> vec3<f32> {
+ let toe = (log - vec3<f32>(0.0729055341958355)) / 10.5402377416545;
+ let curve = min(exp2(log * 17.52 - vec3<f32>(9.72)), vec3<f32>(65504.0));
+ return select(curve, toe, log <= vec3<f32>(0.155251141552511));
+}
+
+/// Contrast about middle grey, in log: 1 as shot, 0 flat grey, 2 every
+/// level twice as many stops from grey. Grey stays where it is, and a
+/// highlight above white is pushed or pulled like any other level.
+fn contrast(rgb: vec3<f32>, amount: f32) -> vec3<f32> {
+ let grey = to_log(vec3<f32>(MID_GREY));
+ return from_log((to_log(rgb) - grey) * amount + grey);
+}
+
+/// Saturation about luminance, in light: 1 as shot, 0 grey, above 1
+/// richer. A colour pushed past Rec. 709's gamut goes negative in a
+/// channel rather than clipping, so turning it back down restores it.
+fn saturation(rgb: vec3<f32>, amount: f32) -> vec3<f32> {
+ return mix(vec3<f32>(luma(rgb)), rgb, amount);
+}
+"#;
+
+/// The vertex stage every shader draws with: one triangle over the whole
+/// target, the clip trimming it to the square.
+const VERTEX: &str = r#"
struct VsOut {
@builtin(position) position: vec4<f32>,
@location(0) uv: vec2<f32>,
@@ -387,7 +532,6 @@ struct VsOut {
@vertex
fn vs_main(@builtin(vertex_index) index: u32) -> VsOut {
- // One triangle over the whole target; the clip trims it to the square.
let x = f32(i32(index & 1u) * 4 - 1);
let y = f32(i32(index >> 1u) * 4 - 1);
var out: VsOut;
@@ -395,7 +539,11 @@ fn vs_main(@builtin(vertex_index) index: u32) -> VsOut {
out.uv = vec2<f32>((x + 1.0) * 0.5, 1.0 - (y + 1.0) * 0.5);
return out;
}
+"#;
+/// An effect's fragment under the format 1 contract: the package's colour
+/// mixed over the untouched layer by intensity, then taken back into light.
+const EFFECT_FRAGMENT_LEGACY: &str = r#"
@fragment
fn fs_main(in: VsOut) -> @location(0) vec4<f32> {
let base = sample(in.uv);
@@ -404,6 +552,85 @@ fn fs_main(in: VsOut) -> @location(0) vec4<f32> {
}
"#;
+/// An effect's fragment under the scene-linear contract: the package's
+/// colour mixed over the untouched layer by intensity, in light.
+const EFFECT_FRAGMENT_LINEAR: &str = r#"
+@fragment
+fn fs_main(in: VsOut) -> @location(0) vec4<f32> {
+ let base = sample(in.uv);
+ let treated = effect(in.uv);
+ return mix(base, treated, clamp(frame.intensity, 0.0, 1.0));
+}
+"#;
+
+/// A transition's fragment under the format 1 contract: the package owns
+/// the blend, so the pipeline does no mixing of its own.
+const TRANSITION_FRAGMENT_LEGACY: &str = r#"
+@fragment
+fn fs_main(in: VsOut) -> @location(0) vec4<f32> {
+ return legacy_out(transition(in.uv, frame.progress));
+}
+"#;
+
+/// A transition's fragment under the scene-linear contract.
+const TRANSITION_FRAGMENT_LINEAR: &str = r#"
+@fragment
+fn fs_main(in: VsOut) -> @location(0) vec4<f32> {
+ return transition(in.uv, frame.progress);
+}
+"#;
+
+/// Which edition of the contract a package's shader is stitched into, by
+/// the format its manifest declares; see the module doc.
+#[derive(Clone, Copy, PartialEq, Eq, Debug)]
+pub enum Contract {
+ /// Format 1: the picture gamma-encoded and clipped to `0..1`, the
+ /// display-referred grading library, the result taken back into light.
+ Legacy,
+ /// Format 2 on: the working space as it is, and the scene-linear
+ /// library.
+ Linear,
+}
+
+impl Contract {
+ /// The edition `manifest` asks for.
+ pub fn of(manifest: &Manifest) -> Contract {
+ if manifest.scene_linear() {
+ Contract::Linear
+ } else {
+ Contract::Legacy
+ }
+ }
+
+ /// Everything the host stitches after a package's body for `entry`:
+ /// the head, the sampling, the basics, the library and the draw stages.
+ fn host(self, entry: Entry) -> String {
+ let (head, sampling, fragment) = match (entry, self) {
+ (Entry::Effect, Contract::Legacy) => {
+ (EFFECT_HEAD, EFFECT_SAMPLE_LEGACY, EFFECT_FRAGMENT_LEGACY)
+ }
+ (Entry::Effect, Contract::Linear) => {
+ (EFFECT_HEAD, EFFECT_SAMPLE_LINEAR, EFFECT_FRAGMENT_LINEAR)
+ }
+ (Entry::Transition, Contract::Legacy) => (
+ TRANSITION_HEAD,
+ TRANSITION_SAMPLE_LEGACY,
+ TRANSITION_FRAGMENT_LEGACY,
+ ),
+ (Entry::Transition, Contract::Linear) => (
+ TRANSITION_HEAD,
+ TRANSITION_SAMPLE_LINEAR,
+ TRANSITION_FRAGMENT_LINEAR,
+ ),
+ };
+ let library = match self {
+ Contract::Legacy => LEGACY_LIBRARY,
+ Contract::Linear => LINEAR_LIBRARY,
+ };
+ [head, sampling, BASICS, library, VERTEX, fragment].concat()
+ }
+}
+
/// Where one parameter lands in the uniform buffer.
#[derive(Clone, Debug, PartialEq)]
struct Slot {
@@ -423,12 +650,13 @@ pub struct Shader {
}
impl Shader {
- /// Stitches `body` into the host's contract, checks it, and reads the
- /// `Params` struct for where each of the manifest's parameters lands.
- /// Every declared parameter must be a field of the struct; a field the
+ /// Stitches `body` into the host's contract - the edition the
+ /// manifest's format asks for - checks it, and reads the `Params`
+ /// struct for where each of the manifest's parameters lands. Every
+ /// declared parameter must be a field of the struct; a field the
/// manifest does not declare is allowed and stays zero.
pub fn compile(manifest: &Manifest, body: &str) -> Result<Shader, String> {
- let (source, slots, span) = stitch(manifest, body, Entry::Effect, PRELUDE, POSTLUDE)?;
+ let (source, slots, span) = stitch(manifest, body, Entry::Effect)?;
Ok(Shader {
package: manifest.effect.id.clone(),
key: pipeline_key(&manifest.effect.id, manifest.effect.version, &source),
@@ -664,18 +892,17 @@ impl Entry {
}
}
-/// Stitches a package `body` into the host's contract, parses and validates
-/// the result with naga, and reads its `Params` struct for where each declared
-/// parameter lands. Shared by [`Shader`] and [`TransitionShader`], which differ
-/// only in their prelude/postlude and entry function. Returns the finished
-/// module, the parameter slots in declaration order, and the padded uniform
-/// span.
+/// Stitches a package `body` into the host's contract for `entry`, in the
+/// edition its manifest's format asks for, parses and validates the result
+/// with naga, and reads its `Params` struct for where each declared
+/// parameter lands. Shared by [`Shader`] and [`TransitionShader`], which
+/// differ only in the host's half and the entry function. Returns the
+/// finished module, the parameter slots in declaration order, and the
+/// padded uniform span.
fn stitch(
manifest: &Manifest,
body: &str,
entry: Entry,
- prelude: &str,
- postlude: &str,
) -> Result<(Arc<str>, Vec<Slot>, usize), String> {
let declares_params = body
.split("struct")
@@ -684,15 +911,15 @@ fn stitch(
if !body.contains(&format!("fn {}", entry.name())) {
return Err(format!("the shader declares no `{}`", entry.signature()));
}
- let mut source = String::with_capacity(prelude.len() + body.len() + postlude.len() + 64);
+ let host = Contract::of(manifest).host(entry);
+ let mut source = String::with_capacity(host.len() + body.len() + 64);
if !declares_params {
// A package with no knobs still has to bind something.
source.push_str("struct Params { _unused: f32 }\n");
}
source.push_str(body);
source.push('\n');
- source.push_str(prelude);
- source.push_str(postlude);
+ source.push_str(&host);
let module =
naga::front::wgsl::parse_str(&source).map_err(|error| error.emit_to_string(&source))?;
@@ -824,114 +1051,6 @@ fn lay_params(
bytes
}
-/// The marker that opens the grading library inside [`PRELUDE`]. A transition
-/// reuses that same library by slicing it out here rather than copying it.
-const GRADING_MARKER: &str = "// ── the grading library ──";
-
-/// The shared grading library: the second half of [`PRELUDE`], from the
-/// grading marker to the end. It only reads `sample`, `texel`, `luma`, `hash`,
-/// `frame.size` and `frame.time`, all of which the transition head supplies,
-/// so it works unchanged over two inputs.
-fn grading() -> &'static str {
- let at = PRELUDE
- .find(GRADING_MARKER)
- .expect("the prelude carries a grading library");
- &PRELUDE[at..]
-}
-
-/// The transition head: the host's half of a two-input transition. It binds
-/// the outgoing picture and the incoming one at group 0, repurposes the
-/// frame's spare slot as `progress`, and re-declares the same basics the
-/// effect head does so the shared grading library (appended after this) works.
-/// `sample` reads the outgoing picture, so a helper like `soften` needs no
-/// wiring.
-const TRANSITION_HEAD: &str = r#"// ── the host's half of a transition; see concat-effects/src/shader.rs ──
-struct Frame {
- /// The layer's size in pixels.
- size: vec2<f32>,
- /// Seconds into the timeline.
- time: f32,
- /// How far through the cut, 0 the outgoing picture, 1 the incoming one.
- progress: f32,
-}
-
-@group(0) @binding(0) var from_texture: texture_2d<f32>;
-@group(0) @binding(1) var from_sampler: sampler;
-@group(0) @binding(2) var to_texture: texture_2d<f32>;
-@group(0) @binding(3) var to_sampler: sampler;
-@group(1) @binding(0) var<uniform> frame: Frame;
-@group(1) @binding(1) var<uniform> params: Params;
-@group(2) @binding(0) var lut_texture: texture_3d<f32>;
-@group(2) @binding(1) var lut_sampler: sampler;
-
-/// The outgoing picture's colour at `uv`, straight alpha, gamma-encoded
-/// Rec. 709 as the packages were written for (see `legacy_in`).
-fn from_at(uv: vec2<f32>) -> vec4<f32> {
- return legacy_in(textureSample(from_texture, from_sampler, uv));
-}
-
-/// The incoming picture's colour at `uv`, likewise.
-fn to_at(uv: vec2<f32>) -> vec4<f32> {
- return legacy_in(textureSample(to_texture, to_sampler, uv));
-}
-
-/// What the shared grading helpers read: the outgoing picture, so `soften`
-/// and its like work on the from-side with no wiring by the author.
-fn sample(uv: vec2<f32>) -> vec4<f32> {
- return from_at(uv);
-}
-
-/// One pixel, as a fraction of the layer.
-fn texel() -> vec2<f32> {
- return vec2<f32>(1.0, 1.0) / frame.size;
-}
-
-/// Luminance, Rec. 709.
-fn luma(rgb: vec3<f32>) -> f32 {
- return dot(rgb, vec3<f32>(0.2126, 0.7152, 0.0722));
-}
-
-/// The package's look-up table applied to a colour - the identity when the
-/// package ships none. Sampled at the texel centres.
-fn lut(rgb: vec3<f32>) -> vec3<f32> {
- let n = f32(textureDimensions(lut_texture).x);
- let uvw = clamp(rgb, vec3<f32>(0.0), vec3<f32>(1.0)) * (n - 1.0) / n + vec3<f32>(0.5 / n);
- return textureSampleLevel(lut_texture, lut_sampler, uvw, 0.0).rgb;
-}
-
-/// A hash in 0..1 from a point and a seed, for grain and dither.
-fn hash(p: vec2<f32>, seed: f32) -> f32 {
- let q = vec3<f32>(p, seed);
- return fract(sin(dot(q, vec3<f32>(12.9898, 78.233, 37.719))) * 43758.5453);
-}
-
-"#;
-
-/// The transition's draw stages: a full-screen triangle, and a fragment that
-/// hands the whole result to the package's `transition` - it owns the blend,
-/// so the pipeline does no mixing of its own.
-const TRANSITION_POSTLUDE: &str = r#"
-struct VsOut {
- @builtin(position) position: vec4<f32>,
- @location(0) uv: vec2<f32>,
-}
-
-@vertex
-fn vs_main(@builtin(vertex_index) index: u32) -> VsOut {
- let x = f32(i32(index & 1u) * 4 - 1);
- let y = f32(i32(index >> 1u) * 4 - 1);
- var out: VsOut;
- out.position = vec4<f32>(x, y, 0.0, 1.0);
- out.uv = vec2<f32>((x + 1.0) * 0.5, 1.0 - (y + 1.0) * 0.5);
- return out;
-}
-
-@fragment
-fn fs_main(in: VsOut) -> @location(0) vec4<f32> {
- return legacy_out(transition(in.uv, frame.progress));
-}
-"#;
-
/// A transition package's shader, stitched, checked and laid out.
#[derive(Clone, Debug)]
pub struct TransitionShader {
@@ -943,17 +1062,11 @@ pub struct TransitionShader {
impl TransitionShader {
/// Stitches `body` into the transition contract - two bound pictures and a
- /// progress - checks it, and reads the `Params` struct for its parameters'
- /// layout. Every declared parameter must be a field of the struct.
+ /// progress, in the edition the manifest's format asks for - checks it,
+ /// and reads the `Params` struct for its parameters' layout. Every
+ /// declared parameter must be a field of the struct.
pub fn compile(manifest: &Manifest, body: &str) -> Result<TransitionShader, String> {
- let prelude = format!("{TRANSITION_HEAD}{}", grading());
- let (source, slots, span) = stitch(
- manifest,
- body,
- Entry::Transition,
- &prelude,
- TRANSITION_POSTLUDE,
- )?;
+ let (source, slots, span) = stitch(manifest, body, Entry::Transition)?;
Ok(TransitionShader {
key: pipeline_key(&manifest.effect.id, manifest.effect.version, &source),
source,
@@ -1051,6 +1164,69 @@ fn effect(uv: vec2<f32>) -> vec4<f32> {
assert_eq!(f32::from_le_bytes(bytes[4..8].try_into().unwrap()), 0.5);
}
+ fn linear_manifest(kind: &str, table: &str) -> Manifest {
+ Manifest::parse(&format!(
+ "format = 2\n[effect]\nid = \"test.light\"\nname = \"Light\"\nkind = \"{kind}\"\n[{table}]\nentry = \"effect.wgsl\"\n"
+ ))
+ .expect("a valid manifest")
+ }
+
+ /// A format 2 shader samples the working space with nothing between it
+ /// and the texture, is mixed back in light, and is given the
+ /// scene-linear library in place of the display-referred one, whose
+ /// helpers clip; a format 1 shader keeps the wrapper and the library it
+ /// was written against.
+ #[test]
+ fn the_format_picks_the_edition_of_the_contract() {
+ let linear = Shader::compile(
+ &linear_manifest("effect", "wgsl"),
+ "fn effect(uv: vec2<f32>) -> vec4<f32> {
+ let c = sample(uv);
+ let graded = saturation(contrast(exposure(c.rgb, 1.0), 1.2), 0.9);
+ return vec4<f32>(from_log(to_log(graded)) * luma(vec3<f32>(MID_GREY)), c.a);
+ }",
+ )
+ .expect("the scene-linear library is there");
+ assert_eq!(
+ Contract::of(&linear_manifest("effect", "wgsl")),
+ Contract::Linear
+ );
+ assert!(!linear.source().contains("legacy_"), "no wrapper");
+ assert!(
+ linear
+ .source()
+ .contains("return mix(base, treated, clamp(frame.intensity, 0.0, 1.0));"),
+ "mixed in light"
+ );
+ let clipping = Shader::compile(
+ &linear_manifest("effect", "wgsl"),
+ "fn effect(uv: vec2<f32>) -> vec4<f32> { return vec4<f32>(s_curve(sample(uv).rgb, 1.0), 1.0); }",
+ );
+ assert!(clipping.is_err(), "a display-referred helper is not given");
+
+ let legacy = Shader::compile(
+ &manifest(""),
+ "fn effect(uv: vec2<f32>) -> vec4<f32> { return vec4<f32>(s_curve(sample(uv).rgb, 1.0), 1.0); }",
+ )
+ .expect("the display-referred library is there");
+ assert_eq!(Contract::of(&manifest("")), Contract::Legacy);
+ assert!(
+ legacy
+ .source()
+ .contains("return legacy_in(textureSample(source, source_sampler, uv));")
+ );
+ assert!(legacy.source().contains("return legacy_out(mix("));
+
+ let transition = TransitionShader::compile(
+ &linear_manifest("transition", "transition"),
+ "fn transition(uv: vec2<f32>, progress: f32) -> vec4<f32> {
+ return mix(from_at(uv), to_at(uv), progress) * exp2(0.0) + vec4<f32>(exposure(sample(uv).rgb, 0.0) * 0.0, 0.0);
+ }",
+ )
+ .expect("a scene-linear transition");
+ assert!(!transition.source().contains("legacy_"), "no wrapper");
+ }
+
#[test]
fn a_package_with_no_knobs_still_binds() {
let manifest = manifest("");
diff --git a/src/crates/concat-render/Cargo.toml b/src/crates/concat-render/Cargo.toml
index d4bf84a2..0b6262f0 100644
--- a/src/crates/concat-render/Cargo.toml
+++ b/src/crates/concat-render/Cargo.toml
@@ -16,6 +16,9 @@ concat-core.workspace = true
log = "0.4"
wgpu.workspace = true
pollster.workspace = true
+# The working space's half floats, written and read back as numbers where
+# an effect's probes check them.
+half = "2"
[dev-dependencies]
# The pass test compiles a real package shader through the catalogue's
diff --git a/src/crates/concat-render/src/gpu.rs b/src/crates/concat-render/src/gpu.rs
index 85875178..60164cc7 100644
--- a/src/crates/concat-render/src/gpu.rs
+++ b/src/crates/concat-render/src/gpu.rs
@@ -1333,6 +1333,111 @@ impl WgpuCompositor {
}
}
+ /// `passes` over a picture `side` pixels square of one colour, straight
+ /// RGBA in the working space, and the colour of its middle pixel after
+ /// them, read back in the half floats the working space holds: what an
+ /// effect package's probes are checked against, with nothing between
+ /// the shaders and the numbers - no upload's gamma on the way in, no
+ /// resolve's clipping on the way out. The passes see the timeline at
+ /// `seconds`, their clip just begun. None when the device is dead or
+ /// the read-back fails.
+ pub fn probe(
+ &mut self,
+ passes: &[ShaderPass],
+ colour: [f32; 4],
+ side: u32,
+ seconds: f32,
+ ) -> Option<[f32; 4]> {
+ if self.dead {
+ return None;
+ }
+ let side = side.max(1);
+ self.used.values_mut().for_each(|used| *used = 0);
+ self.composites += 1;
+ let source = self.claim(side, side);
+ let texel: Vec<u8> = colour
+ .iter()
+ .flat_map(|channel| half::f16::from_f32(*channel).to_le_bytes())
+ .collect();
+ self.queue.write_texture(
+ wgpu::TexelCopyTextureInfo {
+ texture: &self.pool[&(side, side)][source].texture,
+ mip_level: 0,
+ origin: wgpu::Origin3d::ZERO,
+ aspect: wgpu::TextureAspect::All,
+ },
+ &texel.repeat((side * side) as usize),
+ wgpu::TexelCopyBufferLayout {
+ offset: 0,
+ bytes_per_row: Some(side * WORK_BYTES as u32),
+ rows_per_image: Some(side),
+ },
+ wgpu::Extent3d {
+ width: side,
+ height: side,
+ depth_or_array_layers: 1,
+ },
+ );
+ let drawn = self.run_passes(side, side, source, passes, seconds, seconds);
+
+ let buffer = self.device.create_buffer(&wgpu::BufferDescriptor {
+ label: Some("concat probe"),
+ size: wgpu::COPY_BYTES_PER_ROW_ALIGNMENT.into(),
+ usage: wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::MAP_READ,
+ mapped_at_creation: false,
+ });
+ let mut encoder = self
+ .device
+ .create_command_encoder(&wgpu::CommandEncoderDescriptor {
+ label: Some("concat probe"),
+ });
+ encoder.copy_texture_to_buffer(
+ wgpu::TexelCopyTextureInfo {
+ texture: &self.pool[&(side, side)][drawn].texture,
+ mip_level: 0,
+ origin: wgpu::Origin3d {
+ x: side / 2,
+ y: side / 2,
+ z: 0,
+ },
+ aspect: wgpu::TextureAspect::All,
+ },
+ wgpu::TexelCopyBufferInfo {
+ buffer: &buffer,
+ layout: wgpu::TexelCopyBufferLayout {
+ offset: 0,
+ bytes_per_row: Some(wgpu::COPY_BYTES_PER_ROW_ALIGNMENT),
+ rows_per_image: Some(1),
+ },
+ },
+ wgpu::Extent3d {
+ width: 1,
+ height: 1,
+ depth_or_array_layers: 1,
+ },
+ );
+ self.queue.submit([encoder.finish()]);
+ let slice = buffer.slice(..);
+ let (mapped_tx, mapped_rx) = std::sync::mpsc::channel();
+ slice.map_async(wgpu::MapMode::Read, move |result| {
+ let _ = mapped_tx.send(result);
+ });
+ let waited = self.device.poll(wgpu::PollType::wait_indefinitely());
+ self.retire();
+ if waited.is_err() || !matches!(mapped_rx.try_recv(), Ok(Ok(()))) {
+ return None;
+ }
+ let data = slice.get_mapped_range().ok()?;
+ let mut out = [0.0; 4];
+ for (channel, bytes) in out
+ .iter_mut()
+ .zip(data[..WORK_BYTES as usize].chunks_exact(2))
+ {
+ *channel = half::f16::from_le_bytes([bytes[0], bytes[1]]).to_f32();
+ }
+ Some(out)
+ }
+
/// The render passes: every draw over `clear` into `view`, which is a
/// view of `target`. One pass, except that a Lighten or Darken layer
/// needs the ground as it stands: the pass ends, the target is copied
diff --git a/src/crates/concat-render/src/gpu/tests.rs b/src/crates/concat-render/src/gpu/tests.rs
index f0061620..08446585 100644
--- a/src/crates/concat-render/src/gpu/tests.rs
+++ b/src/crates/concat-render/src/gpu/tests.rs
@@ -898,3 +898,118 @@ fn an_hdr_frame_is_conformed_to_sdr_on_the_way_in() {
"PQ 1000 nits came out {pq_peak:?}"
);
}
+
+/// A pass of a format 2 package - the scene-linear contract - with `body`
+/// as its shader and no knobs, at `intensity`.
+fn scene_linear(id: &str, body: &str, intensity: f32) -> ShaderPass {
+ let manifest = concat_effects::Manifest::parse(&format!(
+ "format = 2\n[effect]\nid = \"{id}\"\nname = \"Test\"\nkind = \"effect\"\n[wgsl]\nentry = \"effect.wgsl\"\n"
+ ))
+ .expect("a manifest");
+ let shader = concat_effects::Shader::compile(&manifest, body).expect("compiles");
+ shader.pass(&BTreeMap::new(), &manifest.params, intensity, None, None)
+}
+
+/// Within `tolerance` of `want` a channel, relative, for the colour and
+/// alpha alike.
+fn near(got: [f32; 4], want: [f32; 4], tolerance: f32) -> bool {
+ got.iter()
+ .zip(want)
+ .all(|(got, want)| (got - want).abs() <= tolerance * want.abs().max(0.01))
+}
+
+/// Every built-in package's probes: a picture of one working-space colour
+/// through its shader comes out as the probe pins, in floats.
+#[test]
+fn every_package_probe_holds() {
+ let Some(mut gpu) = gpu() else { return };
+ let mut failures = Vec::new();
+ let mut probed = 0;
+ for package in concat_effects::Catalogue::builtin().packages() {
+ for (n, probe) in package.probes.iter().enumerate() {
+ let pass = package
+ .probe_pass(probe)
+ .expect("a probed package has a shader");
+ let got = gpu.probe(&[pass], probe.input, 8, 0.0).expect("reads back");
+ probed += 1;
+ if let Err(error) = probe.check(got) {
+ failures.push(format!("{}: {}\n {error}", package.id(), probe.label(n)));
+ }
+ }
+ }
+ eprintln!("{probed} probes");
+ assert!(probed > 0, "no package has a probe");
+ assert!(failures.is_empty(), "\n{}", failures.join("\n"));
+}
+
+/// A format 2 stack hands its light on unclipped: four times the light and
+/// a quarter of it again is the picture it was, a highlight far above
+/// white in between. The same stack in format 1 is clipped to white at the
+/// second pass, as those packages always were.
+#[test]
+fn a_scene_linear_stack_keeps_the_light_above_white() {
+ let Some(mut gpu) = gpu() else { return };
+ const UP: &str = "fn effect(uv: vec2<f32>) -> vec4<f32> { let c = sample(uv); return vec4<f32>(c.rgb * 4.0, c.a); }";
+ const DOWN: &str = "fn effect(uv: vec2<f32>) -> vec4<f32> { let c = sample(uv); return vec4<f32>(c.rgb * 0.25, c.a); }";
+ let colour = [0.7, 0.35, 0.1, 1.0];
+ let linear = [
+ scene_linear("test.up", UP, 1.0),
+ scene_linear("test.down", DOWN, 1.0),
+ ];
+ let between = gpu.probe(&linear[..1], colour, 8, 0.0).expect("reads back");
+ assert!(near(between, [2.8, 1.4, 0.4, 1.0], 0.004), "{between:?}");
+ let got = gpu.probe(&linear, colour, 8, 0.0).expect("reads back");
+ assert!(near(got, colour, 0.004), "there and back gave {got:?}");
+
+ let legacy = [
+ package("test.up", UP, "", &[], 1.0),
+ package("test.down", DOWN, "", &[], 1.0),
+ ];
+ let clipped = gpu.probe(&legacy, colour, 8, 0.0).expect("reads back");
+ assert!(clipped[0] < 0.1, "format 1 clips at white: {clipped:?}");
+}
+
+/// `to_log` puts middle grey, SDR white and black where ACEScct does, and
+/// `from_log` brings any level back - a highlight, the toe, a negative
+/// channel - as it went in.
+#[test]
+fn the_log_space_goes_there_and_back() {
+ let Some(mut gpu) = gpu() else { return };
+ let to_log = scene_linear(
+ "test.log",
+ "fn effect(uv: vec2<f32>) -> vec4<f32> { let c = sample(uv); return vec4<f32>(to_log(c.rgb), c.a); }",
+ 1.0,
+ );
+ let got = gpu
+ .probe(std::slice::from_ref(&to_log), [0.18, 1.0, 0.0, 1.0], 4, 0.0)
+ .expect("reads back");
+ assert!(near(got, [0.4136, 0.5548, 0.0729, 1.0], 0.002), "{got:?}");
+
+ let round = scene_linear(
+ "test.round",
+ "fn effect(uv: vec2<f32>) -> vec4<f32> { let c = sample(uv); return vec4<f32>(from_log(to_log(c.rgb)), c.a); }",
+ 1.0,
+ );
+ for colour in [[6.0, 0.18, -0.02, 1.0], [0.001, 0.0, 1.0, 1.0]] {
+ let got = gpu
+ .probe(std::slice::from_ref(&round), colour, 4, 0.0)
+ .expect("reads back");
+ assert!(near(got, colour, 0.004), "{colour:?} came back {got:?}");
+ }
+}
+
+/// A format 2 pass is mixed over the untouched layer in light: a quarter
+/// of the way from 0.2 to white is 0.4.
+#[test]
+fn a_scene_linear_pass_mixes_by_intensity_in_light() {
+ let Some(mut gpu) = gpu() else { return };
+ let white = scene_linear(
+ "test.white",
+ "fn effect(uv: vec2<f32>) -> vec4<f32> { return vec4<f32>(1.0, 1.0, 1.0, sample(uv).a); }",
+ 0.25,
+ );
+ let got = gpu
+ .probe(&[white], [0.2, 0.2, 0.2, 1.0], 4, 0.0)
+ .expect("reads back");
+ assert!(near(got, [0.4, 0.4, 0.4, 1.0], 0.004), "{got:?}");
+}
diff --git a/src/crates/concat/src/studio.rs b/src/crates/concat/src/studio.rs
index 1aca5590..3da25703 100644
--- a/src/crates/concat/src/studio.rs
+++ b/src/crates/concat/src/studio.rs
@@ -1133,11 +1133,13 @@ fn import_cube(dir: &std::path::Path, path: &std::path::Path) -> Result<String,
let folder = dir.join(&id);
std::fs::create_dir_all(&folder).map_err(|error| error.to_string())?;
let name = stem.trim().to_owned();
+ // Format 1: a table is made for the gamma-encoded picture, which is
+ // what a format 1 shader is handed. The look-up effect with a log
+ // shaper (phase 2, step 5) is what takes an imported table into light.
let manifest = format!(
- "format = {}\n\n[effect]\nid = \"{id}\"\nname = {name:?}\nkind = \"filter\"\ncategory = \"Imported\"\n\
+ "format = 1\n\n[effect]\nid = \"{id}\"\nname = {name:?}\nkind = \"filter\"\ncategory = \"Imported\"\n\
description = \"A look imported from a .cube table.\"\n\n[lut]\nfile = \"look.cube\"\n\n\
- [ffmpeg]\nchain = \"lut3d=file={{lut}}\"\n\n[wgsl]\nentry = \"effect.wgsl\"\n",
- concat_effects::FORMAT
+ [ffmpeg]\nchain = \"lut3d=file={{lut}}\"\n\n[wgsl]\nentry = \"effect.wgsl\"\n"
);
std::fs::write(folder.join("effect.toml"), manifest).map_err(|error| error.to_string())?;
std::fs::write(