Headless 3D and VFX engine for agents. Research preview.
//! Pipelines and bind-group layouts, compiled once per Renderer and shared by scenes.
use super::*;
use crate::forward_variant::FeatureMask;
/// One owner for device pipeline slots and the shared installed-scene set.
#[derive(Default)]
pub(crate) struct Registry {
pub(crate) scene: [OnceLock<std::sync::Arc<CachedPipelines>>; 2],
pub(crate) environment: OnceLock<wgpu::ComputePipeline>,
pub(crate) environment_reduce: OnceLock<wgpu::ComputePipeline>,
pub(crate) display_stats: OnceLock<[wgpu::ComputePipeline; 2]>,
pub(crate) light_temperature: OnceLock<wgpu::ComputePipeline>,
pub(crate) camera_indirect_args: OnceLock<wgpu::ComputePipeline>,
pub(crate) mips: OnceLock<([wgpu::RenderPipeline; 3], wgpu::Sampler)>,
pub(crate) reconstruction: OnceLock<std::sync::Arc<crate::denoise::spatial::Pipelines>>,
pub(crate) bc7: OnceLock<crate::gpu_bc7::Codec>,
}
/// Prewarm only a registry this scene can use. Media, denoising and ray
/// refraction own scene-specific layouts even without a material program.
/// The final registry is selected after material and medium installation.
pub(crate) fn prewarm_builtin(scene: &Scene, effects: EffectPlan) -> Result<bool> {
Ok(scene.render.aovs.is_empty()
&& scene.images.is_empty()
&& crate::attributes::names(scene)?.is_empty()
&& !programs::has_programs(scene)
&& !crate::rt::ray_shadows(scene)
&& !crate::rt::ray_refraction(scene)
&& !effects.denoise
&& !effects.probes
&& environment_node::Settings::from_scene(scene)?.medium.is_none())
}
pub(crate) fn control_formats(denoise: bool) -> &'static [Option<wgpu::TextureFormat>] {
const FORMATS: [Option<wgpu::TextureFormat>;5] = [
Some(wgpu::TextureFormat::R32Uint),
Some(wgpu::TextureFormat::Rgba16Float),Some(wgpu::TextureFormat::Rgba16Float),
Some(wgpu::TextureFormat::Rgba16Float),Some(wgpu::TextureFormat::Rgba32Float),
];
&FORMATS[..if denoise {5} else {4}]
}
/// All lazy descriptor jobs use the same compile-once and scoped-worker path.
/// A failed build (a scene shader that does not compile) leaves its slot empty
/// and returns the error through the job's handle.
type Job<'scope> = std::thread::ScopedJoinHandle<'scope, Result<()>>;
fn compile<'scope, T: Send + Sync + 'scope, F: FnOnce() -> Result<T> + Send + 'scope>(
scope: &'scope std::thread::Scope<'scope, '_>,
slot: &'scope OnceLock<T>,
needed: bool,
build: F,
) -> Option<Job<'scope>> {
(needed && slot.get().is_none()).then(|| scope.spawn(move || try_init(slot, build).map(drop)))
}
/// `OnceLock::get_or_init` for a fallible build: concurrent callers still wait for
/// one build; a failure leaves the slot empty and returns its error to that caller.
pub(crate) fn try_init<T>(slot: &OnceLock<T>, build: impl FnOnce() -> Result<T>) -> Result<&T> {
struct Failed;
let mut failure = None;
// OnceLock is not poisoned by an unwinding initializer; resume_unwind skips the panic hook.
let init = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| slot.get_or_init(|| {
build().unwrap_or_else(|error| {
failure = Some(error);
std::panic::resume_unwind(Box::new(Failed))
})
})));
match (init, failure) {
(Ok(value), _) => Ok(value),
(Err(_), Some(error)) => Err(error),
(Err(panic), None) => std::panic::resume_unwind(panic),
}
}
/// A scoped worker's result, re-raising its panic.
pub(crate) fn join<T>(job: std::thread::ScopedJoinHandle<'_, T>) -> T {
job.join().unwrap_or_else(|panic| std::panic::resume_unwind(panic))
}
/// Join lazy descriptor jobs, returning the first failure.
fn joined<'scope>(jobs: impl IntoIterator<Item = Option<Job<'scope>>>) -> Result<()> {
jobs.into_iter().flatten().try_for_each(join)
}
/// Infallible replay paths only run after the install compiler join.
pub(crate) fn base<T>(slot: &OnceLock<T>) -> &T {
slot.get().expect("base pipelines installed")
}
/// Owned pipeline-creation handle: background variant workers outlive the install
/// call that started them, so they cannot borrow the Renderer.
#[derive(Clone)]
pub(crate) struct Compiler {
#[cfg(test)]
pub(crate) hit_selections: std::sync::Arc<Mutex<Vec<(ProgramKernel, ProgramKernel)>>>,
device: wgpu::Device,
cache: Option<wgpu::PipelineCache>,
/// Wall time per driver pipeline creation call; concurrent times overlap.
pub(crate) timings: std::sync::Arc<Mutex<std::collections::BTreeMap<String, f64>>>,
known: std::sync::Arc<Mutex<Known>>,
pending: std::sync::Arc<(Mutex<Pending>, std::sync::Condvar)>,
schedule: std::sync::Arc<(Mutex<Schedule>, std::sync::Condvar)>,
/// Driver creations so far; unchanged since the last save means nothing to persist.
created: std::sync::Arc<std::sync::atomic::AtomicUsize>,
}
/// Background variant workers still compiling, and the first one that failed.
#[derive(Default)]
struct Pending {
workers: usize,
failure: Option<String>,
}
/// Driver pipeline creation around critical-path work (the hardware encoder attach).
#[derive(Default)]
struct Schedule {
critical: bool,
foreground_preparations: usize,
active: usize,
}
/// One admitted driver pipeline creation; frees its place when dropped.
struct Permit<'a>(&'a (Mutex<Schedule>, std::sync::Condvar));
impl Drop for Permit<'_> {
fn drop(&mut self) {
self.0.0.lock().unwrap().active -= 1;
self.0.1.notify_all();
}
}
/// Defer optional variants until every foreground preparation has finished.
/// This covers Slang admission as well as driver calls, including error exits.
pub(crate) struct ForegroundPreparation(std::sync::Arc<(Mutex<Schedule>, std::sync::Condvar)>);
impl Drop for ForegroundPreparation {
fn drop(&mut self) {
self.0.0.lock().unwrap().foreground_preparations -= 1;
self.0.1.notify_all();
}
}
impl<'a> Permit<'a> {
fn new(schedule: &'a (Mutex<Schedule>, std::sync::Condvar), background: bool) -> Self {
let (state, signal) = schedule;
let mut state = signal.wait_while(state.lock().unwrap(), |s| {
(background && s.foreground_preparations != 0)
|| s.critical && (background || s.active >= crate::constants::CRITICAL_PIPELINE_THREADS)
}).unwrap();
state.active += 1;
Self(schedule)
}
}
impl Compiler {
pub(crate) fn new(
device: &wgpu::Device,
cache: Option<&wgpu::PipelineCache>,
known: Known,
) -> Self {
Self {
#[cfg(test)]
hit_selections: Default::default(),
device: device.clone(),
cache: cache.cloned(),
timings: Default::default(),
known: std::sync::Arc::new(Mutex::new(known)),
pending: Default::default(),
schedule: Default::default(),
created: Default::default(),
}
}
pub(crate) fn created(&self) -> usize {
self.created.load(std::sync::atomic::Ordering::Acquire)
}
/// Mark critical-path driver work (encoder attach) in flight or finished. While it
/// runs, install creations are throttled and background variants wait.
pub(crate) fn set_critical(&self, critical: bool) {
self.schedule.0.lock().unwrap().critical = critical;
self.schedule.1.notify_all();
}
/// Admit one creation: at most CRITICAL_PIPELINE_THREADS at once during critical
/// work; background variants only once it has finished.
fn permit(&self, background: bool) -> Permit<'_> {
Permit::new(&self.schedule, background)
}
pub(crate) fn foreground_preparation(&self) -> ForegroundPreparation {
self.schedule.0.lock().unwrap().foreground_preparations += 1;
ForegroundPreparation(self.schedule.clone())
}
#[cfg(test)]
pub(crate) fn is_idle(&self) -> bool {
self.pending.0.lock().unwrap().workers == 0
}
/// Extract a cache only between driver creations. Holding admission closed
/// prevents a deferred worker entering the driver during the snapshot; workers
/// still compiling Slang need not finish. Never wait for an active creation.
pub(crate) fn when_idle<T>(&self, save: impl FnOnce() -> T) -> Option<T> {
let state = self.schedule.0.try_lock().ok()?;
if state.active != 0 {
return None;
}
Some(save())
}
/// Block until every background variant has finished; a failed worker is an error.
pub(crate) fn settle(&self) -> Result<()> {
let (pending, done) = &*self.pending;
let pending = done.wait_while(pending.lock().unwrap(), |p| p.workers > 0).unwrap();
match &pending.failure {
Some(failure) => Err(anyhow::anyhow!("pipeline variant: {failure}")),
None => Ok(()),
}
}
/// Run one optional variant compilation after foreground preparation. A failure
/// or panic still retires the worker (its drawn key keeps the superset fallback),
/// so settling reports it instead of waiting forever.
pub(crate) fn spawn_variant(&self, mode: VariantCompile, build: impl FnOnce() -> Result<()> + Send + 'static) {
self.pending.0.lock().unwrap().workers += 1;
let c = self.clone();
std::thread::spawn(move || {
if let VariantCompile::Gated(gate) = &mode {
let (open, signal) = &**gate;
let _open = signal.wait_while(open.lock().unwrap(), |open| !*open);
}
let failure = match std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
drop(c.permit(true));
build()
})) {
Ok(Ok(())) => None,
Ok(Err(error)) => Some(format!("{error:#}")),
Err(_) => Some("worker panicked".into()),
};
let (pending, done) = &*c.pending;
let mut pending = pending.lock().unwrap();
pending.workers -= 1;
if pending.failure.is_none() { pending.failure = failure; }
done.notify_all();
});
}
fn time(&self, label: Option<&str>, start: std::time::Instant) {
let ms=start.elapsed().as_secs_f64()*1000.;
crate::timing::creation(&self.device,label.unwrap_or("pipeline"),"pipeline",0.,ms);
*self
.timings
.lock()
.unwrap()
.entry(label.unwrap_or("pipeline").into())
.or_default() += ms;
}
pub(crate) fn render(&self, descriptor: &wgpu::RenderPipelineDescriptor<'_>) -> wgpu::RenderPipeline {
let _permit = self.permit(false);
let start = std::time::Instant::now();
let _progress = vork_slang::progress::Job::start(true);
let pipeline = crate::gpu_memory::render_pipeline(&self.device, descriptor);
self.created.fetch_add(1, std::sync::atomic::Ordering::AcqRel);
self.time(descriptor.label, start);
pipeline
}
pub(crate) fn compute(&self, descriptor: &wgpu::ComputePipelineDescriptor<'_>) -> wgpu::ComputePipeline {
let _permit = self.permit(false);
let start = std::time::Instant::now();
let _progress = vork_slang::progress::Job::start(true);
let pipeline = crate::gpu_memory::compute_pipeline(&self.device, descriptor);
self.created.fetch_add(1, std::sync::atomic::Ordering::AcqRel);
self.time(descriptor.label, start);
pipeline
}
/// Publish an optional pipeline through the same retained slot for every install.
pub(crate) fn install_variant<P:Clone+Send+Sync+'static>(&self,mode:&VariantCompile,slot:std::sync::Arc<OnceLock<P>>,fallback:Option<P>,build:impl FnOnce(&Compiler)->Result<P>+Send+'static)->Result<Drawn<P>> {
if let (true,Some(pipeline))=(mode.fallback(),&fallback) {return Ok(Drawn::inline(pipeline.clone()));}
let deferred=fallback.is_some();
self.publish_variant(mode,slot,fallback,deferred,build)
}
/// The caller keeps its existing pass sequence until this optional kernel is ready.
pub(crate) fn install_optional<P:Clone+Send+Sync+'static>(&self,mode:&VariantCompile,slot:std::sync::Arc<OnceLock<P>>,warm:bool,build:impl FnOnce(&Compiler)->Result<P>+Send+'static)->Result<Drawn<P>> {
let deferred=mode.defer(slot.get().is_some() || warm,true);
self.publish_variant(mode,slot,None,deferred,build)
}
fn publish_variant<P:Clone+Send+Sync+'static>(&self,mode:&VariantCompile,slot:std::sync::Arc<OnceLock<P>>,fallback:Option<P>,deferred:bool,build:impl FnOnce(&Compiler)->Result<P>+Send+'static)->Result<Drawn<P>> {
if deferred {
let (worker,target)=(self.clone(),slot.clone());
self.spawn_variant(mode.clone(),move || try_init(&target,||build(&worker)).map(drop));
} else {try_init(&slot,||build(self))?;}
Ok(Drawn {variant:slot,fallback,deferred})
}
pub(crate) fn compute_entry(&self, layout:&wgpu::PipelineLayout, module:&wgpu::ShaderModule, entry:&str, label:&str)->wgpu::ComputePipeline {
self.compute(&wgpu::ComputePipelineDescriptor {label:Some(label),layout:Some(layout),module,entry_point:Some(entry),compilation_options:Default::default(),cache:self.cache.as_ref()})
}
pub(crate) fn is_known(&self, key: &blake3::Hash) -> bool {
self.known.lock().unwrap().keys.contains(key.as_bytes())
}
pub(crate) fn remember(&self, key: blake3::Hash) {
let mut known = self.known.lock().unwrap();
known.added |= known.keys.insert(*key.as_bytes());
}
/// The key set to persist with the blob, when it gained keys since the last save.
pub(crate) fn known_snapshot(&self) -> Option<Known> {
let mut known = self.known.lock().unwrap();
std::mem::take(&mut known.added).then(|| Known {
path: known.path.clone(),
keys: known.keys.clone(),
added: true,
})
}
}
/// Content keys of geometry pipelines the persistent pipeline cache holds: a known
/// variant is a warm hit and compiles inline; an unknown one compiles in the background.
#[derive(Default)]
pub(crate) struct Known {
path: std::path::PathBuf,
keys: std::collections::HashSet<[u8; 32]>,
added: bool,
}
impl Known {
pub(crate) fn load(path: std::path::PathBuf, blob_accepted: bool) -> Self {
let keys = blob_accepted
.then(|| crate::disk_cache::read(&path))
.flatten()
.map(|bytes| {
bytes
.chunks_exact(32)
.map(|key| key.try_into().unwrap())
.collect()
})
.unwrap_or_default();
Self {
path,
keys,
added: false,
}
}
pub(crate) fn save(&self) -> Result<()> {
let mut keys: Vec<_> = self.keys.iter().collect();
keys.sort_unstable();
crate::disk_cache::write(
&self.path,
&keys.into_iter().flatten().copied().collect::<Vec<u8>>(),
)?;
Ok(())
}
}
/// How install obtains feature variants that are not yet in the persistent cache.
#[derive(Clone, Default)]
#[cfg_attr(not(test), allow(dead_code))]
pub(crate) enum VariantCompile {
/// Draw with the shared superset pipeline until the variant compiles in the background.
#[default]
Background,
/// Draw only the generic; one-frame shots have no use for a later variant.
Fallback,
/// `vork setup`: Fallback's choices, and the hit kernels compile the superset
/// key a later Fallback install draws with (CachedPipelines::drawn_kernel).
Setup,
/// Startup's ordinary table configuration: retain material proofs while
/// sharing hit evaluators across light mixes. Other kernels use Setup.
SetupPlain,
/// Compile every variant before install returns.
Inline,
/// Tests: background workers start only once the gate opens, regardless of warmth.
Gated(std::sync::Arc<(Mutex<bool>, std::sync::Condvar)>),
}
impl VariantCompile {
/// The caller admits a generic only when it is suitable for foreground use.
/// Geometry generics are cheap shipped controls; camera generics need a warm
/// driver cache, otherwise their larger JIT loses to direct specialization.
pub(crate) fn defer(&self,warm:bool,generic_ready:bool)->bool {
match self {
Self::Inline=>false,
Self::Gated(_)=>true,
Self::Background|Self::Fallback|Self::Setup|Self::SetupPlain=>!warm && generic_ready,
}
}
/// One-frame choices: draw generics and compile no later variant.
pub(crate) fn fallback(&self)->bool {matches!(self,Self::Fallback|Self::Setup|Self::SetupPlain)}
}
/// A retained variant; the caller supplies a pipeline fallback or keeps its existing passes.
#[derive(Clone)]
pub(crate) struct Drawn<P = wgpu::RenderPipeline> {
variant: std::sync::Arc<OnceLock<P>>,
fallback: Option<P>,
deferred: bool,
}
impl<P> Drawn<P> {
pub(crate) fn inline(pipeline:P)->Self {
Self {variant:std::sync::Arc::new(OnceLock::from(pipeline)),fallback:None,deferred:false}
}
pub(crate) fn current(&self, prefer_variant:bool) -> &P {
if prefer_variant {self.variant.get().or(self.fallback.as_ref())} else {self.fallback.as_ref().or(self.variant.get())}.expect("installed variant or fallback")
}
pub(crate) fn deferred(&self)->bool {self.deferred}
pub(crate) fn ready(&self) -> bool {
self.variant.get().is_some()
}
}
impl crate::InstalledScene {
/// Whether every drawn pipeline is its final variant (no superset fallback in use).
pub(crate) fn variants_ready(&self) -> bool {
self.geometry_pipelines.values().all(Drawn::ready) && self.decoupled.as_ref().is_none_or(|d|d.variants_ready())
}
/// Drawn pipelines installed behind a superset fallback (cold variants).
pub(crate) fn deferred_variants(&self) -> usize {
self.geometry_pipelines
.values()
.filter(|d| d.deferred())
.count() + self.decoupled.as_ref().map_or(0,|d|d.deferred_variants())
}
}
/// The shader one drawn key uses: module plus fragment override constants. Variant
/// backends implement this; the fallback key must cover every drawn feature and each
/// feature gate must stay `FEATURE && weight > 0`, so fallback pixels match.
pub(crate) trait VariantShader: Send + Sync {
/// The vertex and fragment modules (one module may serve both stages).
fn modules(&self, key: GeometryKey) -> Result<[wgpu::ShaderModule; 2]>;
/// Whether the generic control shader ships with the renderer.
fn generic_shipped(&self) -> bool;
fn constants(&self, key: GeometryKey) -> Vec<(&'static str, f64)>;
/// Shipped table evaluator, when it can serve the scene's transport.
fn camera_generic(&self, kernel: ProgramKernel) -> Option<&'static crate::native::Compiled>;
/// A shipped executable's warm hint, independent of unrelated scene state.
/// Constructors still create the current scene's complete pipeline layout.
fn shared_kernel_key(&self, _kernel: ProgramKernel) -> Option<blake3::Hash> { None }
/// A compute kernel with the scene's programs at hits, and its entry.
fn program_kernel(&self, kernel: ProgramKernel) -> Result<(wgpu::ShaderModule, &'static str)>;
/// Whether `program_kernel` would compile nothing: shipped, or its code is stored.
fn kernel_stored(&self, kernel: ProgramKernel) -> Result<bool>;
}
/// Compute kernels that evaluate surfaces at ray hits. GI, reflections and path
/// transport specialize over installed capabilities; other kernels compile per
/// scene when programs or attributes require it.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub(crate) enum ProgramKernel {
/// Path transport with adaptive or fixed sampling.
Path { adaptive: bool, catchers: bool, random_walk: bool, features: FeatureMask, boundaries: u32, emitter_profiles: bool, media: Option<u32> },
/// Ray-traced diffuse indirect.
Gi { features: FeatureMask },
/// Ray-traced reflections that shade unseen hits.
Reflections { features: FeatureMask },
/// The irradiance volume update (probes.rs).
Probes { features:FeatureMask, directional:bool },
/// Fixed camera stages and the scene's authored-program evaluation.
Decoupled { stage: ShadeStage, features: FeatureMask, subsurface: bool, emitter_profiles: bool, boundaries: u32 },
}
impl ProgramKernel {
/// Untextured, unlayered table materials share one hit evaluator across light
/// mixes. Keep runtime metalness, sidedness and every analytic light kind;
/// do not turn on unrelated texture/layer/transport capabilities.
pub(crate) fn plain_hit(self) -> Option<Self> {
use crate::forward_variant::*;
let lighting = FEATURE_LIGHT_TYPES | FEATURE_PUNCTUAL | FEATURE_FINITE
| FEATURE_RECTANGLE | FEATURE_ELLIPSE | FEATURE_SHADOW_RAYS;
let allowed = lighting | FEATURE_SPECIALIZED | FEATURE_LIT | FEATURE_SIDED
| FeatureMask::from(SHADING_METAL);
match self {
Self::Gi { features } if features & FEATURE_SPECIALIZED != 0 && features & !allowed == 0 => Some(Self::Gi { features: allowed }),
Self::Reflections { features } if features & FEATURE_SPECIALIZED != 0 && features & !allowed == 0 => Some(Self::Reflections { features: allowed }),
_ => None,
}
}
/// The same kernel over the generic feature key (variant.slang Unspecialized:
/// layered and metallic shading kept), for kernels that otherwise specialize to
/// the scene and have no shipped generic: ray GI, reflection and probe hits,
/// camera indirect work, and transmissive table/occupancy stages with boundaries.
pub(crate) fn superset(self) -> Option<Self> {
let all = (crate::forward_variant::SHADING_LAYERS | crate::forward_variant::SHADING_METAL) as FeatureMask;
match self {
Self::Gi {..} => Some(Self::Gi { features: all }),
Self::Reflections {..} => Some(Self::Reflections { features: all }),
Self::Probes {directional,..} => Some(Self::Probes { features: all, directional }),
// These stages store evaluations, whose record size belongs to the scene.
Self::Decoupled { stage: ShadeStage::Indirect | ShadeStage::Evaluate | ShadeStage::EvaluateOpaque, .. } => {
use crate::forward_variant::{FEATURE_EXACT_RECORD,FEATURE_RECORD_WORDS};
let mut superset = self;
if let Self::Decoupled { features, .. } = &mut superset { *features = all | FEATURE_EXACT_RECORD | *features & FEATURE_RECORD_WORDS; }
Some(superset)
}
Self::Decoupled { stage: ShadeStage::Occupancy, .. } => {
let mut superset = self;
if let Self::Decoupled { features, .. } = &mut superset { *features = all; }
Some(superset)
}
_ => None,
}
}
pub(crate) fn camera_label(self)->Option<String> {
let Self::Decoupled {stage,..}=self else {return None;};
Some(match stage {
ShadeStage::EvaluateOpaque=>"camera material evaluate opaque table".into(),
ShadeStage::Evaluate=>"camera material evaluate table".into(),
ShadeStage::EvaluateProgram(id)=>format!("camera material evaluate program {id}"),
ShadeStage::Compose=>"camera result composition".into(),
ShadeStage::Fused=>"camera fused table shading".into(),
ShadeStage::Indirect=>"camera unsupported indirect work".into(),
ShadeStage::Receivers=>"camera medium receivers".into(),
ShadeStage::Occupancy=>"camera dielectric occupancy".into(),
ShadeStage::Index=>"camera occupied slots".into(),
ShadeStage::Classify=>"camera material classify".into(),
ShadeStage::Prefix=>"camera material prefix".into(),
ShadeStage::Scatter=>"camera material scatter".into(),
})
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub(crate) enum ShadeStage {
Indirect, Fused, Receivers, Occupancy, Index, Classify, Prefix, Scatter, EvaluateOpaque, Evaluate, EvaluateProgram(u32), Compose }
impl ShadeStage {
pub(crate) fn composes(self)->bool {matches!(self,Self::Compose|Self::Fused)}
/// Stages that evaluate the built-in material table (Evaluate, EvaluateOpaque, Fused);
/// each program evaluates its own bin.
pub(crate) fn table(self)->bool {matches!(self,Self::Evaluate|Self::EvaluateOpaque|Self::Fused)}
}
#[derive(Clone,Copy,Debug,PartialEq,Eq,Hash)]
pub(crate) enum CoverageStage {Depth,Visibility}
/// One drawn geometry pipeline: its pass role and, for shading roles, the material
/// feature mask it specializes. Install creates exactly the roles its draws record.
#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
pub(crate) enum Role {
ProgramCoverage {program:u32, stage:CoverageStage},
/// Alpha-tested shadow caster.
Fibre(crate::fibre_transport::Stage),
/// Double-sided opaque depth, position only.
OpaqueDepth,
OpaqueSingleDepth,
/// Alpha-tested depth; `hashed` for dithered coverage (its entry reads SV_PrimitiveID).
MaskedDepth {hashed:bool},
/// Decoupled visibility keys, double- and single-sided and alpha-tested (passes/decoupled.rs).
Visibility,
VisibilitySingle,
VisibilityMasked,
/// Transparent draws' fragment lists in front of the visibility passes' depth.
TransparentFragments,
Controls(FeatureMask),
ProgramControls { program:u32, features:FeatureMask, transparent:bool },
TransparentControls(FeatureMask),
}
impl Role {
/// The single selection rule shared by install (what to compile) and bundles (what to bind).
pub(crate) fn of(
kind: crate::bundles::Kind,
flags: &crate::plan::DrawFlags,
material: &crate::materials::Material,
) -> Self {
// Program entries always read the primitive (ctx.primitive_id).
let hashed=material.dithered && material.program==0;
let role=Self::of_capabilities(kind, flags, material.double_sided, hashed, material.features);
if material.program!=0 {
match role {
Self::MaskedDepth {..}=>return Self::ProgramCoverage {program:material.program,stage:CoverageStage::Depth},
Self::VisibilityMasked=>return Self::ProgramCoverage {program:material.program,stage:CoverageStage::Visibility},
Self::Controls(features)=>return Self::ProgramControls {program:material.program,features,transparent:false},
Self::TransparentControls(features)=>return Self::ProgramControls {program:material.program,features,transparent:true},
_=>{}
}
}
role
}
/// `hashed`: table entries that declare SV_PrimitiveID (forward_variant::FEATURE_DITHERED).
fn of_capabilities(kind: crate::bundles::Kind, flags: &crate::plan::DrawFlags,
double_sided: bool, hashed: bool, features: FeatureMask) -> Self {
use crate::bundles::Kind;
let features = features | if hashed {crate::forward_variant::FEATURE_DITHERED} else {0};
match kind {
Kind::Fibre(stage,_) => Self::Fibre(stage),
Kind::Depth if flags.alpha_mask => Self::MaskedDepth {hashed},
Kind::Depth if double_sided => Self::OpaqueDepth,
Kind::Depth => Self::OpaqueSingleDepth,
Kind::Visibility(_) if flags.alpha_mask => Self::VisibilityMasked,
Kind::Visibility(_) if double_sided => Self::Visibility,
Kind::Visibility(_) => Self::VisibilitySingle,
Kind::TransparentFragments(_) => Self::TransparentFragments,
Kind::Controls => Self::Controls(
features
& !(crate::materials::FEATURE_LIGHT_TYPES
| crate::materials::FEATURE_PUNCTUAL
| crate::materials::FEATURE_FINITE
| crate::materials::FEATURE_RECTANGLE
| crate::materials::FEATURE_ELLIPSE),
),
// Controls evaluate the surface/environment response, never finite lights.
Kind::TransparentControls => Self::TransparentControls(
features
& !(crate::materials::FEATURE_LIGHT_TYPES
| crate::materials::FEATURE_PUNCTUAL
| crate::materials::FEATURE_FINITE
| crate::materials::FEATURE_RECTANGLE
| crate::materials::FEATURE_ELLIPSE),
),
}
}
/// The material feature mask this role specializes (0 for depth and shadow roles).
pub(crate) fn shading(self) -> FeatureMask {
match self {
Self::Controls(m) | Self::TransparentControls(m) | Self::ProgramControls {features:m,..} => m,
_ => 0,
}
}
/// The shared pipeline evaluating every material feature, when this role specializes.
/// The superset keeps the key's hashed coverage: the generic is shipped with and without it.
fn superset(self) -> Option<Self> {
let (Self::Controls(m) | Self::TransparentControls(m)) = self else {return None};
let all = FeatureMask::from(crate::materials::SHADING_LAYERS | crate::materials::SHADING_METAL)
| m & crate::forward_variant::FEATURE_DITHERED;
if m == all {return None;}
Some(if matches!(self, Self::Controls(_)) {Self::Controls(all)} else {Self::TransparentControls(all)})
}
/// Bundle kinds a draw is recorded in; mirrors the recorder's draw filters.
/// Raster colour is decoupled: opaque draws record visibility keys and
/// controls, transparent ones fragment lists and controls, and the shade
/// pass produces colour. Path frames record controls.
pub(crate) fn kinds(
flags: &crate::plan::DrawFlags,
decoupled: bool,
) -> &'static [crate::bundles::Kind] {
use crate::bundles::Kind;
match (flags.transparent, decoupled) {
(false, true) => &[Kind::Depth, Kind::Visibility(0), Kind::Controls],
(false, false) => &[Kind::Depth, Kind::Controls],
(true, true) => &[Kind::TransparentFragments(0), Kind::TransparentControls],
(true, false) => &[Kind::TransparentControls],
}
}
}
/// Installed pipelines per (vertex layout, role), shared by every scene on this registry.
pub(crate) type GeometryKey = (crate::geometry::VertexLayout, Role);
pub(crate) struct CachedPipelines {
pub(crate) raster_samples: u32,
pub(crate) denoise: bool,
/// Hash of every source and state input shared by this registry's pipelines.
identity: blake3::Hash,
kernel_identity: blake3::Hash,
/// Camera ray transport: shadows, refraction/thickness, or probes.
pub(crate) ray_shadows: bool,
/// Material programs provide procedural coverage to ray transport.
geometry: Mutex<
std::collections::HashMap<GeometryKey, std::sync::Arc<OnceLock<wgpu::RenderPipeline>>>,
>,
pub(crate) camera_evaluations: Mutex<std::collections::HashMap<ProgramKernel,std::sync::Arc<OnceLock<wgpu::ComputePipeline>>>>,
/// Module and override constants per drawn key (the variant backend seam).
pub(crate) shader: Box<dyn VariantShader>,
/// Decoupled slot merge (passes/decoupled.rs), built on first use.
pub(crate) decoupled_merge: OnceLock<wgpu::ComputePipeline>,
cluster_module: OnceLock<wgpu::ShaderModule>,
deform_module: OnceLock<wgpu::ShaderModule>,
depth_layout: wgpu::PipelineLayout,
/// Decoupled transparent fragments' group 2 (passes/decoupled.rs Fragments) and layout.
pub(crate) fragments_layout: wgpu::BindGroupLayout,
pub(crate) fragments_geometry_layout: wgpu::BindGroupLayout,
pub(crate) field_controls: bool,
fragments_pipeline_layout: wgpu::PipelineLayout,
fibre_layout: wgpu::PipelineLayout,
pub(crate) fibre_capture_layout: wgpu::BindGroupLayout,
control_targets: Vec<Option<wgpu::ColorTargetState>>,
pub(crate) resolve_module: String,
pub(crate) resolve_native: Option<medium::Native>,
control_module: OnceLock<wgpu::ShaderModule>,
resolve_layout: wgpu::PipelineLayout,
pub(crate) deform_pipeline: OnceLock<wgpu::ComputePipeline>,
pub(crate) cluster_pipeline: OnceLock<wgpu::ComputePipeline>,
pub(crate) camera_cull_pipeline: OnceLock<[wgpu::ComputePipeline; 3]>,
pub(crate) global_layout: wgpu::BindGroupLayout,
pub(crate) mat_layout: wgpu::BindGroupLayout,
pub(crate) camera_pages: u32,
pub(crate) shadow_layout: wgpu::BindGroupLayout,
pub(crate) resolve_pipeline: OnceLock<wgpu::ComputePipeline>,
pub(crate) fused_resolve_pipeline: OnceLock<wgpu::ComputePipeline>,
pub(crate) post_source_pipeline: OnceLock<wgpu::ComputePipeline>,
pub(crate) control_resolve_pipeline: OnceLock<wgpu::ComputePipeline>,
pub(crate) ao_blur_horizontal_pipeline: OnceLock<wgpu::ComputePipeline>,
pub(crate) ao_blur_vertical_pipeline: OnceLock<wgpu::ComputePipeline>,
}
impl CachedPipelines {
/// Shared registry/ledger identity, including shader inputs and descriptor
/// array capacities. Keys remembered by setup must describe the same pipeline
/// a later process creates, independently of the installed scene's values.
pub(crate) fn identity(source: &str, resolve: &str, raster_samples: u32, ray_shadows: bool,
slang: &crate::slang_forward::SlangScene, output_format: wgpu::TextureFormat) -> blake3::Hash {
let mut identity = blake3::Hasher::new();
identity.update(source.as_bytes());
identity.update(resolve.as_bytes());
identity.update(&slang.attributes.to_le_bytes());
identity.update(&slang.textures.max(1).to_le_bytes());
identity.update(&slang.samplers.max(1).to_le_bytes());
identity.update(&slang.shadow_capacity.to_le_bytes());
identity.update(&slang.aov_count.to_le_bytes());
identity.update(&[u8::from(slang.denoise), u8::from(slang.field_controls), u8::from(slang.no_shadow_containment)]);
identity.update(&[u8::from(ray_shadows), u8::from(slang.ray_refraction), u8::from(slang.probes), u8::from(slang.connection_transmission)]);
// Raster fibre resources change the shadow layout even when the material
// program is identical to one installed for a path scene.
identity.update(&[u8::from(slang.fibre)]);
identity.update(&[u8::from(slang.volume_visibility)]);
// Coverage changes fallback admission. Preserve opaque setup identities.
if slang.surface_coverage {identity.update(b"surface coverage");}
if let Some(native)=&slang.medium {
identity.update(&native.steps.to_le_bytes());
identity.update(native.point.as_bytes());identity.update(&native.identity);
identity.update(native.transport.as_bytes());
for value in [native.sample_pages.max(1), native.froxel_pages.max(1), native.froxel_page_elements, native.visibility_lights] {
identity.update(&value.to_le_bytes());
}
for flag in native.defines() { identity.update(flag.as_bytes()); identity.update(&[0]); }
identity.update(&[u8::from(native.ray_shadows), u8::from(native.mesh_sources), u8::from(native.program_coverage), u8::from(native.implicit), u8::from(native.surface_connection.is_some())]);
identity.update(&native.surface_connection.unwrap_or_default().to_le_bytes());
for (name,source) in &native.modules {identity.update(name.as_bytes());identity.update(source.as_bytes());}
for path in &native.includes {identity.update(path.to_string_lossy().as_bytes());}
}
if let Some(p)=&slang.propagation {
for (name,source) in &p.modules {identity.update(name.as_bytes());identity.update(source.as_bytes());}
for path in &p.include {identity.update(path.to_string_lossy().as_bytes());}
}
if let Some(camera)=&slang.camera {
for (name,source) in &camera.modules {identity.update(name.as_bytes());identity.update(source.as_bytes());}
for path in &camera.include {identity.update(path.to_string_lossy().as_bytes());}
}
if let Some(environment)=&slang.environment {
for (name,source) in &environment.modules {identity.update(name.as_bytes());identity.update(source.as_bytes());}
for path in &environment.include {identity.update(path.to_string_lossy().as_bytes());}
}
identity.update(&raster_samples.to_le_bytes());
identity.update(format!("{output_format:?}").as_bytes());
identity.finalize()
}
/// The pipeline for one drawn role, compiled once per registry. Different keys
/// compile concurrently; the registry lock is held only to find the slot.
pub(crate) fn geometry(&self, c: &Compiler, key: GeometryKey) -> Result<wgpu::RenderPipeline> {
try_init(&self.slot(key), || self.build_geometry(c, key)).cloned()
}
fn slot(&self, key: GeometryKey) -> std::sync::Arc<OnceLock<wgpu::RenderPipeline>> {
std::sync::Arc::clone(self.geometry.lock().unwrap().entry(key).or_default())
}
pub(crate) fn camera_slot(&self,key:ProgramKernel)->std::sync::Arc<OnceLock<wgpu::ComputePipeline>> {
self.camera_evaluations.lock().unwrap().entry(key).or_default().clone()
}
pub(crate) fn content_key(&self, key: impl std::fmt::Debug) -> blake3::Hash {
let mut hash = blake3::Hasher::new();
hash.update(self.identity.as_bytes());
hash.update(format!("{key:?}").as_bytes());
hash.finalize()
}
/// Surface compute kernels do not consume the display/resolve program or
/// the raster control pass's denoising attachments. Keep their ledger separate
/// from the complete registry identity so setup entries survive those edits.
fn kernel_identity(source: &str, raster_samples: u32, ray_shadows: bool,
slang: &crate::slang_forward::SlangScene) -> blake3::Hash {
let mut slang = slang.clone();
slang.denoise = false;
// Surface kernels never link camera-ray or path-propagation programs.
slang.camera = None;
slang.propagation = None;
Self::identity(source, "", raster_samples, ray_shadows, &slang, wgpu::TextureFormat::Rgba8Unorm)
}
pub(crate) fn kernel_content_key(&self, kernel: ProgramKernel) -> blake3::Hash {
if matches!(kernel, ProgramKernel::Path {..}) { return self.content_key(kernel); }
if let Some(key) = self.shader.shared_kernel_key(kernel) { return key; }
let mut hash = blake3::Hasher::new();
hash.update(self.kernel_identity.as_bytes());
hash.update(format!("{kernel:?}").as_bytes());
hash.finalize()
}
/// Install the drawn keys. Warm variants (in the persistent cache) compile inline;
/// cold ones draw with their shared superset until a background worker lands them.
pub(crate) fn install_geometry(
self: &std::sync::Arc<Self>,
r: &Renderer,
keys: std::collections::HashSet<GeometryKey>,
mode: &VariantCompile,
) -> Result<std::collections::HashMap<GeometryKey, Drawn>> {
let c = &r.compiler;
let warm =
|key: GeometryKey| self.slot(key).get().is_some() || c.is_known(&self.content_key(key));
// The shipped generic needs no Slang compilation. Even one cold key
// starts behind it; compiling a scene-union fallback would block frame 1.
let plan: Vec<_> = keys.iter().map(|&key| {
let fallback = key.1.superset().and_then(|family| {
let defer=mode.defer(warm(key),self.shader.generic_shipped() || warm((key.0,family)));
defer.then_some((key.0, family))
});
(key, fallback)
}).collect();
let inline: std::collections::HashSet<_> = plan
.iter()
.map(|&(key, fallback)| fallback.unwrap_or(key))
.collect();
let inline:Vec<_>=inline.into_iter().collect();
let cursor=std::sync::atomic::AtomicUsize::new(0);
let compiled: std::collections::HashMap<_, _> = std::thread::scope(|scope| {
(0..inline.len().min(std::thread::available_parallelism().map_or(1,usize::from)))
.map(|_|scope.spawn(|| {
let mut pipelines=Vec::new();
loop {
let index=cursor.fetch_add(1,std::sync::atomic::Ordering::Relaxed);
let Some(&key)=inline.get(index) else {break;};
pipelines.push((key,self.geometry(c,key)?));
}
Ok(pipelines)
})).collect::<Vec<_>>().into_iter()
.map(join).collect::<Result<Vec<_>>>()
})?.into_iter().flatten().collect();
plan.into_iter()
.map(|(key, fallback)| {
let this=self.clone();
let drawn=c.install_variant(mode,self.slot(key),fallback.map(|f|compiled[&f].clone()),move |worker|this.build_geometry(worker,key))?;
Ok((key, drawn))
})
.collect()
}
fn build_geometry(&self, c: &Compiler, key: GeometryKey) -> Result<wgpu::RenderPipeline> {
let pipeline = self.build_role(c, key)?;
c.remember(self.content_key(key));
Ok(pipeline)
}
fn build_role(&self, c: &Compiler, (packed, role): GeometryKey) -> Result<wgpu::RenderPipeline> {
let fibre_near_targets=[Some(wgpu::ColorTargetState {format:wgpu::TextureFormat::Rg32Uint,blend:None,write_mask:wgpu::ColorWrites::ALL})];
let fibre_targets=vec![Some(wgpu::ColorTargetState {format:wgpu::TextureFormat::Rgba16Float,
blend:Some(wgpu::BlendState {color:wgpu::BlendComponent {src_factor:wgpu::BlendFactor::One,dst_factor:wgpu::BlendFactor::One,operation:wgpu::BlendOperation::Add},alpha:wgpu::BlendComponent {src_factor:wgpu::BlendFactor::One,dst_factor:wgpu::BlendFactor::One,operation:wgpu::BlendOperation::Add}}),write_mask:wgpu::ColorWrites::ALL});1];
let fragment_targets = [Some(wgpu::ColorTargetState {
format: crate::passes::decoupled::KEY_FORMAT, blend: None, write_mask: wgpu::ColorWrites::empty(),
})];
let visibility_targets = [Some(wgpu::ColorTargetState {
format: crate::passes::decoupled::KEY_FORMAT, blend: None, write_mask: wgpu::ColorWrites::ALL,
})];
let depth = &self.depth_layout;
let samples = self.raster_samples;
let (layout, label, vs, fs, samples, write, targets): (
_,
_,
_,
_,
_,
_,
&[Option<wgpu::ColorTargetState>],
) = match role {
Role::Fibre(stage) => (
if stage.additive() {&self.fibre_layout} else {depth},
"fibre transport capture","shadow_vs",stage.entry(),1,
!stage.additive(),
if stage.additive() {&fibre_targets} else if stage==crate::fibre_transport::Stage::Near {&fibre_near_targets} else {&[]}
),
Role::OpaqueDepth => (
depth,
"packed opaque depth",
"opaque_depth_vs",
"",
samples,
true,
&[],
),
Role::OpaqueSingleDepth => (
depth,
"packed single-sided opaque depth",
"opaque_single_depth_vs",
"opaque_single_depth_fs",
samples,
true,
&[],
),
Role::MaskedDepth {..} | Role::ProgramCoverage {stage:CoverageStage::Depth,..} => (
depth,
"packed depth",
"main_vs",
if role==(Role::MaskedDepth {hashed:true}) {"hashed_depth_fs"} else {"depth_fs"},
samples,
true,
&[],
),
Role::Visibility | Role::VisibilitySingle | Role::VisibilityMasked | Role::ProgramCoverage {stage:CoverageStage::Visibility,..} => (
&self.fragments_pipeline_layout,
"decoupled visibility",
if matches!(role,Role::VisibilityMasked | Role::ProgramCoverage {stage:CoverageStage::Visibility,..}) { "masked_vs" } else { "vs" },
match role { Role::Visibility => "fs", Role::VisibilitySingle => "single_fs", _ => "masked_fs" },
1,
true,
&visibility_targets,
),
// In the visibility pass after its opaque keys, writing no key.
Role::TransparentFragments => (
&self.fragments_pipeline_layout,
"decoupled transparent fragments",
"masked_vs",
if self.field_controls {"transparent_fragments_fs"} else {"transparent_triangles_fs"},
1,
false,
&fragment_targets,
),
Role::Controls(_) | Role::ProgramControls {transparent:false,..} => (
if self.field_controls {&self.fragments_pipeline_layout} else {depth},
"packed opaque controls",
"main_vs",
"controls_fs",
samples,
self.field_controls,
&self.control_targets,
),
Role::TransparentControls(_) | Role::ProgramControls {transparent:true,..} => (
if self.field_controls {&self.fragments_pipeline_layout} else {depth},
"packed controls",
"main_vs",
"transparent_controls_fs",
samples,
true,
&self.control_targets,
),
};
let shading = role.shading();
let variant_label = if shading & crate::materials::FEATURE_SPECIALIZED != 0 {
format!("{label} key={shading:016x}")
} else {
label.to_owned()
};
Ok(packed_geometry_pipeline(
c,
&self.shader.modules((packed, role))?,
&self.shader.constants((packed, role)),
layout,
&variant_label,
vs,
fs,
samples,
write,
targets,
packed,
))
}
// Slang registration: ("clusters", "main", "compute"). Per-file discovery
// registers shaders/clusters.slang; no shared build registry edit is needed.
fn build_cluster_pipeline(&self, r: &Renderer) -> wgpu::ComputePipeline {
let entries = cluster_entries();
let bind_layout = r
.device
.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
label: Some("cluster light culling"),
entries: &entries,
});
let layout = r
.device
.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
label: Some("cluster light culling"),
bind_group_layouts: &[Some(&bind_layout)],
immediate_size: 0,
});
r.create_compute_pipeline(&wgpu::ComputePipelineDescriptor {
label: Some("cluster light culling"),
layout: Some(&layout),
module: self
.cluster_module
.get_or_init(|| native::shader_module(&r.device, &native::CLUSTERS_CULL)),
entry_point: Some("cull"),
compilation_options: Default::default(),
cache: r.cache.as_ref(),
})
}
fn build_deform_pipeline(&self, r: &Renderer) -> wgpu::ComputePipeline {
passes::deform::pipeline(r, &self.deform_module)
}
pub(crate) fn ensure_assets(&self, r: &Renderer, plan: &crate::plan::ScenePlan) -> Result<()> {
std::thread::scope(|scope| {
let compute_jobs: [(_, _, fn(&Self, &Renderer) -> wgpu::ComputePipeline); 2] = [
(
&self.cluster_pipeline,
plan.cluster,
Self::build_cluster_pipeline,
),
(
&self.deform_pipeline,
plan.deform,
Self::build_deform_pipeline,
),
];
joined(compute_jobs.map(|(slot, needed, build)| compile(scope, slot, needed, move || Ok(build(self, r)))))
})
}
/// The path transport module and entry, with the scene's programs at hits.
pub(crate) fn program_kernel(&self, kernel: ProgramKernel) -> Result<(wgpu::ShaderModule, &'static str)> {
self.shader.program_kernel(kernel)
}
/// The kernel an install draws for `kernel`. Kernels specialized to the scene's
/// material features have a superset key that shades every material the same way
/// and stores the scene's evaluation record;
/// a one-frame install draws with the superset when `vork setup` stored it and the
/// specialization is not stored, instead of compiling (a still has no later frame
/// to use the specialization). Setup compiles the superset. Every other install
/// specializes: a cold specialization compiles faster than the superset. The
/// lookups are content-addressed, so a superset of a scene setup never saw
/// (other programs or inputs) is simply absent.
/// Shipped late-specialization artifacts exist for every capability key;
/// prefer a remembered device superset before consulting artifact presence.
pub(crate) fn drawn_kernel(&self, kernel: ProgramKernel, mode: &VariantCompile, compiler: &Compiler) -> ProgramKernel {
if matches!(mode, VariantCompile::Background | VariantCompile::Fallback)
&& !compiler.is_known(&self.kernel_content_key(kernel))
{
if let Some(plain) = kernel.plain_hit().filter(|plain| compiler.is_known(&self.kernel_content_key(*plain))) {
return plain;
}
}
let Some(superset) = kernel.superset() else { return kernel };
let stored = |kernel| self.shader.kernel_stored(kernel).unwrap_or(false);
match mode {
VariantCompile::Setup => superset,
VariantCompile::SetupPlain => kernel.plain_hit().unwrap_or(superset),
VariantCompile::Fallback if !compiler.is_known(&self.kernel_content_key(kernel))
&& compiler.is_known(&self.kernel_content_key(superset)) => superset,
VariantCompile::Fallback if !stored(kernel) && stored(superset) => superset,
_ => kernel,
}
}
/// The output layout and dispatch must use the same planned resolve, including
/// encoder surfaces attached after frame-slot creation.
pub(crate) fn output_resolve(&self, effects: EffectPlan) -> &OnceLock<wgpu::ComputePipeline> {
if effects.fuse_controls() {
&self.fused_resolve_pipeline
} else {
&self.resolve_pipeline
}
}
pub(crate) fn ensure_effects(&self, r: &Renderer, features: EffectPlan) -> Result<()> {
let ao_blur_layout = crate::passes::ao::slang_layout(&r.device);
enum Module {
Slang(&'static crate::native::Compiled),
Resolve,
}
let jobs = [
(
&self.fused_resolve_pipeline,
features.fuse_controls(),
Module::Resolve,
Some(&self.resolve_layout),
"main",
"fused control and output resolve",
),
(
&self.resolve_pipeline,
!features.fuse_controls(),
Module::Resolve,
Some(&self.resolve_layout),
"main",
"resolve",
),
(
&self.post_source_pipeline,
features.compositor || features.denoise,
Module::Resolve,
Some(&self.resolve_layout),
"post_source",
"scene-linear post source",
),
(
&self.ao_blur_horizontal_pipeline,
features.indirect,
Module::Slang(&crate::native::AO_BLUR_HORIZONTAL),
Some(&ao_blur_layout),
"horizontal",
"AO per-sample horizontal reconstruction",
),
(
&self.ao_blur_vertical_pipeline,
features.indirect,
Module::Slang(&crate::native::AO_BLUR_VERTICAL),
Some(&ao_blur_layout),
"vertical",
"AO per-sample vertical reconstruction",
),
];
std::thread::scope(|scope| {
scope.spawn(|| {
environment::Environment::pipeline(r);
});
let fixed = [
compile(scope, &self.control_resolve_pipeline, !features.fuse_controls(), || {
let shader = control_resolve_shader(self.raster_samples, self.denoise);
let module = self
.control_module
.get_or_init(|| crate::native::shader_module(&r.device, shader));
let entries = control_resolve_entries(self.raster_samples, self.denoise);
let group = r
.device
.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
label: Some("control resolve"),
entries: &entries,
});
let layout = r
.device
.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
label: Some("control resolve"),
bind_group_layouts: &[Some(&group)],
immediate_size: 0,
});
Ok(r.create_compute_pipeline(&wgpu::ComputePipelineDescriptor {
label: Some("single-sample controls"),
layout: Some(&layout),
module,
entry_point: Some(shader.entry),
compilation_options: Default::default(),
cache: r.cache.as_ref(),
}))
}),
];
let descriptors = jobs.map(|(slot, needed, module, layout, entry, label)| {
compile(scope, slot, needed, move || {
if matches!(&module, Module::Resolve) {
let entry=if label == "fused control and output resolve" {
if self.raster_samples > 1 {"resolve_fused"} else {"resolve_fused_single"}
} else {entry};
return Ok(passes::resolve::pipeline(r,&self.resolve_module,self.resolve_native.as_ref(),entry,layout));
}
let native_module;
let module = match module {
Module::Resolve => unreachable!(),
Module::Slang(shader) => {
native_module = crate::native::shader_module(&r.device, shader);
&native_module
}
};
Ok(r.create_compute_pipeline(&wgpu::ComputePipelineDescriptor {
label: Some(label),
layout,
module,
entry_point: Some(entry),
compilation_options: wgpu::PipelineCompilationOptions {
constants: if label == "fused control and output resolve" { &[("FUSED_CONTROLS", 1.)] } else { &[] },
..Default::default()
},
cache: r.cache.as_ref(),
}))
})
});
joined(fixed.into_iter().chain(descriptors))
})
}
pub(crate) fn with_sources(
r: &Renderer,
source: &str,
resolve: &str,
resolve_native: Option<&medium::Native>,
raster_samples: u32,
ray_shadows: bool,
slang: crate::slang_forward::SlangScene,
) -> Self {
let d = &r.device;
let globals=global_entries();
let global_layout = d.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
label: Some("frame + objects"),
entries: &globals,
});
let mat_layout = d.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
label: Some("material"),
entries: &material_entries_for(slang.textures.max(1),slang.samplers.max(1)),
});
let shadow_entries = camera_shadow_entries(ray_shadows);
let shadow_layout = d.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
label: Some("shadow read"),
entries: &shadow_entries,
});
let fibre_capture_layout=d.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {label:Some("fibre capture inputs"),entries:&crate::fibre_transport::capture_entries()});
let fibre_layout=d.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {label:Some("fibre transport capture"),bind_group_layouts:&[Some(&global_layout),Some(&mat_layout),Some(&fibre_capture_layout)],immediate_size:0});
// Depth and controls read only frame/object + material tables.
let depth_layout = d.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
label: Some("packed depth layout"),
bind_group_layouts: &[Some(&global_layout), Some(&mat_layout)],
immediate_size: 0,
});
let fragments_layout = d.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
label: Some("transparent fragments"),
entries: &crate::passes::decoupled::fragments_entries(resolve_native.map_or(0,|n|n.sample_pages)),
});
let fragments_geometry_layout=crate::passes::decoupled::fragments_geometry_layout(d);
let fragments_pipeline_layout = d.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
label: Some("decoupled transparent fragments"),
bind_group_layouts: &[Some(&global_layout), Some(&mat_layout), Some(&fragments_layout), Some(&fragments_geometry_layout)],
immediate_size: 0,
});
let denoise=slang.denoise;
let camera_pages=crate::passes::decoupled::evaluation_pages(&d.limits(),slang.aov_count);
// The controls pass writes ambient, IDs, normals, motion (and denoising albedo);
// colour comes from shading.
let control_targets: Vec<_> = control_formats(denoise).iter().map(|format|
format.map(wgpu::ColorTargetState::from)).collect();
let resolve_module = resolve.to_owned();
let mut resolve_entries = passes::resolve::layout_entries(
if raster_samples > 1 { "resolve_color" } else { "resolve_fused_single" },
);
if resolve_native.is_some_and(|n|n.program_coverage) {
resolve_entries.extend(passes::resolve::shadow_closure_entries());
}
if resolve_native.is_some() {
resolve_entries.push(buffer_entry(64,wgpu::ShaderStages::COMPUTE,wgpu::BufferBindingType::Uniform));
resolve_entries.push(buffer_entry(65,wgpu::ShaderStages::COMPUTE,wgpu::BufferBindingType::Storage {read_only:true}));
resolve_entries.push(buffer_entry(3,wgpu::ShaderStages::COMPUTE,wgpu::BufferBindingType::Uniform));
if resolve_native.is_some_and(|n|n.ray_shadows) {resolve_entries.extend(crate::rt::layout_entries(59,wgpu::ShaderStages::COMPUTE));resolve_entries.push(buffer_entry(71,wgpu::ShaderStages::COMPUTE,wgpu::BufferBindingType::Storage {read_only:true}));}
}
let output_entry = wgpu::BindGroupLayoutEntry {
binding: 0,
visibility: wgpu::ShaderStages::COMPUTE,
ty: wgpu::BindingType::StorageTexture {
access: wgpu::StorageTextureAccess::WriteOnly,
format: r.output_format(),
view_dimension: wgpu::TextureViewDimension::D2,
},
count: None,
};
let output_layout = d.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
label: Some("encoder surface"),
entries: &[output_entry],
});
let resolve_bind_layout = d.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
label: Some("resolve and motion resources"),
entries: &resolve_entries,
});
let resolve_layout = d.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
label: Some("resolve and motion layout"),
bind_group_layouts: &[Some(&resolve_bind_layout), Some(&output_layout)],
immediate_size: 0,
});
let identity = Self::identity(source, resolve, raster_samples, ray_shadows, &slang, r.output_format());
let kernel_identity = Self::kernel_identity(source, raster_samples, ray_shadows, &slang);
Self {
kernel_identity,
decoupled_merge: OnceLock::new(),
raster_samples,
denoise,
identity,
ray_shadows,
field_controls: slang.field_controls,
// Every raster role uses native Slang, including mesh media.
shader: Box::new(crate::slang_forward::SlangForward::new(
r,
ray_shadows,
raster_samples > 1,
slang,
)),
cluster_module: OnceLock::new(),
deform_module: OnceLock::new(),
depth_layout,
fragments_layout,
fragments_geometry_layout,
fragments_pipeline_layout,
fibre_layout,
fibre_capture_layout,
geometry: Mutex::default(),
camera_evaluations: Mutex::default(),
control_targets,
resolve_module,
resolve_native: resolve_native.cloned(),
control_module: OnceLock::new(),
resolve_layout,
deform_pipeline: OnceLock::new(),
cluster_pipeline: OnceLock::new(),
camera_cull_pipeline: OnceLock::new(),
global_layout,
mat_layout,
camera_pages,
shadow_layout,
resolve_pipeline: OnceLock::new(),
fused_resolve_pipeline: OnceLock::new(),
post_source_pipeline: OnceLock::new(),
control_resolve_pipeline: OnceLock::new(),
ao_blur_horizontal_pipeline: OnceLock::new(),
ao_blur_vertical_pipeline: OnceLock::new(),
}
}
}
/// Group 0 of every geometry pass (shaders/frame.slang): frame, objects, lights,
/// environment, LTC tables and clusters.
/// Scene globals (frame.slang), read by raster stages and the compute kernels that shade surfaces.
pub(crate) fn global_entries() -> Vec<wgpu::BindGroupLayoutEntry> {
let mut entries = vec![
buffer_entry(
0,
wgpu::ShaderStages::VERTEX_FRAGMENT,
wgpu::BufferBindingType::Uniform,
),
buffer_entry(
1,
wgpu::ShaderStages::VERTEX_FRAGMENT,
wgpu::BufferBindingType::Storage { read_only: true },
),
buffer_entry(
2,
wgpu::ShaderStages::FRAGMENT,
wgpu::BufferBindingType::Storage { read_only: true },
),
buffer_entry(
7,
wgpu::ShaderStages::FRAGMENT,
wgpu::BufferBindingType::Uniform,
),
buffer_entry(
8,
wgpu::ShaderStages::FRAGMENT,
wgpu::BufferBindingType::Storage { read_only: true },
),
texture_entry(
3,
wgpu::TextureSampleType::Float { filterable: true },
false,
),
sampler_entry(4, false),
texture_entry(
5,
wgpu::TextureSampleType::Float { filterable: true },
false,
),
texture_entry(
6,
wgpu::TextureSampleType::Float { filterable: true },
false,
),
texture_entry(
9,
wgpu::TextureSampleType::Float { filterable: true },
false,
),
];
for e in &mut entries {e.visibility |= wgpu::ShaderStages::COMPUTE;}
entries
}
/// Group 1: records plus scene-sized material texture and sampler tables. Ray-traced AO also reads it from compute for alpha-tested hits.
pub(crate) fn material_entries(_rays: bool) -> Vec<wgpu::BindGroupLayoutEntry> {material_entries_for(1,1)}
pub(crate) fn material_entries_for(textures:u32,samplers:u32) -> Vec<wgpu::BindGroupLayoutEntry> {
let textures=textures.max(vork_slang::registry::MATERIAL_TEXTURE_CAPACITY);
let samplers=samplers.max(vork_slang::registry::MATERIAL_SAMPLER_CAPACITY);
use crate::binding_abi::{MATERIAL, Resource};
let visibility = wgpu::ShaderStages::FRAGMENT | wgpu::ShaderStages::COMPUTE;
MATERIAL.iter().enumerate().map(|(binding, description)| {
let binding=binding as u32;
let (ty,count)=match description.resource {
Resource::ReadBuffer(_) | Resource::WriteBuffer(_) => (wgpu::BindingType::Buffer {
ty:wgpu::BufferBindingType::Storage {read_only:matches!(description.resource,Resource::ReadBuffer(_))},
has_dynamic_offset:false,min_binding_size:None,
},None),
Resource::Textures=>(texture_entry(binding,wgpu::TextureSampleType::Float {filterable:true},false).ty,std::num::NonZeroU32::new(textures)),
Resource::Samplers=>(sampler_entry(binding,false).ty,std::num::NonZeroU32::new(samplers)),
};
wgpu::BindGroupLayoutEntry {binding,visibility: if binding == 3 {visibility | wgpu::ShaderStages::VERTEX} else {visibility},ty,count}
}).collect()
}
/// Group 2: immutable emitter-sampling rows.
pub(crate) fn shadow_entries() -> Vec<wgpu::BindGroupLayoutEntry> {
vec![crate::shadows::sequence_entry()]
}
/// Stable camera resource table. Optional consumers bind empty records.
pub(crate) fn camera_shadow_entries(rays:bool)->Vec<wgpu::BindGroupLayoutEntry> {
let stages=wgpu::ShaderStages::COMPUTE;
let mut entries=shadow_entries();
if rays {
entries.extend(crate::rt::layout_entries(1,stages));
entries.push(crate::rt::hit_buffers_entry(3,stages));
} else {
entries.extend((1..4).map(|i|buffer_entry(i,stages,wgpu::BufferBindingType::Storage {read_only:true})));
}
entries.extend(crate::fibre_transport::read_entries(4));
entries.extend(crate::probes::read_entries(9,stages));
for e in &mut entries {e.visibility=stages;}
entries
}
pub(crate) fn buffer_entry(
binding: u32,
visibility: wgpu::ShaderStages,
ty: wgpu::BufferBindingType,
) -> wgpu::BindGroupLayoutEntry {
wgpu::BindGroupLayoutEntry {
binding,
visibility,
ty: wgpu::BindingType::Buffer {
ty,
has_dynamic_offset: false,
min_binding_size: None,
},
count: None,
}
}
pub(crate) fn environment_texture_entry(binding:u32)->wgpu::BindGroupLayoutEntry {
let mut entry=texture_entry(binding,wgpu::TextureSampleType::Uint,false);
if let wgpu::BindingType::Texture {view_dimension,..}=&mut entry.ty {*view_dimension=wgpu::TextureViewDimension::D2Array;}
entry
}
pub(crate) fn texture_entry(
binding: u32,
sample_type: wgpu::TextureSampleType,
multisampled: bool,
) -> wgpu::BindGroupLayoutEntry {
wgpu::BindGroupLayoutEntry {
binding,
visibility: wgpu::ShaderStages::FRAGMENT,
ty: wgpu::BindingType::Texture {
sample_type,
view_dimension: wgpu::TextureViewDimension::D2,
multisampled,
},
count: None,
}
}
pub(crate) fn sampler_entry(binding: u32, comparison: bool) -> wgpu::BindGroupLayoutEntry {
wgpu::BindGroupLayoutEntry {
binding,
visibility: wgpu::ShaderStages::FRAGMENT,
ty: wgpu::BindingType::Sampler(if comparison {
wgpu::SamplerBindingType::Comparison
} else {
wgpu::SamplerBindingType::Filtering
}),
count: None,
}
}
fn packed_geometry_pipeline(
c: &Compiler,
[vertex, fragment]: &[wgpu::ShaderModule; 2],
constants: &[(&str, f64)],
layout: &wgpu::PipelineLayout,
label: &str,
vs: &str,
fs: &str,
samples: u32,
write: bool,
targets: &[Option<wgpu::ColorTargetState>],
packed: crate::geometry::VertexLayout,
) -> wgpu::RenderPipeline {
// Every vertex stage but the fibre captures' is a camera stage (camera-instance remap).
let camera = vs != "shadow_vs";
let mut attributes = packed.attributes().to_vec();
// wgpu compacts empty vertex layouts. Put the instance stream before the
// optional constant stream, keeping every active binding contiguous.
if camera {attributes.insert(3,vec![wgpu::VertexAttribute {shader_location:vork_slang::registry::CAMERA_INSTANCE_LOCATION,offset:0,format:wgpu::VertexFormat::Uint32}]);}
// Decoupled visibility reads its pass's parameter block as a constant stream after it.
let visibility = matches!(fs, "fs" | "single_fs" | "masked_fs" | "transparent_fragments_fs" | "transparent_triangles_fs");
if visibility {attributes.insert(4,vec![wgpu::VertexAttribute {shader_location:vork_slang::registry::VISIBILITY_PASS_LOCATION,offset:0,format:wgpu::VertexFormat::Uint32x4},wgpu::VertexAttribute {shader_location:vork_slang::registry::VISIBILITY_LENS_LOCATION,offset:16,format:wgpu::VertexFormat::Float32x2}]);}
let buffers: Vec<_> = attributes
.iter()
.enumerate()
.map(|(slot, attributes)| wgpu::VertexBufferLayout {
array_stride: match slot {
0 => packed.vertex_stride(),
1 => packed.vertex_stride() * if packed.deform {2} else {1},
2 => {
if packed.constant_attributes() {
0
} else {
packed.attribute_stride()
}
}
3 if camera => 4,
_ => 0,
},
step_mode: if camera && slot==3 {wgpu::VertexStepMode::Instance} else {wgpu::VertexStepMode::Vertex},
attributes,
})
.collect();
let buffer_count = attributes.iter().rposition(|a| !a.is_empty()).unwrap() + 1;
c.render(&wgpu::RenderPipelineDescriptor {
label: Some(label),
layout: Some(layout),
vertex: wgpu::VertexState {
module: vertex,
entry_point: Some(vs),
compilation_options: Default::default(),
buffers: &buffers[..buffer_count],
},
primitive: wgpu::PrimitiveState {
cull_mode: None,
..Default::default()
},
depth_stencil: Some(wgpu::DepthStencilState {
format: wgpu::TextureFormat::Depth32Float,
depth_write_enabled: Some(write),
depth_compare: Some(if fs=="fibre_far_fs" {
wgpu::CompareFunction::Greater
} else if fs=="fibre_accumulate_fs" {
wgpu::CompareFunction::Always
} else if write && fs=="controls_fs" {
wgpu::CompareFunction::LessEqual
} else if write {
wgpu::CompareFunction::Less
} else if matches!(fs,"transparent_fs"|"transparent_receiver_fs"|"transparent_fragments_fs"|"transparent_triangles_fs") {
wgpu::CompareFunction::LessEqual
} else {
wgpu::CompareFunction::Equal
}),
stencil: Default::default(),
bias: Default::default(),
}),
multisample: wgpu::MultisampleState {
count: samples,
mask: !0,
alpha_to_coverage_enabled: false,
},
fragment: (!fs.is_empty()).then_some(
wgpu::FragmentState {
module: fragment,
entry_point: Some(fs),
compilation_options: wgpu::PipelineCompilationOptions {
constants,
..Default::default()
},
targets,
},
),
multiview_mask: None,
cache: c.cache.as_ref(),
})
}
#[cfg(all(test, vork_private_tests))]
include!("pipelines_tests_private.rs");
/// Replace one complete shader hook; drift must fail before pipeline compilation.
pub(crate) fn replace_hook(source: &str, hook: &str, replacement: &str) -> Result<String> {
ensure!(
source.matches(hook).count() == 1,
"shader hook must occur exactly once: {hook:?}"
);
Ok(source.replacen(hook, replacement, 1))
}
/// Control resolve for the raster coverage sample count (msaa4 or single-sample jitter).
/// Native single-sample/MSAA entries, with optional denoising guide output.
pub(crate) fn control_resolve_shader(samples: u32, denoise: bool) -> &'static crate::native::Compiled {
match (samples, denoise) {
(1, false) => &crate::native::CONTROL_RESOLVE_SINGLE_RESOLVE,
(1, true) => &crate::native::CONTROL_RESOLVE_SINGLE_RESOLVE_DENOISE,
(crate::constants::RASTER_MSAA_SAMPLES, false) => &crate::native::CONTROL_RESOLVE_MSAA_RESOLVE,
(crate::constants::RASTER_MSAA_SAMPLES, true) => &crate::native::CONTROL_RESOLVE_MSAA_RESOLVE_DENOISE,
_ => panic!("unsupported control resolve sample count: {samples}"),
}
}
/// Single-sample controls copy an RGBA16F texel; MSAA RGB averages retain f32.
pub(crate) fn resolved_ambient_format(samples: u32) -> wgpu::TextureFormat {
if samples == 1 { wgpu::TextureFormat::Rgba16Float } else { wgpu::TextureFormat::Rgba32Float }
}
pub(crate) fn control_resolve_entries(samples: u32, denoise: bool) -> Vec<wgpu::BindGroupLayoutEntry> {
use wgpu::{BindingType, TextureFormat as Format, TextureSampleType as Sample};
let mut entries = Vec::new();
for (binding, sample_type) in [
Sample::Depth,
Sample::Uint,
Sample::Float { filterable: false },
Sample::Float { filterable: false },
Sample::Float { filterable: false },
]
.into_iter()
.enumerate()
{
entries.push(wgpu::BindGroupLayoutEntry {
binding: binding as u32,
visibility: wgpu::ShaderStages::COMPUTE,
count: None,
ty: BindingType::Texture {
sample_type,
view_dimension: wgpu::TextureViewDimension::D2,
multisampled: samples > 1,
},
});
}
for (index, format) in [
Format::Rg32Float,
Format::R32Uint,
Format::Rgba16Float,
resolved_ambient_format(samples),
Format::Rgba16Float,
]
.into_iter()
.enumerate()
{
entries.push(wgpu::BindGroupLayoutEntry {
binding: 5 + index as u32,
visibility: wgpu::ShaderStages::COMPUTE,
count: None,
ty: BindingType::StorageTexture {
access: wgpu::StorageTextureAccess::WriteOnly,
format,
view_dimension: wgpu::TextureViewDimension::D2,
},
});
}
entries.push(buffer_entry(10, wgpu::ShaderStages::COMPUTE, wgpu::BufferBindingType::Uniform));
if denoise {
entries.push(wgpu::BindGroupLayoutEntry {
binding: 11, visibility: wgpu::ShaderStages::COMPUTE, count: None,
ty: BindingType::Texture { sample_type: Sample::Float { filterable: false }, view_dimension: wgpu::TextureViewDimension::D2, multisampled: samples > 1 },
});
entries.push(buffer_entry(12, wgpu::ShaderStages::COMPUTE, wgpu::BufferBindingType::Storage { read_only: false }));
}
entries
}
#[cfg(test)]
mod raster_control_tests {
#[test]
fn hooks_reject_missing_and_duplicate_matches() {
assert!(super::replace_hook("", "hook", "replacement").is_err());
assert!(super::replace_hook("hook hook", "hook", "replacement").is_err());
assert_eq!(
super::replace_hook("before hook after", "hook", "replacement").unwrap(),
"before replacement after"
);
}
#[test]
fn raster_coverage_counts_have_distinct_shared_registry_entries() -> anyhow::Result<()> {
let Some(r) = crate::test_renderer()? else { return Ok(()); };
let single = r.cached_pipelines(1);
let msaa = r.cached_pipelines(crate::constants::RASTER_MSAA_SAMPLES);
assert!(!std::sync::Arc::ptr_eq(&single, &msaa));
assert!(std::sync::Arc::ptr_eq(&single, &r.cached_pipelines(1)));
assert!(std::sync::Arc::ptr_eq(&msaa, &r.cached_pipelines(crate::constants::RASTER_MSAA_SAMPLES)));
Ok(())
}
}
pub(crate) fn cluster_entries() -> Vec<wgpu::BindGroupLayoutEntry> {
[
wgpu::BufferBindingType::Uniform,
wgpu::BufferBindingType::Storage { read_only: true },
wgpu::BufferBindingType::Uniform,
wgpu::BufferBindingType::Storage { read_only: false },
]
.into_iter()
.enumerate()
.map(|(binding, ty)| buffer_entry(binding as u32, wgpu::ShaderStages::COMPUTE, ty))
.collect()
}
/// The same scene globals for ray kernels, independent of their image bindings.
pub(crate) fn ray_globals<'a>(s: &'a InstalledScene, uniform: &'a wgpu::Buffer, objects: &'a wgpu::Buffer, lights: &'a wgpu::Buffer, clusters: &'a wgpu::Buffer, cluster_lights: &'a wgpu::Buffer) -> Vec<wgpu::BindGroupEntry<'a>> {
vec![entry(0,uniform.as_entire_binding()),entry(1,objects.as_entire_binding()),entry(2,lights.as_entire_binding()),
entry(3,wgpu::BindingResource::TextureView(&s.environment.specular)),entry(4,wgpu::BindingResource::Sampler(&s.environment.sampler)),
entry(5,wgpu::BindingResource::TextureView(&s.environment.diffuse)),entry(6,wgpu::BindingResource::TextureView(&s.environment.brdf)),
entry(7,clusters.as_entire_binding()),entry(8,cluster_lights.as_entire_binding()),entry(9,wgpu::BindingResource::TextureView(&s.environment.ltc))]
}
#[cfg(test)]
mod foreground_admission_tests {
use super::*;
#[test]
fn deferred_compilation_waits_for_foreground_preparation() {
let schedule = std::sync::Arc::new((Mutex::new(Schedule { foreground_preparations: 1, ..Default::default() }), std::sync::Condvar::new()));
let foreground = ForegroundPreparation(schedule.clone());
std::thread::scope(|scope| {
let (started_tx, started_rx) = std::sync::mpsc::channel();
let (admitted_tx, admitted_rx) = std::sync::mpsc::channel();
let schedule = &schedule;
let worker = scope.spawn(move || {
started_tx.send(()).unwrap();
let _permit = Permit::new(schedule, true);
admitted_tx.send(()).unwrap();
});
started_rx.recv().unwrap();
// Foreground work remains admitted; only optional compilation waits.
drop(Permit::new(schedule, false));
assert!(admitted_rx.recv_timeout(std::time::Duration::from_millis(20)).is_err());
drop(foreground);
admitted_rx.recv_timeout(std::time::Duration::from_secs(5)).unwrap();
worker.join().unwrap();
});
}
#[test]
fn panicked_variant_worker_fails_settle_instead_of_hanging() -> Result<()> {
let Some(r) = crate::test_renderer()? else { return Ok(()); };
// A standalone compiler: the renderer's own drop also settles its workers.
let compiler = Compiler::new(&r.device, None, Known::default());
compiler.spawn_variant(VariantCompile::Background, || panic!("injected variant failure"));
compiler.spawn_variant(VariantCompile::Background, || Err(anyhow::anyhow!("injected compile failure")));
let (settled_tx, settled) = std::sync::mpsc::channel();
let settling = compiler.clone();
std::thread::spawn(move || settled_tx.send(settling.settle()).unwrap());
let result = settled.recv_timeout(std::time::Duration::from_secs(10)).expect("settle hung after a variant worker panic");
assert!(result.is_err());
Ok(())
}
}
/// Populate shipped pipeline descriptors through the same constructors used at
/// install and frame-slot creation. No scene-keyed material variants are needed.
pub(crate) fn warm_builtin(r: &Renderer) -> Result<()> {
materials::mip_resources(r);
if crate::gpu_bc7::supported(r, 4, 4, 64) {
crate::gpu_bc7::Context::new(r)?;
}
environment::Environment::pipeline(r);
environment::reduce_pipeline(r);
render_images::publication_pipeline(r);
for samples in [1, crate::constants::RASTER_MSAA_SAMPLES] {
passes::subsurface::pipelines(r, samples);
// Geometry layouts do not depend on device ray-query support. Camera
// shadow resources are warmed separately with their actual ray axis.
for attributes in 0..=crate::constants::PRECOMPILED_ATTRIBUTE_SLOTS as u32 {
for denoise in [false, true] {
let p = if denoise || attributes>0 {
std::sync::Arc::new(CachedPipelines::with_sources(r, "", RESOLVE, None,
samples, false, crate::slang_forward::SlangScene { denoise, attributes, ..Default::default() }))
} else { r.cached_pipelines(samples) };
if attributes == 0 {
p.ensure_effects(r, EffectPlan::default())?;
let effects = EffectPlan { indirect:true, reflections:true,
compositor:true, ..Default::default() };
p.ensure_effects(r, effects)?;
passes::camera_cull::pipelines(r, &p);
passes::decoupled::merge_pipeline(&p, r);
p.deform_pipeline.get_or_init(|| p.build_deform_pipeline(r));
p.cluster_pipeline.get_or_init(|| p.build_cluster_pipeline(r));
if r.device.features().contains(wgpu::Features::EXPERIMENTAL_RAY_QUERY) && !denoise && samples == 1 {
crate::probes::pipelines(r, &p, 0, &VariantCompile::Inline)?;
}
}
let all = crate::forward_variant::ForwardKey::generic(crate::forward_variant::Stage::Controls,false).features;
let mut roles = std::collections::HashSet::new();
for transparent in [false,true] { for alpha_mask in [false,true] {
for double_sided in [false,true] { for dithered in [false,true] {
let flags = crate::plan::DrawFlags { transparent, alpha_mask,
casts_shadows:true, hair:false, moving:false };
for &kind in Role::kinds(&flags, true) {
roles.insert(Role::of_capabilities(kind, &flags, double_sided, dithered, all));
}
}}
}}
let mut keys = Vec::new();
for layout in crate::geometry::VertexLayout::builtin_layouts(attributes as u8) {
for &role in &roles {
if denoise && !matches!(role, Role::Controls(_) | Role::TransparentControls(_) | Role::ProgramControls {..}) { continue; }
if samples > 1 && matches!(role,
Role::Visibility | Role::VisibilitySingle | Role::VisibilityMasked | Role::TransparentFragments) { continue; }
keys.push((layout,role));
}
}
warm_geometry(r,&p,keys)?;
}
}
}
// Visibility writes only sample depth; it does not evaluate authored media.
// Prewarm common page counts; installation compiles larger layouts on demand.
for pages in 1..=crate::camera_native::PRECOMPILED_MEDIUM_PAGES {
for attributes in 0..=crate::constants::PRECOMPILED_ATTRIBUTE_SLOTS as u32 {
let medium = medium::Native { sample_pages:pages, froxel_pages:1, ..Default::default() };
let p = CachedPipelines::with_sources(r,"",RESOLVE,Some(&medium),1,false,
crate::slang_forward::SlangScene { attributes, volume_visibility:true,
medium:Some(std::sync::Arc::new(medium.clone())), ..Default::default() });
let keys = crate::geometry::VertexLayout::builtin_layouts(attributes as u8).into_iter()
.flat_map(|layout| [Role::Visibility,Role::VisibilitySingle,Role::VisibilityMasked,Role::TransparentFragments]
.into_iter().map(move |role|(layout,role))).collect();
warm_geometry(r,&p,keys)?;
}
}
r.errors.check()
}
/// Setup bounds driver concurrency independently of the finite descriptor count.
fn warm_geometry(r:&Renderer, p:&CachedPipelines, keys:Vec<GeometryKey>) -> Result<()> {
// Exhaustive vertex-fetch/role descriptors only help when another process
// can reuse them. Without a pipeline cache, Vulkan drivers such as lavapipe
// repeat this entire matrix at startup; library programs are still compiled
// by their frame-slot constructors. Metal retains pipelines in its system cache.
if !r.release_preparation && r.cache.is_none() && r.adapter_info.backend != wgpu::Backend::Metal {
return Ok(());
}
let next=std::sync::atomic::AtomicUsize::new(0);
std::thread::scope(|scope| {
(0..std::thread::available_parallelism().map_or(1,usize::from).min(8)).map(|_| {
let (keys,next)=(&keys,&next);
scope.spawn(move || {
while let Some(&key)=keys.get(next.fetch_add(1,std::sync::atomic::Ordering::Relaxed)) {
p.geometry(&r.compiler,key)?;
}
Ok(())
})
}).collect::<Vec<_>>().into_iter()
.try_for_each(join)
})
}
#[cfg(test)]
mod registry_identity_tests {
use super::*;
#[test]
fn plain_hit_preserves_capabilities_and_rejects_complex_materials() {
use crate::forward_variant::*;
for features in [FEATURE_SPECIALIZED, FEATURE_SPECIALIZED | FeatureMask::from(SHADING_METAL)
| FEATURE_SIDED | FEATURE_LIGHT_TYPES | FEATURE_FINITE | FEATURE_RECTANGLE] {
let ProgramKernel::Gi { features: plain } = (ProgramKernel::Gi { features }).plain_hit().unwrap() else { unreachable!() };
assert_eq!(features & !plain, 0, "a plain hit key may only add capabilities");
assert_eq!(plain & ((1 << (TEXTURE_FEATURES + 2)) - 4), 0, "no texture lookups");
assert_eq!(plain & FeatureMask::from(SHADING_LAYERS), 0, "no layered material evaluation");
assert_eq!((ProgramKernel::Reflections { features }).plain_hit(), Some(ProgramKernel::Reflections { features: plain }));
}
for features in [0, FEATURE_SPECIALIZED | FEATURE_COAT, FEATURE_SPECIALIZED | FEATURE_TRANSMISSION,
FEATURE_SPECIALIZED | FEATURE_LOBES, FEATURE_SPECIALIZED | (1 << 2)] {
assert!((ProgramKernel::Gi { features }).plain_hit().is_none());
}
}
#[test]
fn surface_warm_keys_ignore_display_denoise_and_camera_programs() {
let base=crate::slang_forward::SlangScene::default();
let mut changed=base.clone();
changed.denoise=true;
changed.camera=Some(std::sync::Arc::new(crate::camera_program::Native {
modules:vec![("camera".into(),"different camera rays".into())],include:vec![],
}));
changed.propagation=Some(crate::propagation::Native {
modules:vec![("propagation".into(),"path-only segment hook".into())],include:vec![],words:vec![],
});
assert_eq!(CachedPipelines::kernel_identity("",1,true,&base),CachedPipelines::kernel_identity("",1,true,&changed));
// The complete registry still distinguishes those consumers and output state.
assert_ne!(CachedPipelines::identity("","standard",1,true,&base,wgpu::TextureFormat::Rgba8Unorm),
CachedPipelines::identity("","agx",1,true,&changed,wgpu::TextureFormat::Rgba16Float));
changed.connection_transmission=true;
assert_ne!(CachedPipelines::kernel_identity("",1,true,&base),CachedPipelines::kernel_identity("",1,true,&changed));
changed=base.clone();changed.textures=8;
assert_ne!(CachedPipelines::kernel_identity("",1,true,&base),CachedPipelines::kernel_identity("",1,true,&changed));
}
#[test]
fn remembered_keys_cover_shader_inputs_and_descriptor_capacities() {
let base=crate::slang_forward::SlangScene::default();
let key=|s:&crate::slang_forward::SlangScene|CachedPipelines::identity("",RESOLVE,1,false,s,wgpu::TextureFormat::Rgba8Unorm);
let mut sentinel=base.clone();sentinel.textures=1;sentinel.samplers=1;
assert_eq!(key(&base),key(&sentinel),"zero counts create the same one-element sentinel tables");
for changed in [
crate::slang_forward::SlangScene {attributes:1,..base.clone()},
crate::slang_forward::SlangScene {textures:2,..base.clone()},
crate::slang_forward::SlangScene {samplers:2,..base.clone()},
crate::slang_forward::SlangScene {aov_count:1,..base.clone()},
crate::slang_forward::SlangScene {surface_coverage:true,..base.clone()},
crate::slang_forward::SlangScene {field_controls:true,..base.clone()},
crate::slang_forward::SlangScene {no_shadow_containment:true,..base.clone()},
crate::slang_forward::SlangScene {probes:true,..base.clone()},
] {assert_ne!(key(&base),key(&changed));}
let medium=|pages|crate::slang_forward::SlangScene {
medium:Some(std::sync::Arc::new(medium::Native {sample_pages:pages,..Default::default()})),..base.clone()
};
assert_ne!(key(&medium(1)),key(&medium(2)));
}
}