diff --git a/crates/Cargo.lock b/crates/Cargo.lock index da41d7070d..ad32f5dc25 100644 --- a/crates/Cargo.lock +++ b/crates/Cargo.lock @@ -994,6 +994,7 @@ dependencies = [ "cosmic-text", "image", "metal 0.29.0", + "naga", "ndarray 0.16.1", "objc", "ort", diff --git a/crates/Cargo.toml b/crates/Cargo.toml index a65f9aaef2..48a77d7756 100644 --- a/crates/Cargo.toml +++ b/crates/Cargo.toml @@ -60,6 +60,7 @@ version = "0.58" features = [ "Win32_Foundation", "Win32_Graphics_Direct3D", + "Win32_Graphics_Direct3D_Fxc", # D3DCompile à l'exécution des effets shader (shader_fx.rs) "Win32_Graphics_Direct3D11", "Win32_Graphics_Dxgi", "Win32_Graphics_Dxgi_Common", diff --git a/crates/compositor-view-napi/src/lib.rs b/crates/compositor-view-napi/src/lib.rs index ed98a71046..447df805cf 100644 --- a/crates/compositor-view-napi/src/lib.rs +++ b/crates/compositor-view-napi/src/lib.rs @@ -388,6 +388,35 @@ pub fn set_active_clip( } } +/// Ce que l'outil de l'agent apprend d'un effet avant de l'accepter (`docs/shader-effects.md`, E.3). +#[napi(object)] +pub struct ShaderEffectCheck { + /// L'erreur telle que l'agent doit la lire (ligne, colonne, extrait), ou `None` s'il est accepté. + pub error: Option, + /// Le palier de coût : "light", "medium", "heavy" ou "very-heavy". Indicatif, jamais un refus. + pub tier: Option, + /// Lectures de `frame()` par pixel, boucles multipliées par leur borne. + pub frame_reads: Option, + /// Itérations de boucle par pixel. + pub iterations: Option, +} + +/// Vérifie le WGSL d'un effet shader : validation, bornes des boucles, compilation réelle pour le +/// backend de la machine quand elle existe (FXC sur Windows), et palier de coût. `params_json` : +/// les paramètres déclarés, `[{ "name": "strength", "type": "number" }, …]`. +#[napi] +pub fn check_shader_effect(code: String, params_json: String) -> ShaderEffectCheck { + match openscreen_compositor::shader_fx::check_for_agent_json(&code, ¶ms_json) { + Ok(report) => ShaderEffectCheck { + error: None, + tier: Some(report.tier.name().to_string()), + frame_reads: Some(report.frame_reads as f64), + iterations: Some(report.iterations as f64), + }, + Err(error) => ShaderEffectCheck { error: Some(error), tier: None, frame_reads: None, iterations: None }, + } +} + /// Installe la scène de l'app (JSON `SceneDescription`) sur la vue : layout preset piloté par /// l'app au lieu de la fixture. JSON invalide → ignoré côté natif. #[napi] diff --git a/crates/compositor/Cargo.toml b/crates/compositor/Cargo.toml index cc9ef64593..246f914e20 100644 --- a/crates/compositor/Cargo.toml +++ b/crates/compositor/Cargo.toml @@ -37,6 +37,9 @@ ndarray = { workspace = true, optional = true } serde.workspace = true serde_json.workspace = true image.workspace = true +# Effets shader écrits à l'exécution (`shader_fx`) : la version que wgpu 24 tire déjà. Pas au-delà +# de 24 : dès la 25, la sortie HLSL ne passe plus FXC en SM 5.0 (voir `shader_fx::to_hlsl`). +naga = { version = "24", features = ["wgsl-in", "hlsl-out"] } # Acces Vulkan brut, UNIQUEMENT pour ouvrir le device avec les extensions de # memoire externe (cf. `d3d_linux::open_device_with_dmabuf_export`). Les versions @@ -50,6 +53,8 @@ image.workspace = true [target.'cfg(target_os = "linux")'.dependencies] ash = "0.38" wgpu-hal = { version = "24", features = ["vulkan"] } +# `shader_fx::check_for_agent` traduit l'effet en SPIR-V, comme wgpu le fera pour Vulkan. +naga = { version = "24", features = ["spv-out"] } # Windows : D3D11 + D3D11VA + Direct2D/DirectWrite + HLSL à l'exécution. [target.'cfg(windows)'.dependencies] diff --git a/crates/compositor/src/compositor_linux.rs b/crates/compositor/src/compositor_linux.rs index e3176ad8c5..541840ae28 100644 --- a/crates/compositor/src/compositor_linux.rs +++ b/crates/compositor/src/compositor_linux.rs @@ -47,7 +47,7 @@ use crate::frame_geometry::{ plan_frame, tilted_screen_cb, CursorPlacement, CursorPlanInput, FrameGeometryInput, ShadowCaster, SpriteShape, }; -use crate::scene::{Scene, SceneBackground, WallpaperMotion}; +use crate::scene::{Scene, SceneBackground, SceneShaderEffect, ShaderEffectTarget, WallpaperMotion}; const LAYER_WGSL: &str = include_str!("vk_shaders/layer.wgsl"); const BLUR_WGSL: &str = include_str!("vk_shaders/blur.wgsl"); @@ -116,6 +116,24 @@ struct BgCache { tex: wgpu::Texture, } +/// Un effet shader de la scène (`shader_fx`), par hash de sa source. +enum ShaderFx { + /// Module et pipeline se construisent sur un thread de fond (`spawn_shader_fx`). + Pending(std::sync::mpsc::Receiver>), + Ready(wgpu::RenderPipeline), + /// Erreur déjà écrite ; l'effet ne se dessine pas. + Failed, +} + +struct ShaderFxEntry { + state: ShaderFx, + /// Dernier usage, pour l'éviction (`SHADER_FX_CACHE`). + used: u64, +} + +/// Combien d'effets compilés le compositeur garde. Un agent qui itère en crée un par version. +const SHADER_FX_CACHE: usize = 64; + /// Une copie RT -> staging DEJA SOUMISE, dont le mapping est arme mais pas /// encore recolte. On garde `idx` (l'index de soumission rendu par /// `Queue::submit`) pour n'attendre QUE cette soumission-la, et les dimensions @@ -435,6 +453,20 @@ pub struct Compositor { seg_scratch: RefCell>, /// Le chargement du modele a echoue : ne pas reessayer a chaque frame. seg_failed: RefCell, + + /// Layout des effets shader : les quatre bindings du prélude (`shader_fx::PRELUDE_V1`). + shader_fx_bgl: wgpu::BindGroupLayout, + shader_fx_layout: wgpu::PipelineLayout, + /// Effets shader de la scène, compilés une fois par source, les moins récents évincés au-delà + /// de `SHADER_FX_CACHE`. + shader_fx: RefCell>, + shader_fx_tick: std::cell::Cell, + /// Vrai par défaut : une frame dont l'effet compile encore attend son pipeline, parce qu'un + /// export ne doit jamais rendre de frame sans l'effet. La preview le passe à faux et saute + /// l'effet le temps de la compilation, puis recompose (`shader_fx_landed`). + shader_fx_blocking: std::cell::Cell, + /// Le calque transparent des textes, alloué à la première frame qui porte un effet `text`. + text_layer: RefCell>, } impl Compositor { @@ -699,6 +731,40 @@ impl Compositor { multiview: None, cache: None, }); + // Effets shader (`shader_fx`) : un layout explicite, celui du prélude. Avec `layout: None`, + // un effet qui ne lit pas `ctx` perdrait ce binding, et son bind group ne validerait plus. + let fx_entry = |binding: u32, ty: wgpu::BindingType| wgpu::BindGroupLayoutEntry { + binding, + visibility: wgpu::ShaderStages::FRAGMENT, + ty, + count: None, + }; + let fx_uniform = wgpu::BindingType::Buffer { + ty: wgpu::BufferBindingType::Uniform, + has_dynamic_offset: false, + min_binding_size: None, + }; + let shader_fx_bgl = gpu.device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor { + label: Some("shader-fx"), + entries: &[ + fx_entry( + 0, + wgpu::BindingType::Texture { + sample_type: wgpu::TextureSampleType::Float { filterable: true }, + view_dimension: wgpu::TextureViewDimension::D2, + multisampled: false, + }, + ), + fx_entry(1, wgpu::BindingType::Sampler(wgpu::SamplerBindingType::Filtering)), + fx_entry(2, fx_uniform), + fx_entry(3, fx_uniform), + ], + }); + let shader_fx_layout = gpu.device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor { + label: Some("shader-fx"), + bind_group_layouts: &[&shader_fx_bgl], + push_constant_ranges: &[], + }); let (blur_half, blur_qtr, blur_oct, trail_view) = Self::make_blur_targets(&gpu, w, h); let (rt, rt_view, accum, accum_view, readback_bpr) = Self::make_targets(&gpu, w, h); let (ann_copy, ann_copy_view, ann_copy_mips) = Self::make_ann_copy(&gpu, w, h); @@ -772,6 +838,12 @@ impl Compositor { seg_rate: RefCell::new(crate::segmentation::RateLimiter::new(SEGMENTATION_HZ)), seg_scratch: RefCell::new(Vec::new()), seg_failed: RefCell::new(false), + shader_fx_bgl, + shader_fx_layout, + shader_fx: RefCell::new(std::collections::HashMap::new()), + shader_fx_tick: std::cell::Cell::new(0), + shader_fx_blocking: std::cell::Cell::new(true), + text_layer: RefCell::new(None), }) } @@ -819,6 +891,7 @@ impl Compositor { ann_copy_view, ann_copy_mips, bg_cache: RefCell::new(None), + text_layer: RefCell::new(None), ..self }) } @@ -1165,9 +1238,243 @@ impl Compositor { } pub fn set_scene(&self, s: Option) { + // Les effets nouveaux partent compiler tout de suite, hors du thread de rendu : à la + // première frame qui les montre, ils sont en général déjà prêts. + if let Some(scene) = &s { + for effect in &scene.shader_effects { + self.shader_fx_entry(effect); + } + } *self.scene.borrow_mut() = s; } + /// Faux pour la preview : voir `shader_fx_blocking`. + pub fn set_shader_fx_blocking(&self, on: bool) { + self.shader_fx_blocking.set(on); + } + + /// Fait aboutir les compilations terminées. Vrai si un effet vient d'être prêt : la preview + /// en pause doit alors recomposer, sinon elle resterait sur la frame sans l'effet. + pub fn shader_fx_landed(&self) -> bool { + let mut landed = false; + for entry in self.shader_fx.borrow_mut().values_mut() { + let got = match &entry.state { + ShaderFx::Pending(rx) => rx.try_recv(), + _ => continue, + }; + match got { + Ok(result) => { + entry.state = Self::finish_shader_fx(result); + landed = true; + } + Err(std::sync::mpsc::TryRecvError::Empty) => {} + Err(std::sync::mpsc::TryRecvError::Disconnected) => entry.state = ShaderFx::Failed, + } + } + landed + } + + /// La clé de cache d'`effect`, sa compilation lancée s'il est neuf, et son dernier usage noté. + /// `None` pour un contrat que ce compositeur ne connaît pas : la région ne se dessine pas. + fn shader_fx_entry(&self, effect: &SceneShaderEffect) -> Option { + if effect.contract != crate::shader_fx::CONTRACT { + return None; + } + let key = crate::shader_fx::source_hash(effect); + let tick = self.shader_fx_tick.get() + 1; + self.shader_fx_tick.set(tick); + let mut fx = self.shader_fx.borrow_mut(); + fx.entry(key) + .or_insert_with(|| ShaderFxEntry { + state: ShaderFx::Pending(self.spawn_shader_fx(effect)), + used: tick, + }) + .used = tick; + // Un agent qui itère crée une entrée par version : on garde les plus récentes. + if fx.len() > SHADER_FX_CACHE { + if let Some(oldest) = fx.iter().min_by_key(|(_, e)| e.used).map(|(k, _)| *k) { + fx.remove(&oldest); + } + } + Some(key) + } + + /// Construit le pipeline d'`effect` sur un thread de fond : `Device` est `Send + Sync`, et le + /// pilote compile le SPIR-V dans `create_render_pipeline`. naga valide le code avant wgpu : + /// aucun `on_uncaptured_error` n'est posé, et une erreur de validation wgpu fait paniquer. Si + /// wgpu panique malgré tout, seul ce thread meurt, et le canal fermé vaut un échec. + fn spawn_shader_fx( + &self, + effect: &SceneShaderEffect, + ) -> std::sync::mpsc::Receiver> { + let (tx, rx) = std::sync::mpsc::channel(); + let (device, layout) = (self.gpu.device.clone(), self.shader_fx_layout.clone()); + let (code, params) = (effect.code.clone(), effect.params.clone()); + std::thread::Builder::new() + .name("shader-fx".into()) + .spawn(move || { + let built = crate::shader_fx::analyze(&code, ¶ms).map(|_| { + let module = device.create_shader_module(wgpu::ShaderModuleDescriptor { + label: Some("shader-fx"), + source: wgpu::ShaderSource::Wgsl( + crate::shader_fx::module_source(&code, ¶ms).into(), + ), + }); + device.create_render_pipeline(&wgpu::RenderPipelineDescriptor { + label: Some("shader-fx"), + layout: Some(&layout), + vertex: wgpu::VertexState { + module: &module, + entry_point: Some("fx_vs"), + compilation_options: wgpu::PipelineCompilationOptions::default(), + buffers: &[], + }, + fragment: Some(wgpu::FragmentState { + module: &module, + entry_point: Some("fx_fs"), + compilation_options: wgpu::PipelineCompilationOptions::default(), + targets: &[Some(wgpu::ColorTargetState { + format: wgpu::TextureFormat::Rgba8Unorm, + blend: None, + write_mask: wgpu::ColorWrites::ALL, + })], + }), + primitive: wgpu::PrimitiveState::default(), + depth_stencil: None, + multisample: wgpu::MultisampleState::default(), + multiview: None, + cache: None, + }) + }); + let _ = tx.send(built); + }) + .expect("thread shader-fx"); + rx + } + + fn finish_shader_fx(result: Result) -> ShaderFx { + match result { + Ok(pipeline) => ShaderFx::Ready(pipeline), + Err(e) => { + eprintln!("[shader-fx] {e}"); + ShaderFx::Failed + } + } + } + + /// Le pipeline d'`effect`. Le compositeur d'export attend sa compilation ; la preview + /// (`shader_fx_blocking` faux) rend `None` tant qu'il compile. `None` aussi s'il a échoué. + fn shader_fx_ready(&self, effect: &SceneShaderEffect) -> Option { + let key = self.shader_fx_entry(effect)?; + let mut fx = self.shader_fx.borrow_mut(); + let entry = fx.get_mut(&key)?; + if let ShaderFx::Pending(rx) = &entry.state { + let got = if self.shader_fx_blocking.get() { + rx.recv().map_err(|e| e.to_string()) + } else { + match rx.try_recv() { + Ok(result) => Ok(result), + Err(std::sync::mpsc::TryRecvError::Empty) => return None, + Err(e) => Err(e.to_string()), + } + }; + entry.state = Self::finish_shader_fx(got.and_then(|result| result)); + } + match &entry.state { + ShaderFx::Ready(pipeline) => Some(pipeline.clone()), + _ => None, + } + } + + /// Une passe d'effet sur `dst` (le RT, ou le calque des textes) : `dst` est copié dans le + /// niveau 0 d'`ann_copy`, libre à ce stade (les flous et le cristal de Prism Glow l'ont déjà + /// lu, plus tôt dans l'encodeur), puis l'effet le repeint en entier. + fn encode_shader_effect( + &self, + encoder: &mut wgpu::CommandEncoder, + effect: &SceneShaderEffect, + dst: (&wgpu::Texture, &wgpu::TextureView), + ctx: &crate::shader_fx::FxContext, + ) { + let Some(pipeline) = self.shader_fx_ready(effect) else { return }; + let ctx_bytes = unsafe { + std::slice::from_raw_parts( + ctx as *const crate::shader_fx::FxContext as *const u8, + std::mem::size_of::(), + ) + }; + let params: Vec = + crate::shader_fx::pack_params(effect).iter().flat_map(|v| v.to_ne_bytes()).collect(); + let uniform = |label: &str, contents: &[u8]| { + self.gpu.device.create_buffer_init(&wgpu::util::BufferInitDescriptor { + label: Some(label), + contents, + usage: wgpu::BufferUsages::UNIFORM, + }) + }; + let (ctx_buf, params_buf) = (uniform("shader-fx-ctx", ctx_bytes), uniform("shader-fx-params", ¶ms)); + // Les bindings du prélude : la frame (0), le sampler (1), `ctx` (2), `params` (3). + let bind = self.gpu.device.create_bind_group(&wgpu::BindGroupDescriptor { + label: Some("shader-fx"), + layout: &self.shader_fx_bgl, + entries: &[ + wgpu::BindGroupEntry { + binding: 0, + resource: wgpu::BindingResource::TextureView(&self.ann_copy_view), + }, + wgpu::BindGroupEntry { + binding: 1, + resource: wgpu::BindingResource::Sampler(&self.sampler), + }, + wgpu::BindGroupEntry { binding: 2, resource: ctx_buf.as_entire_binding() }, + wgpu::BindGroupEntry { binding: 3, resource: params_buf.as_entire_binding() }, + ], + }); + encoder.copy_texture_to_texture( + dst.0.as_image_copy(), + self.ann_copy.as_image_copy(), + wgpu::Extent3d { width: self.render_w, height: self.render_h, depth_or_array_layers: 1 }, + ); + let mut rpass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor { + label: Some("shader-fx-pass"), + color_attachments: &[Some(wgpu::RenderPassColorAttachment { + view: dst.1, + resolve_target: None, + ops: wgpu::Operations { load: wgpu::LoadOp::Load, store: wgpu::StoreOp::Store }, + })], + depth_stencil_attachment: None, + timestamp_writes: None, + occlusion_query_set: None, + }); + rpass.set_pipeline(&pipeline); + rpass.set_bind_group(0, &bind, &[]); + rpass.draw(0..3, 0..1); + } + + /// Le calque transparent des textes, à la taille de rendu, alloué à la première frame qui en a + /// besoin (un effet `ShaderEffectTarget::Text`). + fn text_layer(&self) -> (wgpu::Texture, wgpu::TextureView) { + if let Some(layer) = self.text_layer.borrow().as_ref() { + return layer.clone(); + } + let tex = self.gpu.device.create_texture(&wgpu::TextureDescriptor { + label: Some("text-layer"), + size: wgpu::Extent3d { width: self.render_w, height: self.render_h, depth_or_array_layers: 1 }, + mip_level_count: 1, + sample_count: 1, + dimension: wgpu::TextureDimension::D2, + format: wgpu::TextureFormat::Rgba8Unorm, + // COPY_SRC : un effet `text` le copie dans `ann_copy` avant de le repeindre. + usage: wgpu::TextureUsages::RENDER_ATTACHMENT + | wgpu::TextureUsages::TEXTURE_BINDING + | wgpu::TextureUsages::COPY_SRC, + view_formats: &[], + }); + let view = tex.create_view(&wgpu::TextureViewDescriptor::default()); + *self.text_layer.borrow_mut() = Some((tex.clone(), view.clone())); + (tex, view) + } + pub fn set_cursor(&self, track: crate::cursor::CursorTrack) { *self.cursor.borrow_mut() = Some(track); } @@ -2919,6 +3226,9 @@ impl Compositor { /// Le cristal de Prism Glow : il lit la copie de l'image composee (`CursorPlan::glass`). glass: bool, } + // La pointe et les clics récents, tels que les effets shader les lisent. + let mut fx_cursor = None; + let mut fx_clicks = Vec::new(); let cursor_draw: Option = (|| { let track = cursor_ref.as_ref()?; let plan = plan_cursor( @@ -2938,6 +3248,8 @@ impl Compositor { }, )? .for_backend(self.gpu.backend == crate::d3d::Backend::Cpu); + fx_cursor = Some(plan.pointer); + fx_clicks = plan.clicks.clone(); // `taps == 1` : un seul placement, celui de l'instant rendu -- le // chemin net d'avant, inchange. Au-dela, on echelonne les copies @@ -3431,21 +3743,48 @@ impl Compositor { self.draw_layer(&mut rpass, layer, false); } } + // Effets shader de l'agent, autour des textes selon leur cible (`docs/shader-effects.md`, + // D.1) : `image` avant les annotations, `text` sur un calque des textes a part, `both` sur + // l'image finale. Meme ordre que `compositor_windows.rs`. + let fx_inputs = crate::shader_fx::FxFrameInputs { + cursor: fx_cursor, + clicks: fx_clicks, + footage: crate::shader_fx::bounds(&g.footage_quad([rw, rh]).corners), + camera: lp.has_webcam.then_some(g.w_dst), + }; + let effects = scene_ref + .as_ref() + .map(|s| crate::shader_fx::active_effects(&s.shader_effects, g.source_t)) + .unwrap_or_default(); + let fx_context = |e: &SceneShaderEffect| { + crate::shader_fx::context(e, g.source_t, g.programme_t, [rw, rh], &fx_inputs) + }; + let with_target = |target: ShaderEffectTarget| -> Vec<&SceneShaderEffect> { + effects.iter().copied().filter(|e| e.target == target).collect() + }; + for e in with_target(ShaderEffectTarget::Image) { + self.encode_shader_effect(&mut encoder, e, (&self.rt, &self.rt_view), &fx_context(e)); + } + // Un effet `text` : les textes sur un calque transparent, l'effet sur ce calque seul, puis + // le calque pose sur l'image (« over » premultiplie). L'image dessous reste intacte. + let text_effects = with_target(ShaderEffectTarget::Text); + let text_layer = (!text_effects.is_empty()).then(|| self.text_layer()); // Passe 3 : les autres annotations, par-dessus tout le reste (les flous sont passes avant // le curseur). Elle existe meme sans annotation : deux passes consecutives sur la MEME // cible avec `LoadOp::Load` ne coutent rien de plus qu'une seule sur un GPU desktop, et un // seul chemin de code vaut mieux qu'un branchement qui ne serait exerce que dans un projet // sur dix. { + let (view, load) = match &text_layer { + Some((_, view)) => (view, wgpu::LoadOp::Clear(wgpu::Color::TRANSPARENT)), + None => (&self.rt_view, wgpu::LoadOp::Load), + }; let mut rpass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor { label: Some("ann-pass"), color_attachments: &[Some(wgpu::RenderPassColorAttachment { - view: &self.rt_view, + view, resolve_target: None, - ops: wgpu::Operations { - load: wgpu::LoadOp::Load, - store: wgpu::StoreOp::Store, - }, + ops: wgpu::Operations { load, store: wgpu::StoreOp::Store }, })], depth_stencil_attachment: None, timestamp_writes: None, @@ -3456,6 +3795,47 @@ impl Compositor { self.draw_layer(&mut rpass, &a.layer, false); } } + if let Some((tex, view)) = &text_layer { + for e in text_effects { + self.encode_shader_effect(&mut encoder, e, (tex, view), &fx_context(e)); + } + // Le calque pose sur le RT par la passe qui recopie `accum` : layout du blur, et un + // uniforme que `fs_copy` ne lit pas. + let uniform = self.gpu.device.create_buffer_init(&wgpu::util::BufferInitDescriptor { + label: Some("text-layer-uniform"), + contents: layer_bytes(&LayerCB::default()), + usage: wgpu::BufferUsages::UNIFORM, + }); + let bind = self.gpu.device.create_bind_group(&wgpu::BindGroupDescriptor { + label: Some("text-layer"), + layout: &self.blur_bgl, + entries: &[ + wgpu::BindGroupEntry { binding: 0, resource: uniform.as_entire_binding() }, + wgpu::BindGroupEntry { binding: 1, resource: wgpu::BindingResource::TextureView(view) }, + wgpu::BindGroupEntry { + binding: 2, + resource: wgpu::BindingResource::Sampler(&self.sampler), + }, + ], + }); + let mut rpass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor { + label: Some("text-layer-composite"), + color_attachments: &[Some(wgpu::RenderPassColorAttachment { + view: &self.rt_view, + resolve_target: None, + ops: wgpu::Operations { load: wgpu::LoadOp::Load, store: wgpu::StoreOp::Store }, + })], + depth_stencil_attachment: None, + timestamp_writes: None, + occlusion_query_set: None, + }); + rpass.set_pipeline(&self.pipeline_copy); + rpass.set_bind_group(0, &bind, &[]); + rpass.draw(0..3, 0..1); + } + for e in with_target(ShaderEffectTarget::Both) { + self.encode_shader_effect(&mut encoder, e, (&self.rt, &self.rt_view), &fx_context(e)); + } self.gpu.context.submit(std::iter::once(encoder.finish())); Ok(()) } @@ -6543,6 +6923,215 @@ mod tests { assert!(n > 50, "trop peu de points visibles : {n}"); assert!(worst <= 0.25, "le rendu s'ecarte de la projection de {worst:.2} px"); } + + // ----------------------------------------------------------------------- + // Effets shader (`shader_fx`) : les tests de `compositor_windows.rs`, sur lavapipe. + // ----------------------------------------------------------------------- + + /// Une scène à fond rouge plein, l'écran rétréci par le padding : les coins sont du fond. + fn shader_fx_scene(effects: serde_json::Value) -> Scene { + let json = serde_json::json!({ + "clips": [], + "layout": {"preset":"no-webcam","webcamSize":1,"webcamShape":"rectangle","webcamMirror":false,"webcamPosition":null,"webcamReactiveZoom":false}, + "effects": {"padding":0.5,"blur":false,"shadow":0,"roundnessFrac":0,"motionBlur":0}, + "background": {"kind":"color","color":"#ff0000"}, + "zoomRegions": [], + "cursor": {"show":false,"size":1,"smoothing":0,"motionBlur":0,"clickBounce":0,"clipToBounds":false,"theme":"default"}, + "cropByClip": [], + "output": {"width":320,"height":180,"fps":null}, + "shaderEffects": effects, + }); + Scene::from_json(&json.to_string()).expect("scène") + } + + /// Un fragment d'effet de 1 s à 3 s, tel que l'app l'envoie. + fn fx(code: &str, target: &str, lane: u32) -> serde_json::Value { + serde_json::json!({ + "clipIndex": 0, "startSec": 1.0, "endSec": 3.0, "target": target, "lane": lane, + "contract": 1, "code": code, + "params": [{"name": "level", "type": "number"}, {"name": "tint", "type": "color"}], + "values": {"level": 1.0, "tint": [0.0, 1.0, 0.0, 1.0]}, + }) + } + + const INVERT: &str = "fn effect(uv: vec2) -> vec4 {\n let c = frame(uv);\n return vec4(vec3(params.level) - c.rgb, 1.0);\n}\n"; + const BLUE: &str = "fn effect(uv: vec2) -> vec4 { return vec4(0.0, 0.0, 1.0, 1.0); }"; + const TINT: &str = "fn effect(uv: vec2) -> vec4 { return params.tint; }"; + const SAME: &str = "fn effect(uv: vec2) -> vec4 { return frame(uv); }"; + + fn fx_cfg() -> Cfg { + let mut cfg = Cfg::c8(); + cfg.bg_blur = 0.0; + cfg.mblur_n = 1; + cfg + } + + fn fx_compositor(gpu: &Gpu, w: u32, h: u32, effects: serde_json::Value) -> Compositor { + let comp = Compositor::new_sized(gpu, w, h).expect("compositeur"); + let scene = shader_fx_scene(effects); + comp.set_live_params(live_params_from_scene(&scene)); + comp.set_scene(Some(scene)); + comp + } + + /// Le pixel du coin haut-gauche (du fond) après une frame composée au temps source `t`. + fn corner_at(comp: &Compositor, gpu: &Gpu, t: f32) -> [u8; 3] { + let screen = FakeFrame::new(gpu, 64, 64, |_, _| 126); + comp.set_timeline_time(Some(t)); + comp.set_programme_time(Some(t)); + unsafe { comp.compose_frame(screen.as_ptr(), std::ptr::null(), 0.0, &fx_cfg()) }.expect("compose"); + let (_, _, rgba) = unsafe { comp.readback_direct() }.expect("readback"); + [rgba[0], rgba[1], rgba[2]] + } + + /// Le coin à 2 s, dans la région, sous les effets donnés. + fn corner_under(effects: serde_json::Value) -> Option<[u8; 3]> { + let gpu = gpu()?; + Some(corner_at(&fx_compositor(&gpu, 320, 180, effects), &gpu, 2.0)) + } + + /// La passe de l'agent repeint l'image composée, dans sa région et nulle part ailleurs. Le + /// compositeur par défaut est celui de l'export : il attend le pipeline, jamais de frame sans. + #[test] + fn a_shader_effect_repaints_the_composed_frame_inside_its_region() { + let Some(gpu) = gpu() else { return }; + let comp = fx_compositor(&gpu, 320, 180, serde_json::json!([fx(INVERT, "image", 0)])); + assert_eq!(corner_at(&comp, &gpu, 0.5), [255, 0, 0], "avant la région : le fond rouge"); + assert_eq!(corner_at(&comp, &gpu, 2.0), [0, 255, 255], "dans la région : rouge inversé"); + assert_eq!(corner_at(&comp, &gpu, 3.5), [255, 0, 0], "après la région : le fond rouge"); + } + + /// La preview ne bloque pas : elle saute l'effet tant qu'il compile, et `shader_fx_landed` + /// lui dit quand recomposer. Ensuite la frame est celle de l'export, au pixel. + #[test] + fn the_preview_shows_the_effect_once_it_landed() { + let Some(gpu) = gpu() else { return }; + let comp = Compositor::new_sized(&gpu, 320, 180).expect("compositeur"); + comp.set_shader_fx_blocking(false); + let scene = shader_fx_scene(serde_json::json!([fx(INVERT, "image", 0)])); + comp.set_live_params(live_params_from_scene(&scene)); + let start = std::time::Instant::now(); + comp.set_scene(Some(scene)); + while !comp.shader_fx_landed() { + assert!(start.elapsed().as_secs() < 30, "la compilation n'a jamais abouti"); + std::thread::sleep(std::time::Duration::from_millis(1)); + } + eprintln!("effet prêt en {:.1} ms", start.elapsed().as_secs_f64() * 1000.0); + assert_eq!(corner_at(&comp, &gpu, 2.0), [0, 255, 255]); + } + + /// Un WGSL invalide, une binding de plus ou un contrat inconnu ne cassent pas le rendu : + /// l'effet ne se dessine pas, la frame reste celle de la composition. Aucun n'atteint wgpu, + /// qui paniquerait sur une erreur de validation. + #[test] + fn a_broken_or_unknown_effect_leaves_the_frame_untouched() { + let broken = fx("fn effect(uv: vec2) -> vec4 { nope }", "image", 0); + let extra = fx( + "@group(0) @binding(4) var extra: vec4;\nfn effect(uv: vec2) -> vec4 { return extra; }", + "image", + 0, + ); + let mut future = fx(BLUE, "image", 0); + future["contract"] = serde_json::json!(2); + for effect in [broken, extra, future] { + let Some(corner) = corner_under(serde_json::json!([effect])) else { return }; + assert_eq!(corner, [255, 0, 0]); + } + } + + /// Les paramètres arrivent dans `params` au layout de la struct générée : la couleur `tint` + /// suit le nombre `level` dans le buffer, et se lit telle que l'app l'a écrite. + #[test] + fn a_color_parameter_reaches_the_shader() { + let Some(corner) = corner_under(serde_json::json!([fx(TINT, "image", 0)])) else { return }; + assert_eq!(corner, [0, 255, 0]); + } + + /// Les lanes s'appliquent dans l'ordre : bleu puis inversion donne jaune, l'inverse donne bleu. + #[test] + fn lanes_apply_in_order() { + let Some(blue_then_invert) = + corner_under(serde_json::json!([fx(INVERT, "image", 1), fx(BLUE, "image", 0)])) + else { + return; + }; + assert_eq!(blue_then_invert, [255, 255, 0]); + let invert_then_blue = + corner_under(serde_json::json!([fx(INVERT, "image", 0), fx(BLUE, "image", 1)])).unwrap(); + assert_eq!(invert_then_blue, [0, 0, 255]); + } + + /// `text` ne touche que le calque des textes, posé ensuite sur l'image ; `both` voit tout. + /// Sans annotation, le calque est transparent : un effet `text` qui le rend tel quel laisse + /// l'image intacte, un effet `text` opaque la recouvre. + #[test] + fn the_three_targets_keep_to_their_layer() { + let Some(image_only) = corner_under(serde_json::json!([fx(BLUE, "image", 0)])) else { return }; + assert_eq!(image_only, [0, 0, 255]); + let text_untouched = + corner_under(serde_json::json!([fx(BLUE, "image", 0), fx(SAME, "text", 0)])).unwrap(); + assert_eq!(text_untouched, [0, 0, 255], "un calque transparent ne change pas l'image"); + let text_opaque = + corner_under(serde_json::json!([fx(BLUE, "image", 0), fx(TINT, "text", 0)])).unwrap(); + assert_eq!(text_opaque, [0, 255, 0], "le calque des textes, opaque, posé sur l'image"); + let both = corner_under(serde_json::json!([fx(BLUE, "image", 0), fx(INVERT, "both", 0)])).unwrap(); + assert_eq!(both, [255, 255, 0], "`both` voit l'image finale"); + } + + /// Calibre les paliers de coût : le surcoût par frame d'un effet qui lit `frame()` N fois, + /// à 1080p et en 4K, sur le GPU de la machine. Opt-in, comme les autres mesures : + /// + /// OPENSCREEN_FX_BENCH=1 cargo test -p openscreen-compositor --release --lib + /// shader_fx_tier_calibration -- --nocapture + /// + /// 200 frames par mesure ; `OPENSCREEN_FX_BENCH_FRAMES=5` sur lavapipe, où 512 lectures en 4K + /// prennent 5 s par frame. + #[test] + fn shader_fx_tier_calibration() { + if std::env::var_os("OPENSCREEN_FX_BENCH").is_none() { + eprintln!("OPENSCREEN_FX_BENCH absent — saute"); + return; + } + let gpu = Gpu::create_auto(false).expect("device Vulkan"); + eprintln!("backend : {:?}", gpu.backend); + let screen = FakeFrame::new(&gpu, 1920, 1080, |x, y| ((x ^ y) & 0xff) as u8); + let cfg = fx_cfg(); + let reads_effect = |n: u32| { + format!( + "fn effect(uv: vec2) -> vec4 {{\n var acc = vec4(0.0);\n for (var i = 0; i < {n}; i++) {{\n let a = f32(i) * 2.399;\n acc += frame(uv + vec2(cos(a), sin(a)) * fx_px(f32(i)));\n }}\n return acc / {n}.0;\n}}\n" + ) + }; + let frames: u32 = std::env::var("OPENSCREEN_FX_BENCH_FRAMES").ok().and_then(|v| v.parse().ok()).unwrap_or(200); + let per_frame = |w: u32, h: u32, effects: serde_json::Value| -> f64 { + let comp = fx_compositor(&gpu, w, h, effects); + comp.set_timeline_time(Some(2.0)); + comp.set_programme_time(Some(2.0)); + unsafe { comp.compose_frame(screen.as_ptr(), std::ptr::null(), 0.0, &cfg) }.unwrap(); + unsafe { comp.readback_direct() }.unwrap(); + let t0 = std::time::Instant::now(); + for f in 0..frames { + unsafe { comp.compose_frame(screen.as_ptr(), std::ptr::null(), f as f32, &cfg) }.unwrap(); + } + unsafe { comp.readback_direct() }.unwrap(); + t0.elapsed().as_secs_f64() * 1000.0 / frames as f64 + }; + for (w, h) in [(1920u32, 1080u32), (3840, 2160)] { + let base = (0..3).map(|_| per_frame(w, h, serde_json::json!([]))).fold(f64::MAX, f64::min); + eprintln!("{w}x{h} : sans effet {base:.3} ms/frame"); + for reads in [1u32, 8, 32, 128, 512] { + let code = reads_effect(reads); + let report = crate::shader_fx::analyze(&code, &[]).expect("analyse").report; + let with = (0..3) + .map(|_| per_frame(w, h, serde_json::json!([fx(&code, "image", 0)]))) + .fold(f64::MAX, f64::min); + eprintln!( + "{w}x{h} : {reads:>3} lectures ({:>10}) : +{:.3} ms/frame", + report.tier.name(), + with - base + ); + } + } + } } // --------------------------------------------------------------------------- diff --git a/crates/compositor/src/compositor_windows.rs b/crates/compositor/src/compositor_windows.rs index 26dc8f67b8..6014ec98c8 100644 --- a/crates/compositor/src/compositor_windows.rs +++ b/crates/compositor/src/compositor_windows.rs @@ -16,7 +16,10 @@ use crate::frame_geometry::{ WEBCAM_SHADOW_OPACITY, WEBCAM_SHADOW_SPREAD_FRAC, }; use crate::cursor::CursorTrack; -use crate::scene::{Scene, SceneBackground, SceneCrop, SceneCursorSprite, WallpaperMotion}; +use crate::scene::{ + Scene, SceneBackground, SceneCrop, SceneCursorSprite, SceneShaderEffect, ShaderEffectTarget, + WallpaperMotion, +}; use crate::d3d::Gpu; use crate::ffi::AVFrame; use anyhow::{bail, Result}; @@ -26,7 +29,8 @@ use std::ffi::c_void; use windows::core::Interface; use windows::Win32::Foundation::RECT; use windows::Win32::Graphics::Direct3D::{ - D3D11_SRV_DIMENSION_TEXTURE2D, D3D_PRIMITIVE_TOPOLOGY_TRIANGLESTRIP, + D3D11_SRV_DIMENSION_TEXTURE2D, D3D_PRIMITIVE_TOPOLOGY_TRIANGLELIST, + D3D_PRIMITIVE_TOPOLOGY_TRIANGLESTRIP, }; use windows::Win32::Graphics::Direct3D11::*; use windows::Win32::Graphics::Dxgi::Common::*; @@ -85,6 +89,31 @@ struct BgCache { tex: ID3D11Texture2D, } +/// Un effet shader de la scène (`shader_fx`), par hash de sa source. +enum ShaderFx { + /// naga + FXC tournent sur un thread de fond. + Pending(std::sync::mpsc::Receiver>), + Ready(ID3D11VertexShader, ID3D11PixelShader), + /// Erreur déjà écrite ; l'effet ne se dessine pas. + Failed, +} + +struct ShaderFxEntry { + state: ShaderFx, + /// Dernier usage, pour l'éviction (`SHADER_FX_CACHE`). + used: u64, +} + +/// Combien d'effets compilés le compositeur garde. Un agent qui itère en crée un par version. +const SHADER_FX_CACHE: usize = 64; + +/// Le calque transparent des textes, pour les effets qui ne visent qu'eux. +struct TextLayer { + tex: ID3D11Texture2D, + rtv: ID3D11RenderTargetView, + srv: ID3D11ShaderResourceView, +} + struct DofPyramid { rtv: ID3D11RenderTargetView, srv: ID3D11ShaderResourceView, @@ -264,6 +293,19 @@ pub struct Compositor { /// Pyramide de profondeur de champ, allouée au premier écran incliné et recréée quand la /// texture décodeur change de taille. Rien n'est alloué tant qu'aucun tilt n'est rendu. dof_pyramid: RefCell>, + /// Effets shader de la scène, compilés une fois par source, les moins récents évincés au-delà + /// de `SHADER_FX_CACHE`. + shader_fx: RefCell>, + shader_fx_tick: Cell, + /// `ctx` (b2) et `params` (b3) de la passe d'effet. + shader_fx_cb: ID3D11Buffer, + shader_fx_params_cb: ID3D11Buffer, + /// Alloué à la première frame qui porte un effet `text` ; à la taille de rendu. + text_layer: RefCell>, + /// Vrai par défaut : une frame dont l'effet compile encore attend son binaire, parce qu'un + /// export ne doit jamais rendre de frame sans l'effet. La preview le passe à faux et saute + /// l'effet le temps de la compilation (~10 ms), puis recompose (`shader_fx_landed`). + shader_fx_blocking: Cell, /// Device WARP : la profondeur de champ y obéit à `DOF_ON_CPU_BACKEND`. cpu_backend: bool, } @@ -426,6 +468,7 @@ impl Compositor { bg_cache: RefCell::new(None), live_readback_staging: RefCell::new(None), nv12_readback_staging: RefCell::new(None), + text_layer: RefCell::new(None), ..self }) } @@ -654,6 +697,18 @@ impl Compositor { }; let mut cbuf: Option = None; dev.CreateBuffer(&bd, None, Some(&mut cbuf))?; + let fx_bd = D3D11_BUFFER_DESC { + ByteWidth: std::mem::size_of::() as u32, + ..bd + }; + let mut shader_fx_cb: Option = None; + dev.CreateBuffer(&fx_bd, None, Some(&mut shader_fx_cb))?; + let fx_params_bd = D3D11_BUFFER_DESC { + ByteWidth: crate::shader_fx::PARAMS_BUFFER_BYTES as u32, + ..bd + }; + let mut shader_fx_params_cb: Option = None; + dev.CreateBuffer(&fx_params_bd, None, Some(&mut shader_fx_params_cb))?; // --- blend alpha prémultiplié --- let mut bl = D3D11_BLEND_DESC::default(); @@ -791,6 +846,12 @@ impl Compositor { seg_failed: RefCell::new(false), nv12_readback_staging: RefCell::new(None), dof_pyramid: RefCell::new(None), + shader_fx: RefCell::new(HashMap::new()), + shader_fx_tick: Cell::new(0), + shader_fx_cb: shader_fx_cb.unwrap(), + shader_fx_params_cb: shader_fx_params_cb.unwrap(), + shader_fx_blocking: Cell::new(true), + text_layer: RefCell::new(None), cpu_backend: gpu.backend == crate::d3d::Backend::Cpu, }) } @@ -839,9 +900,207 @@ impl Compositor { /// Installe (ou retire) la scène de l'app. Présente → `compose_frame` prend ses placements /// depuis le layout preset au lieu du planning fixture. pub fn set_scene(&self, s: Option) { + // Les effets nouveaux partent compiler tout de suite, hors du thread de rendu : à la + // première frame qui les montre, ils sont en général déjà prêts. + if let Some(scene) = &s { + for effect in &scene.shader_effects { + self.shader_fx_entry(effect); + } + } *self.scene.borrow_mut() = s; } + /// Faux pour la preview : voir `shader_fx_blocking`. + pub fn set_shader_fx_blocking(&self, on: bool) { + self.shader_fx_blocking.set(on); + } + + /// Fait aboutir les compilations terminées. Vrai si un effet vient d'être prêt : la preview + /// en pause doit alors recomposer, sinon elle resterait sur la frame sans l'effet. + pub fn shader_fx_landed(&self) -> bool { + let mut landed = false; + for entry in self.shader_fx.borrow_mut().values_mut() { + let got = match &entry.state { + ShaderFx::Pending(rx) => rx.try_recv(), + _ => continue, + }; + match got { + Ok(result) => { + entry.state = self.finish_shader_fx(result); + landed = true; + } + Err(std::sync::mpsc::TryRecvError::Empty) => {} + Err(std::sync::mpsc::TryRecvError::Disconnected) => entry.state = ShaderFx::Failed, + } + } + landed + } + + /// La clé de cache d'`effect`, sa compilation lancée s'il est neuf, et son dernier usage noté. + /// `None` pour un contrat que ce compositeur ne connaît pas : la région ne se dessine pas. + fn shader_fx_entry(&self, effect: &SceneShaderEffect) -> Option { + if effect.contract != crate::shader_fx::CONTRACT { + return None; + } + let key = crate::shader_fx::source_hash(effect); + let tick = self.shader_fx_tick.get() + 1; + self.shader_fx_tick.set(tick); + let mut fx = self.shader_fx.borrow_mut(); + fx.entry(key) + .or_insert_with(|| ShaderFxEntry { + state: ShaderFx::Pending(crate::shader_fx::spawn_compile(effect)), + used: tick, + }) + .used = tick; + // Un agent qui itère crée une entrée par version : on garde les plus récentes. + if fx.len() > SHADER_FX_CACHE { + if let Some(oldest) = fx.iter().min_by_key(|(_, e)| e.used).map(|(k, _)| *k) { + fx.remove(&oldest); + } + } + Some(key) + } + + fn finish_shader_fx(&self, result: Result) -> ShaderFx { + let created = result.and_then(|c| unsafe { + let (mut vs, mut ps) = (None, None); + self.dev + .CreateVertexShader(&c.vs, None, Some(&mut vs)) + .and_then(|()| self.dev.CreatePixelShader(&c.ps, None, Some(&mut ps))) + .map_err(|e| e.to_string())?; + Ok((vs.unwrap(), ps.unwrap())) + }); + match created { + Ok((vs, ps)) => ShaderFx::Ready(vs, ps), + Err(e) => { + eprintln!("[shader-fx] {e}"); + ShaderFx::Failed + } + } + } + + /// Les shaders d'`effect`. Le compositeur d'export attend leur compilation ; la preview + /// (`shader_fx_blocking` faux) rend `None` tant qu'ils compilent. `None` aussi s'ils ont échoué. + fn shader_fx_ready(&self, effect: &SceneShaderEffect) -> Option<(ID3D11VertexShader, ID3D11PixelShader)> { + let key = self.shader_fx_entry(effect)?; + let mut fx = self.shader_fx.borrow_mut(); + let entry = fx.get_mut(&key)?; + if let ShaderFx::Pending(rx) = &entry.state { + let got = if self.shader_fx_blocking.get() { + rx.recv().map_err(|e| e.to_string()) + } else { + match rx.try_recv() { + Ok(result) => Ok(result), + Err(std::sync::mpsc::TryRecvError::Empty) => return None, + Err(e) => Err(e.to_string()), + } + }; + entry.state = match got { + Ok(result) => self.finish_shader_fx(result), + Err(e) => { + eprintln!("[shader-fx] {e}"); + ShaderFx::Failed + } + }; + } + match &entry.state { + ShaderFx::Ready(vs, ps) => Some((vs.clone(), ps.clone())), + _ => None, + } + } + + unsafe fn upload_bytes(&self, buf: &ID3D11Buffer, bytes: &[u8]) -> bool { + let mut m = D3D11_MAPPED_SUBRESOURCE::default(); + if self.ctx.Map(buf, 0, D3D11_MAP_WRITE_DISCARD, 0, Some(&mut m)).is_err() { + return false; + } + std::ptr::copy_nonoverlapping(bytes.as_ptr(), m.pData as *mut u8, bytes.len()); + self.ctx.Unmap(buf, 0); + true + } + + /// Une passe d'effet sur `dst` (le RT principal, ou le calque des textes) : `dst` est copié + /// dans `ann_copy`, libre à ce stade, puis l'effet le repeint en entier. + unsafe fn apply_shader_effect( + &self, + effect: &SceneShaderEffect, + dst: (&ID3D11Texture2D, &ID3D11RenderTargetView), + cb: &crate::shader_fx::FxContext, + ) { + let Some((vs, ps)) = self.shader_fx_ready(effect) else { return }; + let ctx_bytes = std::slice::from_raw_parts( + cb as *const crate::shader_fx::FxContext as *const u8, + std::mem::size_of::(), + ); + let params = crate::shader_fx::pack_params(effect); + let params_bytes = std::slice::from_raw_parts( + params.as_ptr() as *const u8, + (params.len() * 4).min(crate::shader_fx::PARAMS_BUFFER_BYTES), + ); + if !self.upload_bytes(&self.shader_fx_cb, ctx_bytes) + || !self.upload_bytes(&self.shader_fx_params_cb, params_bytes) + { + return; + } + // On ne lit pas la cible sur laquelle on dessine : copie dans `ann_copy` (les flous + // d'annotation et le cristal de Prism Glow l'ont déjà lue). + self.ctx.CopySubresourceRegion(&self.ann_copy, 0, 0, 0, 0, dst.0, 0, None); + self.ctx.OMSetRenderTargets(Some(&[Some(dst.1.clone())]), None); + let vp = D3D11_VIEWPORT { + TopLeftX: 0.0, + TopLeftY: 0.0, + Width: self.rw(), + Height: self.rh(), + MinDepth: 0.0, + MaxDepth: 1.0, + }; + self.ctx.RSSetViewports(Some(&[vp])); + self.ctx.IASetPrimitiveTopology(D3D_PRIMITIVE_TOPOLOGY_TRIANGLELIST); + self.ctx.VSSetShader(&vs, None); + self.ctx.PSSetShader(&ps, None); + // Les registres du prélude tels que naga les sort : t0, s1, b2 (ctx), b3 (params). + self.ctx.PSSetShaderResources(0, Some(&[Some(self.ann_copy_srv.clone())])); + self.ctx.PSSetSamplers(1, Some(&[Some(self.sampler.clone())])); + self.ctx.PSSetConstantBuffers( + 2, + Some(&[Some(self.shader_fx_cb.clone()), Some(self.shader_fx_params_cb.clone())]), + ); + self.ctx.OMSetBlendState(&self.blend_none, None, 0xffffffff); + self.ctx.Draw(3, 0); + self.ctx.PSSetShaderResources(0, Some(&[None])); + self.ctx.PSSetConstantBuffers(2, Some(&[None, None])); + self.bind_compose_state(); + } + + /// Le calque transparent des textes, à la taille de rendu, alloué à la première frame qui en a + /// besoin (un effet `ShaderEffectTarget::Text`). + unsafe fn text_layer(&self) -> Result<(ID3D11Texture2D, ID3D11RenderTargetView, ID3D11ShaderResourceView)> { + if let Some(l) = self.text_layer.borrow().as_ref() { + return Ok((l.tex.clone(), l.rtv.clone(), l.srv.clone())); + } + let mut d = D3D11_TEXTURE2D_DESC::default(); + self.rt.GetDesc(&mut d); + d.BindFlags = (D3D11_BIND_RENDER_TARGET.0 | D3D11_BIND_SHADER_RESOURCE.0) as u32; + d.MiscFlags = 0; + d.CPUAccessFlags = 0; + d.Usage = D3D11_USAGE_DEFAULT; + let mut tex: Option = None; + self.dev.CreateTexture2D(&d, None, Some(&mut tex))?; + let tex = tex.ok_or_else(|| anyhow::anyhow!("CreateTexture2D (calque des textes)"))?; + let mut rtv: Option = None; + self.dev.CreateRenderTargetView(&tex, None, Some(&mut rtv))?; + let mut srv: Option = None; + self.dev.CreateShaderResourceView(&tex, None, Some(&mut srv))?; + let layer = TextLayer { + tex, + rtv: rtv.ok_or_else(|| anyhow::anyhow!("RTV (calque des textes)"))?, + srv: srv.ok_or_else(|| anyhow::anyhow!("SRV (calque des textes)"))?, + }; + let out = (layer.tex.clone(), layer.rtv.clone(), layer.srv.clone()); + *self.text_layer.borrow_mut() = Some(layer); + Ok(out) + } + /// The Y (R8) and UV (R8G8) views of the decoder frame — over a private COPY, never /// over the decoder surface itself. /// @@ -2315,6 +2574,10 @@ impl Compositor { // pixels déjà floutés. Les autres annotations restent le calque le plus haut (plus bas). self.draw_annotations(scene_ref.as_ref(), source_t, s_ann, &g, true); + // La pointe et les clics récents, tels que les effets shader les lisent. + let mut fx_cursor = None; + let mut fx_clicks = Vec::new(); + // --- curseur custom : suit le mapping src/dst (zoom+layout), click bounce, // et flou de mouvement (parité `compositor_macos.rs` et `compositor_linux.rs`) --- if let Some(track) = cursor_ref.as_ref() { @@ -2333,6 +2596,8 @@ impl Compositor { ) .map(|p| p.for_backend(self.cpu_backend)); if let Some(plan) = plan { + fx_cursor = Some(plan.pointer); + fx_clicks = plan.clicks.clone(); let cursor_sprites: HashMap = scene_ref .as_ref() .map(|s| s.cursor.cursor_sprites.clone()) @@ -2540,6 +2805,29 @@ impl Compositor { } } + // --- effets shader de l'agent, autour des textes selon leur cible (`docs/shader-effects.md`, + // D.1) : `image` avant les annotations et les sous-titres, `text` sur un calque des textes + // à part, `both` sur l'image finale. + let fx_inputs = crate::shader_fx::FxFrameInputs { + cursor: fx_cursor, + clicks: fx_clicks, + footage: crate::shader_fx::bounds(&g.footage_quad([self.rw(), self.rh()]).corners), + camera: lp.has_webcam.then_some(w_dst), + }; + let effects = scene_ref + .as_ref() + .map(|s| crate::shader_fx::active_effects(&s.shader_effects, source_t)) + .unwrap_or_default(); + let fx_context = |e: &SceneShaderEffect| { + crate::shader_fx::context(e, source_t, g.programme_t, [self.rw(), self.rh()], &fx_inputs) + }; + let with_target = |target: ShaderEffectTarget| -> Vec<&SceneShaderEffect> { + effects.iter().copied().filter(|e| e.target == target).collect() + }; + for e in with_target(ShaderEffectTarget::Image) { + self.apply_shader_effect(e, (&self.rt, &self.rtv), &fx_context(e)); + } + // --- annotations : calque le plus haut, comme dans le DOM de la preview (le calque y est // monté après la vidéo). Ancrées sur `s_ann`, le rect ÉCRAN SANS ZOOM — c'est le conteneur // que reçoit l'overlay web (`layout.screenRect`) — et volontairement pas sur le rect de @@ -2553,7 +2841,34 @@ impl Compositor { // `source_t`, la même base de temps que les zoom/speed regions : le temps SOURCE du clip, // pas le compteur de frames. C'est ce qui garde une annotation alignée sur l'image quand // une speed region répète ou saute des frames. - self.draw_annotations(scene_ref.as_ref(), source_t, s_ann, &g, false); + let text_effects = with_target(ShaderEffectTarget::Text); + if text_effects.is_empty() { + self.draw_annotations(scene_ref.as_ref(), source_t, s_ann, &g, false); + } else { + // Les textes sur un calque transparent, l'effet sur ce calque seul, puis le calque + // posé sur l'image (« over » prémultiplié) : l'image dessous reste intacte. + let (tex, rtv, srv) = self.text_layer()?; + self.bind_compose_state(); + self.ctx.OMSetRenderTargets(Some(&[Some(rtv.clone())]), None); + self.ctx.ClearRenderTargetView(&rtv, &[0.0, 0.0, 0.0, 0.0]); + self.draw_annotations(scene_ref.as_ref(), source_t, s_ann, &g, false); + for e in text_effects { + self.apply_shader_effect(e, (&tex, &rtv), &fx_context(e)); + } + self.ctx.OMSetRenderTargets(Some(&[Some(self.rtv.clone())]), None); + self.ctx.PSSetShaderResources(0, Some(&[Some(srv)])); + self.ctx.VSSetShader(&self.vs_fs, None); + self.ctx.PSSetShader(&self.ps_tex, None); + self.ctx.PSSetSamplers(0, Some(&[Some(self.sampler.clone())])); + self.ctx.OMSetBlendState(&self.blend, None, 0xffffffff); + self.ctx.Draw(3, 0); + self.ctx.PSSetShaderResources(0, Some(&[None])); + self.bind_compose_state(); + } + + for e in with_target(ShaderEffectTarget::Both) { + self.apply_shader_effect(e, (&self.rt, &self.rtv), &fx_context(e)); + } Ok(()) } @@ -3554,4 +3869,199 @@ mod tests { let (rw, rh, rgba) = unsafe { comp.readback_direct() }.expect("readback"); assert_eq!((rw, rh, rgba.len()), (182, 322, 182 * 322 * 4)); } + + /// Une scène à fond rouge plein, l'écran rétréci par le padding : les coins sont du fond. + fn shader_fx_scene(effects: serde_json::Value) -> Scene { + let json = serde_json::json!({ + "clips": [], + "layout": {"preset":"no-webcam","webcamSize":1,"webcamShape":"rectangle","webcamMirror":false,"webcamPosition":null,"webcamReactiveZoom":false}, + "effects": {"padding":0.5,"blur":false,"shadow":0,"roundnessFrac":0,"motionBlur":0}, + "background": {"kind":"color","color":"#ff0000"}, + "zoomRegions": [], + "cursor": {"show":false,"size":1,"smoothing":0,"motionBlur":0,"clickBounce":0,"clipToBounds":false,"theme":"default"}, + "cropByClip": [], + "output": {"width":320,"height":180,"fps":null}, + "shaderEffects": effects, + }); + Scene::from_json(&json.to_string()).expect("scène") + } + + /// Un fragment d'effet de 1 s à 3 s, tel que l'app l'envoie. + fn fx(code: &str, target: &str, lane: u32) -> serde_json::Value { + serde_json::json!({ + "clipIndex": 0, "startSec": 1.0, "endSec": 3.0, "target": target, "lane": lane, + "contract": 1, "code": code, + "params": [{"name": "level", "type": "number"}, {"name": "tint", "type": "color"}], + "values": {"level": 1.0, "tint": [0.0, 1.0, 0.0, 1.0]}, + }) + } + + const INVERT: &str = "fn effect(uv: vec2) -> vec4 {\n let c = frame(uv);\n return vec4(vec3(params.level) - c.rgb, 1.0);\n}\n"; + const BLUE: &str = "fn effect(uv: vec2) -> vec4 { return vec4(0.0, 0.0, 1.0, 1.0); }"; + const TINT: &str = "fn effect(uv: vec2) -> vec4 { return params.tint; }"; + const SAME: &str = "fn effect(uv: vec2) -> vec4 { return frame(uv); }"; + + fn fx_cfg() -> crate::config::Cfg { + let mut cfg = crate::config::Cfg::c8(); + cfg.bg_blur = 0.0; + cfg.mblur_n = 1; + cfg + } + + /// Le pixel du coin haut-gauche (du fond) après une frame composée au temps source `t`. + fn corner_at(comp: &Compositor, gpu: &crate::d3d::Gpu, t: f32) -> [u8; 3] { + let (screen, _tex) = nv12_frame(gpu, 64, 64); + comp.set_timeline_time(Some(t)); + comp.set_programme_time(Some(t)); + unsafe { comp.compose_frame(&*screen, &*screen, 0.0, &fx_cfg()) }.expect("compose"); + let (_, _, rgba) = unsafe { comp.readback_direct() }.expect("readback"); + [rgba[0], rgba[1], rgba[2]] + } + + /// Le coin à 2 s, dans la région, sous les effets donnés. + fn corner_under(effects: serde_json::Value) -> Option<[u8; 3]> { + let gpu = crate::d3d::Gpu::create_auto(false).ok()?; + let comp = Compositor::new_sized(&gpu, 320, 180).expect("compositeur"); + comp.set_scene(Some(shader_fx_scene(effects))); + Some(corner_at(&comp, &gpu, 2.0)) + } + + /// La passe de l'agent repeint l'image composée, dans sa région et nulle part ailleurs. Le + /// compositeur par défaut est celui de l'export : il attend le shader, jamais de frame sans. + #[test] + fn a_shader_effect_repaints_the_composed_frame_inside_its_region() { + let Ok(gpu) = crate::d3d::Gpu::create_auto(false) else { + eprintln!("pas de device D3D11 — test sauté"); + return; + }; + let comp = Compositor::new_sized(&gpu, 320, 180).expect("compositeur"); + comp.set_scene(Some(shader_fx_scene(serde_json::json!([fx(INVERT, "image", 0)])))); + assert_eq!(corner_at(&comp, &gpu, 0.5), [255, 0, 0], "avant la région : le fond rouge"); + assert_eq!(corner_at(&comp, &gpu, 2.0), [0, 255, 255], "dans la région : rouge inversé"); + assert_eq!(corner_at(&comp, &gpu, 3.5), [255, 0, 0], "après la région : le fond rouge"); + } + + /// La preview ne bloque pas : elle saute l'effet tant qu'il compile, et `shader_fx_landed` + /// lui dit quand recomposer. Ensuite la frame est celle de l'export, au pixel. + #[test] + fn the_preview_shows_the_effect_once_it_landed() { + let Ok(gpu) = crate::d3d::Gpu::create_auto(false) else { + eprintln!("pas de device D3D11 — test sauté"); + return; + }; + let comp = Compositor::new_sized(&gpu, 320, 180).expect("compositeur"); + comp.set_shader_fx_blocking(false); + comp.set_scene(Some(shader_fx_scene(serde_json::json!([fx(INVERT, "image", 0)])))); + let start = std::time::Instant::now(); + while !comp.shader_fx_landed() { + assert!(start.elapsed().as_secs() < 10, "la compilation n'a jamais abouti"); + std::thread::sleep(std::time::Duration::from_millis(1)); + } + eprintln!("effet prêt en {:.1} ms", start.elapsed().as_secs_f64() * 1000.0); + assert_eq!(corner_at(&comp, &gpu, 2.0), [0, 255, 255]); + } + + /// Un WGSL invalide, ou un contrat inconnu, ne casse pas le rendu : l'effet ne se dessine + /// pas, la frame reste celle de la composition. + #[test] + fn a_broken_or_unknown_effect_leaves_the_frame_untouched() { + let broken = fx("fn effect(uv: vec2) -> vec4 { nope }", "image", 0); + let mut future = fx(BLUE, "image", 0); + future["contract"] = serde_json::json!(2); + for effect in [broken, future] { + let Some(corner) = corner_under(serde_json::json!([effect])) else { return }; + assert_eq!(corner, [255, 0, 0]); + } + } + + /// Les paramètres arrivent dans `params` au layout de la struct générée : la couleur `tint` + /// suit le nombre `level` dans le buffer, et se lit telle que l'app l'a écrite. + #[test] + fn a_color_parameter_reaches_the_shader() { + let Some(corner) = corner_under(serde_json::json!([fx(TINT, "image", 0)])) else { return }; + assert_eq!(corner, [0, 255, 0]); + } + + /// Les lanes s'appliquent dans l'ordre : bleu puis inversion donne jaune, l'inverse donne bleu. + #[test] + fn lanes_apply_in_order() { + let Some(blue_then_invert) = + corner_under(serde_json::json!([fx(INVERT, "image", 1), fx(BLUE, "image", 0)])) + else { + return; + }; + assert_eq!(blue_then_invert, [255, 255, 0]); + let invert_then_blue = + corner_under(serde_json::json!([fx(INVERT, "image", 0), fx(BLUE, "image", 1)])).unwrap(); + assert_eq!(invert_then_blue, [0, 0, 255]); + } + + /// `text` ne touche que le calque des textes, posé ensuite sur l'image ; `both` voit tout. + /// Sans annotation, le calque est transparent : un effet `text` qui le rend tel quel laisse + /// l'image intacte, un effet `text` opaque la recouvre. + #[test] + fn the_three_targets_keep_to_their_layer() { + let Some(image_only) = corner_under(serde_json::json!([fx(BLUE, "image", 0)])) else { return }; + assert_eq!(image_only, [0, 0, 255]); + let text_untouched = + corner_under(serde_json::json!([fx(BLUE, "image", 0), fx(SAME, "text", 0)])).unwrap(); + assert_eq!(text_untouched, [0, 0, 255], "un calque transparent ne change pas l'image"); + let text_opaque = + corner_under(serde_json::json!([fx(BLUE, "image", 0), fx(TINT, "text", 0)])).unwrap(); + assert_eq!(text_opaque, [0, 255, 0], "le calque des textes, opaque, posé sur l'image"); + let both = corner_under(serde_json::json!([fx(BLUE, "image", 0), fx(INVERT, "both", 0)])).unwrap(); + assert_eq!(both, [255, 255, 0], "`both` voit l'image finale"); + } + + /// Calibre les paliers de coût : le surcoût par frame d'un effet qui lit `frame()` N fois, + /// à 1080p et en 4K, sur le GPU de la machine. Opt-in, comme les autres mesures : + /// + /// set OPENSCREEN_FX_BENCH=1 && cargo test -p openscreen-compositor --release + /// shader_fx_tier_calibration -- --nocapture + #[test] + fn shader_fx_tier_calibration() { + if std::env::var_os("OPENSCREEN_FX_BENCH").is_none() { + eprintln!("OPENSCREEN_FX_BENCH absent — saute"); + return; + } + let gpu = crate::d3d::Gpu::create_backend(crate::d3d::Backend::Hardware, false) + .expect("device D3D11"); + let (screen, _tex) = nv12_frame(&gpu, 1920, 1080); + let cfg = fx_cfg(); + let reads_effect = |n: u32| { + format!( + "fn effect(uv: vec2) -> vec4 {{\n var acc = vec4(0.0);\n for (var i = 0; i < {n}; i++) {{\n let a = f32(i) * 2.399;\n acc += frame(uv + vec2(cos(a), sin(a)) * fx_px(f32(i)));\n }}\n return acc / {n}.0;\n}}\n" + ) + }; + let per_frame = |w: u32, h: u32, effects: serde_json::Value| -> f64 { + let comp = Compositor::new_sized(&gpu, w, h).expect("compositeur"); + comp.set_scene(Some(shader_fx_scene(effects))); + comp.set_timeline_time(Some(2.0)); + comp.set_programme_time(Some(2.0)); + unsafe { comp.compose_frame(&*screen, &*screen, 0.0, &cfg) }.unwrap(); + unsafe { comp.readback_direct() }.unwrap(); + let n = 200; + let t0 = std::time::Instant::now(); + for f in 0..n { + unsafe { comp.compose_frame(&*screen, &*screen, f as f32, &cfg) }.unwrap(); + } + unsafe { comp.readback_direct() }.unwrap(); + t0.elapsed().as_secs_f64() * 1000.0 / n as f64 + }; + for (w, h) in [(1920u32, 1080u32), (3840, 2160)] { + let base = (0..5).map(|_| per_frame(w, h, serde_json::json!([]))).fold(f64::MAX, f64::min); + for reads in [1u32, 8, 32, 128, 512] { + let code = reads_effect(reads); + let report = crate::shader_fx::analyze(&code, &[]).expect("analyse").report; + let with = (0..5) + .map(|_| per_frame(w, h, serde_json::json!([fx(&code, "image", 0)]))) + .fold(f64::MAX, f64::min); + eprintln!( + "{w}x{h} : {reads:>3} lectures ({:>10}) : +{:.3} ms/frame", + report.tier.name(), + with - base + ); + } + } + } } diff --git a/crates/compositor/src/frame_geometry.rs b/crates/compositor/src/frame_geometry.rs index 0decdb21f1..24de397595 100644 --- a/crates/compositor/src/frame_geometry.rs +++ b/crates/compositor/src/frame_geometry.rs @@ -3599,6 +3599,13 @@ pub struct CursorPlan { /// composée, le métrage et ses flous de confidentialité, que le backend lui copie juste avant /// de le dessiner. Seuls des pixels floutés passent ainsi à travers le verre. pub glass: bool, + /// Pour les effets shader (`shader_fx`) : la pointe en 0..1 de SORTIE, zoom, layout et tilt + /// appliqués — ce qu'un effet ne peut pas recalculer lui-même. + pub pointer: [f32; 2], + /// Les clics des `shader_fx::CLICK_WINDOW_S` dernières secondes, du plus récent au plus ancien, + /// au plus `shader_fx::MAX_CLICKS` : le point de la pointe AU MOMENT du clic, en 0..1 de sortie, + /// et l'âge en secondes. + pub clicks: Vec<([f32; 2], f32)>, } impl CursorPlan { @@ -3887,7 +3894,19 @@ pub fn plan_cursor(g: &FrameGeometry, input: &CursorPlanInput) -> Option>() + .into_iter() + .rev() + .take(crate::shader_fx::MAX_CLICKS) + .filter_map(|(tc, p)| Some((place(Some(p), g.s_dst)?.upright_center(), input.t - tc))) + .collect(); + Some(CursorPlan { + pointer: placement.upright_center(), + clicks, placement, prev_placement, size_px, @@ -8849,6 +8868,46 @@ mod tests { assert!(!plan(true, 1.08).expect("visible").impacts.is_empty(), "garde : l'anneau du clic"); } + /// Les effets shader lisent la pointe et les clics récents en uv de SORTIE : un clic garde le + /// point où la pointe était quand il a eu lieu, le plus récent vient en premier, et un clic + /// sort de la liste après la fenêtre. + #[test] + fn the_plan_hands_effects_the_pointer_and_the_recent_clicks() { + let scene = model_scene(); + let cfg = crate::config::all().pop().expect("cfg"); + let fg = full_frame_geometry(); + let track = crate::cursor::CursorTrack::new_with_visibility( + vec![(0.0, 0.3, 0.6), (1.0, 0.3, 0.6), (1.2, 0.5, 0.4), (2.0, 0.8, 0.2), (6.0, 0.8, 0.2)], + vec![1.0, 1.2], + vec![], + vec![(0.0, true)], + ); + let plan = |t: f32| { + plan_cursor( + &fg, + &CursorPlanInput { + render_px: [1920.0, 1080.0], + u_max: 1.0, + v_max: 1.0, + cfg: &cfg, + live: LiveParams::default(), + scene: Some(&scene), + track: &track, + t, + }, + ) + .expect("visible") + }; + assert!(plan(0.5).clicks.is_empty(), "pas encore de clic"); + let (first, second) = (plan(1.0).pointer, plan(1.2).pointer); + let clicks = plan(1.5).clicks; + assert_eq!(clicks.len(), 2); + assert_eq!((clicks[0].0, clicks[1].0), (second, first), "le plus récent d'abord, au point du clic"); + assert!((clicks[0].1 - 0.3).abs() < 1e-4 && (clicks[1].1 - 0.5).abs() < 1e-4, "{clicks:?}"); + assert_ne!(plan(2.5).pointer, second, "la pointe a bougé depuis"); + assert_eq!(plan(1.1 + crate::shader_fx::CLICK_WINDOW_S).clicks.len(), 1, "le premier est sorti"); + } + /// Sous un angle fixe, l'écran tourne autour du centre de sa boîte ZOOMÉE, réduit de son /// containment : le curseur y perdait ~18 % au point de focus même, pendant que le zoom /// grossissait l'image. Il y garde sa taille à plat, à la perspective de biais près ; ailleurs, diff --git a/crates/compositor/src/lib.rs b/crates/compositor/src/lib.rs index b336797050..4aed792934 100644 --- a/crates/compositor/src/lib.rs +++ b/crates/compositor/src/lib.rs @@ -47,6 +47,8 @@ pub mod prism_mesh; pub mod remux; pub mod scene; pub mod sculpt; +// Effets shader écrits par un agent (docs/shader-effects.md) : WGSL -> naga -> backend. +pub mod shader_fx; // Segmentation du sujet webcam (masque -> `t3`). Le module compile toujours ; sans la feature // `segmentation` ses deux entrées échouent proprement, ce qui garde le reste du crate // indépendant du choix de packaging d'ONNX Runtime. diff --git a/crates/compositor/src/live.rs b/crates/compositor/src/live.rs index 16c75bd9e0..74cb719595 100644 --- a/crates/compositor/src/live.rs +++ b/crates/compositor/src/live.rs @@ -1491,6 +1491,10 @@ unsafe fn render_thread( // Chemin de PRODUCTION : matériel si possible, backend CPU sinon (voir `create_auto`). let gpu = Gpu::create_auto(false)?; let mut comp = Compositor::new(&gpu)?; + // La preview ne bloque jamais sur la compilation d'un effet shader : elle le saute le temps + // qu'il compile (voir `shader_fx_landed` plus bas). L'export, lui, attend. + #[cfg(any(windows, target_os = "linux"))] + comp.set_shader_fx_blocking(false); // Vue live = le VRAI enregistrement, pas la fenêtre fixture (100s@6s, taillée pour l'ancien // fixture POC). On charge toute la piste depuis t=0 ; 24h couvre large toute recording réelle. // Gardée à part (raw_cursor) pour pouvoir régénérer une variante lissée sans relire le @@ -1781,6 +1785,12 @@ unsafe fn render_thread( continue; } + // Un effet shader vient de finir de compiler : la frame en pause doit le montrer. + #[cfg(any(windows, target_os = "linux"))] + let fx_landed = comp.shader_fx_landed(); + #[cfg(not(any(windows, target_os = "linux")))] + let fx_landed = false; + // avance : seek app-piloté (presentTime) prioritaire, sinon lecture libre (60 fps) let requested = shared.requested_frame.lock().unwrap().take(); let now = Instant::now(); @@ -1915,7 +1925,7 @@ unsafe fn render_thread( break; } } - } else if first || ip_changed || scene_changed || clip_changed || resized { + } else if first || ip_changed || scene_changed || clip_changed || resized || fx_landed { // pause : recompose la frame courante (param / scène / clip / résolution changés). (settle_until, last_settle) = open_settle_window(now); let _ = player.recompose(&comp, &cfg); diff --git a/crates/compositor/src/scene.rs b/crates/compositor/src/scene.rs index 895fa6b2a2..7fea6bd7f7 100644 --- a/crates/compositor/src/scene.rs +++ b/crates/compositor/src/scene.rs @@ -547,6 +547,76 @@ pub struct SceneCameraFullscreenRegion { pub continues_after: bool, } +/// Un fragment de région d'effet shader (`docs/shader-effects.md`, B.5). Temps source du clip, +/// comme les autres régions ; la définition (code, paramètres) voyage avec chaque fragment. +#[derive(Debug, Clone, Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct SceneShaderEffect { + #[serde(default)] + pub clip_index: Option, + pub start_sec: f64, + pub end_sec: f64, + /// L'étendue de la pilule ENTIÈRE en temps programme, d'où `ctx.region`. Absente : la + /// progression court sur le fragment, en temps source. + #[serde(default)] + pub programme_start_sec: Option, + #[serde(default)] + pub programme_end_sec: Option, + #[serde(default)] + pub target: ShaderEffectTarget, + /// Ordre d'application : la lane 0 d'abord, au plus près du contenu. + #[serde(default)] + pub lane: u32, + /// Version du contrat. Une version que ce compositeur ne connaît pas ne se dessine pas. + #[serde(default = "default_contract")] + pub contract: u32, + /// Le WGSL de l'agent : une `fn effect(uv: vec2) -> vec4`. + pub code: String, + /// Les paramètres déclarés, dans l'ordre de la struct `FxParams` générée. + #[serde(default)] + pub params: Vec, + /// Les valeurs, déjà normalisées par l'app : un nombre, ou 2 ou 4 floats. + #[serde(default)] + pub values: std::collections::HashMap, +} + +fn default_contract() -> u32 { + crate::shader_fx::CONTRACT +} + +/// Ce qu'un effet transforme : l'image sans les textes, les textes seuls, ou les deux. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Deserialize)] +#[serde(rename_all = "lowercase")] +pub enum ShaderEffectTarget { + #[default] + Image, + Text, + Both, +} + +#[derive(Debug, Clone, PartialEq, Eq, Deserialize)] +pub struct ShaderParamDecl { + pub name: String, + #[serde(rename = "type")] + pub ty: ShaderParamType, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Deserialize)] +#[serde(rename_all = "lowercase")] +pub enum ShaderParamType { + Number, + Toggle, + Color, + Point, +} + +#[derive(Debug, Clone, PartialEq, Deserialize)] +#[serde(untagged)] +pub enum ShaderParamValue { + Scalar(f32), + Vector(Vec), +} + /// Rendu du curseur. #[derive(Debug, Clone, Deserialize)] #[serde(rename_all = "camelCase")] @@ -798,6 +868,9 @@ pub struct Scene { /// Effet d'arrière-plan de la webcam. Absent = aucun effet. #[serde(default)] pub webcam_effect: Option, + /// Effets shader écrits par un agent (`shader_fx`). Absent = aucun. + #[serde(default)] + pub shader_effects: Vec, /// État de rendu interne, positionné par `for_clip_window` (jamais envoyé par l'app). #[serde(skip)] pub(crate) active_clip_index: usize, @@ -845,6 +918,9 @@ impl Scene { scene.annotations.retain(|annotation| { belongs(annotation.clip_index, annotation.start_sec, annotation.end_sec) }); + scene.shader_effects.retain(|effect| { + belongs(effect.clip_index, effect.start_sec, effect.end_sec) + }); // Le layout dépend de la FORME de la source du clip (dimensions natives × crop), qui // varie d'un clip à l'autre. On installe donc celui du clip composé dans les champs // scalaires : `compose_frame` continue de lire un seul `layout`, sans jamais avoir à diff --git a/crates/compositor/src/shader_fx.rs b/crates/compositor/src/shader_fx.rs new file mode 100644 index 0000000000..87e4ad54e0 --- /dev/null +++ b/crates/compositor/src/shader_fx.rs @@ -0,0 +1,965 @@ +//! Effets shader écrits par un agent (`docs/shader-effects.md`) : du WGSL qui définit +//! `fn effect(uv: vec2) -> vec4`, appliqué en une passe plein cadre par `compose_frame`, +//! donc à l'identique en preview et à l'export. +//! +//! Ce module porte ce qui ne dépend d'aucun backend : le contrat (le prélude et la struct des +//! paramètres, générée), la validation, la borne des boucles, l'estimation du coût en paliers, la +//! sélection des régions actives et le remplissage des constant buffers. Chaque backend traduit le +//! module par naga et le compile une fois, hors de la boucle de rendu. +//! +//! L'effet est une fonction PURE de l'image composée, du temps, du curseur et de ses paramètres : +//! pas d'état d'une frame à l'autre. C'est ce qui garde la preview (qui saute d'une frame à +//! l'autre au seek) et l'export (qui les rend dans l'ordre) d'accord. + +use crate::scene::{SceneShaderEffect, ShaderEffectTarget, ShaderParamDecl, ShaderParamType, ShaderParamValue}; +use std::hash::{Hash, Hasher}; + +/// La version du contrat que ce prélude implémente. Un prélude livré ne change plus : une entrée +/// nouvelle s'ajoute à la fin de `FxContext`, un changement de sens crée la version suivante. +pub const CONTRACT: u32 = 1; + +/// Les entrées que l'effet lit, en plus de ses paramètres. Placées APRÈS le code de l'agent (et +/// après `FxParams`) : en WGSL l'ordre des déclarations de module est libre, et les erreurs +/// pointent ainsi les lignes que l'agent a écrites. Voir la section C de la spec. +pub const PRELUDE_V1: &str = r#" +struct FxContext { + resolution: vec2, + time: f32, + aspect: f32, + region: vec4, + cursor: vec4, + clicks: array, 4>, + footage: vec4, + camera: vec4, +}; +@group(0) @binding(0) var fx_frame: texture_2d; +@group(0) @binding(1) var fx_sampler: sampler; +@group(0) @binding(2) var ctx: FxContext; + +fn frame(uv: vec2) -> vec4 { + return textureSampleLevel(fx_frame, fx_sampler, uv, 0.0); +} + +fn fx_px(n: f32) -> f32 { + return n / 1080.0; +} + +fn fx_pcg(v: u32) -> u32 { + let state = v * 747796405u + 2891336453u; + let word = ((state >> ((state >> 28u) + 4u)) ^ state) * 277803737u; + return (word >> 22u) ^ word; +} + +fn fx_hash(p: vec2) -> f32 { + return f32(fx_pcg(p.x ^ fx_pcg(p.y)) >> 8u) / 16777216.0; +} + +struct FxVsOut { + @builtin(position) pos: vec4, + @location(0) uv: vec2, +}; + +@vertex +fn fx_vs(@builtin(vertex_index) i: u32) -> FxVsOut { + let p = vec2(f32((i << 1u) & 2u), f32(i & 2u)); + var o: FxVsOut; + o.pos = vec4(p.x * 2.0 - 1.0, 1.0 - p.y * 2.0, 0.0, 1.0); + o.uv = p; + return o; +} + +@fragment +fn fx_fs(v: FxVsOut) -> @location(0) vec4 { + return effect(v.uv); +} +"#; + +/// Combien de clics récents l'effet voit (`ctx.clicks`), du plus récent au plus ancien. +pub const MAX_CLICKS: usize = 4; +/// Jusqu'où un clic reste visible des effets : au-delà, son entrée est vide (`w` = 0). +pub const CLICK_WINDOW_S: f32 = 2.0; +/// Le plafond de sécurité du travail par pixel, toutes boucles imbriquées comprises. Ce n'est pas +/// un budget : c'est l'ordre de grandeur où un GPU intégré atteint le TDR en 1080p. +pub const MAX_ITERATIONS_PER_PIXEL: u64 = 4096; +/// Taille du constant buffer des paramètres : le plafond technique (32) de `vec4`. +pub const PARAMS_BUFFER_BYTES: usize = 32 * 16; + +/// Le constant buffer `ctx`, au layout de `FxContext` (144 octets). +#[repr(C)] +#[derive(Debug, Clone, Copy, PartialEq, Default)] +pub struct FxContext { + pub resolution: [f32; 2], + pub time: f32, + pub aspect: f32, + pub region: [f32; 4], + pub cursor: [f32; 4], + pub clicks: [[f32; 4]; MAX_CLICKS], + pub footage: [f32; 4], + pub camera: [f32; 4], +} + +/// Ce que le plan du curseur et la géométrie de la frame donnent aux effets, en uv de sortie. +#[derive(Debug, Clone, Default, PartialEq)] +pub struct FxFrameInputs { + pub cursor: Option<[f32; 2]>, + /// Les clics récents, du plus récent au plus ancien : point et âge en secondes. + pub clicks: Vec<([f32; 2], f32)>, + pub footage: [f32; 4], + pub camera: Option<[f32; 4]>, +} + +/// Le palier de coût d'un effet (section C.7 de la spec) : indicatif, jamais un refus. +#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)] +pub enum Tier { + Light, + Medium, + Heavy, + VeryHeavy, +} + +impl Tier { + /// Les seuils, en lectures de `frame()` par pixel. Sur la RTX 4070 Ti, une lecture coûte + /// ~4 µs par frame en 1080p : léger ≤ 0,06 ms, moyen ≤ 0,14 ms, lourd ≤ 0,54 ms + /// (`shader_fx_tier_calibration`, rendering-performance.md). + pub fn of(frame_reads: u64) -> Tier { + match frame_reads { + 0..=8 => Tier::Light, + 9..=32 => Tier::Medium, + 33..=128 => Tier::Heavy, + _ => Tier::VeryHeavy, + } + } + + pub fn name(self) -> &'static str { + match self { + Tier::Light => "light", + Tier::Medium => "medium", + Tier::Heavy => "heavy", + Tier::VeryHeavy => "very-heavy", + } + } +} + +/// Ce que la validation sait d'un effet accepté. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct EffectReport { + /// Lectures de texture par pixel, boucles multipliées par leur borne (le pire des branches). + pub frame_reads: u64, + /// Itérations de boucle par pixel, toutes boucles imbriquées comprises. + pub iterations: u64, + pub tier: Tier, +} + +impl ShaderParamType { + fn wgsl(self) -> &'static str { + match self { + ShaderParamType::Number | ShaderParamType::Toggle => "f32", + ShaderParamType::Color => "vec4", + ShaderParamType::Point => "vec2", + } + } + + /// (taille, alignement) en octets, règles WGSL de l'espace `uniform`. + fn size_align(self) -> (usize, usize) { + match self { + ShaderParamType::Number | ShaderParamType::Toggle => (4, 4), + ShaderParamType::Color => (16, 16), + ShaderParamType::Point => (8, 8), + } + } +} + +const RESERVED_PARAM_NAMES: &[&str] = &["unused"]; + +/// La struct `FxParams` et son binding, générés depuis les déclarations. WGSL refuse une struct +/// vide : sans paramètre, un champ `unused` en tient lieu. +fn params_source(params: &[ShaderParamDecl]) -> String { + let mut out = String::from("struct FxParams {\n"); + if params.is_empty() { + out.push_str(" unused: f32,\n"); + } + for p in params { + out.push_str(&format!(" {}: {},\n", p.name, p.ty.wgsl())); + } + out.push_str("};\n@group(0) @binding(3) var params: FxParams;\n"); + out +} + +/// Le module complet que naga compile : le code de l'agent d'abord, pour que ses lignes gardent +/// leur numéro dans les erreurs. +pub fn module_source(user: &str, params: &[ShaderParamDecl]) -> String { + format!("{user}\n{}{PRELUDE_V1}", params_source(params)) +} + +fn check_params(params: &[ShaderParamDecl]) -> Result<(), String> { + let mut seen = std::collections::HashSet::new(); + for p in params { + let valid = p.name.len() <= 32 + && p.name.starts_with(|c: char| c.is_ascii_lowercase()) + && p.name.chars().all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '_'); + if !valid { + return Err(format!("parameter `{}`: names are snake_case, a-z first, at most 32 characters", p.name)); + } + if RESERVED_PARAM_NAMES.contains(&p.name.as_str()) || !seen.insert(p.name.as_str()) { + return Err(format!("parameter `{}` is declared twice or reserved", p.name)); + } + } + Ok(()) +} + +/// Le module parsé, validé, et sa première fonction d'entrée de fragment. +pub struct Parsed { + pub module: naga::Module, + pub info: naga::valid::ModuleInfo, + pub report: EffectReport, +} + +/// Valide un effet comme l'agent doit le lire : paramètres, syntaxe et types (naga), bornes des +/// boucles, puis estimation du coût. L'erreur porte la ligne et la colonne du code de l'agent. +pub fn analyze(user: &str, params: &[ShaderParamDecl]) -> Result { + check_params(params)?; + let src = module_source(user, params); + let module = naga::front::wgsl::parse_str(&src).map_err(|e| e.emit_to_string(&src))?; + let info = naga::valid::Validator::new( + naga::valid::ValidationFlags::all(), + naga::valid::Capabilities::empty(), + ) + .validate(&module) + .map_err(|e| e.emit_to_string(&src))?; + // Les bindings sont ceux du prélude, et eux seuls : chaque backend lie ces quatre-là. Linux + // valide le pipeline contre ce layout, et une erreur de validation wgpu y fait paniquer. + for (handle, var) in module.global_variables.iter() { + let name = var.name.as_deref().unwrap_or("?"); + if var.binding.is_some() && !["fx_frame", "fx_sampler", "ctx", "params"].contains(&name) { + let line = module.global_variables.get_span(handle).location(&src).line_number; + return Err(format!( + "`{name}` at line {line}: an effect declares no binding of its own, it reads frame(), ctx and params" + )); + } + } + let entry = module + .entry_points + .iter() + .find(|e| e.name == "fx_fs") + .ok_or("the module has no fx_fs entry point")?; + let mut costs = CostWalk { module: &module, src: &src, by_function: Default::default() }; + let cost = costs.block(&entry.function, &entry.function.body)?; + if cost.iterations > MAX_ITERATIONS_PER_PIXEL { + return Err(format!( + "the loops run {} iterations per pixel, over the safety ceiling of {MAX_ITERATIONS_PER_PIXEL}: \ + past it a GPU can stall long enough for the system to reset it", + cost.iterations + )); + } + let report = EffectReport { frame_reads: cost.reads, iterations: cost.iterations, tier: Tier::of(cost.reads) }; + Ok(Parsed { module, info, report }) +} + +/// Ce que coûte un bloc, par pixel. +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)] +struct Cost { + reads: u64, + iterations: u64, +} + +impl Cost { + fn add(self, o: Cost) -> Cost { + Cost { reads: self.reads.saturating_add(o.reads), iterations: self.iterations.saturating_add(o.iterations) } + } + fn max(self, o: Cost) -> Cost { + Cost { reads: self.reads.max(o.reads), iterations: self.iterations.max(o.iterations) } + } + fn times(self, n: u64) -> Cost { + Cost { reads: self.reads.saturating_mul(n), iterations: self.iterations.saturating_mul(n) } + } +} + +/// Parcourt l'IR de naga depuis `fx_fs` : les fonctions appelées sont dépliées, une branche +/// compte pour la plus chère, une boucle multiplie son corps par sa borne. +struct CostWalk<'a> { + module: &'a naga::Module, + src: &'a str, + by_function: std::collections::HashMap, Cost>, +} + +impl CostWalk<'_> { + fn block(&mut self, func: &naga::Function, block: &naga::Block) -> Result { + let mut total = Cost::default(); + for (stmt, span) in block.span_iter() { + let c = match stmt { + naga::Statement::Emit(range) => { + let reads = range + .clone() + .filter(|&h| { + matches!( + func.expressions[h], + naga::Expression::ImageSample { .. } | naga::Expression::ImageLoad { .. } + ) + }) + .count() as u64; + Cost { reads, iterations: 0 } + } + naga::Statement::Block(b) => self.block(func, b)?, + naga::Statement::If { accept, reject, .. } => { + self.block(func, accept)?.max(self.block(func, reject)?) + } + naga::Statement::Switch { cases, .. } => { + let mut worst = Cost::default(); + for case in cases { + worst = worst.max(self.block(func, &case.body)?); + } + worst + } + naga::Statement::Loop { body, continuing, break_if } => { + let trips = self.trip_count(func, block, body, continuing, *break_if, *span)?; + let inner = self.block(func, body)?.add(self.block(func, continuing)?); + Cost { reads: inner.reads, iterations: inner.iterations.saturating_add(1) }.times(trips) + } + naga::Statement::Call { function, .. } => self.function(*function)?, + _ => Cost::default(), + }; + total = total.add(c); + } + Ok(total) + } + + fn function(&mut self, h: naga::Handle) -> Result { + if let Some(c) = self.by_function.get(&h) { + return Ok(*c); + } + let module = self.module; + let f = &module.functions[h]; + let c = self.block(f, &f.body)?; + self.by_function.insert(h, c); + Ok(c) + } + + fn refuse(&self, span: naga::Span, why: &str) -> String { + let line = span.location(self.src).line_number; + format!( + "the loop at line {line} {why}. Write it as `for (var i = 0; i < 16; i++)`: a counter \ + initialised with a literal, compared to a literal, stepped by a literal in the loop header" + ) + } + + /// Le nombre de tours d'une boucle `for` à bornes littérales. Toute autre forme est refusée : + /// une boucle qui ne finit pas bloque le GPU jusqu'au TDR. + fn trip_count( + &self, + func: &naga::Function, + parent: &naga::Block, + body: &naga::Block, + continuing: &naga::Block, + break_if: Option>, + span: naga::Span, + ) -> Result { + use naga::{BinaryOperator as B, Expression as E, Statement as S}; + if break_if.is_some() { + return Err(self.refuse(span, "ends on `break if`")); + } + // Le `for` de WGSL devient `loop { if (cond) {} else { break; } … continuing { pas } }`. + let guard = body.iter().find(|s| !matches!(s, S::Emit(_))); + let Some(S::If { condition, accept, reject }) = guard else { + return Err(self.refuse(span, "has no bound in its header")); + }; + if !accept.is_empty() || reject.len() != 1 || !matches!(reject.iter().next(), Some(S::Break)) { + return Err(self.refuse(span, "has no bound in its header")); + } + let E::Binary { op, left, right } = func.expressions[*condition] else { + return Err(self.refuse(span, "is not bounded by a comparison")); + }; + let (var, bound, op) = match (self.counter(func, left), self.literal(func, right)) { + (Some(v), Some(k)) => (v, k, op), + _ => match (self.literal(func, left), self.counter(func, right)) { + // `N > i` se lit `i < N`. + (Some(k), Some(v)) => (v, k, match op { + B::Greater => B::Less, + B::GreaterEqual => B::LessEqual, + B::Less => B::Greater, + B::LessEqual => B::GreaterEqual, + other => other, + }), + _ => return Err(self.refuse(span, "is not bounded by a literal")), + }, + }; + let init = func.local_variables[var] + .init + .and_then(|h| self.literal(func, h)) + .or_else(|| self.store_before(func, parent, var)) + .ok_or_else(|| self.refuse(span, "starts its counter from a value that is not a literal"))?; + let step = self + .step(func, continuing, var) + .ok_or_else(|| self.refuse(span, "does not step its counter by a literal in its header"))?; + if Self::writes(func, body, var) { + return Err(self.refuse(span, "changes its counter inside its body")); + } + let trips = match op { + B::Less if step > 0.0 => ((bound - init) / step).ceil(), + B::LessEqual if step > 0.0 => ((bound - init) / step).floor() + 1.0, + B::Greater if step < 0.0 => ((init - bound) / -step).ceil(), + B::GreaterEqual if step < 0.0 => ((init - bound) / -step).floor() + 1.0, + _ => return Err(self.refuse(span, "never reaches its bound")), + }; + Ok(trips.max(0.0) as u64) + } + + /// `Load(LocalVariable(v))` : le compteur d'une condition. + fn counter(&self, func: &naga::Function, h: naga::Handle) -> Option> { + match func.expressions[h] { + naga::Expression::Load { pointer } => match func.expressions[pointer] { + naga::Expression::LocalVariable(v) => Some(v), + _ => None, + }, + _ => None, + } + } + + /// Un littéral, directement ou par une constante de module. + fn literal(&self, func: &naga::Function, h: naga::Handle) -> Option { + let lit = |e: &naga::Expression| match *e { + naga::Expression::Literal(l) => match l { + naga::Literal::I32(v) => Some(v as f64), + naga::Literal::U32(v) => Some(v as f64), + naga::Literal::F32(v) => Some(v as f64), + naga::Literal::I64(v) => Some(v as f64), + naga::Literal::U64(v) => Some(v as f64), + naga::Literal::F64(v) => Some(v), + naga::Literal::AbstractInt(v) => Some(v as f64), + naga::Literal::AbstractFloat(v) => Some(v), + _ => None, + }, + _ => None, + }; + match &func.expressions[h] { + naga::Expression::Constant(c) => lit(&self.module.global_expressions[self.module.constants[*c].init]), + e => lit(e), + } + } + + /// Le dernier `Store` d'un littéral dans `var` qui précède une boucle dans son bloc. + fn store_before(&self, func: &naga::Function, parent: &naga::Block, var: naga::Handle) -> Option { + let mut found = None; + for s in parent.iter() { + match s { + naga::Statement::Store { pointer, value } + if matches!(func.expressions[*pointer], naga::Expression::LocalVariable(v) if v == var) => + { + found = self.literal(func, *value); + } + naga::Statement::Loop { .. } => {} + _ => {} + } + } + found + } + + /// Le pas du compteur dans `continuing` : `i = i + k` ou `i = i - k`, `k` littéral. + fn step(&self, func: &naga::Function, continuing: &naga::Block, var: naga::Handle) -> Option { + continuing.iter().find_map(|s| match s { + naga::Statement::Store { pointer, value } + if matches!(func.expressions[*pointer], naga::Expression::LocalVariable(v) if v == var) => + { + match func.expressions[*value] { + naga::Expression::Binary { op, left, right } if self.counter(func, left) == Some(var) => { + let k = self.literal(func, right)?; + match op { + naga::BinaryOperator::Add => Some(k), + naga::BinaryOperator::Subtract => Some(-k), + _ => None, + } + } + _ => None, + } + } + _ => None, + }) + } + + /// Le corps écrit-il le compteur (directement, ou en passant son pointeur à une fonction) ? + fn writes(func: &naga::Function, block: &naga::Block, var: naga::Handle) -> bool { + let is_var = |h: naga::Handle| { + matches!(func.expressions[h], naga::Expression::LocalVariable(v) if v == var) + }; + block.iter().any(|s| match s { + naga::Statement::Store { pointer, .. } => is_var(*pointer), + naga::Statement::Call { arguments, .. } => arguments.iter().any(|&a| is_var(a)), + naga::Statement::Block(b) => Self::writes(func, b, var), + naga::Statement::If { accept, reject, .. } => Self::writes(func, accept, var) || Self::writes(func, reject, var), + naga::Statement::Switch { cases, .. } => cases.iter().any(|c| Self::writes(func, &c.body, var)), + naga::Statement::Loop { body, continuing, .. } => { + Self::writes(func, body, var) || Self::writes(func, continuing, var) + } + _ => false, + }) + } +} + +/// HLSL SM 5.0 pour D3D11/FXC. naga 24 est la dernière version dont la sortie HLSL passe FXC : +/// à partir de la 25 elle déclare les samplers dans un tas D3D12 (`register(s0, space0)`), que +/// `ps_5_0` refuse (X3721). Ne pas monter naga sans faire passer ce module. +pub fn to_hlsl(parsed: &Parsed) -> Result { + let options = naga::back::hlsl::Options { + shader_model: naga::back::hlsl::ShaderModel::V5_0, + ..Default::default() + }; + let mut out = String::new(); + naga::back::hlsl::Writer::new(&mut out, &options) + .write(&parsed.module, &parsed.info, None) + .map_err(|e| e.to_string())?; + Ok(out) +} + +/// Clé du cache des shaders compilés : ce qui change le binaire, et rien d'autre. +pub fn source_hash(effect: &SceneShaderEffect) -> u64 { + let mut h = std::collections::hash_map::DefaultHasher::new(); + effect.contract.hash(&mut h); + effect.code.hash(&mut h); + for p in &effect.params { + p.name.hash(&mut h); + p.ty.hash(&mut h); + } + h.finish() +} + +/// Les régions actives au temps source `t`, dans l'ordre où elles s'appliquent : par lane, puis +/// dans l'ordre de la scène. +pub fn active_effects(effects: &[SceneShaderEffect], t: f32) -> Vec<&SceneShaderEffect> { + let t = t as f64; + let mut active: Vec<_> = effects.iter().filter(|e| t >= e.start_sec && t < e.end_sec).collect(); + active.sort_by_key(|e| e.lane); + active +} + +/// La boîte englobante (x, y, w, h) d'un quad, en uv de sortie : `ctx.footage` sous un tilt 3D. +pub fn bounds(corners: &[[f32; 2]; 4]) -> [f32; 4] { + let (mut x0, mut y0, mut x1, mut y1) = (f32::MAX, f32::MAX, f32::MIN, f32::MIN); + for [x, y] in corners { + (x0, y0, x1, y1) = (x0.min(*x), y0.min(*y), x1.max(*x), y1.max(*y)); + } + [x0, y0, x1 - x0, y1 - y0] +} + +/// `ctx.region` : progression sur la pilule entière en temps programme quand l'app la donne, sur +/// le fragment en temps source sinon. +fn region(effect: &SceneShaderEffect, source_t: f32, programme_t: f32) -> [f32; 4] { + let (start, end, now) = match (effect.programme_start_sec, effect.programme_end_sec) { + (Some(s), Some(e)) => (s, e, programme_t as f64), + _ => (effect.start_sec, effect.end_sec, source_t as f64), + }; + let span = (end - start).max(1e-6); + let since = (now - start).max(0.0); + [(since / span).clamp(0.0, 1.0) as f32, span as f32, since as f32, 0.0] +} + +pub fn context( + effect: &SceneShaderEffect, + source_t: f32, + programme_t: f32, + resolution: [f32; 2], + inputs: &FxFrameInputs, +) -> FxContext { + let mut clicks = [[0.0; 4]; MAX_CLICKS]; + for (slot, ([x, y], age)) in clicks.iter_mut().zip(&inputs.clicks) { + *slot = [*x, *y, *age, 1.0]; + } + FxContext { + resolution, + time: programme_t, + aspect: resolution[0] / resolution[1].max(1.0), + region: region(effect, source_t, programme_t), + cursor: inputs.cursor.map_or([0.0; 4], |[x, y]| [x, y, 1.0, 0.0]), + clicks, + footage: inputs.footage, + camera: inputs.camera.unwrap_or([0.0; 4]), + } +} + +/// Les paramètres de la région, rangés comme la struct `FxParams` générée (règles d'alignement de +/// WGSL), en mots de 4 octets. Une valeur absente vaut 0 : l'app envoie déjà les défauts. +pub fn pack_params(effect: &SceneShaderEffect) -> Vec { + let mut words: Vec = Vec::new(); + let mut offset = 0usize; + for p in &effect.params { + let (size, align) = p.ty.size_align(); + offset = offset.div_ceil(align) * align; + let end = offset + size; + words.resize(end / 4, 0.0); + let value: Vec = match effect.values.get(&p.name) { + Some(ShaderParamValue::Scalar(v)) => vec![*v], + Some(ShaderParamValue::Vector(v)) => v.clone(), + None => Vec::new(), + }; + for (i, v) in value.into_iter().take(size / 4).enumerate() { + words[offset / 4 + i] = v; + } + offset = end; + } + words.resize(offset.div_ceil(16).max(1) * 4, 0.0); + words +} + +/// Le bytecode DXBC des deux étages, prêt pour `CreateVertexShader` / `CreatePixelShader`. +#[cfg(windows)] +pub struct CompiledFx { + pub vs: Vec, + pub ps: Vec, +} + +#[cfg(windows)] +pub fn compile_dxbc(code: &str, params: &[ShaderParamDecl]) -> Result { + let parsed = analyze(code, params)?; + let hlsl = to_hlsl(&parsed)?; + Ok(CompiledFx { + vs: d3d_compile(&hlsl, "fx_vs", "vs_5_0")?, + ps: d3d_compile(&hlsl, "fx_fs", "ps_5_0")?, + }) +} + +#[cfg(windows)] +fn d3d_compile(hlsl: &str, entry: &str, profile: &str) -> Result, String> { + use windows::core::PCSTR; + use windows::Win32::Graphics::Direct3D::Fxc::{D3DCompile, D3DCOMPILE_OPTIMIZATION_LEVEL3}; + use windows::Win32::Graphics::Direct3D::ID3DBlob; + + fn bytes(blob: &ID3DBlob) -> Vec { + unsafe { + std::slice::from_raw_parts(blob.GetBufferPointer() as *const u8, blob.GetBufferSize()) + .to_vec() + } + } + let (entry_z, profile_z) = (format!("{entry}\0"), format!("{profile}\0")); + let (mut code, mut errors): (Option, Option) = (None, None); + let compiled = unsafe { + D3DCompile( + hlsl.as_ptr().cast(), + hlsl.len(), + PCSTR(b"effect.hlsl\0".as_ptr()), + None, + None, + PCSTR(entry_z.as_ptr()), + PCSTR(profile_z.as_ptr()), + D3DCOMPILE_OPTIMIZATION_LEVEL3, + 0, + &mut code, + Some(&mut errors), + ) + }; + match (compiled, code) { + (Ok(()), Some(code)) => Ok(bytes(&code)), + (result, _) => { + let log = errors.as_ref().map(bytes).unwrap_or_default(); + Err(format!("{entry}: {result:?}\n{}", String::from_utf8_lossy(&log))) + } + } +} + +/// Compile sur un thread à part ; le résultat arrive par le canal. naga + FXC prennent ~10 ms +/// pour un effet de 60 lignes, soit une frame de preview : jamais sur le thread de rendu. +#[cfg(windows)] +pub fn spawn_compile(effect: &SceneShaderEffect) -> std::sync::mpsc::Receiver> { + let (tx, rx) = std::sync::mpsc::channel(); + let (code, params) = (effect.code.clone(), effect.params.clone()); + std::thread::Builder::new() + .name("shader-fx".into()) + .spawn(move || { + let _ = tx.send(compile_dxbc(&code, ¶ms)); + }) + .expect("thread shader-fx"); + rx +} + +/// Le SPIR-V que wgpu tirera du même module pour Vulkan. Le compositeur Linux passe le WGSL à +/// wgpu, qui refait cette traduction lui-même : celle-ci ne sert qu'à la vérifier d'avance. +#[cfg(target_os = "linux")] +fn to_spirv(parsed: &Parsed) -> Result, String> { + naga::back::spv::write_vec(&parsed.module, &parsed.info, &naga::back::spv::Options::default(), None) + .map_err(|e| e.to_string()) +} + +/// Ce que l'outil de l'agent demande avant d'accepter un code : la validation, la compilation +/// réelle pour le backend de la machine quand elle existe, et le palier. +pub fn check_for_agent(code: &str, params: &[ShaderParamDecl]) -> Result { + let parsed = analyze(code, params)?; + #[cfg(windows)] + compile_dxbc(code, params)?; + #[cfg(target_os = "linux")] + to_spirv(&parsed)?; + Ok(parsed.report) +} + +/// `check_for_agent`, les paramètres reçus en JSON (`[{ "name", "type" }, …]`) depuis l'addon. +pub fn check_for_agent_json(code: &str, params_json: &str) -> Result { + let params: Vec = + serde_json::from_str(params_json).map_err(|e| format!("params: {e}"))?; + check_for_agent(code, ¶ms) +} + +/// Un effet tel que les tests et les bancs le construisent. +#[cfg(test)] +pub(crate) fn test_effect(code: &str, params: Vec, values: &[(&str, ShaderParamValue)]) -> SceneShaderEffect { + SceneShaderEffect { + clip_index: Some(0), + start_sec: 1.0, + end_sec: 3.0, + programme_start_sec: None, + programme_end_sec: None, + target: ShaderEffectTarget::Image, + lane: 0, + contract: CONTRACT, + code: code.into(), + params, + values: values.iter().map(|(k, v)| (k.to_string(), v.clone())).collect(), + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn decl(name: &str, ty: ShaderParamType) -> ShaderParamDecl { + ShaderParamDecl { name: name.into(), ty } + } + + const VIGNETTE: &str = "fn effect(uv: vec2) -> vec4 {\n let c = frame(uv);\n let d = distance(uv, vec2(0.5));\n return vec4(c.rgb * (1.0 - d * params.strength * ctx.region.x), c.a);\n}\n"; + + #[test] + fn a_valid_effect_becomes_hlsl_that_d3d11_accepts() { + let parsed = analyze(VIGNETTE, &[decl("strength", ShaderParamType::Number)]).expect("analyze"); + let hlsl = to_hlsl(&parsed).expect("translate"); + assert!(hlsl.contains("fx_vs") && hlsl.contains("fx_fs")); + // Les registres que les backends lient : t0, s1, b2 (ctx), b3 (params), sans `space`. + for reg in ["register(t0)", "register(s1)", "register(b2)", "register(b3)"] { + assert!(hlsl.contains(reg), "{reg} missing:\n{hlsl}"); + } + assert!(!hlsl.contains("space"), "FXC ps_5_0 refuse les espaces de registres"); + } + + #[test] + fn an_error_points_at_the_line_the_agent_wrote() { + let broken = "fn effect(uv: vec2) -> vec4 {\n return frame(uv) * nope;\n}\n"; + let err = analyze(broken, &[]).err().expect("must fail"); + assert!(err.contains("nope") && err.contains(":2:"), "{err}"); + } + + #[test] + fn an_effect_without_the_entry_function_is_refused() { + assert!(analyze("fn other() {}", &[]).is_err()); + } + + #[test] + fn an_effect_declares_no_binding_of_its_own() { + let code = "@group(0) @binding(4) var extra: texture_2d;\n\ + fn effect(uv: vec2) -> vec4 { return textureLoad(extra, vec2(0), 0); }\n"; + let err = analyze(code, &[]).err().expect("refusé"); + assert!(err.contains("`extra` at line 1"), "{err}"); + } + + #[cfg(target_os = "linux")] + #[test] + fn a_valid_effect_becomes_spirv() { + let parsed = analyze(VIGNETTE, &[decl("strength", ShaderParamType::Number)]).expect("analyze"); + assert!(!to_spirv(&parsed).expect("spirv").is_empty()); + } + + #[test] + fn parameter_names_are_checked() { + for bad in ["Strength", "2x", "unused", "a-b"] { + assert!(analyze(VIGNETTE, &[decl(bad, ShaderParamType::Number)]).is_err(), "{bad}"); + } + let twice = [decl("a", ShaderParamType::Number), decl("a", ShaderParamType::Color)]; + assert!(analyze(VIGNETTE, &twice).is_err()); + } + + /// Le packer et la struct générée doivent placer chaque paramètre au même octet : un écart lirait + /// une couleur là où l'app a écrit une force. + #[test] + fn the_packer_matches_the_offsets_naga_gives_the_generated_struct() { + let params = vec![ + decl("a", ShaderParamType::Number), + decl("tint", ShaderParamType::Color), + decl("on", ShaderParamType::Toggle), + decl("at", ShaderParamType::Point), + decl("b", ShaderParamType::Number), + ]; + let code = "fn effect(uv: vec2) -> vec4 { return frame(uv) * params.a + params.tint * params.on + vec4(params.at, params.b, 0.0); }"; + let parsed = analyze(code, ¶ms).expect("analyze"); + let ty = parsed + .module + .types + .iter() + .find(|(_, t)| t.name.as_deref() == Some("FxParams")) + .expect("FxParams") + .1; + let naga::TypeInner::Struct { members, span } = &ty.inner else { panic!("struct") }; + let values = [ + ("a", ShaderParamValue::Scalar(1.0)), + ("tint", ShaderParamValue::Vector(vec![2.0, 3.0, 4.0, 5.0])), + ("on", ShaderParamValue::Scalar(6.0)), + ("at", ShaderParamValue::Vector(vec![7.0, 8.0])), + ("b", ShaderParamValue::Scalar(9.0)), + ]; + let words = pack_params(&test_effect(code, params, &values)); + assert_eq!(words.len() * 4, (*span as usize).div_ceil(16) * 16); + let first = |name: &str| members.iter().find(|m| m.name.as_deref() == Some(name)).unwrap().offset as usize / 4; + assert_eq!(words[first("a")], 1.0); + assert_eq!(&words[first("tint")..first("tint") + 4], &[2.0, 3.0, 4.0, 5.0]); + assert_eq!(words[first("on")], 6.0); + assert_eq!(&words[first("at")..first("at") + 2], &[7.0, 8.0]); + assert_eq!(words[first("b")], 9.0); + } + + #[test] + fn the_context_matches_its_wgsl_struct() { + let parsed = analyze(VIGNETTE, &[decl("strength", ShaderParamType::Number)]).unwrap(); + let ty = parsed.module.types.iter().find(|(_, t)| t.name.as_deref() == Some("FxContext")).unwrap().1; + let naga::TypeInner::Struct { members, span } = &ty.inner else { panic!("struct") }; + assert_eq!(std::mem::size_of::(), *span as usize); + let offset = |name: &str| members.iter().find(|m| m.name.as_deref() == Some(name)).unwrap().offset as usize; + let c = FxContext::default(); + let base = &c as *const FxContext as usize; + assert_eq!(offset("region"), &c.region as *const _ as usize - base); + assert_eq!(offset("clicks"), &c.clicks as *const _ as usize - base); + assert_eq!(offset("camera"), &c.camera as *const _ as usize - base); + } + + #[test] + fn a_for_loop_with_literal_bounds_is_counted() { + let code = "fn effect(uv: vec2) -> vec4 {\n var acc = vec4(0.0);\n for (var i = 0; i < 16; i++) {\n acc += frame(uv + vec2(f32(i) * 0.001, 0.0));\n }\n return acc / 16.0;\n}\n"; + let r = analyze(code, &[]).expect("analyze").report; + assert_eq!((r.frame_reads, r.iterations, r.tier), (16, 16, Tier::Medium)); + } + + #[test] + fn nested_loops_multiply_and_called_functions_are_unfolded() { + let code = "fn tap(uv: vec2) -> vec4 { return frame(uv) + frame(uv * 0.5); }\nfn effect(uv: vec2) -> vec4 {\n var acc = vec4(0.0);\n for (var y = 0u; y <= 7u; y += 1u) {\n for (var x = 8; x > 0; x--) {\n acc += tap(uv);\n }\n }\n return acc;\n}\n"; + let r = analyze(code, &[]).expect("analyze").report; + assert_eq!(r.frame_reads, 8 * 8 * 2); + assert_eq!(r.iterations, 8 * (8 + 1)); + assert_eq!(r.tier, Tier::Heavy); + } + + #[test] + fn a_branch_counts_for_the_dearer_side() { + let code = "fn effect(uv: vec2) -> vec4 {\n if (uv.x > 0.5) { return frame(uv) + frame(uv) + frame(uv); }\n return frame(uv);\n}\n"; + assert_eq!(analyze(code, &[]).unwrap().report.frame_reads, 4, "branche chère + suite"); + } + + #[test] + fn loops_without_a_literal_bound_are_refused_with_their_line() { + let refused = [ + ("fn effect(uv: vec2) -> vec4 {\n var i = 0;\n loop {\n i++;\n if (i > 4) { break; }\n }\n return frame(uv);\n}\n", 3), + ("fn effect(uv: vec2) -> vec4 {\n var i = 0;\n while (i < 4) {\n i++;\n }\n return frame(uv);\n}\n", 3), + ("fn effect(uv: vec2) -> vec4 {\n let n = i32(uv.x * 100.0);\n for (var i = 0; i < n; i++) {}\n return frame(uv);\n}\n", 3), + ("fn effect(uv: vec2) -> vec4 {\n for (var i = 0; i < 4; i++) { i = 0; }\n return frame(uv);\n}\n", 2), + ("fn effect(uv: vec2) -> vec4 {\n for (var i = 0; i < 4; i--) {}\n return frame(uv);\n}\n", 2), + ]; + for (code, line) in refused { + let err = analyze(code, &[]).err().unwrap_or_else(|| panic!("accepted: {code}")); + assert!(err.contains(&format!("line {line}")) && err.contains("for (var i = 0"), "{err}"); + } + } + + #[test] + fn a_module_constant_is_a_literal_bound() { + let code = "const TAPS = 12;\nfn effect(uv: vec2) -> vec4 {\n var acc = vec4(0.0);\n for (var i = 0; i < TAPS; i += 3) { acc += frame(uv); }\n return acc;\n}\n"; + assert_eq!(analyze(code, &[]).expect("analyze").report.iterations, 4); + } + + #[test] + fn the_safety_ceiling_refuses_runaway_work() { + let code = "fn effect(uv: vec2) -> vec4 {\n var a = 0.0;\n for (var i = 0; i < 100; i++) { for (var j = 0; j < 100; j++) { a += 1.0; } }\n return frame(uv) * a;\n}\n"; + let err = analyze(code, &[]).err().expect("must fail"); + assert!(err.contains("10100") && err.contains("4096"), "{err}"); + } + + #[test] + fn the_ripple_of_the_spec_is_light() { + let code = include_str!("../../../docs/shader-effects.md") + .split("```wgsl\n") + .nth(2) + .and_then(|s| s.split("```").next()) + .expect("l'exemple C.6"); + let params = vec![ + decl("strength", ShaderParamType::Number), + decl("radius", ShaderParamType::Number), + decl("duration", ShaderParamType::Number), + ]; + let r = analyze(code, ¶ms).expect("l'exemple de la spec compile").report; + assert_eq!((r.frame_reads, r.tier), (1, Tier::Light)); + } + + /// The examples agents read in the MCP resource (`electron/mcp/effects-contract.ts`) compile + /// against this prelude, at the tier the resource promises. + #[test] + fn the_examples_of_the_mcp_contract_compile() { + let src = include_str!("../../../electron/mcp/effects-contract.ts"); + let examples: Vec = src + .split("## Example") + .skip(1) + .map(|section| { + section + .lines() + .filter_map(|l| l.strip_prefix(" ")) + .collect::>() + .join("\n") + }) + .collect(); + assert_eq!(examples.len(), 2, "le ripple et la vignette"); + let ripple = [ + decl("strength", ShaderParamType::Number), + decl("radius", ShaderParamType::Number), + decl("duration", ShaderParamType::Number), + ]; + let vignette = [decl("depth", ShaderParamType::Number), decl("tint", ShaderParamType::Color)]; + assert_eq!(analyze(&examples[0], &ripple).expect("ripple").report.tier, Tier::Light); + assert_eq!(analyze(&examples[1], &vignette).expect("vignette").report.tier, Tier::Light); + } + + #[test] + fn the_active_regions_and_their_progress() { + let mut a = test_effect(VIGNETTE, vec![], &[]); + a.lane = 1; + let b = test_effect(VIGNETTE, vec![], &[]); + let effects = [a, b]; + assert!(active_effects(&effects, 0.5).is_empty()); + let active = active_effects(&effects, 2.0); + assert_eq!(active.iter().map(|e| e.lane).collect::>(), [0, 1], "par lane"); + assert!(active_effects(&effects, 3.0).is_empty(), "fin exclusive"); + + let ctx = context(&effects[1], 2.0, 10.0, [1920.0, 1080.0], &FxFrameInputs::default()); + assert_eq!(ctx.region, [0.5, 2.0, 1.0, 0.0], "fragment, temps source"); + let mut whole = effects[1].clone(); + (whole.programme_start_sec, whole.programme_end_sec) = (Some(8.0), Some(12.0)); + let ctx = context(&whole, 2.0, 10.0, [1920.0, 1080.0], &FxFrameInputs::default()); + assert_eq!(ctx.region, [0.5, 4.0, 2.0, 0.0], "pilule entière, temps programme"); + assert_eq!((ctx.cursor[2], ctx.clicks[0][3], ctx.camera), (0.0, 0.0, [0.0; 4])); + + let inputs = FxFrameInputs { + cursor: Some([0.25, 0.5]), + clicks: vec![([0.3, 0.6], 0.2), ([0.1, 0.1], 1.5)], + footage: [0.1, 0.1, 0.8, 0.8], + camera: Some([0.7, 0.7, 0.2, 0.2]), + }; + let ctx = context(&whole, 2.0, 10.0, [1920.0, 1080.0], &inputs); + assert_eq!(ctx.cursor, [0.25, 0.5, 1.0, 0.0]); + assert_eq!(ctx.clicks[..3], [[0.3, 0.6, 0.2, 1.0], [0.1, 0.1, 1.5, 1.0], [0.0; 4]]); + assert_eq!((ctx.footage, ctx.camera), ([0.1, 0.1, 0.8, 0.8], [0.7, 0.7, 0.2, 0.2])); + } + + #[test] + fn the_cache_key_follows_code_and_layout_not_values() { + let p = vec![decl("strength", ShaderParamType::Number)]; + let a = test_effect(VIGNETTE, p.clone(), &[("strength", ShaderParamValue::Scalar(1.0))]); + let mut b = test_effect(VIGNETTE, p, &[("strength", ShaderParamValue::Scalar(2.0))]); + assert_eq!(source_hash(&a), source_hash(&b), "une valeur ne recompile rien"); + b.params[0].ty = ShaderParamType::Color; + assert_ne!(source_hash(&a), source_hash(&b), "un layout différent est un autre binaire"); + } + + #[cfg(windows)] + #[test] + fn fxc_compiles_both_stages() { + let c = compile_dxbc(VIGNETTE, &[decl("strength", ShaderParamType::Number)]).expect("compile"); + assert!(!c.vs.is_empty() && !c.ps.is_empty()); + } +} diff --git a/docs/shader-effects.md b/docs/shader-effects.md new file mode 100644 index 0000000000..b4d1a6ed2d --- /dev/null +++ b/docs/shader-effects.md @@ -0,0 +1,804 @@ +# Effets shader écrits par les agents + +Un agent écrit un effet visuel en WGSL. Le compositeur l'applique en une passe sur l'image +composée, en preview comme à l'export. L'effet vit dans le document comme une région de la +timeline : on peut le relire, le régler, le déplacer et le supprimer, que l'on soit l'utilisateur +ou un agent. + +Ce document fixe le modèle, le contrat, le DSL, le rendu et l'interface, puis découpe les PR. +Il part du spike Windows (branche `worktree-custom-shader-fx-spike`, commits `9cb30018d` et +`42728e335`). + +**Ce que le spike a établi** + +- **Coût.** +0,04 ms par frame en 1080p, +0,12 ms en 4K, pour un effet lourd. +- **Export.** 520 ms sans effet, 523 ms avec, pour 180 frames. +- **Preview.** Le rendu tient la cadence de la source, avec ou sans effet. +- **SSOT.** Entre la vue live et le MP4, l'écart reste au niveau du bruit du codec. +- **Boucle d'agent.** À partir du prompt « effet ripple lors du clic », un agent a écrit un + effet correct en deux itérations, par les seuls outils MCP. + +--- + +## A. Les principes + +1. **Le compositeur reste la seule source de pixels.** Un effet est une passe de + `compose_frame`, que la preview et l'export appellent tous les deux. Il n'existe pas de + chemin de rendu propre aux effets. +2. **Le document ne stocke que la source.** Le WGSL, son nom, sa description, ses paramètres et + les valeurs posées. Tout binaire compilé en est dérivé, et n'est jamais écrit dans le projet. +3. **Un effet est une fonction pure** de l'image composée, du temps, du curseur et de ses + paramètres. Pas d'état d'une frame à l'autre. +4. **Le rendu ne compile jamais.** Le code est compilé à l'écriture, puis à la pose de la scène, + sur un thread de fond. +5. **Ce que seul le compositeur sait entre dans le contrat.** La place de l'écran, de la webcam + et du curseur dans la sortie, après zoom, layout et tilt : un effet ne peut pas la recalculer. + Le prompt du ripple l'a montré, il ne pouvait pas s'écrire sans. +6. **L'agent passe par le DSL.** Il appelle des outils de document. Il n'écrit jamais le JSON du + projet. +7. **Pour tout le monde.** Aucun réglage, aucune condition ne réserve la fonctionnalité à + certains utilisateurs. + +--- + +## B. Le modèle de données + +### B.1 Deux objets : la définition et la région + +- **La définition** (`shaderEffects`) porte le code, son nom, sa description et ses paramètres + déclarés. Elle dit ce qu'est l'effet. +- **La région** (`shaderEffectRanges`) pose une définition sur la timeline, avec ses valeurs de + paramètres. Elle dit où l'effet s'applique et comment il est réglé. + +La séparation sert trois choses : +- réutiliser un effet à plusieurs endroits sans dupliquer son code ; +- régler une région (`values`) sans réécrire de code ; +- garder léger le snapshot de l'agent, où le code n'apparaît qu'une fois par définition. + +### B.2 Le schéma + +Deux tableaux de premier rang dans `documentSchemaShape` +(`src/lib/ai-edition/schema/index.ts`), à côté de `zoomRanges` : + +```ts +const paramName = z.string().regex(/^[a-z][a-z0-9_]{0,31}$/); + +const shaderEffectParamSchema = z.discriminatedUnion("type", [ + z.object({ type: z.literal("number"), name: paramName, label: z.string().max(40), + default: z.number(), min: z.number(), max: z.number() }), + z.object({ type: z.literal("toggle"), name: paramName, label: z.string().max(40), + default: z.boolean() }), + z.object({ type: z.literal("color"), name: paramName, label: z.string().max(40), + default: hexColor }), + z.object({ type: z.literal("point"), name: paramName, label: z.string().max(40), + default: z.object({ x: z.number().min(0).max(1), y: z.number().min(0).max(1) }) }), +]); + +export const shaderEffectSchema = z.object({ + id: z.string().min(1), // "fx_…" + name: z.string().min(1).max(60), // ce que la pilule affiche + description: z.string().max(500).default(""), // pour l'agent suivant : ce que l'effet fait + contract: z.number().int().positive(), // pas un littéral : voir C.5 + code: z.string().min(1).max(65_536), // plafond technique, pas un budget (C.7) + params: z.array(shaderEffectParamSchema).max(32).default([]), + origin: z.enum(["agent", "user"]).default("agent"), + cost: z.object({ tier, frameReads }).optional(), // estimation du compositeur, en cache +}).superRefine(/* noms uniques, min ≤ default ≤ max */); + +export const shaderEffectRangeSchema = endGteStart(z.object({ + id: z.string().min(1), // "fxr_…", un par fragment + startMs: z.number().nonnegative(), // cache dérivé de l'ancre, comme les zooms + endMs: z.number().nonnegative(), + ...clipAnchorShape, + effectId: z.string().min(1), + values: z.record(z.string(), shaderEffectValueSchema).default({}), + target: z.enum(["image", "text", "both"]).default("image"), + lane: z.number().int().min(0).max(7).default(0), +}), "endMs", "startMs"); + +// documentSchemaShape +shaderEffects: z.array(shaderEffectSchema).optional(), +shaderEffectRanges: z.array(shaderEffectRangeSchema).optional(), +``` + +- **`values`** ne porte que ce qui diffère du `default` de la définition. Une valeur hors bornes + est ramenée dans ses bornes à l'écriture (les outils) et à la lecture (la scène), sans erreur. + Le parse ne le peut pas : les bornes sont dans la définition, pas dans la région. +- **Les `label`** sont écrits par l'agent, dans la langue de l'utilisateur, et affichés tels + quels. Ils ne passent pas par l'i18n : c'est du contenu, pas de l'interface. +- **Une pilule, ce sont les fragments identiques et contigus** (`regionIdentityKey`), comme pour + les zooms. Il n'y a pas de clé de groupe : une région coupée par un trim ou une frontière de + clip reste une seule pilule, et sa progression (`ctx.region`) court sur la pilule entière (B.5). +- **`cost`** est l'estimation du compositeur (C.7), mise en cache quand le code a été vérifié. Elle + est dérivée, jamais une entrée : un code modifié la recalcule. +- **Une définition que plus aucune région n'utilise est retirée** par l'édition qui a retiré sa + dernière région (`removeRegion`, `mapAllRegionCollections`). Le document ne garde pas de code + mort. +- **Les `max` du schéma sont des plafonds techniques, pas des budgets.** Ils protègent le document + (64 Ko de code, 32 paramètres, 8 lanes) et sont loin au-dessus de tout effet raisonnable. Ce que + l'agent doit viser, ce sont les paliers de C.7. + +### B.3 Ancrée sur le clip, comme les autres régions + +Une région d'effet est une région de plus, pas un cas à part. Elle passe par tout le pipeline des +modificateurs ([timeline-model.md](../technical-documentation/architecture/timeline-model.md)), +et suit donc les clips quand on les déplace, les coupe ou les supprime. Le spike la stockait en +ms brutes, sans ancre : elle restait en place pendant que les clips bougeaient. + +- **`RegionKind`** gagne `"shaderEffect"`. Les sites qui switchent dessus sont listés dans + [editor-shell.md, « Adding a region kind »](../technical-documentation/architecture/editor-shell.md) + (ses numéros de ligne sont périmés). Les principaux : + - **le crochet des éditions de clips :** `mapAllRegionCollections` (`document/timeline.ts`), + par lequel passent moveClip, duplicateClip, setClipSourceRange, removeClip, replaceTimeline + et l'insertion ; + - **les listes codées en dur :** `anchoredRegionsOf`, et `removeRegion`/`EDIT_REGIONS`, dont + les types rendent un oubli bloquant à la compilation ; + - **côté agent :** `ModifierKind`, `modifierIds`, `modifierIdsOf` et la recherche d'id de + `removeModifier` (`agent-tools.ts`) ; + - **côté éditeur :** `removeRegions` (`useTimeline.ts`), `regionClipboard.ts`, le + copier-coller et la touche Suppr de `NewEditorShell.tsx`. +- **L'identité des pilules** (`regionIdentityKey`) compte tous les champs sauf la position et la + provenance. Deux régions contiguës du même effet, aux mêmes `values`, se fondent donc en une + pilule, comme deux zooms identiques. +- **Les pistes.** Deux régions d'une même `lane` ne se chevauchent pas, avec la règle des autres + régions (`refuseIfBlocked`). Les lanes s'appliquent dans l'ordre : la lane 0 d'abord, au plus + près du contenu. C'est ce qui permet un ripple sur toute la vidéo ET un glitch + sur une coupe. +- **Après une édition de clip** qui fait se chevaucher deux régions d'une même lane, le rendu + applique les deux, dans l'ordre du tableau, et la piste les montre superposées. Pas de + réparation automatique : contrairement à l'audio, deux effets superposés ne cassent rien. + +### B.4 Persistance + +- **Champs additifs et optionnels, sans montée de `schemaVersion`.** C'est la convention de + `vocabulary` : `.optional()`, et `z.object` qui ignore les clés inconnues. Un document écrit + avant cette fonctionnalité s'ouvre tel quel, un document sans effet n'en porte aucune trace, et + tout lecteur prend une liste absente pour vide. +- **Le prix de ce choix.** Une build antérieure qui ouvre puis sauvegarde un projet perd ses + effets en silence. Voir K, question 1. +- **Pas dans les style presets.** Un preset porte le look du projet, jamais son contenu + (`stylePresets.ts`), et un effet est posé sur des moments précis du contenu. +- **`openscreen info`** compte les effets avec les zooms et les trims (`documentInfoFields`, + `projectCommands.ts`). + +### B.5 Ce que la scène native reçoit + +`buildSceneDescription` projette les régions comme les zooms (`projectRegionsToSource`). Il +ajoute à chaque fragment ce que le compositeur ne peut pas recalculer : + +```json +"shaderEffects": [{ + "clipIndex": 0, "startSec": 1.0, "endSec": 5.0, + "programmeStartSec": 1.0, "programmeEndSec": 5.0, + "target": "image", "lane": 0, + "contract": 1, "code": "fn effect(uv: vec2) -> vec4 { … }", + "params": [ { "name": "strength", "type": "number" } ], + "values": { "strength": 1.0 } +}] +``` + +- **`programmeStart/EndSec`** est l'étendue de la pilule entière en temps programme. Le + compositeur en tire `ctx.region` sans rien savoir des trims. +- **`values` est déjà normalisé :** une couleur devient 4 floats, un toggle 0 ou 1, un point + 2 floats, et une valeur absente prend son `default`. +- **Le packing dans l'uniform** se fait côté Rust, au même endroit que la struct WGSL générée. + Le layout n'a qu'une source. +- **Les fragments sous un trim** (`underTrim`) restent dans la scène, comme pour les autres + régions. Ils se dessinent quand la tête de lecture est posée sur le trim, et l'export ne les + rencontre jamais. + +--- + +## C. Le contrat WGSL (version 1) + +### C.1 Ce que l'agent écrit + +Une seule fonction, appelée pour chaque pixel de la sortie : + +```wgsl +fn effect(uv: vec2) -> vec4 +``` + +`uv` va de (0, 0) en haut à gauche à (1, 1) en bas à droite de la sortie. La fonction rend la +couleur finale du pixel. Le reste du module (bindings, entrées, `@vertex`, `@fragment`) est écrit +par le compositeur et placé APRÈS le code de l'agent : en WGSL, l'ordre des déclarations est +libre, et les erreurs pointent ainsi les lignes que l'agent a écrites. + +### C.2 Ce qui est fourni + +| Nom | Type | Sens | +|---|---|---| +| `frame(uv)` | `vec4` | L'image composée en ce point (D.1 dit ce qu'elle contient). Échantillonnage bilinéaire, bords répétés. | +| `ctx.resolution` | `vec2` | Taille de la sortie, en px. | +| `ctx.aspect` | `f32` | Largeur sur hauteur de la sortie, pour les distances circulaires en uv. | +| `ctx.time` | `f32` | Secondes de programme, continues à travers coupes, clips et vitesses. | +| `ctx.region` | `vec4` | x : progression de 0 à 1 sur la pilule entière. y : sa durée en s. z : secondes depuis son début. | +| `ctx.cursor` | `vec4` | xy : la pointe en uv de sortie. z : 1 si elle est à l'écran. | +| `ctx.clicks[i]` | `vec4` | Les 4 derniers clics des 2 dernières secondes, du plus récent au plus ancien. xy : le point du clic en uv de sortie. z : secondes écoulées depuis. w : 1 si l'entrée est occupée. | +| `ctx.footage` | `vec4` | Le rect de l'enregistrement en uv de sortie (x, y, w, h), après zoom et layout. Sous un tilt 3D, c'est sa boîte englobante. | +| `ctx.camera` | `vec4` | Le rect de la webcam en uv de sortie. Taille nulle sans caméra. | +| `params.` | selon le type | Les paramètres déclarés par l'effet (C.3). | +| `fx_px(n)` | `f32` | `n` pixels d'une sortie 1080p, en fraction de la hauteur. | +| `fx_hash(p)` | `f32` | Hasard déterministe dans [0, 1) pour un `vec2`, identique sur tous les GPU (PCG). | + +- **Tout ce qui est en uv de sortie** est déjà passé par le zoom, le layout, le cadre et le + tilt. Ces valeurs viennent de `plan_frame` et `plan_cursor` (`frame_geometry.rs`), que les + trois backends partagent. +- **Le point d'un clic** est la pointe à l'instant du clic, au même endroit que l'impact intégré + (mode 16). +- **Le curseur dessiné** passe par le lissage et peut traîner un instant derrière ce point quand + la souris arrive pile au moment du clic. Ce cas est rare sur une vraie prise. +- **Le spike exposait un seul clic** (`ctx.click`). Avec quatre, deux clics rapprochés gardent + chacun leur onde. +- **Rien d'autre n'est lié.** Une variable `@group`/`@binding` dans le code de l'agent est + refusée, avec sa ligne : aucun backend ne la lierait. + +### C.3 Les paramètres sont nommés et typés + +Un effet déclare ses paramètres. Le compositeur en génère une struct `FxParams` liée en uniform, +et le code lit `params.radius`, jamais `param(2)`. Un agent qui relit l'effet six mois plus tard +comprend ce qu'il lit, et l'inspecteur sait quel contrôle afficher. + +| `type` | WGSL | Dans le document | Contrôle de l'inspecteur | +|---|---|---|---| +| `number` | `f32` | nombre, entre `min` et `max` | curseur | +| `toggle` | `f32` (0 ou 1) | booléen | interrupteur | +| `color` | `vec4` (RGBA, 0 à 1) | `#rrggbb` ou `#rrggbbaa` | sélecteur de couleur | +| `point` | `vec2` (uv de sortie) | `{ x, y }` | deux curseurs | + +- **Huit paramètres au plus, recommandé.** Au-delà, l'inspecteur devient une liste que personne + ne règle. Ce n'est pas un refus : le plafond technique est à 32. +- **Les noms** sont des identifiants WGSL en `snake_case`, uniques, hors mots réservés. +- **Le layout uniform est calculé côté Rust** avec les règles d'alignement de WGSL : `f32` sur 4, + `vec2` sur 8, `vec4` sur 16. Il produit le même ordre et les mêmes trous que la struct générée, + et un test compare les offsets de naga à ceux du packer. +- **Un paramètre doit se voir.** La description de l'outil exige qu'il change visiblement + l'effet sur toute sa plage. Un contrôle qui ne fait rien à l'écran est exactement ce que + l'inspecteur doit éviter. + +### C.4 Les règles + +- **Pure.** Le résultat ne dépend que de `uv`, de `frame()`, de `ctx` et de `params`. Pas d'état + d'une frame à l'autre, pas d'horloge, pas de compteur de frames. La preview saute d'une frame à + l'autre au seek, l'export les rend dans l'ordre, et les deux doivent donner le même pixel. +- **Indépendante de la résolution.** La preview rend plus petit que l'export. Distances en uv ou + en `fx_px`, jamais en px bruts. +- **Hasard par `fx_hash`.** Le classique `fract(sin(x) * 43758.5453)` donne des valeurs + différentes d'un GPU à l'autre. +- **Boucles à borne littérale.** Toute boucle s'arrête sur un compteur comparé à un littéral + (`for (var i = 0; i < 16; i++)`). Une boucle dont la borne n'est pas un littéral est refusée. + C'est la seule règle ferme du contrat, et ce n'est pas un budget : une boucle qui ne finit pas + bloque le GPU, le TDR de Windows le réinitialise, et l'app perd son device sans retour (G.2). + La valeur de la borne, elle, est libre : elle compte dans le palier de coût (C.7). +- **Un plafond de sécurité sur le travail par pixel :** 4 096 itérations, toutes boucles + imbriquées comprises. L'ordre de grandeur visé est le seuil du TDR (2 s par frame) sur un GPU + intégré en 1080p ; c'est une estimation, que la PR 1 mesure et ajuste. Un flou de 64 taps en + fait 64, un raymarching de 64 pas sur 8 objets 512. +- **Alpha.** Pour les cibles `image` et `both`, la valeur rendue remplace le pixel ; les + encodeurs ignorent l'alpha, et rendre `frame(uv).a` suffit. Pour la cible `text`, `frame()` + rend le calque des textes en alpha prémultiplié, transparent hors du texte, et l'effet doit + rendre de l'alpha prémultiplié lui aussi (D.1). + +### C.5 Le contrat est versionné + +Chaque définition porte `contract: 1`. +- **Le prélude d'une version livrée ne change plus.** Une entrée nouvelle s'ajoute à la fin de + `FxContext` : le code existant ne la lit pas et compile à l'identique. +- **Un changement de sens crée la version 2,** et le compositeur garde le prélude de la 1. +- **Un document qui porte une version inconnue** (écrit par une build plus récente) garde ses + régions, sans les appliquer. + +### C.6 Exemple + +Le ripple du spike, réécrit pour le contrat v1 : + +```wgsl +// Une onde part de chaque clic, réfracte l'image et laisse deux ou trois vagues derrière elle. +fn ripple(uv: vec2, click: vec4) -> vec2 { + if (click.w < 0.5 || click.z > params.duration) { return vec2(0.0); } + let t = click.z / params.duration; + let aspect = ctx.resolution.x / ctx.resolution.y; + let d = (uv - click.xy) * vec2(aspect, 1.0); + let r = length(d); + let x = params.radius * (1.0 - pow(1.0 - t, 3.0)) - r; + let env = smoothstep(-0.008, 0.0, x) * exp(-max(x, 0.0) / 0.07); + let wave = sin(x / 0.03 * 6.2831853) * env * (1.0 - t) * (1.0 - t) * params.strength; + let dir = select(vec2(0.0), d / r, r > 1e-5); + return dir * wave * 0.01 / vec2(aspect, 1.0); +} + +fn effect(uv: vec2) -> vec4 { + var offset = vec2(0.0); + for (var i = 0; i < 4; i++) { offset += ripple(uv, ctx.clicks[i]); } + return frame(uv - offset); +} +``` + +Avec `params` : `strength` (number, 0 à 2, 1), `radius` (number, 0,05 à 0,5, 0,2), `duration` +(number, 0,3 à 2 s, 0,9). + +### C.7 Le coût : des paliers indicatifs, pas des limites + +Le coût d'un effet est estimé depuis son code, sans le faire tourner. Il ne dépend donc pas de la +machine : le même code reçoit le même palier partout, et un effet haut de gamme n'est jamais +refusé parce que la machine qui l'écrit est modeste. + +- **L'estimation se fait sur l'IR de naga.** Elle compte les lectures de `frame()` par pixel, + multipliées par la borne des boucles qui les contiennent ; les fonctions appelées sont + dépliées. Les lectures de texture dominent le coût mesuré dans le spike : c'est la bande + passante qui paie. +- **Les paliers**, en lectures par pixel : + +| Palier | Lectures | Exemples | Recommandation | +|---|---|---|---| +| Léger | ≤ 8 | vignette, étalonnage, ripple à 4 clics | Partout, y compris sur toute la vidéo. | +| Moyen | ≤ 32 | aberration chromatique échantillonnée, petit flou, glitch | Sur des régions de quelques dizaines de secondes. | +| Lourd | ≤ 128 | gros flou, bokeh | Sur des régions courtes : une transition, un moment fort. | +| Très lourd | au-delà | raymarching, simulations | Quelques secondes. L'export reste juste, mais plus lent ; la preview peut ralentir sur un petit GPU. | + +- **Mesuré sur la RTX 4070 Ti** (`shader_fx_tier_calibration`) : environ 4 µs par lecture en + 1080p et 17 µs en 4K, au-dessus d'un fixe de 0,03 ms. Un effet léger coûte au plus 0,06 ms par + frame en 1080p, un moyen 0,14 ms, un lourd 0,54 ms, 512 lectures 2,1 ms. Le détail est dans + [rendering-performance.md](../technical-documentation/engineering/rendering-performance.md). +- **Mesuré sur lavapipe** (le repli CPU de Linux, 16 threads) : environ 1,4 ms par lecture en + 1080p, 350 fois la RTX. Un effet léger y ajoute jusqu'à 11 ms à une frame qui en coûte 7,5 ; + un lourd, 234 ms. L'ordre des paliers tient, mais sans GPU même un effet léger double le + temps d'export. +- **Le GPU intégré de référence** (le Radeon 610M des mesures Linux) reste à mesurer : on y attend + plusieurs fois ces coûts. La description de l'outil donnera les paliers en ms sur les deux + machines, pour que l'agent raisonne en temps et non en lectures. +- **Plusieurs effets au même instant s'additionnent.** Le retour d'un outil donne le palier de + l'effet, et le palier cumulé du moment le plus chargé de sa région. +- **Rien n'est refusé au coût.** Le palier et sa recommandation reviennent à l'agent (E.3), qui + décide, et ils restent lisibles dans le snapshot (E.2). + +--- + +## D. Le rendu + +### D.1 Où la passe s'insère + +`compose_frame` dessine, dans l'ordre : +1. le fond ; +2. le métrage et le cadre ; +3. les flous de confidentialité ; +4. le curseur ; +5. la webcam ; +6. les annotations et les sous-titres. + +Une région choisit sa cible (`target`). Sans demande explicite, c'est `image`. + +- **`image`** : l'image sans les textes. La passe s'insère avant les annotations et les + sous-titres. Un effet déforme l'écran, la webcam, le curseur et le fond, jamais le texte que + l'utilisateur a posé pour être lu. +- **`text`** : les textes seuls (annotations et sous-titres). Les textes sont dessinés dans un + calque transparent à part, l'effet s'y applique, puis le calque est composé par-dessus l'image + (« over » prémultiplié). L'image dessous reste intacte. Le calque n'existe que si une région + `text` couvre la frame. +- **`both`** : l'image finale, textes compris, par exemple pour un fondu au noir qui doit couvrir + les sous-titres. La passe vient après tout. + +Les flous de confidentialité restent sûrs. L'effet ne voit que des pixels déjà floutés et ne peut +rien y retrouver : il n'existe aucun chemin vers l'image d'avant le flou. + +### D.2 Plusieurs effets à la fois + +- **L'ordre.** Les régions actives à la frame s'appliquent par lane croissante, puis dans + l'ordre du tableau. +- **Le coût.** Chacune fait une copie du RT dans `ann_copy` et une passe plein cadre. +- **Les cibles s'enchaînent dans l'ordre du dessin :** les effets `image`, puis les textes et + leurs effets `text`, puis les effets `both`. Un effet ne voit que ce qui est dessiné avant lui. + +### D.3 Les chemins de rendu + +- **Un seul `compose_frame`.** La preview (`live.rs`), l'export MP4 et l'export GIF + (`walk_composited_timeline`, `timeline_walk.rs`) l'appellent tous. Les effets apparaissent + donc partout, sans code propre à chaque chemin. +- **Une passe par frame de sortie.** `compose_frame_mb` n'a aucun appelant, et le flou de + mouvement est calculé par calque (`mb_taps`). + +### D.4 La compilation : une fois, hors du rendu + +Il y a deux compilations, à deux moments : + +1. **À l'écriture.** Quand un outil pose ou change un code (`addEffect`, + `setEffectDefinition`), le processus principal appelle `validateShaderEffect` de l'addon. + - **La compilation est réelle,** pour le backend de la machine, en plus de la validation + naga. « Accepté » veut donc dire « se dessinera ». + - **Le coût est estimé** depuis le code (C.7), sans rendu ni mesure sur la machine. + - **L'erreur revient à l'agent** avec la ligne et la colonne de SON code. +2. **À la pose de la scène** (`Compositor::set_scene`). Chaque code nouveau part compiler sur un + thread de fond. + - **La preview** saute l'effet le temps de la compilation, environ 10 ms, puis recompose la + frame en pause (`shader_fx_landed`). + - **L'export** attend le binaire, et ne rend jamais une frame sans son effet. C'est le mode + par défaut du compositeur : seule la vue live le coupe. + +Le cache est en mémoire, par compositeur. +- **La clé** est le hash de (contrat, layout des paramètres, code). +- **L'éviction** est LRU au-delà de 64 entrées : un agent qui itère en crée une par version. +- **Pas de cache disque en v1.** 10 ms par effet ne le justifient pas, et Metal comme Mesa gardent + déjà leur propre cache de shaders. L'app ne passe d'ailleurs aujourd'hui aucun dossier + inscriptible au natif : il faudrait une variable d'environnement sur le modèle de + `OPENSCREEN_FONTS_DIR`. + +### D.5 Par plateforme + +Une seule source WGSL, traduite par naga au moment de compiler. + +| | Windows | macOS | Linux | +|---|---|---|---| +| Traduction | naga vers HLSL SM 5.0 | naga vers MSL | aucune : WGSL tel quel | +| Compilation | `D3DCompile` (FXC) vers DXBC, puis `CreateVertexShader`/`CreatePixelShader` | `new_library_with_source`, puis `make_pipeline(…, Blend::Replace)` | `create_shader_module`, puis `create_render_pipeline` | +| Thread de fond | naga et FXC (fait) | bibliothèque et pipeline, sous `autoreleasepool` | module et pipeline (fait) | +| Copie du RT | `CopySubresourceRegion` vers `ann_copy` (fait) | `snapshot_rt(cmd_buf, false)` | `copy_texture_to_texture` vers le niveau 0 d'`ann_copy` (fait) | +| Insertion | fin de `compose_frame` (fait) | entre `draw_annotations(…, false)` et `submit` | `image` entre la passe caméra et l'ann-pass, `text` et `both` après (fait) | +| Uniforms | `Map(WRITE_DISCARD)` (fait) | `set_fragment_bytes` | `create_buffer_init(UNIFORM)` par passe (fait) | + +**macOS en détail** +- **Activer `msl-out`.** Le dépôt l'obtient aujourd'hui par unification des features de wgpu ; le + déclarer explicitement sous `cfg(target_os = "macos")`. +- **Pas d'objet sampler.** Les shaders Metal du dépôt utilisent des `constexpr sampler` : + passer le sampler en `inline_samplers` de naga (`BindSamplerTarget::Inline`). +- **Lier les bindings explicitement.** Remplir `per_entry_point_map` pour `fx_fs` : texture, + sampler, buffer. Sinon `fake_missing_bindings` émet `[[user(fake0)]]`, qui n'est pas du MSL + valide. +- **Lire les noms de fonctions** dans `TranslationInfo.entry_point_names`. +- **Le thread de fond.** `Device`, `Library` et `RenderPipelineState` de metal-rs sont `Send` et + `Sync`, et `live.rs` déplace déjà un `Gpu` vers un thread de préchargement. + +**Linux en détail** +- **Un bind group layout explicite,** jamais `layout: None`. Sinon un effet qui n'appelle pas + `frame()`, ou ne lit pas `ctx`, perd ces bindings, et le bind group échoue à la validation. +- **Le thread de fond.** `wgpu::Device` est `Send`, `Sync` et `Clone` : le pipeline peut se + construire hors du thread de rendu. +- **Valider avant wgpu.** Aucun `on_uncaptured_error` n'est posé, donc une erreur de validation + wgpu fait paniquer. La pré-validation (`shader_fx::analyze`) en protège : naga 24, celui de + wgpu 24, et le refus de tout binding que le prélude ne déclare pas. Si wgpu panique malgré tout, + seul le thread de compilation meurt, et l'effet ne se dessine pas (D.6). +- **« Accepté » sous Linux.** `check_for_agent` traduit l'effet en SPIR-V par naga, comme wgpu le + fera. La compilation par le pilote Vulkan n'a lieu qu'à `set_scene`, faute de device dans + l'outil. +- **Le calque des textes** est une texture RGBA8 transparente, posée sur le RT par la passe qui + recopie déjà `accum` (`pipeline_copy`, « over » prémultiplié). + +**naga reste en 24.** À partir de la 25, sa sortie HLSL déclare les samplers dans un tas D3D12 +(`register(s0, space0)`), que FXC refuse en `ps_5_0` (erreur X3721). Le test +`a_valid_effect_becomes_hlsl_that_d3d11_accepts` garde cette frontière : il doit passer avant tout +bump de naga ou de wgpu. + +### D.6 Un effet qui ne compile pas au rendu + +Ce cas arrive avec un document écrit ailleurs, une version de contrat inconnue ou un +compilateur qui diffère d'une machine à l'autre. +- **La région ne se dessine pas,** et la frame reste celle de la composition. +- **L'erreur est écrite une fois** dans le journal natif (`[shader-fx]`) et remonte à + l'inspecteur (F.2). +- **L'export ne s'arrête pas.** Un effet manquant vaut mieux qu'un export perdu, et l'agent ou + l'utilisateur a déjà vu l'erreur à l'écriture. + +--- + +## E. Le DSL : ce que l'agent appelle et relit + +Les effets passent par les outils de document, comme le reste : `TOOL_ARG_SCHEMAS`, +`TOOL_DESCRIPTIONS`, `executeAgentTool`. Le serveur MCP les sert sans rien de plus, et l'agent +intégré les reçoit par le même tableau. + +### E.1 Les outils + +| Outil | Arguments | Effet | +|---|---|---| +| `addEffect` | `startSec`, `endSec` (secondes de règle), `effect` **ou** `effectId`, `values?`, `target?`, `lane?` | Pose une région. Avec `effect` (`name`, `description`, `code`, `params?`), crée d'abord la définition. Avec `effectId`, réutilise une définition du projet. | +| `setEffect` | `effectRegionId`, `startSec?`, `endSec?`, `values?`, `target?`, `lane?` | Change une région. Seuls les champs passés changent. | +| `setEffectDefinition` | `effectId`, `name?`, `description?`, `code?`, `params?` | Change une définition, donc toutes les régions qui l'utilisent. Un code neuf est compilé avant d'être accepté. Les `values` d'un paramètre retiré tombent, un paramètre nouveau prend son `default`. | +| `getEffect` | `effectId` | Lecture : la définition entière, code compris. | +| `removeModifier` | `id` | Retire une région d'effet, comme un zoom. | + +- **Un seul `add`.** Écrire puis poser un effet est le cas courant : un appel, pas deux. + `effectId` sert à réutiliser. +- **Pas de `removeEffect`.** La définition part avec sa dernière région (B.2). +- **Les noms suivent le DSL :** `add*`, puis `set*` qui ne touche que les champs passés, puis + `removeModifier` pour retirer. Pas de neutralisation (force à 0, durée nulle) à la place d'un + retrait. +- **Le placement suit les autres régions :** `anchorForAgent` / `landingOf`. Le modèle est + `addCameraFullscreen`. Une étendue qui ne couvre aucun clip est refusée (`coversNoClip`), et + une région qui en heurterait une autre de la même lane aussi (`refuseIfBlocked`). + +### E.2 Ce que l'agent relit + +`getCurrentDocument` ajoute deux listes, sans le code, qui coûterait cher en tokens à chaque +lecture : + +```json +"effects": [ + { "id": "fxr_…", "effectId": "fx_…", "name": "Ripple au clic", + "startSec": 0, "endSec": 6, "target": "image", "lane": 0, "values": { "strength": 1 } } +], +"effectDefinitions": [ + { "effectId": "fx_…", "name": "Ripple au clic", + "description": "Une onde part de chaque clic et réfracte l'image.", + "contract": 1, "lines": 22, "regions": 1, + "cost": { "tier": "light", "frameReads": 4 }, + "params": [ { "name": "strength", "type": "number", "label": "Force", + "default": 1, "min": 0, "max": 2 } ] } +] +``` + +- **Les pilules sont coalescées** comme les autres régions (`coalesceForAgent`) : un id par + pilule, celui de son premier fragment. +- **Le code se lit par `getEffect`,** quand l'agent veut le modifier. +- **`description` est écrite par l'agent** et lue par l'agent suivant. La description de l'outil + l'exige : ce que l'effet fait, en une phrase, pas comment il le fait. +- **`cost`** est l'estimation mise en cache dans la définition. `null` signifie que rien n'a pu + vérifier le code quand il a été écrit. +- **`timeBaseNote`** nomme les effets parmi les régions en secondes de règle. + +### E.3 Les retours + +- **Accepté :** l'id, l'étendue posée (`landingReport`, comme les autres régions : fragments, + bornes rognées), et le coût : le palier de l'effet, le palier cumulé du moment le plus chargé, + et la recommandation du palier quand la région la dépasse. Par exemple : « lourd sur 45 s : + pour une région longue, vise moyen ». +- **Refusé à la compilation :** l'enveloppe `{ error }`, avec l'erreur de naga ou du compilateur + du backend, lignes et colonnes de SON code. Le document ne change pas. +- **Refusé pour une boucle sans borne littérale,** ou au-delà du plafond de sécurité de C.4, + avec la ligne de la boucle. C'est le seul refus qui ne vient pas du compilateur. +- **Sans validateur branché** (un harnais de test), le code est stocké et `validated: false` le + dit. + +### E.4 Voir le résultat sans exporter + +Aujourd'hui `getFrames` (`media-tools.ts`) ne montre que le dernier export : vérifier un effet +coûte un export complet. Sur un projet de dix minutes, la boucle de l'agent devient trop lente. + +**`getFrames` rend désormais depuis le document quand l'export manque ou est périmé.** +- Il passe par le même compositeur, la même scène et les mêmes secondes de règle, et rend les + frames demandées à la taille d'export. +- C'est le chemin que le spike a utilisé pour comparer la vue live à l'export : une vue sans + fenêtre, `setScene`, `presentTime`, `readFrame`. +- Avec un export à jour, l'outil garde son comportement actuel. + +### E.5 Ce que l'agent lit avant d'écrire + +- **`TOOL_DESCRIPTIONS.addEffect`** porte le contrat court : la signature, les entrées de C.2, + les règles de C.4, les paliers de C.7 en ms, les trois cibles et le défaut `image`, l'exigence + d'un paramètre visible, et la vérification avec `getFrames`. +- **La ressource MCP `openscreen://effects/contract`** porte le contrat complet et deux + exemples : le ripple au clic et une vignette qui respire. + - **Ce serait la première ressource du serveur,** qui n'en a aucune aujourd'hui. + - **Pourquoi une ressource :** le contrat est trop long pour une description d'outil, et il + évolue avec `contract`. +- **Le prompt de base** (`BASE_SYSTEM_PROMPT`) gagne deux choses : + - une ligne dans la carte des intentions : un effet visuel que les réglages n'offrent pas se + fait avec `addEffect` ; + - les effets dans la ligne des bases de temps. +- **Le skill `openscreen-demo`** gagne une entrée « effets » à son étape 6. + +### E.6 L'agent intégré + +Il a les mêmes outils, mais pas le validateur : `ChatRunEnv` ne le transmet pas. Il manque +quatre ajouts d'une ligne, sur le modèle de `cameraSegmentation` : +- le champ dans `ChatRunEnv` ; +- son passage dans `chat-service.ts` ; +- le champ dans `InvokeArgs`, et son passage à `buildTools` ; +- `validateShaderEffect: (code) => loudnessService.validateShaderEffect(code)` dans + `handlers.ts`, à côté de `cameraSegmentation`. + +### E.7 Le banc (workbench) + +Un scénario, `effect-ripple-on-click`, sur une mire avec trois clics : + +- **Attendu :** un `addEffect` dont le code lit `ctx.clicks`, une région qui couvre chaque clic et + la demi-seconde qui suit, et la cible `image`, puisque rien ne demande les textes. +- **Pas exigé :** lire la piste du curseur. Le compositeur donne déjà les clics placés sur la + sortie, c'est tout l'intérêt du contrat (C.2). + +`documentInvariants` valide les deux nouvelles listes : chaque région pointe une définition +existante, et ses `values` sont dans les bornes. Hors ligne, rien ne compile le code : le résultat +dit `validated: false`, et les checks lisent le code comme du texte. + +--- + +## F. L'interface + +### F.1 Une piste « Effets » dans la timeline + +- **Où.** Une rangée par lane utilisée, plus une rangée vide pour en ouvrir une nouvelle. Elles se placent sous la piste Full Camera, dans l'ordre des lanes de `V4Timeline.tsx`. +- **La pilule** porte le nom de la définition. La glisser, l'étirer, la sélectionner et la + supprimer se font comme pour un zoom (`selectPill`, `startPillDrag`, `removeRegions`). +- **L'annulation** passe par l'historique habituel (`saveDocument({ history: true })`). Une + édition d'agent reste un seul pas d'annulation par tour (`agentDocumentApply.ts`). +- **Pas de bouton « ajouter un effet » en v1.** Un effet naît d'un agent : le chat intégré ou un + client MCP. Un bouton qui ouvrirait un panneau vide n'aurait rien à proposer. La bibliothèque + d'effets (J) lui donnera un contenu. +- **Le copier-coller** (`regionClipboard`) copie la région avec sa définition. Collée dans un + autre projet, la définition y est recréée. +- **Le site** (`website/scripts/gen-recreation.mjs`) recopie `LANE_ORDER` à la main. La nouvelle + piste n'y casse rien, et la recréation ne la montrera pas tant qu'on ne l'y ajoute pas. + +### F.2 L'inspecteur + +`SelectionPane` (`FloatingInspector.tsx`) gagne une branche `shaderEffect`. Elle contient, dans +l'ordre : + +- **le nom de l'effet,** sans phrase d'explication sous les contrôles ; +- **un contrôle par paramètre déclaré,** généré depuis `params` (curseur, interrupteur, couleur + ou point), qui écrit `values` sur la région ; +- **la cible :** « Image », « Textes » ou « Les deux » (`target`) ; +- **le palier de coût,** en un mot (léger, moyen, lourd, très lourd), sans phrase ; +- **le code,** replié par défaut, en lecture seule, avec un bouton copier ; l'édition du code + passe par l'agent en v1 ; +- **supprimer,** comme pour les autres régions. + +**Un effet qui ne compile pas** affiche l'erreur du compilateur dans l'inspecteur. C'est +l'exception admise aux phrases sous les réglages : sans elle, la pilule existerait sans rien +faire, et ce serait une vraie surprise. + +### F.3 Textes de l'interface + +Les libellés fixes vont dans `timeline.json` (`labels.shaderEffect`) et dans `editor.json` +(`inspector.effectCode`, `inspector.effectLayer`…), pour les 15 locales. +`localeParity.test.ts` et `npm run i18n:check` vérifient leur parité. Les noms et libellés +écrits par l'agent n'y passent pas. + +--- + +## G. SSOT, déterminisme, sécurité + +### G.1 Ce qui garantit preview = export + +- **Un seul chemin de pixels.** La preview et l'export appellent le même `compose_frame`, avec la + même scène : `buildSceneDescription` sert aux deux. +- **Une seule horloge.** `ctx.time` est le temps programme, et `ctx.region` vient de l'étendue + de la pilule en temps programme. Aucun des deux ne lit le compteur de frames. +- **Un effet pur.** C'est le contrat C.4. La validation fait respecter ce qui se vérifie + statiquement (boucles, taille), et la description de l'outil donne le reste à l'agent comme + règle d'écriture. +- **Jamais de placeholder à l'export.** Le mode bloquant est le défaut du compositeur. +- **À résolution égale.** La preview rend plus petit que l'export. Un effet qui suit C.4 donne la + même image, mais pas les mêmes pixels, puisqu'il n'y en a pas le même nombre. C'est déjà vrai + de tout le reste du rendu. + +**Mesure du spike.** Écart entre la frame de la vue live et celle du MP4 exporté, décodé en +BT.709 : 2,2 à 2,6 / 255, dans la région d'effet comme hors d'elle. C'est le bruit du codec. + +### G.2 Un GPU qui ne répond plus + +Le seul vrai risque d'un code écrit par un agent est une boucle qui ne finit pas. Le TDR de +Windows réinitialise alors le GPU, et l'app perd son device. Rien ne gère ce cas dans le dépôt : +le thread de rendu s'arrête sur son erreur (`fatal`, `live.rs`) et ne redémarre pas. + +La protection est statique, posée à la validation : la borne littérale de toute boucle et le +plafond de 4 096 itérations par pixel (C.4). Ce n'est pas un budget de coût, qui n'existe qu'en +paliers indicatifs (C.7). Récupérer un device perdu est un chantier à part : il concerne toute +l'app, pas les effets. + +### G.3 Un projet partagé + +Un projet porte le code de ses effets. Ouvrir le projet de quelqu'un d'autre compile donc du code +qu'on n'a pas écrit. +- **Ce code ne tourne que sur le GPU,** sans accès aux fichiers, au réseau ni à la mémoire du + processus. +- **Les garde-fous de G.2 s'appliquent aussi à l'ouverture.** Un effet refusé reste dans le + document, et sa région ne se dessine pas. + +--- + +## H. Performance + +### H.1 Pas de budget ferme + +- **Une région inactive ne coûte rien.** La passe n'existe que si une région couvre la frame. +- **Le coût d'un effet se lit en paliers** (C.7), estimés depuis le code et identiques sur toutes + les machines. L'agent les connaît et suit leurs recommandations ; rien n'est refusé au coût. +- **Une cible `text`** ajoute un calque transparent et sa composition, seulement aux frames + qu'elle couvre. + +### H.2 Mesuré par le spike (RTX 4070 Ti, D3D11) + +| Mesure | Résultat | +|---|---| +| Compilation (naga + FXC) d'un effet de 60 lignes | 10 ms, sur un thread de fond | +| Passe d'un effet lourd, 1080p | +0,04 ms par frame | +| Passe d'un effet lourd, 4K | +0,12 ms par frame | +| Export de 180 frames en 1752×1080 : sans effet, avec effet, avec effet lourd | 520, 523 et 521 ms | +| Preview en lecture, source à 30 i/s | 30 i/s avec et sans effet | + +Mesuré à la passe Linux (lavapipe sous WSL, 16 threads) : effet prêt en 18 ms après `set_scene`, +module et pipeline compris ; les paliers en C.7. + +À mesurer à l'implémentation : +- un GPU intégré (le Radeon 610M des mesures Linux) ; +- le compilateur Metal. + +Les résultats iront dans +[rendering-performance.md](../technical-documentation/engineering/rendering-performance.md). + +--- + +## I. Les tests + +| Niveau | Ce qu'il couvre | +|---|---| +| Rust, `shader_fx.rs` | Prélude et struct générée ; packer de paramètres contre les offsets de naga ; borne littérale et plafond d'itérations ; estimation du coût et paliers (boucles imbriquées, fonctions dépliées) ; erreurs aux lignes de l'agent ; sélection des régions (lane, ordre, `underTrim`) ; `ctx.region` sur une pilule coupée. | +| Rust, par backend | Une passe repeint la frame dans sa région et nulle part ailleurs ; les trois cibles (`text` laisse l'image intacte, `image` laisse les textes intacts) ; preview non bloquante puis `shader_fx_landed` ; effet cassé = frame intacte. Windows (fait dans le spike), macOS sur le runner CI, Linux sur lavapipe. | +| Rust, `frame_geometry.rs` | `ctx.clicks`, `ctx.footage`, `ctx.camera` en uv de sortie, sous zoom et sous tilt. | +| TS, schéma | Parse, bornes des `values`, définition orpheline retirée, document ancien inchangé. | +| TS, timeline | La région suit `moveClip`, `removeClip`, `replaceTimeline` et les trims (`timelineMap.test.ts`, `timeline.test.ts`). | +| TS, outils | `addEffect` avec `effect` puis avec `effectId` ; `setEffect` ; `setEffectDefinition` ; `getEffect` ; `removeModifier` ; les refus (compilation, boucle sans borne, chevauchement, aucun clip) ; le palier et sa recommandation dans le retour ; le snapshot. | +| TS, scène | Projection, `programmeStart/EndSec` d'une pilule coupée, normalisation des `values`. | +| Banc | Les deux scénarios de E.7. | +| Bout en bout | La boucle du spike par la CLI `mcp` : prompt, `addEffect`, `getFrames`, puis comparaison de la vue live avec l'export. Une ligne dans le [journal e2e](../technical-documentation/testing/manual-e2e-checklist.md). | + +--- + +## J. Hors de la v1 + +- **Effets par calque** (l'écran seul, la webcam seule). La passe agit sur l'image composée. +- **Effets temporels** (traînées, persistance). Ils prendraient les frames précédentes comme + entrées explicites, jamais un état gardé ; ce n'est pas fait. +- **Transitions entre deux clips.** Elles demandent deux images en entrée. +- **L'édition du code dans l'interface.** En v1, le code se lit, se copie, et s'écrit par + l'agent. +- **La bibliothèque d'effets** partagée entre projets, avec un bouton « ajouter » qui la propose. +- **Une poignée sur la preview** pour les paramètres `point`. +- **Le cache disque** des binaires compilés. +- **La récupération d'un device GPU perdu,** un chantier qui concerne toute l'app. + +--- + +## K. Décisions (14/10/2026) + +1. **Champs additifs, sans montée de `schemaVersion`.** Comme `audioTracks`. Une build antérieure + qui sauvegarde le projet perd ses effets : c'est accepté. +2. **Pas de budget ferme, des paliers indicatifs** (C.7). Ils sont estimés depuis le code, donc + indépendants de la machine. L'agent les connaît, avec leurs recommandations. Un budget lié à + la machine aurait refusé des effets haut de gamme sur une machine modeste, alors que l'export, + lui, les rend très bien. +3. **Pas de limites fermes non plus.** Paramètres, code et lanes ont des recommandations, et des + plafonds techniques loin au-dessus (B.2). Seule reste ferme la borne littérale des boucles, + avec son plafond de 4 096 itérations par pixel : une protection contre le blocage du GPU, pas + une limite de créativité. +4. **Pas de bouton « ajouter un effet » en v1.** Les effets naissent des agents. +5. **Trois cibles : `image`, `text`, `both`.** Sans demande explicite, l'effet vise `image`, sous + les textes. + +## L. Découpage en PR + +Le spike n'est pas fusionné tel quel : les PR 1 et 2 reprennent son code, et il est stocké +ailleurs (`legacyEditor`, sans ancre). + +1. **Contrat v1 et passe Windows (Rust).** + - `shader_fx.rs` : struct `FxParams` générée et packer ; `ctx.region`, `ctx.clicks`, + `ctx.footage`, `ctx.camera`, `fx_px`, `fx_hash` ; borne littérale des boucles et plafond + d'itérations ; estimation du coût et paliers, calibrés en ms sur le GPU intégré de + référence. + - `validate_shader_effect` compile pour le backend et rend le palier. + - `scene.rs` lit la nouvelle forme ; la passe Windows gère les trois cibles (calque de textes + à part pour `text`), `lane` et l'éviction LRU. +2. **Modèle de données et DSL (TS).** + - Schéma (B.2) et `RegionKind` dans tout le pipeline (B.3) ; + - outils (E.1), snapshot (E.2), projection de scène (B.5) ; + - validateur branché sur l'agent intégré (E.6) ; + - descriptions, prompt de base, ressource MCP du contrat, skill, `openscreen info`, banc. +3. **Passe macOS.** naga `msl-out`, samplers inline, bindings explicites, thread de fond, tests + sur le runner CI. +4. **Passe Linux.** WGSL direct, bind group layout explicite, thread de fond, test lavapipe. +5. **`getFrames` depuis le document.** Rendu de frames sans export quand celui-ci manque ou est + périmé (E.4). +6. **Interface.** Piste et lanes, inspecteur, copier-coller, i18n. + +La PR 2 dépend de la 1. Les PR 3, 4 et 5 dépendent de la 1 et peuvent avancer en parallèle. La +PR 6 dépend de la 2. + +Chaque PR met à jour la documentation qu'elle rend fausse, dans le même changement : +- `native-compositor.md` ; +- `document-model.md` et `timeline-model.md` ; +- `editor-shell.md`, dont la checklist « Adding a region kind » a ses numéros de ligne à + rafraîchir ; +- `ai-agent.md`, dont le tableau d'outils annonce encore « 26 tools » ; +- `mcp-server.md` ; +- une ligne de [decisions.md](../technical-documentation/architecture/decisions.md) : WGSL et + naga 24, compilation hors du rendu, effet pur ; +- et, à la PR 6, une page de `website/docs/`. diff --git a/electron/ai-edition/agent-tools.test.ts b/electron/ai-edition/agent-tools.test.ts index 9cfc65449b..2d16fc3f2c 100644 --- a/electron/ai-edition/agent-tools.test.ts +++ b/electron/ai-edition/agent-tools.test.ts @@ -192,6 +192,7 @@ describe("the mutating-tool table", () => { "addAnnotation", "addAudio", "addCameraFullscreen", + "addEffect", "addSpeed", "addTrim", "addTrims", @@ -211,6 +212,8 @@ describe("the mutating-tool table", () => { "setAudio", "setCameraFullscreen", "setClipRange", + "setEffect", + "setEffectDefinition", "setEditorSettings", "setSpeed", "setTrim", @@ -3734,3 +3737,178 @@ describe("clip structure (#1180)", () => { }); }); }); + +describe("shader effects", () => { + const CODE = "fn effect(uv: vec2) -> vec4 { return frame(uv) * params.level; }"; + const params = [ + { type: "number", name: "level", label: "Level", default: 1, min: 0, max: 2 }, + { type: "color", name: "tint", label: "Tint", default: "#000000" }, + ]; + // Stands in for the compositor's check: refuses `nope`, prices every effect at 4 reads. + const checkShaderEffect = (code: string) => + code.includes("nope") + ? { error: "error: no definition in scope for identifier: `nope`" } + : { tier: "light" as const, frameReads: 4, iterations: 0 }; + const options = { checkShaderEffect }; + const run = (document: AxcutDocument, name: string, args: unknown) => + executeAgentTool(document, name, JSON.stringify(args), options); + const add = (document: AxcutDocument, args: Record = {}) => + run(document, "addEffect", { + startSec: 2, + endSec: 6, + effect: { name: "Dim", description: "Dims the picture.", code: CODE, params }, + ...args, + }); + + it("writes the effect and poses it, anchored, with only the values that differ", () => { + const added = add(fixtureDocument(), { values: { level: 0.5, tint: "#000000" } }); + expect(added.ok).toBe(true); + const doc = added.document as AxcutDocument; + const [effect] = doc.shaderEffects ?? []; + const [range] = doc.shaderEffectRanges ?? []; + expect(effect).toMatchObject({ + name: "Dim", + contract: 1, + origin: "agent", + cost: { tier: "light", frameReads: 4 }, + }); + expect(range).toMatchObject({ + effectId: effect.id, + startMs: 2000, + endMs: 6000, + clipId: "clip_1", + values: { level: 0.5 }, + target: "image", + lane: 0, + }); + expect(JSON.parse(added.resultJson)).toMatchObject({ + effectRegionId: range.id, + effectId: effect.id, + validated: true, + cost: { tier: "light", busiestTier: "light" }, + }); + expect(() => documentSchema.parse(doc)).not.toThrow(); + }); + + it("refuses code that does not compile, with the compiler's error, and changes nothing", () => { + const refused = add(fixtureDocument(), { + effect: { + name: "Broken", + description: "", + code: "fn effect(uv: vec2) -> vec4 { return nope; }", + }, + }); + expect(refused.ok).toBe(false); + expect(refused.document).toBeUndefined(); + expect(JSON.parse(refused.resultJson).error).toMatch(/does not compile[\s\S]*nope/); + }); + + it("takes either a new effect or one of the project's, not both or neither", () => { + const doc = add(fixtureDocument()).document as AxcutDocument; + const effectId = doc.shaderEffects?.[0].id; + expect(run(doc, "addEffect", { startSec: 8, endSec: 9 }).ok).toBe(false); + const reused = run(doc, "addEffect", { startSec: 8, endSec: 9, effectId }); + expect(reused.ok).toBe(true); + expect(reused.document?.shaderEffects).toHaveLength(1); + expect(reused.document?.shaderEffectRanges).toHaveLength(2); + }); + + it("keeps one lane free of overlaps, and points to another lane", () => { + const doc = add(fixtureDocument()).document as AxcutDocument; + const blocked = add(doc, { startSec: 4, endSec: 8 }); + expect(blocked.ok).toBe(false); + expect(JSON.parse(blocked.resultJson).error).toMatch(/lane 0[\s\S]*another lane/); + expect(add(doc, { startSec: 4, endSec: 8, lane: 1 }).ok).toBe(true); + }); + + it("recommends a lighter tier when a heavy effect runs long, and never refuses it", () => { + const heavy = { + ...options, + checkShaderEffect: () => ({ tier: "heavy" as const, frameReads: 100 }), + }; + const added = executeAgentTool( + fixtureDocument(), + "addEffect", + JSON.stringify({ + startSec: 0, + endSec: 40, + effect: { name: "Blur", description: "", code: CODE, params }, + }), + heavy, + ); + expect(added.ok).toBe(true); + expect(JSON.parse(added.resultJson).cost.advice).toMatch(/heavy over 40\.0 s/); + }); + + it("re-tunes, retargets and moves a region; a value back at its default is dropped", () => { + const doc = add(fixtureDocument(), { values: { level: 0.5 } }).document as AxcutDocument; + const regionId = doc.shaderEffectRanges?.[0].id; + const tuned = run(doc, "setEffect", { + effectRegionId: regionId, + values: { level: 1, tint: "#ff0000" }, + target: "both", + startSec: 10, + endSec: 12, + }); + expect(tuned.ok).toBe(true); + expect(tuned.document?.shaderEffectRanges?.[0]).toMatchObject({ + startMs: 10000, + endMs: 12000, + target: "both", + values: { tint: "#ff0000" }, + }); + }); + + it("changes the definition for every region, recompiles, and drops a removed parameter's values", () => { + const doc = add(fixtureDocument(), { values: { tint: "#ff0000" } }).document as AxcutDocument; + const effectId = doc.shaderEffects?.[0].id; + const refused = run(doc, "setEffectDefinition", { + effectId, + code: "fn effect(uv: vec2) -> vec4 { return nope; }", + }); + expect(refused.ok).toBe(false); + const changed = run(doc, "setEffectDefinition", { effectId, params: [params[0]] }); + expect(changed.ok).toBe(true); + expect(changed.document?.shaderEffectRanges?.[0].values).toEqual({}); + expect(JSON.parse(changed.resultJson)).toMatchObject({ regions: 1, validated: true }); + }); + + it("reads an effect's code by getEffect, and lists effects without it in the snapshot", () => { + const doc = add(fixtureDocument()).document as AxcutDocument; + const effectId = doc.shaderEffects?.[0].id; + const read = JSON.parse(run(doc, "getEffect", { effectId }).resultJson); + expect(read).toMatchObject({ + code: CODE, + regions: [{ startSec: 2, endSec: 6, target: "image", lane: 0 }], + }); + const snapshot = JSON.parse(run(doc, "getCurrentDocument", {}).resultJson); + expect(snapshot.effects).toEqual([ + expect.objectContaining({ effectId, name: "Dim", startSec: 2, endSec: 6 }), + ]); + expect(snapshot.effectDefinitions[0]).toMatchObject({ effectId, lines: 1, regions: 1 }); + expect(snapshot.effectDefinitions[0].code).toBeUndefined(); + expect(snapshot.timeBaseNote).toMatch(/effects/); + }); + + it("removes a region by removeModifier, and its definition with the last one", () => { + const doc = add(fixtureDocument()).document as AxcutDocument; + const removed = run(doc, "removeModifier", { id: doc.shaderEffectRanges?.[0].id }); + expect(removed.ok).toBe(true); + expect(JSON.parse(removed.resultJson).kind).toBe("shaderEffect"); + expect(removed.document?.shaderEffectRanges).toEqual([]); + expect(removed.document?.shaderEffects).toEqual([]); + }); + + it("says when nothing could check the code", () => { + const added = executeAgentTool( + fixtureDocument(), + "addEffect", + JSON.stringify({ + startSec: 1, + endSec: 2, + effect: { name: "Dim", description: "", code: CODE, params }, + }), + ); + expect(JSON.parse(added.resultJson)).toMatchObject({ validated: false, cost: null }); + }); +}); diff --git a/electron/ai-edition/agent-tools.ts b/electron/ai-edition/agent-tools.ts index 3a60dd38d8..4de94e670c 100644 --- a/electron/ai-edition/agent-tools.ts +++ b/electron/ai-edition/agent-tools.ts @@ -47,10 +47,25 @@ import { setDocumentWordText } from "../../src/lib/ai-edition/document/transcrip import { type AxcutAnnotationRegion, type AxcutDocument, + type AxcutShaderEffect, + type AxcutShaderEffectRange, blurDataSchema, clipCropRegionSchema, figureDataSchema, + shaderEffectParamSchema, + shaderEffectSchema, + shaderEffectValueSchema, } from "../../src/lib/ai-edition/schema"; +import { + busiestShaderEffectReads, + findShaderEffect, + SHADER_EFFECT_CONTRACT, + type ShaderEffectCheck, + type ShaderEffectChecker, + shaderEffectCostAdvice, + shaderEffectTierOf, + storedShaderEffectValues, +} from "../../src/lib/ai-edition/shaderEffects"; import { getEditorSettings } from "../../src/lib/ai-edition/store/editorSettings"; import { appendAutoZoomSuggestions } from "../../src/lib/ai-edition/timeline/apply-auto-zooms"; import { hasAnyClipWithCamera } from "../../src/lib/ai-edition/timeline/camera"; @@ -135,6 +150,8 @@ function modifierIds(document: AxcutDocument, kind: ModifierKind): string[] { // `removeRegion` applies the same grouping by routing this kind through // `removeAudioTrack`. return [...new Set(document.audioTracks.map(trackGroupId))]; + case "shaderEffect": + return (document.shaderEffectRanges ?? []).map((region) => region.id); } } @@ -590,6 +607,7 @@ function modifierIdsOf(document: AxcutDocument): string[] { ...document.annotations.map((r) => r.id), ...speedRegions.map((r) => r.id), ...cameraFullscreenRegions.map((r) => r.id), + ...(document.shaderEffectRanges ?? []).map((r) => r.id), ]; } @@ -987,6 +1005,48 @@ export const addCameraFullscreenArgs = z.object({ endSec: secondsSchema, }); +const effectTargetSchema = z.enum(["image", "text", "both"]); +const effectLaneSchema = z.number().int().min(0).max(7); +const effectValuesSchema = z.record(z.string(), shaderEffectValueSchema); + +export const addEffectArgs = z.object({ + startSec: secondsSchema, + endSec: secondsSchema, + effectId: z.string().min(1).optional(), + effect: z + .object({ + name: z.string().min(1).max(60), + description: z.string().max(500), + code: z.string().min(1).max(65_536), + params: z.array(shaderEffectParamSchema).max(32).optional(), + }) + .optional(), + values: effectValuesSchema.optional(), + target: effectTargetSchema.optional(), + lane: effectLaneSchema.optional(), +}); + +export const setEffectArgs = z.object({ + effectRegionId: z.string().min(1), + startSec: secondsSchema.optional(), + endSec: secondsSchema.optional(), + values: effectValuesSchema.optional(), + target: effectTargetSchema.optional(), + lane: effectLaneSchema.optional(), +}); + +export const setEffectDefinitionArgs = z.object({ + effectId: z.string().min(1), + name: z.string().min(1).max(60).optional(), + description: z.string().max(500).optional(), + code: z.string().min(1).max(65_536).optional(), + params: z.array(shaderEffectParamSchema).max(32).optional(), +}); + +export const getEffectArgs = z.object({ + effectId: z.string().min(1), +}); + export const setCameraFullscreenArgs = z.object({ cameraFullscreenId: z.string().min(1), startSec: secondsSchema.optional(), @@ -1062,6 +1122,10 @@ export const OPENSCREEN_TOOL_NAMES = [ "setAnnotation", "addCameraFullscreen", "setCameraFullscreen", + "addEffect", + "setEffect", + "setEffectDefinition", + "getEffect", "addAudio", "setAudio", "removeTrim", @@ -1140,6 +1204,9 @@ export const MUTATING_TOOL_NAMES: ReadonlySet = new Set([ "setAnnotation", "addCameraFullscreen", "setCameraFullscreen", + "addEffect", + "setEffect", + "setEffectDefinition", "addAudio", "setAudio", "removeTrim", @@ -1281,7 +1348,7 @@ export function documentSnapshotForModel( const autoFocusAll = legacy?.autoFocusAll === true; return { timeBaseNote: - "clips and trims are in source-time seconds; zooms, speedRegions, annotations, cameraFullscreenRegions and audioTracks are in virtual (edited-timeline) seconds: the editor's ruler, where a trim leaves a hole instead of shortening it and a speed region stretches nothing. The exported video's clock skips those holes and plays sped-up spans faster, so it differs from the ruler once there are any.", + "clips and trims are in source-time seconds; zooms, speedRegions, annotations, cameraFullscreenRegions, effects and audioTracks are in virtual (edited-timeline) seconds: the editor's ruler, where a trim leaves a hole instead of shortening it and a speed region stretches nothing. The exported video's clock skips those holes and plays sped-up spans faster, so it differs from the ruler once there are any.", audioNote: "audioTracks are imported voiceover / music files laid over the recording. They are clip-anchored like every other region, so they travel with their clip through reorder and trim, and they play at 1x whatever a speed region does to the picture under them. addAudio places an EXISTING asset of kind 'audio': if the project has none, a file has to be imported first (importMedia, where it is offered), so never invent an id.", zoomNote: @@ -1408,6 +1475,29 @@ export function documentSnapshotForModel( startSec: roundSec(c.startMs), endSec: roundSec(c.endMs), })), + // Where each effect is posed, and how. The code is not here: getEffect reads it. + effects: coalesceForAgent(document.shaderEffectRanges ?? []).map((r) => ({ + id: r.id, + effectId: r.effectId, + name: findShaderEffect(document, r.effectId)?.name ?? null, + startSec: roundSec(r.startMs), + endSec: roundSec(r.endMs), + target: r.target, + lane: r.lane, + values: r.values, + })), + effectDefinitions: (document.shaderEffects ?? []).map((e) => ({ + effectId: e.id, + name: e.name, + description: e.description, + contract: e.contract, + lines: e.code.split("\n").length, + regions: coalesceForAgent( + (document.shaderEffectRanges ?? []).filter((r) => r.effectId === e.id), + ).length, + cost: e.cost ?? null, + params: e.params, + })), // Imported audio, collapsed to the pills the ruler draws — a track ventilated // across a clip boundary is several fragments the user sees as one thing, and // the model has to name what the user sees. @@ -1432,6 +1522,71 @@ export function documentSnapshotForModel( }; } +/** A definition as it will be stored: schema-checked, then compiled by the compositor when one is + * wired, its cost cached. An error reads as the agent must act on it. */ +function checkedEffectDefinition( + candidate: unknown, + checker: ShaderEffectChecker | undefined, +): { definition: AxcutShaderEffect; check: ShaderEffectCheck | null } | { error: string } { + const parsed = shaderEffectSchema.safeParse(candidate); + if (!parsed.success) { + return { + error: parsed.error.issues + .map((i) => `${i.path.join(".") || "effect"}: ${i.message}`) + .join("; "), + }; + } + const definition = parsed.data; + const check = checker?.(definition.code, definition.params) ?? null; + if (check?.error) return { error: `The effect does not compile:\n${check.error}` }; + const cost = + check?.tier && typeof check.frameReads === "number" + ? { tier: check.tier, frameReads: check.frameReads } + : undefined; + return { definition: { ...definition, cost }, check }; +} + +/** Two effects of one lane cannot overlap: the refusal names what is in the way, and the way out. */ +function effectLaneBlocked( + ranges: AxcutShaderEffectRange[], + lane: number, + startMs: number, + endMs: number, + except: ReadonlySet = new Set(), +): string | null { + const wall = coalesceRegionsForRuler( + ranges.filter((r) => r.lane === lane && !except.has(r.id)), + ).find((pill) => pill.start * 1000 < endMs && pill.end * 1000 > startMs); + if (!wall) return null; + return ( + `${formatSec(startMs / 1000)} – ${formatSec(endMs / 1000)} would run into effect ${wall.ids[0]} ` + + `at ${formatSec(wall.start)} – ${formatSec(wall.end)} on lane ${lane}, and two effects of one lane ` + + "cannot overlap. Put it on another lane (0–7, applied in order, lane 0 first) or pick a span clear of it." + ); +} + +/** What an effect costs where it was placed: its tier, the busiest moment it shares with the + * other effects, and a recommendation when its tier runs longer than it is meant to. */ +function effectCostReport( + document: AxcutDocument, + definition: AxcutShaderEffect, + startSec: number, + endSec: number, +) { + if (!definition.cost) return { cost: null }; + const busiest = busiestShaderEffectReads(document, startSec * 1000, endSec * 1000); + const advice = shaderEffectCostAdvice(definition.cost.tier, endSec - startSec); + return { + cost: { + tier: definition.cost.tier, + frameReads: definition.cost.frameReads, + busiestTier: shaderEffectTierOf(busiest), + busiestFrameReads: busiest, + ...(advice ? { advice } : {}), + }, + }; +} + function failure(message: string): AgentToolExecution { return { ok: false, resultJson: JSON.stringify({ error: message }) }; } @@ -1578,6 +1733,9 @@ export interface AgentToolOptions { /** Whether this machine can cut out the camera background, asked only by the two tools that * report it. Absent where nothing can ask the compositor: reported as not checked. */ cameraSegmentation?: () => SegmentationSupport; + /** Asks the compositor to check an effect's WGSL (`checkShaderEffect`). Absent where nothing + * can: the effect is stored unchecked, and the result says `validated: false`. */ + checkShaderEffect?: ShaderEffectChecker; /** `addAutoZooms`' plan, made by the async wrapper from the recorded clicks. Absent means * no cursor reader is wired here, which the tool reports as "could not look". */ autoZooms?: AutoZoomPlan; @@ -3169,6 +3327,206 @@ export function executeAgentTool( }; } + case "addEffect": { + const parsed = addEffectArgs.safeParse(args); + if (!parsed.success) return failure(parsed.error.message); + const { effectId, effect, values = {}, target = "image", lane = 0 } = parsed.data; + if ((effectId === undefined) === (effect === undefined)) { + return failure( + "Pass either `effect` to write a new effect, or `effectId` to reuse one of this project's (getCurrentDocument lists them under effectDefinitions), not both.", + ); + } + let definition: AxcutShaderEffect; + let check: ShaderEffectCheck | null = null; + const created = effect !== undefined; + if (effect) { + const checked = checkedEffectDefinition( + { + id: createId("fx"), + ...effect, + contract: SHADER_EFFECT_CONTRACT, + params: effect.params ?? [], + origin: "agent", + }, + options?.checkShaderEffect, + ); + if ("error" in checked) return failure(checked.error); + ({ definition, check } = checked); + } else { + const existing = findShaderEffect(document, effectId as string); + if (!existing) return failure(`Unknown effect: ${effectId}.`); + definition = existing; + } + const startMs = toMs(Math.min(parsed.data.startSec, parsed.data.endSec)); + const endMs = toMs(Math.max(parsed.data.startSec, parsed.data.endSec)); + const blocked = effectLaneBlocked(document.shaderEffectRanges ?? [], lane, startMs, endMs); + if (blocked) return failure(`The effect was NOT placed: ${blocked}`); + const region = { + id: createId("fxr"), + startMs, + endMs, + effectId: definition.id, + values: storedShaderEffectValues(definition, values), + target, + lane, + }; + const placed = anchorForAgent(region, document, "fxr"); + const landing = landingOf(placed, document); + if (!landing.anchored) return coversNoClip("effect", startMs / 1000, endMs / 1000, document); + const next: AxcutDocument = { + ...document, + shaderEffects: created + ? [...(document.shaderEffects ?? []), definition] + : (document.shaderEffects ?? []), + shaderEffectRanges: [...(document.shaderEffectRanges ?? []), ...placed], + }; + return { + ok: true, + document: next, + resultJson: JSON.stringify({ + effectRegionId: landing.ids[0], + effectId: definition.id, + ...landingReport(landing, startMs / 1000, endMs / 1000), + ...(created ? { validated: check !== null } : {}), + ...effectCostReport(next, definition, landing.startSec, landing.endSec), + }), + summary: + `effect "${definition.name}" ${formatSec(landing.startSec)} – ${formatSec(landing.endSec)}` + + landingSuffix(landing, startMs / 1000, endMs / 1000), + }; + } + + case "setEffect": { + const parsed = setEffectArgs.safeParse(args); + if (!parsed.success) return failure(parsed.error.message); + const prev = document.shaderEffectRanges ?? []; + const existing = prev.find((r) => r.id === parsed.data.effectRegionId); + if (!existing) return failure(`Unknown effect region: ${parsed.data.effectRegionId}`); + const definition = findShaderEffect(document, existing.effectId); + if (!definition) return failure(`Effect ${existing.effectId} is missing from the project.`); + const pillIds = new Set(resolvePillIds(prev, existing.id)); + const pill = coalesceRegionsForRuler(prev).find((p) => p.ids.includes(existing.id)); + const { values, target } = parsed.data; + const lane = parsed.data.lane ?? existing.lane; + const patched = prev.map((r) => + pillIds.has(r.id) + ? { + ...r, + values: + values === undefined + ? r.values + : storedShaderEffectValues(definition, { ...r.values, ...values }), + target: target ?? r.target, + lane, + } + : r, + ); + const { startMs, endMs } = resolveSpanMs( + pill + ? { startMs: Math.round(pill.start * 1000), endMs: Math.round(pill.end * 1000) } + : existing, + parsed.data.startSec, + parsed.data.endSec, + ); + const blocked = effectLaneBlocked(patched, lane, startMs, endMs, pillIds); + if (blocked) return failure(`The effect was NOT changed: ${blocked}`); + const moved = parsed.data.startSec !== undefined || parsed.data.endSec !== undefined; + const rebuilt = moved + ? replacePillSpan(patched, existing.id, startMs, endMs, document.timeline.clips, () => + createId("fxr"), + ) + : patched; + const landing = landingAfterPillEdit(prev, rebuilt, pillIds, document); + if (!landing.anchored) return coversNoClip("effect", startMs / 1000, endMs / 1000, document); + const next: AxcutDocument = { ...document, shaderEffectRanges: rebuilt }; + return { + ok: true, + document: next, + resultJson: JSON.stringify({ + effectRegionId: landing.ids[0] ?? existing.id, + effectId: definition.id, + ...landingReport(landing, startMs / 1000, endMs / 1000), + ...effectCostReport(next, definition, landing.startSec, landing.endSec), + }), + summary: + `updated effect "${definition.name}" ${formatSec(landing.startSec)} – ${formatSec(landing.endSec)}` + + landingSuffix(landing, startMs / 1000, endMs / 1000), + }; + } + + case "setEffectDefinition": { + const parsed = setEffectDefinitionArgs.safeParse(args); + if (!parsed.success) return failure(parsed.error.message); + const { effectId, ...patch } = parsed.data; + const existing = findShaderEffect(document, effectId); + if (!existing) return failure(`Unknown effect: ${effectId}.`); + const recompile = patch.code !== undefined || patch.params !== undefined; + const candidate = { + ...existing, + ...Object.fromEntries(Object.entries(patch).filter(([, v]) => v !== undefined)), + cost: recompile ? undefined : existing.cost, + }; + let definition: AxcutShaderEffect; + let check: ShaderEffectCheck | null = null; + if (recompile) { + const checked = checkedEffectDefinition(candidate, options?.checkShaderEffect); + if ("error" in checked) return failure(checked.error); + ({ definition, check } = checked); + } else { + const checked = shaderEffectSchema.safeParse(candidate); + if (!checked.success) return failure(checked.error.message); + definition = checked.data; + } + // The regions follow the new parameters: a removed one's value drops, bounds re-clamp. + const next: AxcutDocument = { + ...document, + shaderEffects: (document.shaderEffects ?? []).map((e) => + e.id === effectId ? definition : e, + ), + shaderEffectRanges: (document.shaderEffectRanges ?? []).map((r) => + r.effectId === effectId + ? { ...r, values: storedShaderEffectValues(definition, r.values) } + : r, + ), + }; + const regions = coalesceForAgent( + (next.shaderEffectRanges ?? []).filter((r) => r.effectId === effectId), + ); + return { + ok: true, + document: next, + resultJson: JSON.stringify({ + effectId, + regions: regions.length, + ...(recompile ? { validated: check !== null } : {}), + ...(definition.cost ? { cost: definition.cost } : {}), + }), + summary: `updated effect "${definition.name}" (${regions.length} region${regions.length === 1 ? "" : "s"})`, + }; + } + + case "getEffect": { + const parsed = getEffectArgs.safeParse(args); + if (!parsed.success) return failure(parsed.error.message); + const effect = findShaderEffect(document, parsed.data.effectId); + if (!effect) return failure(`Unknown effect: ${parsed.data.effectId}.`); + const regions = coalesceForAgent( + (document.shaderEffectRanges ?? []).filter((r) => r.effectId === effect.id), + ).map((r) => ({ + id: r.id, + startSec: roundSec(r.startMs), + endSec: roundSec(r.endMs), + target: r.target, + lane: r.lane, + values: r.values, + })); + return { + ok: true, + resultJson: JSON.stringify({ ...effect, regions }), + summary: `read effect "${effect.name}"`, + }; + } + case "setCameraFullscreen": { const parsed = setCameraFullscreenArgs.safeParse(args); if (!parsed.success) return failure(parsed.error.message); @@ -3411,9 +3769,10 @@ export function executeAgentTool( else if (speedRegions.some((s) => s.id === id)) kind = "speed"; else if (cameraFullscreenRegions.some((c) => c.id === id)) kind = "cameraFullscreen"; else if (document.audioTracks.some((t) => trackGroupId(t) === id)) kind = "audio"; + else if ((document.shaderEffectRanges ?? []).some((r) => r.id === id)) kind = "shaderEffect"; if (!kind) { return failure( - `No zoom / speed / annotation / full-camera / audio modifier with id ${id}. ` + + `No zoom / speed / annotation / full-camera / audio / effect modifier with id ${id}. ` + `For a trim use removeTrim; for a clip use removeClip.`, ); } diff --git a/electron/ai-edition/chat-service.ts b/electron/ai-edition/chat-service.ts index e1e55c94c9..c222a8de44 100644 --- a/electron/ai-edition/chat-service.ts +++ b/electron/ai-edition/chat-service.ts @@ -16,6 +16,7 @@ import { createEmptyDocument, documentSchema, } from "../../src/lib/ai-edition/schema"; +import type { ShaderEffectChecker } from "../../src/lib/ai-edition/shaderEffects"; import type { AiEditionChatMessage, AiEditionChatResult, @@ -322,6 +323,8 @@ export interface ChatRunEnv { cursor?: CursorTelemetryReader; /** Whether this machine can cut out the camera background, asked of the compositor. */ cameraSegmentation?: () => SegmentationSupport; + /** The compositor's check of an agent-written effect's WGSL. */ + checkShaderEffect?: ShaderEffectChecker; /** Runtime-only model retry override used by bounded measurement harnesses. */ maxRetries?: number; } @@ -468,6 +471,7 @@ export async function runChat( editsAllowed, cursor: env.cursor, cameraSegmentation: env.cameraSegmentation, + checkShaderEffect: env.checkShaderEffect, }); // The project was deleted while the agent ran: its sessions are gone, so a diff --git a/electron/ai-edition/deep-agent/service.test.ts b/electron/ai-edition/deep-agent/service.test.ts index 8fa62ea514..22d508fb7a 100644 --- a/electron/ai-edition/deep-agent/service.test.ts +++ b/electron/ai-edition/deep-agent/service.test.ts @@ -83,6 +83,19 @@ const ARGS: Record = { setAnnotation: { annotationId: "ann_nope" }, addCameraFullscreen: { startSec: 1, endSec: 2 }, setCameraFullscreen: { cameraFullscreenId: "cam_nope" }, + // No checker in these tests: the effect is stored unchecked, and the result says so. + addEffect: { + startSec: 1, + endSec: 2, + effect: { + name: "Pass-through", + description: "Shows the frame unchanged.", + code: "fn effect(uv: vec2) -> vec4 { return frame(uv); }", + }, + }, + setEffect: { effectRegionId: "fxr_nope" }, + setEffectDefinition: { effectId: "fx_nope" }, + getEffect: { effectId: "fx_nope" }, // The fixture has no `kind: "audio"` asset, so these exercise the refusal branch — // the honest one to pin: the agent can place imported audio, never import it. addAudio: { assetId: "audio_nope", startSec: 1, endSec: 2 }, @@ -389,6 +402,7 @@ describe("one description of the tools, not two", () => { "getTranscript", "getTranscriptWords", "getCursorTrack", + "getEffect", "getCaptions", "getCaptionTranslationUnits", ]); diff --git a/electron/ai-edition/deep-agent/service.ts b/electron/ai-edition/deep-agent/service.ts index 44571c2dd9..f97fa9cf6a 100644 --- a/electron/ai-edition/deep-agent/service.ts +++ b/electron/ai-edition/deep-agent/service.ts @@ -35,6 +35,7 @@ import { import { AUDIO_FADE_MAX_MS } from "../../../src/lib/ai-edition/document/audioTracks"; import { VOCABULARY_MAX_CHARS } from "../../../src/lib/ai-edition/document/transcript"; import type { AxcutDocument } from "../../../src/lib/ai-edition/schema"; +import type { ShaderEffectChecker } from "../../../src/lib/ai-edition/shaderEffects"; import { collectAutoZoomSuggestionsForDocument } from "../../../src/lib/ai-edition/timeline/apply-auto-zooms"; // ponytail: the legend is DERIVED from the depth→scale table, not retyped. Both // tool descriptions used to assert "depth 1–6 maps to 1.0×–3.5×" — a formula @@ -55,6 +56,7 @@ import { addAudioArgs, addAutoZoomsArgs, addCameraFullscreenArgs, + addEffectArgs, addSpeedArgs, addTrimArgs, addTrimsArgs, @@ -64,6 +66,7 @@ import { duplicateClipArgs, executeAgentTool, getCursorTrackArgs, + getEffectArgs, getTranscriptArgs, getTranscriptWordsArgs, insertClipArgs, @@ -80,6 +83,8 @@ import { setAudioArgs, setCameraFullscreenArgs, setClipRangeArgs, + setEffectArgs, + setEffectDefinitionArgs, setSpeedArgs, setTrimArgs, setWordTextArgs, @@ -149,7 +154,7 @@ const BASE_SYSTEM_PROMPT = [ "You can call the tools below against the live document snapshot; the runtime executes each edit and feeds the result back into the loop.", "The AxcutDocument is the single source of truth. The timeline, the transcript editor, and the chat panel are all direct editors of the same document — when the user places a clip on the timeline, the document updates immediately, and when the timeline is empty, the document has no clips. Your edits operate on the live document, so preserve the user's placed clips.", "", - "Time-bases (do not mix them up): clips and trims are in SOURCE-time seconds of an asset; zooms, speed regions, annotations and camera-fullscreen regions are in VIRTUAL (edited-timeline) seconds — the position on the editor's ruler, where the clips sit end to end. A trim leaves a hole in that ruler rather than shortening it, and a speed region does not stretch it, so the exported video's own clock differs from it as soon as there is a trim or a speed region: always place effects in ruler seconds. getCurrentDocument returns all of them, clearly labelled.", + "Time-bases (do not mix them up): clips and trims are in SOURCE-time seconds of an asset; zooms, speed regions, annotations, camera-fullscreen regions and effects are in VIRTUAL (edited-timeline) seconds — the position on the editor's ruler, where the clips sit end to end. A trim leaves a hole in that ruler rather than shortening it, and a speed region does not stretch it, so the exported video's own clock differs from it as soon as there is a trim or a speed region: always place effects in ruler seconds. getCurrentDocument returns all of them, clearly labelled.", "", // ponytail: these describe what each tool is FOR, deliberately without quoting // user phrasings. A phrase→tool table reads as helpful and is not: it swaps the @@ -167,6 +172,7 @@ const BASE_SYSTEM_PROMPT = [ "- addAudio lays an imported voiceover or music file over a span. It plays an asset the project already has (kind 'audio'); importing or recording one is the editor's job, not a tool you have — so when the project has none, say so rather than naming an id that does not exist.", "- moveClip changes the order of placed clips, one call per clip that moves, preserving ids, source ranges, trims and anchored effects. replaceTimeline rebuilds the timeline from kept intervals and sorts them, so it cannot reorder anything.", "- Captions are the transcript drawn on the video, never typed in: setCaptionSettings turns them on, styles and places them, getCaptions reads them back. To caption in another language, read the phrases with getCaptionTranslationUnits, translate them yourself, store them with putCaptionTranslation, then show that language with setCaptionSettings. A translation never rewrites the transcript. For text the speaker did not say, use addAnnotation.", + "- A visual effect the settings do not offer (a ripple on clicks, a glitch on a cut, a color grade) is written as a shader with addEffect; setEffect re-tunes or moves it, setEffectDefinition changes its code, getEffect reads its code.", "- Deleting is a first-class action, not a workaround: removeTrim, removeModifier, removeClip. Never fake a deletion by re-adding an element or zeroing it out (span 0, speed 1×) — that leaves it in the document and misreports what you did.", "If nothing in the list does what was asked, say so; do not approximate it with a bigger tool.", "", @@ -212,7 +218,7 @@ const CUT_TRANSITIONS_RESULT = `When the result cuts a zoom's move in or out, it export const TOOL_DESCRIPTIONS: Record = { getCurrentDocument: - "Read a compact snapshot of the current project: assets (with durations), timeline clips and trim ranges (source-time), and the zoom / speed / annotation / camera-fullscreen / audio regions (virtual, edited-timeline time), each with the settings its writes take: a zoom's level, focus mode and hidden cursor, an annotation's type, box, look and arrow or blur data, an audio track's level and fades. It also gives the project's look under `settings`, in the shape setEditorSettings takes, with `settingsContext`: the formats, wallpapers and cursor themes on offer, and under `inactive` each setting the editor hides in the current state and why. Call this before editing if the snapshot in the system prompt may be stale. The AxcutDocument is the single source of truth — your edits should preserve the user's placed clips and any timeline state they have already set up.", + "Read a compact snapshot of the current project: assets (with durations), timeline clips and trim ranges (source-time), and the zoom / speed / annotation / camera-fullscreen / audio / effect regions (virtual, edited-timeline time), each with the settings its writes take: a zoom's level, focus mode and hidden cursor, an annotation's type, box, look and arrow or blur data, an audio track's level and fades. It also gives the project's look under `settings`, in the shape setEditorSettings takes, with `settingsContext`: the formats, wallpapers and cursor themes on offer, and under `inactive` each setting the editor hides in the current state and why. Call this before editing if the snapshot in the system prompt may be stale. The AxcutDocument is the single source of truth — your edits should preserve the user's placed clips and any timeline state they have already set up.", getTranscript: "Read the transcript segments (speech and silence, with start/end seconds and text) for an asset. Omit assetId to read the primary asset's transcript.", getCursorTrack: @@ -256,6 +262,14 @@ export const TOOL_DESCRIPTIONS: Record = { 'Change the project\'s look: pass only the settings to change, named as getCurrentDocument returns them under `settings`. Background: wallpaper (a bundled path from settingsContext.bundledWallpapers, a CSS colour or gradient, or a base64 PNG/JPEG data URL; never a file path or web URL; an embedded image reads back as a marker, leave the key out to keep it), wallpaperMotion (moves a gradient or image only), backgroundBlur 0–1. Frame: aspectRatio ("auto", a preset, or an originalAspectRatios token; a fixed format picked for the first time fills the frame with a window that follows the cursor, which formatFollowCursor turns off when settingsContext.formatFill is "available"), padding 0–100 %, borderRadius 0–64 px, shadowIntensity 0–1, frame (none, window, laptop, phone, monitor) and frameTheme (light, dark), motionBlurAmount 0–1, depthOfField (blurs 3D-tilted zooms only). Camera: webcamLayoutPreset, webcamMirrored, webcamReactiveZoom (shrinks on zoom), webcamMaskShape (square or rectangle, the camera\'s own proportions; an untouched roundness follows it), webcamRoundness 0–1, webcamSizePreset 15–60, webcamAnchor (a corner or an edge middle), webcamCropRegion (the framing: a square share of the picture, width = height ≥ 1/3) and webcamCropPan (where that window sits, 0–1 per axis, 0.5 centred), webcamBackgroundMode (none, transparent, blur, custom: needs settingsContext.cameraSegmentation ready), webcamBlurIntensity 0–1, webcamWallpaper (as wallpaper). Cursor, under `cursor`: show, autoHide, theme (settingsContext.cursorThemes), asArrow (the recorded cursor kinds drawn as the arrow instead), size 1.5–6, smoothing 0–1, motionBlur 0–1, clickBounce 0–2, clickImpact, clickSound (only heard when the take recorded clicks) and clickSoundGainDb −24–0, model3d. Also autoFocusAll (every zoom follows the cursor) and audioGainDb −12–12 dB, the master volume. A value out of range or a key not listed is refused with the reason, and nothing changes. The result lists what was applied, including what the editor changes with it, and `inactive` for any of those the current state leaves without effect.', addCameraFullscreen: "Add a camera-fullscreen region over a span of the edited timeline (virtual seconds): the webcam fills the frame for that span. This only does something when the footage under that span comes from an asset with a linked webcam — check assets[].hasCameraTrack (or hasAnyCamera) in getCurrentDocument first. On footage with no camera the call is refused rather than storing a region that would render nothing; say so instead of retrying.", + addEffect: + "Write a visual effect as a shader and pose it over a span of the edited timeline (virtual seconds), or pose one of this project's effects again (effectId). Use it for a look the settings do not offer. `effect.code` is WGSL that defines `fn effect(uv: vec2) -> vec4`, called for every pixel; uv is 0..1 with (0,0) top-left. Available inside it: `frame(uv)` samples the composed picture; `params.` reads each declared parameter; `ctx.time` is programme seconds; `ctx.region.x` goes 0 to 1 across the region (y its length in s, z seconds since it began); `ctx.resolution` and `ctx.aspect`; `ctx.cursor` (xy in uv, z = 1 when on screen); `ctx.clicks[0..3]`, the last four clicks, newest first (xy in uv where it happened, z seconds since, w = 1 when the slot holds one); `ctx.footage` and `ctx.camera`, the recording's and the webcam's rects (x, y, w, h in uv; camera zero-sized when absent) — all already placed through zoom and layout; `fx_px(n)`, n pixels of a 1080p frame as a fraction of the height; `fx_hash(vec2)`, a random number in [0,1) identical on every GPU. Rules: the effect is a pure function of those inputs (no state between frames), so the preview and the export show the same pixels; reason in uv or fx_px, never raw pixels; every loop is a `for` with literal bounds (`for (var i = 0; i < 16; i++)`), at most 4096 iterations per pixel — the one hard rule. `params` declares up to 8 (recommended) parameters, each `{type: number|toggle|color|point, name, label, default}` (number also `min`, `max`); declare one only when moving it visibly changes the effect over its whole range. `target`: `image` (default: the picture under the annotations and captions), `text` (the annotations and captions alone, premultiplied alpha), `both` (everything); use text or both only when asked. Effects of one `lane` (0–7) cannot overlap; lanes apply in order, lane 0 first. The result gives the cost tier (frame() reads per pixel: light ≤ 8, about 0.06 ms per 1080p frame on a fast GPU; medium ≤ 32, 0.14 ms; heavy ≤ 128, 0.54 ms; very heavy beyond) and a recommendation when the tier runs long: light anywhere, medium up to a minute, heavy up to 10 s, very heavy a few seconds. It is a recommendation, never a refusal. Code that does not compile is refused with the compiler's error at the line of your code: fix it and call again. Check the result with getFrames.", + setEffect: + "Move, resize or re-tune an effect region by id (virtual seconds): its span, its parameter `values`, its `target` or its `lane`. Only the fields you pass change; a value equal to the default is dropped. Refused if the new span runs into another effect of the same lane.", + setEffectDefinition: + "Change an effect itself by effectId — its name, description, WGSL `code` or `params` — and with it every region that uses it. New code is compiled first and refused with the compiler's error if it does not compile. A removed parameter's values drop; the bounds re-clamp the others. Read the current code with getEffect before rewriting it.", + getEffect: + "Read one effect of the project in full: its WGSL code, parameters, description, cost and the regions that use it. getCurrentDocument lists effects without their code.", setCameraFullscreen: "Move or resize an existing camera-fullscreen region by id (virtual-timeline seconds). Only the fields you pass are changed. Refused if the new span lands on footage with no linked webcam.", addAudio: `Lay an ALREADY-IMPORTED audio file over the recording across a span of the edited timeline (virtual seconds): a voiceover, or a music bed. assetId must name an asset whose kind is 'audio' — getCurrentDocument lists them. If there is none, a file has to be imported first (importMedia, where it is offered): never guess an id. Omit endSec to play the whole file from offsetSec. kind picks the lane ('voiceover' or 'music'). offsetSec is where in the FILE playback starts, gainDb its level (0 unchanged, negative ducks it), fadeInMs / fadeOutMs its fades (0 to ${AUDIO_FADE_MAX_MS} ms, default none; a track too short for both shares its span between them). A voiceover-lane track is also what gets transcribed, so the lane is not only cosmetic.`, @@ -263,7 +277,7 @@ export const TOOL_DESCRIPTIONS: Record = { removeTrim: "Delete a trim range by id — the cut is undone and that span plays/exports again. This is how you 'remove a trim'; never re-add a trim to undo one.", removeModifier: - "Delete a modifier (zoom / speed / annotation / camera-fullscreen / audio) by id; the kind is resolved from the id. Touching rows with the same styling render as one pill and are deleted together, so read removedIds in the result for the complete set that disappeared. This is how you 'remove'/'delete' one — never neutralise it (span 0, speed 1×), which leaves it in the document. For a trim use removeTrim; for a clip use removeClip.", + "Delete a modifier (zoom / speed / annotation / camera-fullscreen / audio / effect) by id; the kind is resolved from the id. Touching rows with the same styling render as one pill and are deleted together, so read removedIds in the result for the complete set that disappeared. This is how you 'remove'/'delete' one — never neutralise it (span 0, speed 1×), which leaves it in the document. For a trim use removeTrim; for a clip use removeClip.", removeClip: "Delete a placed clip by id; remaining clips close the gap and effects anchored to it are dropped. Use only when the user asks to remove a clip — to shorten one, use setClipRange.", getCaptions: @@ -310,6 +324,8 @@ export interface ToolRuntime { availableByAssetId?: Record; /** Asks the compositor whether this machine can cut out the camera background. */ cameraSegmentation?: () => SegmentationSupport; + /** Asks the compositor to check an effect's WGSL. */ + checkShaderEffect?: ShaderEffectChecker; } /** @@ -393,6 +409,7 @@ export async function runDocumentTool( editsAllowed, cursorTelemetry: { availableByAssetId: runtime.availableByAssetId, load }, cameraSegmentation: runtime.cameraSegmentation, + checkShaderEffect: runtime.checkShaderEffect, autoZooms, }); } @@ -504,6 +521,10 @@ export const TOOL_ARG_SCHEMAS: ReadonlyArray = [ ["setAnnotation", setAnnotationArgs], ["addCameraFullscreen", addCameraFullscreenArgs], ["setCameraFullscreen", setCameraFullscreenArgs], + ["addEffect", addEffectArgs], + ["setEffect", setEffectArgs], + ["setEffectDefinition", setEffectDefinitionArgs], + ["getEffect", getEffectArgs], ["addAudio", addAudioArgs], ["setAudio", setAudioArgs], ["removeTrim", removeTrimArgs], @@ -556,6 +577,8 @@ export interface InvokeArgs { cursor?: CursorTelemetryReader; /** Injected the same way: whether this machine can cut out the camera background. */ cameraSegmentation?: () => SegmentationSupport; + /** Injected the same way: the compositor's check of an effect's WGSL. */ + checkShaderEffect?: ShaderEffectChecker; } /** One cheap probe per asset, run before the tools are built so the very first @@ -631,6 +654,7 @@ export async function invokeOpenScreenAgent(args: InvokeArgs): Promise { const doc = migrateProjectDataToAxcutDocument({ @@ -40,7 +40,19 @@ async function writeDocument(relative: string, screenVideoPath: string): Promise const speedRegions = [{ id: "s1", startMs: 0, endMs: 500, speed: 2 }]; return make( relative, - JSON.stringify({ ...doc, legacyEditor: { ...doc.legacyEditor, speedRegions } }), + JSON.stringify({ + ...doc, + legacyEditor: { ...doc.legacyEditor, speedRegions }, + shaderEffects: [ + { + id: "fx1", + name: "Pass-through", + contract: 1, + code: "fn effect(uv: vec2) -> vec4 { return frame(uv); }", + }, + ], + shaderEffectRanges: [{ id: "fxr1", startMs: 0, endMs: 500, effectId: "fx1" }], + }), ); } @@ -158,6 +170,7 @@ describe("runInfoCommand", () => { trimRegions: 1, speedRegions: 0, annotationRegions: 0, + shaderEffectRegions: 0, exportFormat: "mp4", screenVideoExists: true, }); @@ -179,6 +192,7 @@ describe("a project the editor saved", () => { zoomRegions: 1, trimRegions: 0, speedRegions: 1, + shaderEffectRegions: 1, }); }); diff --git a/electron/cli/projectCommands.ts b/electron/cli/projectCommands.ts index 6866eb92a6..394c33f532 100644 --- a/electron/cli/projectCommands.ts +++ b/electron/cli/projectCommands.ts @@ -164,6 +164,7 @@ export async function runInfoCommand( trimRegions: fields.trimRegions, speedRegions: fields.speedRegions, annotationRegions: fields.annotationRegions, + shaderEffectRegions: fields.shaderEffectRegions, }; if (json) { @@ -176,7 +177,7 @@ export async function runInfoCommand( `Webcam: ${summary.webcamVideoPath ?? "(none)"}`, `Cursor: ${summary.cursorCaptureMode ?? "(unknown)"}`, `Export: ${summary.exportFormat ?? "?"} / ${summary.exportQuality ?? "?"} / ${summary.aspectRatio ?? "?"}`, - `Timeline: ${summary.zoomRegions} zooms, ${summary.trimRegions} trims, ${summary.speedRegions} speed regions, ${summary.annotationRegions} annotations`, + `Timeline: ${summary.zoomRegions} zooms, ${summary.trimRegions} trims, ${summary.speedRegions} speed regions, ${summary.annotationRegions} annotations, ${summary.shaderEffectRegions} effects`, ].join("\n") + "\n", ); } @@ -197,6 +198,8 @@ interface ProjectInfoFields { trimRegions: number; speedRegions: number; annotationRegions: number; + /** Shader effect regions (stored fragments, like the other counts). A v2 project has none. */ + shaderEffectRegions: number; } const stringOrNull = (value: unknown): string | null => (typeof value === "string" ? value : null); @@ -217,6 +220,7 @@ function legacyInfoFields(data: PackedProjectData): ProjectInfoFields { trimRegions: count("trimRegions"), speedRegions: count("speedRegions"), annotationRegions: count("annotationRegions"), + shaderEffectRegions: 0, }; } @@ -242,5 +246,6 @@ function documentInfoFields(doc: ReturnType): ProjectI trimRegions: doc.timeline.trimRanges.length, speedRegions: Array.isArray(editor.speedRegions) ? editor.speedRegions.length : 0, annotationRegions: doc.annotations.length, + shaderEffectRegions: doc.shaderEffectRanges?.length ?? 0, }; } diff --git a/electron/ipc/handlers.ts b/electron/ipc/handlers.ts index 8a3fa45d32..19ba6b3f5d 100644 --- a/electron/ipc/handlers.ts +++ b/electron/ipc/handlers.ts @@ -5062,6 +5062,7 @@ export function registerIpcHandlers( editsAllowed: () => mcpSettings.getSettings().allowEdits, cursor: agentCursorTelemetryReader, cameraSegmentation: () => loudnessService.probeSegmentation(), + checkShaderEffect: (code, params) => loudnessService.checkShaderEffect(code, params), // The editor's own engine, in this process: `openscreen mcp` transcribes without the app. transcribe: (request) => getSttManager().transcribe(request), version: app.getVersion(), @@ -5234,6 +5235,7 @@ export function registerIpcHandlers( runChat(projectId, sessionId, message, getAiEditionLlmConfig(), document, sink, { cursor: agentCursorTelemetryReader, cameraSegmentation: () => loudnessService.probeSegmentation(), + checkShaderEffect: (code, params) => loudnessService.checkShaderEffect(code, params), }), undoAiEditionToolBatch: (_projectId, _sessionId) => ({ success: false, diff --git a/electron/mcp/effects-contract.test.ts b/electron/mcp/effects-contract.test.ts new file mode 100644 index 0000000000..fce3e8b65f --- /dev/null +++ b/electron/mcp/effects-contract.test.ts @@ -0,0 +1,39 @@ +import { readFileSync } from "node:fs"; +import path from "node:path"; +import { describe, expect, it } from "vitest"; +import { EFFECTS_CONTRACT } from "./effects-contract"; + +// The compositor's prelude is the authority on what an effect can read; the resource agents read +// must name every field of it, or an agent writes against a contract that is not the real one. +describe("the effect contract resource", () => { + const shaderFx = readFileSync( + path.join(__dirname, "../../crates/compositor/src/shader_fx.rs"), + "utf8", + ); + const prelude = shaderFx.slice( + shaderFx.indexOf("pub const PRELUDE_V1"), + shaderFx.indexOf("@group(0) @binding(0)"), + ); + const fields = [...prelude.matchAll(/^\s+([a-z_]+): /gm)].map((m) => m[1]); + + it("names every field of the compositor's FxContext", () => { + expect(fields).toEqual( + expect.arrayContaining([ + "resolution", + "time", + "region", + "cursor", + "clicks", + "footage", + "camera", + ]), + ); + for (const field of fields) expect(EFFECTS_CONTRACT).toContain(`ctx.${field}`); + }); + + it("names every helper the prelude gives", () => { + for (const helper of ["frame(uv)", "fx_px(n)", "fx_hash(p)"]) { + expect(EFFECTS_CONTRACT).toContain(helper); + } + }); +}); diff --git a/electron/mcp/effects-contract.ts b/electron/mcp/effects-contract.ts new file mode 100644 index 0000000000..929de027e9 --- /dev/null +++ b/electron/mcp/effects-contract.ts @@ -0,0 +1,131 @@ +/** + * The WGSL contract of agent-written shader effects, served as an MCP resource + * (`openscreen://effects/contract`): too long for a tool description, and versioned with the + * contract. The compositor's prelude (`crates/compositor/src/shader_fx.rs`) is the authority; + * `effects-contract.test.ts` checks that every `ctx` field it declares is described here. + * The design is in docs/shader-effects.md. + */ + +export const EFFECTS_CONTRACT_URI = "openscreen://effects/contract"; + +export const EFFECTS_NOTE = `Before writing a shader effect with addEffect, read the resource ${EFFECTS_CONTRACT_URI}: the full WGSL contract and two examples.`; + +export const EFFECTS_CONTRACT = `# OpenScreen shader effects — WGSL contract 1 + +An effect is WGSL that defines one function, called for every pixel of the output: + + fn effect(uv: vec2) -> vec4 + +\`uv\` runs from (0, 0) top-left to (1, 1) bottom-right of the output. Return the pixel's color. +Declare nothing else the compositor provides: bindings, entry points and the inputs below are +added after your code, so compiler errors point at your lines. + +## Inputs + +| Name | Type | Meaning | +|---|---|---| +| frame(uv) | vec4 | The composed picture at uv (bilinear, edges clamped). | +| ctx.resolution | vec2 | Output size in pixels. | +| ctx.aspect | f32 | Width over height, for round distances in uv. | +| ctx.time | f32 | Programme seconds, continuous through cuts, clips and speed changes. | +| ctx.region | vec4 | x: progress 0 → 1 across the whole region; y: its length in s; z: seconds since it began. | +| ctx.cursor | vec4 | xy: the pointer tip in uv; z: 1 when it is on screen. | +| ctx.clicks[i] | vec4 | The last 4 clicks of the last 2 s, newest first. xy: where it happened, in uv; z: seconds since; w: 1 when the slot holds one. | +| ctx.footage | vec4 | The recording's rect in uv (x, y, w, h), after zoom and layout; under a 3D tilt, its bounding box. | +| ctx.camera | vec4 | The webcam's rect in uv; zero-sized without a camera. | +| params. | per type | Your declared parameters. | +| fx_px(n) | f32 | n pixels of a 1080p output, as a fraction of the height. | +| fx_hash(p) | f32 | A random number in [0, 1) for a vec2, identical on every GPU. | + +Everything in uv is already placed through zoom, layout, frame and tilt: never recompute where +the screen, the camera or the pointer sit. + +## Parameters + +Declare each one as \`{ type, name, label, default }\`; a number also takes \`min\` and \`max\`. + +| type | WGSL | value in the document | +|---|---|---| +| number | f32 | a number between min and max | +| toggle | f32 (0 or 1) | true or false | +| color | vec4 (RGBA, 0..1) | "#rrggbb" or "#rrggbbaa" | +| point | vec2 (uv) | { "x": 0.5, "y": 0.5 } | + +Names are snake_case. Up to 8 is recommended. Declare a parameter only when moving it visibly +changes the effect over its whole range: each one becomes a control in the editor. + +## Rules + +- **Pure.** The result depends only on uv, frame(), ctx and params. No state between frames, no + clock, no frame counter: the preview jumps between frames when seeking, the export renders them + in order, and both must show the same picture. +- **Resolution-free.** The preview renders smaller than the export: measure in uv or fx_px. +- **Random through fx_hash.** \`fract(sin(x) * 43758.5453)\` differs from one GPU to another. +- **Loops are \`for\` with literal bounds**: \`for (var i = 0; i < 16; i++)\`. Any other loop is + refused, and so is more than 4096 iterations per pixel: a loop that never ends stalls the GPU. + This is the one hard rule. +- **Alpha.** For the targets image and both, the returned color replaces the pixel; return + \`frame(uv).a\` as alpha. For the target text, frame() is the text layer in premultiplied alpha, + transparent outside the text, and the effect must return premultiplied alpha. + +## Targets and lanes + +- **image** (default): the picture under the annotations and captions; the text stays readable. +- **text**: the annotations and captions alone, drawn over the untouched picture afterwards. +- **both**: everything, captions included. + +Use text or both only when the request asks for them. Effects of one lane (0–7) cannot overlap; +lanes apply in order, lane 0 first, so a ripple across the whole video and a glitch on a cut go on +two lanes. + +## Cost + +The result of addEffect gives the cost in frame() reads per pixel, counted from the code (loops +multiplied by their bound), and its tier. Measured on a fast GPU (RTX 4070 Ti) at 1080p: + +| Tier | Reads | Per frame | Recommended for | +|---|---|---|---| +| light | ≤ 8 | ≤ 0.06 ms | anywhere, the whole video included | +| medium | ≤ 32 | ≤ 0.14 ms | up to a minute | +| heavy | ≤ 128 | ≤ 0.54 ms | up to 10 s: a transition, a key moment | +| very heavy | more | 2 ms at 512 | a few seconds | + +An integrated GPU pays several times more. The tiers are recommendations, never refusals. + +## Example: a ripple on every click + +Parameters: strength (number, 0–2, default 1), radius (number, 0.05–0.5, default 0.2), +duration (number, 0.3–2, default 0.9). + + fn ripple(uv: vec2, click: vec4) -> vec2 { + if (click.w < 0.5 || click.z > params.duration) { return vec2(0.0); } + let t = click.z / params.duration; + let d = (uv - click.xy) * vec2(ctx.aspect, 1.0); + let r = length(d); + let x = params.radius * (1.0 - pow(1.0 - t, 3.0)) - r; + let env = smoothstep(-0.008, 0.0, x) * exp(-max(x, 0.0) / 0.07); + let wave = sin(x / 0.03 * 6.2831853) * env * (1.0 - t) * (1.0 - t) * params.strength; + let dir = select(vec2(0.0), d / r, r > 1e-5); + return dir * wave * 0.01 / vec2(ctx.aspect, 1.0); + } + + fn effect(uv: vec2) -> vec4 { + var offset = vec2(0.0); + for (var i = 0; i < 4; i++) { offset += ripple(uv, ctx.clicks[i]); } + return frame(uv - offset); + } + +## Example: a vignette that breathes across the region + +Parameters: depth (number, 0–1, default 0.6), tint (color, default "#000000"). + + fn effect(uv: vec2) -> vec4 { + let c = frame(uv); + let v = (uv - 0.5) * vec2(ctx.aspect, 1.0); + let pulse = sin(ctx.region.x * 3.14159265); + let k = smoothstep(0.35, 0.9, length(v)) * params.depth * pulse; + return vec4(mix(c.rgb, params.tint.rgb, k), c.a); + } + +Check the result with getFrames at the moments that matter. +`; diff --git a/electron/mcp/media-tools.test.ts b/electron/mcp/media-tools.test.ts index f37708fa39..b86ee8a90b 100644 --- a/electron/mcp/media-tools.test.ts +++ b/electron/mcp/media-tools.test.ts @@ -37,10 +37,23 @@ class FakeRunners { /** Set: exports stay running until `releaseExport` is called. */ holdExport = false; releaseExport: () => void = () => undefined; + private exportHeld: () => void = () => undefined; open = 0; constructor(private readonly videoPath: string) {} + /** + * Holds exports until `releaseExport`. Resolves once one has started: by then the server + * counts it as running and has read the project it renders. A fixed sleep guessed at that + * moment, and lost the race whenever the full suite loaded the machine. + */ + holdExports(): Promise { + this.holdExport = true; + return new Promise((resolve) => { + this.exportHeld = resolve; + }); + } + start(request: CliRequest, handlers: RunnerHandlers = {}) { this.started.push(request); this.open++; @@ -71,6 +84,7 @@ class FakeRunners { const result = this.results[request.kind] ?? { success: true }; if (request.kind === "export" && this.holdExport) { this.releaseExport = () => finish(result); + this.exportHeld(); } else if (request.kind !== "record") { finish(result); } else if (this.recordStarts) { @@ -661,9 +675,9 @@ describe("exportVideo", () => { it("runs one export at a time, and closes each runner once it is done", async () => { const { projectId } = await recordTake(); - runners.holdExport = true; + const held = runners.holdExports(); const first = call("exportVideo", { projectId, path: path.join(dir, "a.mp4") }); - await new Promise((resolve) => setTimeout(resolve, 20)); + await held; const second = await call("exportVideo", { projectId, path: path.join(dir, "b.mp4") }); expect(second.isError).toBe(true); expect(textOf(second)).toContain("already running"); @@ -720,9 +734,9 @@ describe("getFrames on a project", () => { const out = path.join(dir, "demo.mp4"); runners.results.export = { success: true, outputPath: out }; - runners.holdExport = true; + const held = runners.holdExports(); const exporting = call("exportVideo", { projectId: first.projectId, path: out }); - await new Promise((resolve) => setTimeout(resolve, 20)); + await held; await call("addTrim", { projectId: first.projectId, startSec: 2, endSec: 4 }); runners.releaseExport(); expect(textOf(await exporting)).toContain("changed while it exported"); diff --git a/electron/mcp/openscreen-mcp-server.ts b/electron/mcp/openscreen-mcp-server.ts index 7b0f3ec38f..257bd70897 100644 --- a/electron/mcp/openscreen-mcp-server.ts +++ b/electron/mcp/openscreen-mcp-server.ts @@ -54,6 +54,7 @@ import { withTranscript, } from "../../src/lib/ai-edition/document/transcript"; import { type AxcutDocument, documentSchema } from "../../src/lib/ai-edition/schema"; +import type { ShaderEffectChecker } from "../../src/lib/ai-edition/shaderEffects"; import { segmentsFromStt, transcriptFromSegments, @@ -83,6 +84,7 @@ import { type ProjectVersion, } from "../ai-edition/document-service"; import type { SttTranscribeRequest, SttTranscribeResponse } from "../stt/transcriptionContract"; +import { EFFECTS_CONTRACT, EFFECTS_CONTRACT_URI, EFFECTS_NOTE } from "./effects-contract"; import type { MediaTools } from "./media-tools"; import { IMPORT_MEDIA_TOOL, @@ -170,6 +172,8 @@ export interface McpToolDeps extends ImportMediaDeps { cursor?: CursorTelemetryReader; /** Whether this machine can cut out the camera background; absent where nothing can ask. */ cameraSegmentation?: () => SegmentationSupport; + /** The compositor's check of an agent-written effect's WGSL; absent where nothing can ask. */ + checkShaderEffect?: ShaderEffectChecker; /** The main process's on-device Whisper (`SttManager.transcribe`). Absent: no transcribe tool. */ transcribe?(request: SttTranscribeRequest): Promise; version: string; @@ -295,6 +299,7 @@ export function mcpInstructions(options: { ] : []), ...(options.transcribe ? [TRANSCRIBE_NOTE] : []), + EFFECTS_NOTE, "", ].join("\n"); return ( @@ -574,6 +579,7 @@ export function createToolRunner(deps: McpToolDeps): McpToolRunner { cursor: deps.cursor, availableByAssetId, cameraSegmentation: deps.cameraSegmentation, + checkShaderEffect: deps.checkShaderEffect, }); } @@ -925,6 +931,20 @@ export function createOpenScreenMcpServer( ); } media?.register(server); + // The effect contract: too long for addEffect's description, and versioned with the contract. + server.registerResource( + "effects-contract", + EFFECTS_CONTRACT_URI, + { + title: "Shader effect contract", + description: + "The WGSL contract of addEffect: the inputs an effect reads, its parameters, the rules, the cost tiers and two examples.", + mimeType: "text/markdown", + }, + async (uri) => ({ + contents: [{ uri: uri.href, mimeType: "text/markdown", text: EFFECTS_CONTRACT }], + }), + ); return server; } diff --git a/electron/native-bridge/services/compositorViewService.ts b/electron/native-bridge/services/compositorViewService.ts index ebab7e0baf..9a88969e1f 100644 --- a/electron/native-bridge/services/compositorViewService.ts +++ b/electron/native-bridge/services/compositorViewService.ts @@ -3,6 +3,7 @@ import { createRequire } from "node:module"; import path from "node:path"; import { fileURLToPath } from "node:url"; import { app, sharedTexture, type WebFrameMain } from "electron"; +import type { ShaderEffectCheck } from "../../../src/lib/ai-edition/shaderEffects"; import { type CursorKind, readCursorAsArrow, @@ -588,6 +589,21 @@ export class CompositorViewService { return resolveSceneAssetPath(SEGMENTATION_MODEL_ASSET) ? "ready" : "no-model"; } + /** Checks an agent-written effect's WGSL in the compositor (`docs/shader-effects.md`, E.3): the + * compile error, or the cost tier. `null` when this addon cannot answer, which the agent tools + * report as "not checked" rather than as a compile failure. */ + checkShaderEffect( + code: string, + params: ReadonlyArray<{ name: string; type: string }>, + ): ShaderEffectCheck | null { + const addon = this.ensureAddon(); + if (!addon || typeof addon.checkShaderEffect !== "function") return null; + return addon.checkShaderEffect( + code, + JSON.stringify(params.map(({ name, type }) => ({ name, type }))), + ); + } + /** Subject mask for one camera frame, no view needed — see `segmentFrame` in the addon. * `null` when the addon (or this version of it) or the model is missing. */ async segmentFrame(rgba: Uint8Array): Promise { diff --git a/electron/native/compositor-view/addon.d.ts b/electron/native/compositor-view/addon.d.ts index 5a285bb4eb..de1bb08d75 100644 --- a/electron/native/compositor-view/addon.d.ts +++ b/electron/native/compositor-view/addon.d.ts @@ -63,6 +63,18 @@ export interface NativeSharedFramePacket { sourceTimeSec?: number; } +/** What `checkShaderEffect` learns of an agent-written effect (`docs/shader-effects.md`, E.3). */ +export interface ShaderEffectCheck { + /** The error as the agent must read it (line, column, excerpt); absent when accepted. */ + error?: string | null; + /** The indicative cost tier: never a refusal. */ + tier?: "light" | "medium" | "heavy" | "very-heavy" | null; + /** `frame()` reads per pixel, loops multiplied by their bound. */ + frameReads?: number | null; + /** Loop iterations per pixel. */ + iterations?: number | null; +} + export interface ExportStats { frames: number; wallS: number; @@ -143,6 +155,10 @@ export interface CompositorViewAddon { /** What this machine offers, asked without allocating a view — the export dialog * needs the answer before any preview exists. Cached native-side. */ probeBackend(): CompositorBackend; + /** Checks an effect's WGSL: validation, literal loop bounds, the real compile for this machine's + * backend where there is one (FXC on Windows), and the cost tier. `paramsJson` is the declared + * parameters, `[{ "name": "strength", "type": "number" }, …]`. Absent from older builds. */ + checkShaderEffect?(code: string, paramsJson: string): ShaderEffectCheck; /** Whether the ONNX Runtime library is where the app staged it, and therefore whether a * segmentation mask can be produced at all. Asked of the machine rather than guessed from diff --git a/skills/openscreen-demo/SKILL.md b/skills/openscreen-demo/SKILL.md index 8fff292bfe..b6450dabb0 100644 --- a/skills/openscreen-demo/SKILL.md +++ b/skills/openscreen-demo/SKILL.md @@ -86,6 +86,7 @@ Use the document tools, always with the `projectId`. Read the project first with - **Frame the app:** when the take shows more than the app, `setClipRange` with a `cropRegion` crops the clip to it. - **Callouts:** one `addAnnotation` per beat, short, placed clear of the action. Text sits on the output frame and stays put when the picture zooms. Use its look for hierarchy: a large title with `animation: "typewriter"`, step callouts with `animation: "pop"`. An arrow, `type: "figure"`, points at a control the text names. `setAnnotation` moves or restyles one. - **Hide what is private:** an email address, a token or a name that shows on screen gets `addAnnotation` with `type: "blur"` over the span it is visible. Its x, y, width and height are percent of the recording's picture, not of the frame, so it stays on what it hides when a zoom moves the picture. Check it with `getFrames`. +- **An effect no setting offers** (a ripple on each click, a glitch on a cut, a color grade): read the resource `openscreen://effects/contract`, then write it as WGSL with `addEffect`. It reads the clicks and the pointer already placed on the frame. Code that does not compile comes back with the compiler's error at your line: fix it and call again. The result gives a cost tier; keep heavy effects to short spans. Check the effect with `getFrames` at the moments it acts. - **Music or a voiceover:** `importMedia` with the file's absolute path adds it to the project's media, then `addAudio` plays it over a span. `removeMedia` takes back a file the timeline no longer uses. - **Name:** `setProjectInfo` renames the project, if the `title` given to `stopRecording` no longer fits. - **Captions, for a narrated take** (`startRecording` with `microphone: true`): diff --git a/src/components/ai-edition/NewEditorShell.tsx b/src/components/ai-edition/NewEditorShell.tsx index 08b52f21e5..5c1974a2d5 100644 --- a/src/components/ai-edition/NewEditorShell.tsx +++ b/src/components/ai-edition/NewEditorShell.tsx @@ -1173,6 +1173,8 @@ export function NewEditorShell() { return; } + // The editor has no effect lane yet, so nothing selects a shader effect to copy. + if (sel.kind === "shaderEffect") return; const source = sel.kind === "zoom" ? tl.zoomRegions diff --git a/src/lib/ai-edition/document/timeline.test.ts b/src/lib/ai-edition/document/timeline.test.ts index 7f203f32a0..765e07202c 100644 --- a/src/lib/ai-edition/document/timeline.test.ts +++ b/src/lib/ai-edition/document/timeline.test.ts @@ -1962,6 +1962,50 @@ describe("removeClip — delete a clip, close the gap, drop its pills", () => { expect(next.zoomRanges[0]).toMatchObject({ startMs: 2000, endMs: 4000 }); }); + // A shader effect is a region like a zoom: it moves with its clip and goes with it. Its + // definition goes with its last region, so no dead code stays in the document. + it("moves a shader effect with its clip, and drops it and its definition with the clip", () => { + const effect = { + id: "fx", + name: "Pass-through", + description: "", + contract: 1, + code: "fn effect(uv: vec2) -> vec4 { return frame(uv); }", + params: [], + origin: "agent" as const, + }; + const range = (id: string, clipId: string, startMs: number) => ({ + id, + clipId, + sourceStartSec: 2, + sourceEndSec: 4, + startMs, + endMs: startMs + 2000, + effectId: "fx", + values: {}, + target: "image" as const, + lane: 0, + }); + const before = { ...doc(), shaderEffects: [effect] }; + const onB = removeClip( + { + ...before, + shaderEffectRanges: [range("fx_a", "clip_a", 2000), range("fx_b", "clip_b", 12000)], + }, + "clip_a", + ); + expect(onB.shaderEffectRanges).toEqual([ + expect.objectContaining({ id: "fx_b", startMs: 2000 }), + ]); + expect(onB.shaderEffects).toEqual([effect]); + const gone = removeClip( + { ...before, shaderEffectRanges: [range("fx_a", "clip_a", 2000)] }, + "clip_a", + ); + expect(gone.shaderEffectRanges).toEqual([]); + expect(gone.shaderEffects).toEqual([]); + }); + it("preserves a bare clipId that is not a complete source anchor", () => { const before = doc(); before.zoomRanges.push( diff --git a/src/lib/ai-edition/document/timeline.ts b/src/lib/ai-edition/document/timeline.ts index 4e1a751419..2b8366ba31 100644 --- a/src/lib/ai-edition/document/timeline.ts +++ b/src/lib/ai-edition/document/timeline.ts @@ -21,6 +21,7 @@ import type { */ export type PlaybackSegment = AxcutClip; +import { pruneUnusedShaderEffects } from "../shaderEffects"; import { type Interval, subtractInterval } from "../timeline/intervals"; import { keptRawSpans } from "../timeline/programme-time"; import { @@ -43,7 +44,14 @@ import { createId } from "./ids"; * exist" has exactly one definition. `trim` is a source-time cut; the rest are pill-merged * effects (zoom / speed / annotation / camera-fullscreen). Clips are removed via * {@link removeClip}, not here — deleting a clip reflows the whole timeline. */ -export type RegionKind = "zoom" | "trim" | "annotation" | "speed" | "cameraFullscreen" | "audio"; +export type RegionKind = + | "zoom" + | "trim" + | "annotation" + | "speed" + | "cameraFullscreen" + | "audio" + | "shaderEffect"; /** Length a clip is given before its media has been probed. Lives here, in the pure * document layer, because that layer decides which clips are still waiting for a real @@ -378,12 +386,17 @@ export function mapAllRegionCollections( ? (legacy?.cameraFullscreenRegions as StoredRegion[]) : undefined; - return { + // A clip edit can take a shader effect's last fragment with it: its definition goes too. + return pruneUnusedShaderEffects({ ...document, zoomRanges: fn( document.zoomRanges as unknown as StoredRegion[], "zoom", ) as unknown as AxcutDocument["zoomRanges"], + shaderEffectRanges: fn( + (document.shaderEffectRanges ?? []) as unknown as StoredRegion[], + "fxr", + ) as unknown as AxcutDocument["shaderEffectRanges"], annotations: fn( document.annotations as unknown as StoredRegion[], "ann", @@ -420,7 +433,7 @@ export function mapAllRegionCollections( : {}), } : document.legacyEditor, - }; + }); } /** A clamped fragment this short has no surviving content — treat it as fully @@ -734,6 +747,7 @@ function anchoredRegionsOf(document: AxcutDocument): Array<{ id: string; clipId: document.annotations as unknown as StoredRegion[], (legacy?.speedRegions as StoredRegion[] | undefined) ?? [], (legacy?.cameraFullscreenRegions as StoredRegion[] | undefined) ?? [], + (document.shaderEffectRanges ?? []) as unknown as StoredRegion[], ]; return collections .flat() @@ -1197,6 +1211,12 @@ export function removeRegion(document: AxcutDocument, kind: RegionKind, id: stri ); return { ...document, legacyEditor: { ...legacy, cameraFullscreenRegions: prev } }; } + case "shaderEffect": + // The definition goes with its last region: no dead code stays in the document. + return pruneUnusedShaderEffects({ + ...document, + shaderEffectRanges: dropPillById(document.shaderEffectRanges ?? [], id), + }); default: { // ponytail: exhaustive — TS errors here if a new RegionKind is added. const exhaustive: never = kind; @@ -1241,6 +1261,10 @@ const EDIT_REGIONS: Record< count: (d) => legacyRegionCount(d, "cameraFullscreenRegions"), clear: (d) => withLegacyRegionsCleared(d, "cameraFullscreenRegions"), }, + shaderEffect: { + count: (d) => (d.shaderEffectRanges ?? []).length, + clear: (d) => ({ ...d, shaderEffectRanges: [], shaderEffects: [] }), + }, }; /** How many edit regions the document holds, stored rows and not pills. Pure. */ diff --git a/src/lib/ai-edition/schema/index.test.ts b/src/lib/ai-edition/schema/index.test.ts index 38aabd8705..977f16ba53 100644 --- a/src/lib/ai-edition/schema/index.test.ts +++ b/src/lib/ai-edition/schema/index.test.ts @@ -13,6 +13,8 @@ import { legacyEditorSchema, parseDocumentFile, rangeSchema, + shaderEffectRangeSchema, + shaderEffectSchema, timelineSchema, trimRangeSchema, upgradeV7DocumentToV8, @@ -1245,3 +1247,44 @@ describe("follow-cursor zooms read as orbits under auto focus", () => { expect(migrateRawDocumentToCurrent(manualOrbit)).toBe(manualOrbit); }); }); + +describe("shader effects (docs/shader-effects.md)", () => { + const effect = { + id: "fx", + name: "Dim", + contract: 1, + code: "fn effect(uv: vec2) -> vec4 { return frame(uv); }", + params: [{ type: "number", name: "level", default: 1, min: 0, max: 2 }], + }; + + it("fills the defaults of a definition and of a region", () => { + expect(shaderEffectSchema.parse(effect)).toMatchObject({ + description: "", + origin: "agent", + params: [{ name: "level", label: "" }], + }); + expect( + shaderEffectRangeSchema.parse({ id: "r", startMs: 0, endMs: 1000, effectId: "fx" }), + ).toMatchObject({ values: {}, target: "image", lane: 0 }); + }); + + it("refuses a parameter declared twice, or a default out of its bounds", () => { + const twice = { ...effect, params: [effect.params[0], effect.params[0]] }; + expect(shaderEffectSchema.safeParse(twice).success).toBe(false); + const outside = { ...effect, params: [{ ...effect.params[0], default: 3 }] }; + expect(shaderEffectSchema.safeParse(outside).success).toBe(false); + }); + + // A newer build may write a contract this one does not know: the document must still open, + // and the compositor leaves those regions undrawn. + it("loads a contract version it does not know", () => { + expect(shaderEffectSchema.safeParse({ ...effect, contract: 2 }).success).toBe(true); + }); + + it("keeps a document without effects free of both keys", () => { + const doc = createEmptyDocument({ title: "t", projectId: "p" }); + const parsed = documentSchema.parse(doc); + expect("shaderEffects" in parsed).toBe(false); + expect("shaderEffectRanges" in parsed).toBe(false); + }); +}); diff --git a/src/lib/ai-edition/schema/index.ts b/src/lib/ai-edition/schema/index.ts index 05edecab07..96b2eff944 100644 --- a/src/lib/ai-edition/schema/index.ts +++ b/src/lib/ai-edition/schema/index.ts @@ -528,6 +528,113 @@ export const zoomRegionSchema = endGteStart( "startMs", ); +// Agent-written shader effects (docs/shader-effects.md, B). A definition carries the WGSL and its +// declared parameters; a range poses it on the timeline, clip-anchored like a zoom, with its own +// parameter values. Additive: a document written before these existed loads unchanged. +const shaderEffectParamName = z.string().regex(/^[a-z][a-z0-9_]{0,31}$/); +const shaderEffectColor = z.string().regex(/^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/); +const shaderEffectPoint = z.object({ x: z.number().min(0).max(1), y: z.number().min(0).max(1) }); +// Written by the agent, in the user's language, shown as-is: content, not interface copy. +const shaderEffectLabel = z.string().max(40).default(""); + +export const shaderEffectParamSchema = z.discriminatedUnion("type", [ + z.object({ + type: z.literal("number"), + name: shaderEffectParamName, + label: shaderEffectLabel, + default: z.number(), + min: z.number(), + max: z.number(), + }), + z.object({ + type: z.literal("toggle"), + name: shaderEffectParamName, + label: shaderEffectLabel, + default: z.boolean(), + }), + z.object({ + type: z.literal("color"), + name: shaderEffectParamName, + label: shaderEffectLabel, + default: shaderEffectColor, + }), + z.object({ + type: z.literal("point"), + name: shaderEffectParamName, + label: shaderEffectLabel, + default: shaderEffectPoint, + }), +]); + +export const shaderEffectValueSchema = z.union([ + z.number(), + z.boolean(), + shaderEffectColor, + shaderEffectPoint, +]); + +export const shaderEffectSchema = z + .object({ + id: z.string().min(1), + // What the pill shows. + name: z.string().min(1).max(60), + // For the next agent: what the effect does, in one sentence. + description: z.string().max(500).default(""), + // The WGSL contract version. Not a literal: a version this build does not know (written by + // a newer one) must still load; the compositor leaves its regions undrawn. + contract: z.number().int().positive(), + code: z.string().min(1).max(65_536), + // The `max` here is a technical ceiling, not a budget: see the cost tiers. + params: z.array(shaderEffectParamSchema).max(32).default([]), + origin: z.enum(["agent", "user"]).default("agent"), + // The compositor's cost estimate, cached when the code was last checked. Derived, never an + // input: `frameReads` is `frame()` reads per pixel, `tier` its indicative tier. + cost: z + .object({ + tier: z.enum(["light", "medium", "heavy", "very-heavy"]), + frameReads: z.number().nonnegative(), + }) + .optional(), + }) + .superRefine((effect, ctx) => { + const names = new Set(); + for (const [index, param] of effect.params.entries()) { + if (names.has(param.name)) { + ctx.addIssue({ + code: "custom", + message: `parameter "${param.name}" is declared twice`, + path: ["params", index], + }); + } + names.add(param.name); + if (param.type === "number" && !(param.min <= param.default && param.default <= param.max)) { + ctx.addIssue({ + code: "custom", + message: `parameter "${param.name}": min ≤ default ≤ max`, + path: ["params", index], + }); + } + } + }); + +export const shaderEffectRangeSchema = endGteStart( + z.object({ + id: z.string().min(1), + startMs: z.number().nonnegative(), + endMs: z.number().nonnegative(), + ...clipAnchorShape, + effectId: z.string().min(1), + // Only the values that differ from the definition's defaults. + values: z.record(z.string(), shaderEffectValueSchema).default({}), + // What the effect transforms: the picture under the texts, the texts alone, or both. + target: z.enum(["image", "text", "both"]).default("image"), + // Application order, lane 0 first, closest to the content. No overlap within a lane. + lane: z.number().int().min(0).max(7).default(0), + }), + "endMs", + "startMs", +); + // External audio import (issue #350) — voiceover / BGM / SFX layered over the // programme. Unlike zoom/speed/annotation/trim, an audio track is NOT // clip-anchored: it floats over the whole timeline, addressed in RAW/document @@ -630,6 +737,11 @@ const documentSchemaShape = z.object({ }), annotations: z.array(annotationRegionSchema).default([]), zoomRanges: z.array(zoomRegionSchema).default([]), + // Agent-written shader effects (docs/shader-effects.md). Optional rather than defaulted, like + // `vocabulary`: a document without effects carries no trace of them, and every reader treats + // an absent list as empty. An older build drops both keys when it saves. + shaderEffects: z.array(shaderEffectSchema).optional(), + shaderEffectRanges: z.array(shaderEffectRangeSchema).optional(), // Imported audio tracks (issue #350). Defaulted so every document written // before this loads unchanged; an older build simply strips the key on save. audioTracks: z.array(audioTrackSchema).default([]), @@ -1265,6 +1377,10 @@ export type AxcutAnnotationRegion = z.infer; export type AxcutZoomRegion = z.infer; export type AxcutCameraTrack = z.infer; export type AxcutAudioTrack = z.infer; +export type AxcutShaderEffect = z.infer; +export type AxcutShaderEffectParam = z.infer; +export type AxcutShaderEffectRange = z.infer; +export type AxcutShaderEffectValue = z.infer; export type AxcutLegacyEditor = z.infer; export type AxcutDocument = z.infer; export type AxcutDocumentInput = z.input; diff --git a/src/lib/ai-edition/shaderEffects.ts b/src/lib/ai-edition/shaderEffects.ts new file mode 100644 index 0000000000..8aa973128d --- /dev/null +++ b/src/lib/ai-edition/shaderEffects.ts @@ -0,0 +1,168 @@ +import type { + AxcutDocument, + AxcutShaderEffect, + AxcutShaderEffectParam, + AxcutShaderEffectRange, + AxcutShaderEffectValue, +} from "./schema"; + +/** + * Agent-written shader effects (docs/shader-effects.md): the pure helpers the agent tools, the + * scene projection and the editor share. The WGSL itself is checked and compiled by the + * compositor (`crates/compositor/src/shader_fx.rs`). + */ + +/** The WGSL contract this build writes and draws. */ +export const SHADER_EFFECT_CONTRACT = 1; + +export type ShaderEffectTier = "light" | "medium" | "heavy" | "very-heavy"; + +/** What the compositor says of an effect's code (`checkShaderEffect` in the addon). */ +export interface ShaderEffectCheck { + error?: string | null; + tier?: ShaderEffectTier | null; + frameReads?: number | null; + iterations?: number | null; +} + +/** Asks the compositor about a code; `null` where nothing can answer (no addon, a test). */ +export type ShaderEffectChecker = ( + code: string, + params: ReadonlyArray>, +) => ShaderEffectCheck | null; + +export function findShaderEffect( + document: AxcutDocument, + effectId: string, +): AxcutShaderEffect | undefined { + return (document.shaderEffects ?? []).find((effect) => effect.id === effectId); +} + +const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value)); +const isColor = (value: unknown): value is string => + typeof value === "string" && /^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/.test(value); +const isPoint = (value: unknown): value is { x: number; y: number } => + typeof value === "object" && + value !== null && + Number.isFinite((value as { x?: unknown }).x) && + Number.isFinite((value as { y?: unknown }).y); + +/** The value a parameter takes: `value` when it has the right type, clamped to the bounds, the + * default otherwise. */ +export function resolveShaderEffectValue( + param: AxcutShaderEffectParam, + value: unknown, +): AxcutShaderEffectValue { + switch (param.type) { + case "number": + return typeof value === "number" && Number.isFinite(value) + ? clamp(value, param.min, param.max) + : param.default; + case "toggle": + return typeof value === "boolean" ? value : param.default; + case "color": + return isColor(value) ? value : param.default; + case "point": + return isPoint(value) ? { x: clamp(value.x, 0, 1), y: clamp(value.y, 0, 1) } : param.default; + } +} + +const sameValue = (a: AxcutShaderEffectValue, b: AxcutShaderEffectValue) => + JSON.stringify(a) === JSON.stringify(b); + +/** What a region stores: only the values that differ from the defaults, each resolved against + * its parameter. Names the definition does not declare are dropped. */ +export function storedShaderEffectValues( + effect: Pick, + values: Record, +): Record { + const stored: Record = {}; + for (const param of effect.params) { + if (!(param.name in values)) continue; + const value = resolveShaderEffectValue(param, values[param.name]); + if (!sameValue(value, param.default)) stored[param.name] = value; + } + return stored; +} + +function hexToRgba(hex: string): [number, number, number, number] { + const channel = (i: number) => Number.parseInt(hex.slice(1 + i * 2, 3 + i * 2), 16) / 255; + return [channel(0), channel(1), channel(2), hex.length === 9 ? channel(3) : 1]; +} + +/** A parameter's value as the compositor packs it: one float, or 2 (point) or 4 (color). */ +export function nativeShaderEffectValue( + param: AxcutShaderEffectParam, + value: unknown, +): number | number[] { + const resolved = resolveShaderEffectValue(param, value); + switch (param.type) { + case "number": + return resolved as number; + case "toggle": + return resolved ? 1 : 0; + case "color": + return hexToRgba(resolved as string); + case "point": { + const { x, y } = resolved as { x: number; y: number }; + return [x, y]; + } + } +} + +/** The document without the definitions no region uses: no dead code is kept. */ +export function pruneUnusedShaderEffects(document: AxcutDocument): AxcutDocument { + const used = new Set((document.shaderEffectRanges ?? []).map((range) => range.effectId)); + if ((document.shaderEffects ?? []).every((effect) => used.has(effect.id))) return document; + return { + ...document, + shaderEffects: (document.shaderEffects ?? []).filter((effect) => used.has(effect.id)), + }; +} + +/** The tier of a number of `frame()` reads per pixel, as the compositor computes it. */ +export function shaderEffectTierOf(frameReads: number): ShaderEffectTier { + if (frameReads <= 8) return "light"; + if (frameReads <= 32) return "medium"; + if (frameReads <= 128) return "heavy"; + return "very-heavy"; +} + +/** The longest span a tier is recommended for, in seconds (spec C.7). */ +const TIER_SPAN_SEC: Record = { + light: Number.POSITIVE_INFINITY, + medium: 60, + heavy: 10, + "very-heavy": 3, +}; + +/** The recommendation an agent gets when a tier runs longer than it is meant to, else null. */ +export function shaderEffectCostAdvice(tier: ShaderEffectTier, spanSec: number): string | null { + if (spanSec <= TIER_SPAN_SEC[tier]) return null; + const lighter = + tier === "very-heavy" ? "heavy or lighter" : tier === "heavy" ? "medium or light" : "light"; + return `${tier} over ${spanSec.toFixed(1)} s: this tier is meant for at most ${TIER_SPAN_SEC[tier]} s; for a region this long, aim ${lighter}. It is a recommendation, not a limit.`; +} + +/** The `frame()` reads of every effect running at the busiest moment of `[startMs, endMs]`. */ +export function busiestShaderEffectReads( + document: AxcutDocument, + startMs: number, + endMs: number, +): number { + const ranges = (document.shaderEffectRanges ?? []).filter( + (r) => r.startMs < endMs && r.endMs > startMs, + ); + const reads = (range: AxcutShaderEffectRange) => + findShaderEffect(document, range.effectId)?.cost?.frameReads ?? 0; + // The load only changes at a region edge, so the busiest moment is one of the starts. + let busiest = 0; + for (const at of [startMs, ...ranges.map((r) => r.startMs)]) { + if (at < startMs || at >= endMs) continue; + const load = ranges + .filter((r) => r.startMs <= at && r.endMs > at) + .reduce((sum, r) => sum + reads(r), 0); + busiest = Math.max(busiest, load); + } + return busiest; +} diff --git a/src/lib/ai-edition/store/useTimeline.test.ts b/src/lib/ai-edition/store/useTimeline.test.ts index 917188529c..cc12709c16 100644 --- a/src/lib/ai-edition/store/useTimeline.test.ts +++ b/src/lib/ai-edition/store/useTimeline.test.ts @@ -750,6 +750,42 @@ describe("useTimeline.clearTimeline", () => { annotation: (tl) => tl.addAnnotation(), speed: (tl) => tl.addSpeed(), cameraFullscreen: (tl) => tl.addCameraFullscreen(), + // The editor has no effect lane: agents add effects, so this one is written as they do. + shaderEffect: async () => { + const doc = useProjectStore.getState().document as AxcutDocument; + const clip = doc.timeline.clips[0]; + await useProjectStore.getState().saveDocument( + { + ...doc, + shaderEffects: [ + { + id: "fx_1", + name: "Pass-through", + description: "", + contract: 1, + code: "fn effect(uv: vec2) -> vec4 { return frame(uv); }", + params: [], + origin: "agent", + }, + ], + shaderEffectRanges: [ + { + id: "fxr_1", + startMs: 0, + endMs: 1000, + clipId: clip.id, + sourceStartSec: clip.sourceStartSec, + sourceEndSec: clip.sourceStartSec + 1, + effectId: "fx_1", + values: {}, + target: "image", + lane: 0, + }, + ], + }, + { history: true }, + ); + }, }; const editKinds = Object.keys(addOf) as EditKind[]; @@ -761,6 +797,7 @@ describe("useTimeline.clearTimeline", () => { annotation: doc?.annotations.length ?? 0, speed: doc ? readSpeedRegions(doc).length : 0, cameraFullscreen: legacy.cameraFullscreenRegions?.length ?? 0, + shaderEffect: doc?.shaderEffectRanges?.length ?? 0, }; }; const noRegions: Record = { @@ -769,6 +806,7 @@ describe("useTimeline.clearTimeline", () => { annotation: 0, speed: 0, cameraFullscreen: 0, + shaderEffect: 0, }; // A project holding everything that is NOT an edit: two clips, a webcam, an imported @@ -928,6 +966,7 @@ describe("useTimeline.clearTimeline", () => { annotation: 1, speed: 1, cameraFullscreen: 1, + shaderEffect: 1, }); await act(async () => { @@ -967,6 +1006,7 @@ describe("useTimeline.clearTimeline", () => { annotation: 1, speed: 1, cameraFullscreen: 1, + shaderEffect: 1, }); act(() => { diff --git a/src/native/sceneDescription.test.ts b/src/native/sceneDescription.test.ts index 0d84461b54..773df2c5e3 100644 --- a/src/native/sceneDescription.test.ts +++ b/src/native/sceneDescription.test.ts @@ -102,6 +102,8 @@ function makeDoc( annotations: overrides.annotations ?? [], zoomRanges: overrides.zoomRanges ?? [], audioTracks: overrides.audioTracks ?? [], + ...(overrides.shaderEffects ? { shaderEffects: overrides.shaderEffects } : {}), + ...(overrides.shaderEffectRanges ? { shaderEffectRanges: overrides.shaderEffectRanges } : {}), legacyEditor: overrides.legacyEditor ?? null, }; } @@ -2949,3 +2951,99 @@ describe("buildSceneDescription.audioTracks", () => { expect(buildSceneDescription(doc).audioTracks).toEqual([]); }); }); + +// --- shaderEffects ------------------------------------------------------------- + +describe("buildSceneDescription.shaderEffects", () => { + const code = "fn effect(uv: vec2) -> vec4 { return frame(uv); }"; + const effect = { + id: "fx1", + name: "Tint", + description: "", + contract: 1, + code, + origin: "agent" as const, + params: [ + { type: "number" as const, name: "level", label: "", default: 1, min: 0, max: 2 }, + { type: "color" as const, name: "tint", label: "", default: "#000000" }, + { type: "toggle" as const, name: "on", label: "", default: false }, + ], + }; + + it("is omitted when there are none", () => { + expect(buildSceneDescription(makeDoc()).shaderEffects).toBeUndefined(); + }); + + // A trim inside the region cuts it in two fragments on the source clock, but it stays one + // pill: both fragments carry the pill's span on the programme clock, which the trim shortened. + it("gives every fragment the whole pill on the programme clock, and every value", () => { + const doc = makeDoc({ + assets: [makeAsset({ id: "a", originalPath: "/a.mp4" })], + clips: [ + makeClip({ + id: "c1", + assetId: "a", + sourceStartSec: 0, + sourceEndSec: 10, + timelineStartSec: 0, + timelineEndSec: 10, + }), + ], + timeline: { + trimRanges: [ + { id: "t1", assetId: "a", startSec: 2, endSec: 4, reason: "", origin: "user" }, + ], + }, + shaderEffects: [effect], + shaderEffectRanges: [ + { + id: "fxr1", + startMs: 1000, + endMs: 6000, + effectId: "fx1", + values: { tint: "#ff0000", on: true }, + target: "text", + lane: 2, + }, + ], + }); + const { shaderEffects } = buildSceneDescription(doc); + expect(shaderEffects?.map((e) => [e.startSec, e.endSec, e.clipIndex])).toEqual([ + [1, 2, 0], + [4, 6, 1], + ]); + for (const fragment of shaderEffects ?? []) { + expect(fragment).toMatchObject({ + programmeStartSec: 1, + programmeEndSec: 4, + target: "text", + lane: 2, + contract: 1, + code, + params: [ + { name: "level", type: "number" }, + { name: "tint", type: "color" }, + { name: "on", type: "toggle" }, + ], + values: { level: 1, tint: [1, 0, 0, 1], on: 1 }, + }); + } + }); + + it("drops a region whose definition is gone", () => { + const doc = makeDoc({ + shaderEffectRanges: [ + { + id: "fxr1", + startMs: 0, + endMs: 1000, + effectId: "fx_gone", + values: {}, + target: "image", + lane: 0, + }, + ], + }); + expect(buildSceneDescription(doc).shaderEffects).toBeUndefined(); + }); +}); diff --git a/src/native/sceneDescription.ts b/src/native/sceneDescription.ts index 5cf2a8e5d5..8c8727ee7b 100644 --- a/src/native/sceneDescription.ts +++ b/src/native/sceneDescription.ts @@ -41,12 +41,16 @@ import { resolvePlaybackSegments, } from "@/lib/ai-edition/document/timeline"; import type { AxcutAudioTrack, AxcutClip, AxcutDocument } from "@/lib/ai-edition/schema"; +import { nativeShaderEffectValue } from "@/lib/ai-edition/shaderEffects"; import { getEditorSettings } from "@/lib/ai-edition/store/editorSettings"; import { assetCameraSource } from "@/lib/ai-edition/timeline/camera"; import { resolveClipSourceEndSec } from "@/lib/ai-edition/timeline/clipDuration"; import { removedRawSpans } from "@/lib/ai-edition/timeline/programme-time"; import { takeProgramme } from "@/lib/ai-edition/timeline/take-programme"; -import { projectRegionsToSource } from "@/lib/ai-edition/timeline/timelineMap"; +import { + coalesceRegionsForRuler, + projectRegionsToSource, +} from "@/lib/ai-edition/timeline/timelineMap"; import { MAGNIFICATION_REFERENCE_PX, MAX_ZOOM_SCALE, @@ -120,6 +124,26 @@ export interface SceneZoomRegion { hideCursor?: boolean; } +/** One fragment of a shader effect region (`(document.shaderEffectRanges ?? [])`), projected onto its + * clip's source time like the other regions, with its definition. `scene.rs` + * `SceneShaderEffect` reads it; docs/shader-effects.md, B.5. */ +export interface SceneShaderEffect { + startSec: number; + endSec: number; + clipIndex?: number; + /** The WHOLE pill on the programme clock (trims skipped, speed applied): the compositor's + * `ctx.region` runs across it instead of restarting at each fragment. */ + programmeStartSec: number; + programmeEndSec: number; + target: "image" | "text" | "both"; + lane: number; + contract: number; + code: string; + params: Array<{ name: string; type: "number" | "toggle" | "color" | "point" }>; + /** Every declared parameter, defaults filled in: one float, or 2 (point) or 4 (color). */ + values: Record; +} + /** A "Full Camera" timeline region (from `legacyEditor.cameraFullscreenRegions`). Times in seconds. */ export interface SceneCameraFullscreenRegion { startSec: number; @@ -479,6 +503,8 @@ export interface SceneDescription { * source-time span after `projectRegionsToSourceTime`). Empty when none set. */ cameraFullscreenRegions: SceneCameraFullscreenRegion[]; + /** Agent-written shader effects, omitted when there are none. */ + shaderEffects?: SceneShaderEffect[]; /** * Speed regions projected onto each clip's source time (one entry per * source-time span after `projectRegionsToSourceTime`). Empty when none set. @@ -1085,6 +1111,59 @@ export function buildSceneDescription( () => createId("speed"), ); + // Shader effects: projected like the zooms, and each fragment told where its WHOLE pill sits + // on the programme clock, through the same projection the exporter plays the timeline with + // (trims skipped, speed applied). A pill cut by a trim or a clip boundary keeps one progress. + const effectsById = new Map((document.shaderEffects ?? []).map((effect) => [effect.id, effect])); + const programmeSec = (rawSec: number) => + projectRawTimelineSecToPlayback( + projectedClips, + document.timeline.trimRanges, + rawSec, + rawSpeedRegions, + ); + const pillSpanById = new Map(); + for (const pill of coalesceRegionsForRuler(document.shaderEffectRanges ?? [])) { + const span = { + programmeStartSec: programmeSec(pill.start), + programmeEndSec: programmeSec(pill.end), + }; + for (const id of pill.ids) pillSpanById.set(id, span); + } + const projectedShaderEffects = projectRegionsToSource( + (document.shaderEffectRanges ?? []).map((range) => ({ + ...range, + ...pillSpanById.get(range.id), + })), + visibleClips, + document.timeline.clips, + () => createId("fxr"), + ); + const sceneShaderEffects: SceneShaderEffect[] = projectedShaderEffects.flatMap((region) => { + const effect = effectsById.get(region.effectId); + if (!effect) return []; + return [ + { + startSec: region.startMs / 1000, + endSec: region.endMs / 1000, + clipIndex: region.clipIndex, + programmeStartSec: region.programmeStartSec ?? region.startMs / 1000, + programmeEndSec: region.programmeEndSec ?? region.endMs / 1000, + target: region.target, + lane: region.lane, + contract: effect.contract, + code: effect.code, + params: effect.params.map(({ name, type }) => ({ name, type })), + values: Object.fromEntries( + effect.params.map((param) => [ + param.name, + nativeShaderEffectValue(param, region.values[param.name]), + ]), + ), + }, + ]; + }); + // Webcam rect, single source of truth between preview & native : // on résout le rect AVEC LA MÊME maths que `PreviewCanvas.computeCompositeLayout` et on // l'envoie au natif dans `layout.webcamRect` (fractions du cadre de sortie). Le natif le @@ -1470,6 +1549,7 @@ export function buildSceneDescription( clipIndex: region.clipIndex, })), cropByClip, + ...(sceneShaderEffects.length > 0 ? { shaderEffects: sceneShaderEffects } : {}), output: { ...pickOutputDims(document, settings.aspectRatio), fps: null }, // Omitted rather than sent as `{mode:"none"}`: the Rust side defaults the field, and // every project without a webcam effect would otherwise carry it for nothing. diff --git a/technical-documentation/architecture/ai-agent.md b/technical-documentation/architecture/ai-agent.md index d36f20614e..7b5f44333c 100644 --- a/technical-documentation/architecture/ai-agent.md +++ b/technical-documentation/architecture/ai-agent.md @@ -41,7 +41,7 @@ The agent is built with LangChain's `createAgent`, not `deepagents`' `createDeep ## Tool schema -The model never free-writes the project document. It can only call the fixed set of 26 tools built by `deep-agent/service.ts#buildTools`, described by `TOOL_DESCRIPTIONS` in the same file and validated against the Zod argument schemas in `agent-tools.ts`; the executor parses JSON, validates arguments, and returns either a new schema-valid snapshot or an error. Those three surfaces (descriptions, built tools, executor cases) are pinned to one another by `deep-agent/service.test.ts` — an earlier fourth surface, `AGENT_TOOL_SPECS`, described the tools in JSON Schema for a provider it had stopped reaching, and drifted. The tools operate on the same [document model](document-model.md) as manual editing. +The model never free-writes the project document. It can only call the fixed set of tools built by `deep-agent/service.ts#buildTools` (`OPENSCREEN_TOOL_NAMES`), described by `TOOL_DESCRIPTIONS` in the same file and validated against the Zod argument schemas in `agent-tools.ts`; the executor parses JSON, validates arguments, and returns either a new schema-valid snapshot or an error. Those three surfaces (descriptions, built tools, executor cases) are pinned to one another by `deep-agent/service.test.ts` — an earlier fourth surface, `AGENT_TOOL_SPECS`, described the tools in JSON Schema for a provider it had stopped reaching, and drifted. The tools operate on the same [document model](document-model.md) as manual editing. | Tool | What it does | What it mutates | |---|---|---| @@ -64,6 +64,10 @@ The model never free-writes the project document. It can only call the fixed set | `setAnnotation` | Moves, resizes, retypes or restyles an annotation. A type change goes through `convertAnnotationKind` with the footage under each fragment (`annotationFootageRect`), as the inspector's type switch does; `figureData` / `blurData` merge only the keys sent. Arguments of another kind (width on a text, blurData on an arrow) are refused. | The corresponding clip-anchored `annotations` fragments. | | `addCameraFullscreen` | Adds a camera-fullscreen region over virtual timeline time; refused when no clip under the span comes from an asset with a linked `cameraTrack`, since such a region can only render nothing. | `legacyEditor.cameraFullscreenRegions`. | | `setCameraFullscreen` | Moves or resizes a camera-fullscreen pill, under the same camera requirement as `addCameraFullscreen`. | The corresponding `legacyEditor.cameraFullscreenRegions` fragments. | +| `addEffect` | Writes a shader effect (WGSL, [docs/shader-effects.md](../../docs/shader-effects.md)) and poses it over virtual timeline time, or poses one of the project's effects again by `effectId`. The compositor checks the code first (`checkShaderEffect`); code that does not compile is refused with the error at the agent's line. The result gives the cost tier and, when the tier runs long, a recommendation, never a refusal. Two effects of one lane cannot overlap. | `shaderEffects` (a new definition) and `shaderEffectRanges`. | +| `setEffect` | Moves, re-tunes (`values`), retargets or changes the lane of an effect pill. | The pill's `shaderEffectRanges` fragments. | +| `setEffectDefinition` | Changes an effect's name, description, code or parameters, and so every region using it; new code is checked first. A removed parameter's values drop. | The `shaderEffects` entry and its regions' `values`. | +| `getEffect` | Reads one effect in full, code included; `getCurrentDocument` lists effects without their code. | Read only. | | `removeTrim` | Deletes a trim so its source span plays and exports again. | `timeline.trimRanges`. | | `removeModifier` | Resolves and deletes a zoom, speed, annotation, or camera-fullscreen pill by ID; `removedIds` reports every touching storage row deleted with that pill. | The matching modifier collection. | | `removeClip` | Deletes a placed clip, closes the gap, and drops effects anchored only to it. The result names the modifiers and trims it took with it. | Timeline clips and affected anchored modifiers. | diff --git a/technical-documentation/architecture/decisions.md b/technical-documentation/architecture/decisions.md index ac249fe6c9..f0f16385da 100644 --- a/technical-documentation/architecture/decisions.md +++ b/technical-documentation/architecture/decisions.md @@ -26,6 +26,7 @@ A decision leaves this list only when the code stops honouring it. | **Migrations are forward-only.** A document is migrated up to the current `schemaVersion` on open and never written back down. | Round-tripping through an older schema loses fields silently. | | **Captions are derived from the transcript, not injected as annotations.** | The earlier design generated annotation objects from captions, which then drifted from the transcript the moment either was edited. The transcript is the SSOT for spoken words. | | **One package, one repository.** No sidecar process, no local HTTP server, no monorepo. | The editing engine was adopted from a project that had a Python worker and a Fastify server; both were replaced by in-process TypeScript and Electron IPC. Adding a second runtime back is a large, permanent cost. | +| **Agent-written shader effects are WGSL, translated by naga 24 and compiled off the render thread; an effect is a pure function of the frame, time, pointer and its parameters.** One source for the three backends; the document keeps only that source, never a binary. Cost is an indicative tier, never a refusal; the one hard rule is literal loop bounds. | The Windows spike measured +0.04 ms per 1080p frame for a heavy effect and an unchanged export time, and preview and export agreeing within codec noise. naga 25+ emits D3D12 sampler heaps that FXC `ps_5_0` rejects. A budget measured on the authoring machine was rejected: it would refuse high-end effects on a modest machine although the export renders them fine. See [docs/shader-effects.md](../../docs/shader-effects.md). | ## Rejected, with the reason diff --git a/technical-documentation/architecture/document-model.md b/technical-documentation/architecture/document-model.md index 5b9940e234..b063fa41d6 100644 --- a/technical-documentation/architecture/document-model.md +++ b/technical-documentation/architecture/document-model.md @@ -27,6 +27,8 @@ and anything unknown is rejected by the `z.literal(axcutSchemaVersion)` check in | `timeline` | `{ clips[], gaps[], trimRanges[], muteRanges[], speedRanges[], captionRanges[] }` | Clips carry their own in/out (`sourceStartSec`/`sourceEndSec`); trims are anchored to a clip (`clipId?`) since v7. See [timeline-model.md](timeline-model.md). | | `annotations[]` | `AxcutAnnotationRegion[]` | Text/image/figure/blur overlays, anchored to a clip (`clipId?`). | | `zoomRanges[]` | `AxcutZoomRegion[]` | Zoom-in effects, depth 1–6, anchored to a clip (`clipId?`). | +| `shaderEffects[]?` | `AxcutShaderEffect[]` | Agent-written shader effects: WGSL `code`, `name`, `description`, the contract version, declared `params`, and the compositor's cached `cost`. Optional: absent on a document without effects. A definition no region uses is dropped by the edit that removed its last region. See [docs/shader-effects.md](../../docs/shader-effects.md). | +| `shaderEffectRanges[]?` | `AxcutShaderEffectRange[]` | Where each effect applies: clip-anchored regions like the zooms, with the parameter `values` that differ from the defaults, a `target` (`image`, `text`, `both`) and a `lane`. Optional, like `shaderEffects`. | | `audioTracks[]` | `AxcutAudioTrack[]` | Imported audio (voiceover / BGM / SFX, issue #350) mixed over the programme. NOT clip-anchored — addressed in RAW/document timeline seconds (`timelineStartSec`), with `trimStartSec`/`trimEndSec` windowing the source and `gainDb` its level. Added from the timeline toolbar; the referenced asset has `kind: "audio"`. | | `legacyEditor` | OpenScreen v2 `ProjectEditorState` passthrough | Appearance/cursor settings not yet first-class in the AI-edition schema. | | `agent` | `{ baseIntent?, pendingQuestions[], suggestions[], lastAppliedOperations[], lastReasoningSummary? }` | LLM agent state. | diff --git a/technical-documentation/architecture/editor-shell.md b/technical-documentation/architecture/editor-shell.md index 53f7fa18fb..47f18c4e96 100644 --- a/technical-documentation/architecture/editor-shell.md +++ b/technical-documentation/architecture/editor-shell.md @@ -104,10 +104,12 @@ selection pane. ## Adding a region kind An ordered checklist of every file that must move when a new modifier -(`"blur"`, `"captionHighlight"`, …) joins the existing five. The kind is added +(`"blur"`, `"captionHighlight"`, …) joins the existing ones. The kind is added to `RegionKind` in `src/lib/ai-edition/document/timeline.ts` (`"zoom" | -"trim" | "annotation" | "speed" | "cameraFullscreen"`, `:18`); every site that -switches on it is checked below. Each path has been verified on this branch. +"trim" | "annotation" | "speed" | "cameraFullscreen" | "audio" | "shaderEffect"`); +every site that switches on it is checked below. `"shaderEffect"` went through +the document and agent steps but has no lane or inspector in the editor yet: +agents write effects ([docs/shader-effects.md](../../docs/shader-effects.md)). Each path has been verified on this branch. 1. **Schema** — `src/lib/ai-edition/schema/index.ts`. Add a `xxxRegionSchema` Zod object that extends the modifier base (`{id, startMs, endMs, diff --git a/technical-documentation/architecture/mcp-server.md b/technical-documentation/architecture/mcp-server.md index 1fd28b93b5..528562d928 100644 --- a/technical-documentation/architecture/mcp-server.md +++ b/technical-documentation/architecture/mcp-server.md @@ -46,6 +46,10 @@ So a tool added to the agent appears over MCP with no further work, and the MCP - **The project tools**, see [The project and its media](#the-project-and-its-media). - MCP metadata: `readOnlyHint` for the reads (`!isMutatingTool`), `listProjects` and `createCheckpoint`, and `destructiveHint` for `replaceTimeline`, the three `remove*` agent tools, `removeMedia` and `restoreCheckpoint`. +### The effect contract + +The server's one resource, `openscreen://effects/contract` ([`effects-contract.ts`](../../electron/mcp/effects-contract.ts)), holds the full WGSL contract of `addEffect`: the inputs an effect reads, its parameters, the rules, the cost tiers and two examples. It is too long for a tool description and versioned with the contract; the instructions point to it. `effects-contract.test.ts` checks that it names every field of the compositor's prelude, and `shader_fx::tests::the_examples_of_the_mcp_contract_compile` compiles its examples. The code an agent writes is checked by `McpToolDeps.checkShaderEffect`, the compositor's `checkShaderEffect`, wired in `registerIpcHandlers` like `cameraSegmentation`; the in-app agent gets the same check through `ChatRunEnv`. + ### The project's look `setEditorSettings` ([`editor-settings-tool.ts`](../../electron/ai-edition/editor-settings-tool.ts)) writes every setting of the editor's look panes: background, frame, format, camera layout, cursor, `autoFocusAll` and `audioGainDb`. It takes a partial `EditorSettingsPatch` and applies it with `applySettingsPatch`, the editor's own write, plus what the panes do around a pick (a first fixed format fills the frame, an untouched camera roundness follows its shape, the camera framing is stored as size and pan). `setAspectRatio` is the same write for the format alone. diff --git a/technical-documentation/architecture/native-compositor.md b/technical-documentation/architecture/native-compositor.md index 6ce4e305ce..c80cd8e839 100644 --- a/technical-documentation/architecture/native-compositor.md +++ b/technical-documentation/architecture/native-compositor.md @@ -29,6 +29,7 @@ and without that flag the runtime corruption is silent. | [`crates/compositor/src/ffi.rs`](../../crates/compositor/src/ffi.rs) | bindgen-generated `libav*` bindings (ffmpeg 8.x headers) | | [`crates/compositor/src/compositor.rs`](../../crates/compositor/src/compositor_windows.rs) | HLSL compositor — every per-frame pass (`compose_frame`, background, screen, webcam, cursor, annotations, shadows, blur) | | [`crates/compositor/src/scene.rs`](../../crates/compositor/src/scene.rs) | the `Scene` struct parsed from the app's `SceneDescription` JSON | +| [`crates/compositor/src/shader_fx.rs`](../../crates/compositor/src/shader_fx.rs) | agent-written shader effects: the WGSL contract, validation and loop rule, cost tiers, parameter packing, background compilation (FXC on Windows; on Linux, `compositor_linux.rs` builds wgpu pipelines) | | [`crates/compositor/src/regions.rs`](../../crates/compositor/src/regions.rs) | zoom / speed / Full Camera regions — envelope shapes and per-frame state sampling | | [`crates/compositor/src/pipeline.rs`](../../crates/compositor/src/pipeline_windows.rs) | demux + `D3D11VA` decode + composite + AMF encode + mux (`run_c0` for decode/encode only, `run_composited` for the full path) | | [`crates/compositor/src/audio.rs`](../../crates/compositor/src/audio.rs) | per-clip audio decode, swresample → f32 planar 48 kHz stereo, libavfilter `atempo` speed stretch (WSOLA fallback), multi-track mix, AAC encoder | @@ -173,6 +174,45 @@ flowchart TB BG --> SS --> SV --> CU --> WS --> WV --> ANN ``` +### Shader effects + +An agent-written effect is WGSL that defines `fn effect(uv: vec2) -> vec4`, carried by the +scene (`Scene::shader_effects`) and applied by `compose_frame` as a full-frame pass. The design and +the contract are in [docs/shader-effects.md](../../docs/shader-effects.md); +[`shader_fx.rs`](../../crates/compositor/src/shader_fx.rs) holds everything that is not +backend-specific. + +- **The module.** The agent's code comes first, then the generated `FxParams` struct (its declared + parameters, bound at `b3`), then the contract-v1 prelude: `frame()`, `ctx` (`b2`), `fx_px`, + `fx_hash` and the `fx_vs`/`fx_fs` entry points. Errors therefore point at the agent's lines. +- **Validation** (`analyze`) is naga's, plus the loop rule: every loop is a `for` with literal + bounds, at most 4 096 iterations per pixel. An effect declares no binding beyond the prelude's + four. It also estimates the cost, in `frame()` reads per pixel, as an indicative tier (light, + medium, heavy, very heavy). Nothing is refused on cost. +- **Compilation never happens on the render thread.** `set_scene` starts one background compile per + new source. The cache is keyed by contract, code and parameter layout, and keeps the 64 most + recently used. + - **Windows:** naga to HLSL SM 5.0, then FXC. + - **Linux:** the WGSL goes to wgpu as it is. The thread builds the shader module and the + pipeline, against an explicit layout of the prelude's four bindings. wgpu panics on a + validation error, since no `on_uncaptured_error` is set: `analyze` runs first so that none + can happen, and a panic would only kill that thread, leaving the effect undrawn. +- **Blocking.** The export compositor waits for a pending compile and never draws a frame without + its effect. The live view (`set_shader_fx_blocking(false)`) skips the effect until it lands, then + recomposes the paused frame (`shader_fx_landed`). +- **Targets.** `image` effects run before the annotations and captions. `text` effects run on a + transparent text layer, which is then drawn over the image. `both` effects run last. Within a + target, effects apply by lane, then in scene order. Each pass copies its destination into + `ann_copy` and repaints it with blending off. +- **`ctx` comes from the frame geometry** and is in output uv: the pointer and the last four clicks + (`plan_cursor`), the footage rect (`FrameGeometry::footage_quad`, bounding box under a tilt), the + camera rect, the region's progress (over the whole pill in programme time when the app sends + `programmeStartSec`/`programmeEndSec`), and programme time. + +naga stays at 24. From 25 on, its HLSL output declares samplers in a D3D12 heap +(`register(s0, space0)`), which FXC rejects for `ps_5_0` (X3721). +`shader_fx::tests::a_valid_effect_becomes_hlsl_that_d3d11_accepts` guards that boundary. + ## Scene contract The app hands the native compositor a flat JSON description once per document @@ -402,6 +442,12 @@ licence. D3D11VA + AMF survive the LGPL-shared build (verified: rasteriser: one that needs no D3D device at all. Giving the helper a WARP device would add a slow path nobody needs alongside a working one. +### Known gap: shader effects do not draw on macOS + +The Metal compositor parses `shader_effects` but does not draw them: an effect is visible on +Windows and Linux only. [docs/shader-effects.md](../../docs/shader-effects.md) (D.5) specifies the +Metal pass. + ### Known gap: the capture fallback is unreachable on a host that fails D3D That fallback is only reachable through the pre-flight probe, and the probe diff --git a/technical-documentation/architecture/timeline-model.md b/technical-documentation/architecture/timeline-model.md index f8f293eb0a..1bcd379809 100644 --- a/technical-documentation/architecture/timeline-model.md +++ b/technical-documentation/architecture/timeline-model.md @@ -33,7 +33,7 @@ existing. ## Clip-anchored modifiers -Every region (zoom / speed / annotation / cameraFullscreen) is stored as one or more +Every region (zoom / speed / annotation / cameraFullscreen / shader effect) is stored as one or more **clip-anchored fragments** — `{clipId, sourceStartSec, sourceEndSec, …payload}` — keyed to the clip it lives on, in that clip's source media time. A region the user drew across a clip boundary is stored as one fragment per covered clip; the fragments carry diff --git a/technical-documentation/engineering/rendering-performance.md b/technical-documentation/engineering/rendering-performance.md index 93c2387c4d..f8bb471875 100644 --- a/technical-documentation/engineering/rendering-performance.md +++ b/technical-documentation/engineering/rendering-performance.md @@ -434,6 +434,34 @@ The editor preview was driven over CDP on the same two builds (not computer-use: **The output did not change.** Every row above exports a byte-identical GIF, checked by hash. That needed one fix first: the median cut sorted `HashMap` entries with a stable sort, so ties kept the map's random per-process order and no two exports of the same project were byte-identical. +## Shader effects — 2026-10-14 + +An agent-written effect (`crates/compositor/src/shader_fx.rs`, [docs/shader-effects.md](../../docs/shader-effects.md)) adds one full-frame pass per active region: a copy of the render target into `ann_copy`, then the effect. Measured with `compositor_windows::tests::shader_fx_tier_calibration` (`OPENSCREEN_FX_BENCH=1`, release) on the RTX 4070 Ti: the extra time per composed frame of an effect that reads `frame()` N times, best of five runs of 200 frames. + +| `frame()` reads | Tier | 1080p | 4K | +|---:|---|---:|---:| +| 1 | light | +0.030 ms | +0.138 ms | +| 8 | light | +0.061 ms | +0.211 ms | +| 32 | medium | +0.137 ms | +0.606 ms | +| 128 | heavy | +0.539 ms | +2.365 ms | +| 512 | very heavy | +2.133 ms | +8.805 ms | + +- **The cost is linear in the reads,** about 4 µs per read at 1080p and 17 µs at 4K, over a fixed 0.03 ms (1080p) for the copy and the pass. It is the texture bandwidth that pays, which is why the tiers count reads. +- **The export does not notice a light effect:** 180 frames at 1752×1080 took 520 ms without, 523 ms with the spike's effect, and 521 ms with a heavier one. The preview held the source's 30 fps either way. +- **On lavapipe, the Linux CPU fallback,** the same bench (`compositor_linux::tests::shader_fx_tier_calibration`, release, best of three runs of 5 frames, WSL on 16 threads) gives about 1.4 ms per read at 1080p, 350 times the RTX: + +| `frame()` reads | Tier | 1080p | 4K | +|---:|---|---:|---:| +| none (the frame alone) | | 7.5 ms | 29.5 ms | +| 1 | light | +3.2 ms | +13.4 ms | +| 8 | light | +11.2 ms | +44.4 ms | +| 32 | medium | +42.1 ms | +159 ms | +| 128 | heavy | +234 ms | +958 ms | +| 512 | very heavy | +1 035 ms | +5 068 ms | + +- **The tiers keep their order on lavapipe,** but without a GPU a light effect already doubles the frame. The pipeline is ready 18 ms after `set_scene` there, module and driver compile included. +- **Not measured yet:** an integrated GPU, where the same reads cost several times more, and the Metal pass. + ## How we got here — the WebCodecs trail > **This section is history.** It records the measurements that killed the browser-based export pipeline and motivated the native one. The code it describes is **gone**: `src/lib/exporter/videoExporter.ts`, `src/bench/runBench.ts` and the `npm run bench:export` script were deleted with the web MP4 pipeline. It is kept because it is the evidence for [why the compositor, not the encoder, was the wall](#the-wall-is-the-compositor) — which is the entire reason `crates/compositor/` exists — and because the [measurement hazards](#measurement-hazards) it uncovered still apply to any new benchmark here. diff --git a/workbench/lib/editorial.ts b/workbench/lib/editorial.ts index 9f4f28150a..1523e5baa0 100644 --- a/workbench/lib/editorial.ts +++ b/workbench/lib/editorial.ts @@ -64,6 +64,7 @@ export function regionFamilies(document: AxcutDocument): RegionFamily[] { { kind: "annotation", regions: document.annotations as unknown as Region[] }, { kind: "speed", regions: legacyRegions(document, "speedRegions") }, { kind: "cameraFullscreen", regions: legacyRegions(document, "cameraFullscreenRegions") }, + { kind: "shaderEffect", regions: (document.shaderEffectRanges ?? []) as unknown as Region[] }, ]; } diff --git a/workbench/lib/oracles.ts b/workbench/lib/oracles.ts index e25f3350da..505ab180b6 100644 --- a/workbench/lib/oracles.ts +++ b/workbench/lib/oracles.ts @@ -201,6 +201,33 @@ export function documentInvariants(document: AxcutDocument): Violation[] { } } + // 3b. Shader effects: every region names a definition the document holds, and its values + // stay inside their parameter's bounds (`storedShaderEffectValues` clamps on write). + const effectsById = new Map((document.shaderEffects ?? []).map((e) => [e.id, e])); + for (const range of document.shaderEffectRanges ?? []) { + const effect = effectsById.get(range.effectId); + if (!effect) { + violations.push({ + rule: "effects.definition-exists", + detail: `effect region ${range.id} names missing effect ${range.effectId}`, + }); + continue; + } + for (const param of effect.params) { + const value = range.values[param.name]; + if ( + param.type === "number" && + typeof value === "number" && + (value < param.min || value > param.max) + ) { + violations.push({ + rule: "effects.value-in-bounds", + detail: `effect region ${range.id}: ${param.name}=${value} outside ${param.min}-${param.max}`, + }); + } + } + } + // 4. Ids stay unique per family. `replaceTimeline` used to mint `clip_1..N` // and `trim_1..N` by hand (DSL-8) instead of going through `createId`; // it now reuses the id of any clip an interval reproduces exactly and diff --git a/workbench/scenarios/effect-ripple-on-click.scn.ts b/workbench/scenarios/effect-ripple-on-click.scn.ts new file mode 100644 index 0000000000..e1a87ce1cf --- /dev/null +++ b/workbench/scenarios/effect-ripple-on-click.scn.ts @@ -0,0 +1,150 @@ +// ponytail: the first scenario of agent-written shader effects (docs/shader-effects.md, E.7). +// The prompt names a visual effect no setting offers, so the one right move is to WRITE one: +// addEffect, with WGSL whose wave starts from `ctx.clicks`, over a region that covers the clicks. +// The effect does not need the cursor track: the compositor hands it every click already placed +// in output uv (contract C.2). Reading the track is therefore neither required nor penalised. +// +// Offline there is no compositor: the code is not compiled, the result says `validated: false`, +// and the checks read the code as text. A live run inside the app compiles it for real. + +import { cursorTelemetry, singleClip } from "../lib/fixtures"; +import { defineScenario, fail, pass } from "../lib/scenario"; + +/** Three clicks, one per dwell, at its middle: 3 s, 9 s and 17 s. */ +const DWELLS = [ + { atSec: 3, holdSec: 1.2, cx: 0.3, cy: 0.4 }, + { atSec: 9, holdSec: 1, cx: 0.72, cy: 0.55 }, + { atSec: 17, holdSec: 0.9, cx: 0.5, cy: 0.8 }, +]; +const DURATION_SEC = 24.703979; +/** How long after a click its ripple must still be inside a region. */ +const RIPPLE_SEC = 0.5; + +const RIPPLE = [ + "fn ripple(uv: vec2, click: vec4) -> vec2 {", + " if (click.w < 0.5 || click.z > params.duration) { return vec2(0.0); }", + " let t = click.z / params.duration;", + " let d = (uv - click.xy) * vec2(ctx.aspect, 1.0);", + " let r = length(d);", + " let x = params.radius * (1.0 - pow(1.0 - t, 3.0)) - r;", + " let env = smoothstep(-0.008, 0.0, x) * exp(-max(x, 0.0) / 0.07);", + " let wave = sin(x / 0.03 * 6.2831853) * env * (1.0 - t) * (1.0 - t);", + " let dir = select(vec2(0.0), d / r, r > 1e-5);", + " return dir * wave * 0.01 / vec2(ctx.aspect, 1.0);", + "}", + "fn effect(uv: vec2) -> vec4 {", + " var offset = vec2(0.0);", + " for (var i = 0; i < 4; i++) { offset += ripple(uv, ctx.clicks[i]); }", + " return frame(uv - offset);", + "}", +].join("\n"); + +export default defineScenario({ + id: "effect-ripple-on-click", + title: "Effet shader — un ripple à chaque clic de souris", + tags: ["effects", "dsl"], + prompt: "Add a ripple effect on every mouse click.", + document: () => singleClip(), + cursorTelemetry: () => cursorTelemetry({ dwells: DWELLS, durationSec: DURATION_SEC }), + gate: 0.6, + reps: 3, + + behaviour: [ + { + id: "beh.writes-an-effect", + weight: 3, + check: (c) => + c.calls("addEffect").length > 0 + ? pass() + : fail("aucun addEffect : aucun réglage ne fait de ripple, il fallait l'écrire"), + }, + ], + + dsl: [ + { + id: "dsl.effect.reads-the-clicks", + weight: 3, + check: (c) => + (c.after.shaderEffects ?? []).some((e) => e.code.includes("ctx.clicks")) + ? pass() + : fail("aucun effet ne lit ctx.clicks : l'onde ne peut pas partir du point du clic"), + }, + { + id: "dsl.effect.covers-the-clicks", + weight: 3, + check: (c) => { + const ranges = c.after.shaderEffectRanges ?? []; + const missed = DWELLS.filter( + (d) => + !ranges.some( + (r) => r.startMs <= d.atSec * 1000 && r.endMs >= (d.atSec + RIPPLE_SEC) * 1000, + ), + ); + return missed.length === 0 + ? pass() + : fail( + `clics hors de toute région d'effet : ${missed.map((d) => `${d.atSec} s`).join(", ")}`, + ); + }, + }, + { + id: "dsl.effect.image-by-default", + weight: 2, + check: (c) => { + const elsewhere = (c.after.shaderEffectRanges ?? []).filter((r) => r.target !== "image"); + return elsewhere.length === 0 + ? pass() + : fail(`cible ${elsewhere[0].target} alors que rien ne demandait les textes`); + }, + }, + { + id: "dsl.turn.completed", + weight: 2, + check: (c) => + c.run.ok ? pass() : fail(`${c.classifyFailure()} : ${(c.run.error ?? "").slice(0, 200)}`), + }, + ], + + demoScript: [ + { kind: "tools", calls: [{ name: "getCurrentDocument", args: {} }] }, + { + kind: "tools", + calls: [ + { + name: "addEffect", + args: { + startSec: 0, + endSec: DURATION_SEC, + effect: { + name: "Ripple on click", + description: "A water ripple spreads from every click and bends the picture.", + code: RIPPLE, + params: [ + { + type: "number", + name: "radius", + label: "Radius", + default: 0.2, + min: 0.05, + max: 0.5, + }, + { + type: "number", + name: "duration", + label: "Duration", + default: 0.9, + min: 0.3, + max: 2, + }, + ], + }, + }, + }, + ], + }, + { + kind: "text", + text: "I added a ripple that spreads from every click, across the whole video.", + }, + ], +}); diff --git a/workbench/scenarios/registry.ts b/workbench/scenarios/registry.ts index bacd869d93..629107fcdc 100644 --- a/workbench/scenarios/registry.ts +++ b/workbench/scenarios/registry.ts @@ -10,6 +10,7 @@ import cursorQuestion, { cursorBlind } from "./cursor-question.scn"; import cutSilencesClean from "./cut-silences-clean.scn"; import describeProject from "./describe-project.scn"; import describeZooms, { describeZoomsMigrated } from "./describe-zooms.scn"; +import effectRippleOnClick from "./effect-ripple-on-click.scn"; import noInventedBounds from "./no-invented-bounds.scn"; import outOfScopeStyling from "./out-of-scope-styling.scn"; import realWizardEnhance, { @@ -52,6 +53,8 @@ export const SCENARIOS: Scenario[] = [ realCutSilences, realZooms, realZoomGrounding, + // Effects the agent writes: no setting offers them, so the move is to write one. + effectRippleOnClick, // Controls: reachable, and expected green. targetRightClip, removeOneModifier,