Skip to content

armgit / vork

Public Imported from GitHub
0

Headless 3D and VFX engine for agents. Research preview.

9.8 KB
Raw Blame
//! Native binding numbers follow wgpu-hal's sorted, dense Vulkan layout and
//! Metal's separate buffer/texture/sampler counters. Shared by build and runtime.
#[derive(Clone, Copy)]
pub enum Kind {
    Uniform,
    ArgumentTable,
    Read,
    Write,
    Sampler,
    Texture,
    Storage,
    Acceleration,
}
pub fn bindings(entry: &str) -> &'static [u32] {
    match entry {
        "volume_receiver_support" | "volume_apply" | "volume_lighting" | "volume_visibility_world" | "resolve_color" | "resolve_fused" | "resolve_fused_single"
        | "post_source" => &[
            0, 1, 2, 4, 5, 6, 7, 8, 9, 10, 11, 12, 16, 24, 41,
            43, 44, 45, 46, 47, 51, 52, 53, 54, 55, 58, 67, 68, 69, 70,
        ],
        _ => panic!("unregistered resolve entry {entry}"),
    }
}
/// Volume transport and receiver-sample pages bind as two arrays in their own
/// group of the volume passes, whatever the page count: a binding per page
/// exhausted Metal's 31 buffer slots per stage, and wgpu forbids binding arrays
/// beside the resolve group's uniforms. Group 3 holds hit buffers when installed.
pub const PAGE_GROUP: u32 = 4;
pub const FROXEL_PAGES: u32 = 0;
pub const SAMPLE_PAGES: u32 = 1;
/// Metal buffer slot of the first page table: after the volume pass's resolve,
/// material and shadow groups and, when installed, its hit table.
pub fn page_base(entry: &str, layout: Layout) -> u32 {
    hit_base(entry, layout) + u32::from(layout.shadow_closures)
}
pub fn kind(binding: u32) -> Kind {
    match binding {
        3 | 5 | 39 | 64 => Kind::Uniform,
        56 | 63 => Kind::ArgumentTable,
        11 | 21 | 38 | 43 | 44 | 45 | 46 | 60 | 65 | 66 | 67 | 71 => Kind::Read,
        72.. => Kind::Write,
        4 | 10 | 17 | 19 | 22 | 23 | 47 | 57 | 61 | 70 => Kind::Write,
        12 => Kind::Sampler,
        26 | 27 | 30 | 31 | 32 | 33 | 36 | 37 => Kind::Storage,
        59 => Kind::Acceleration,
        _ => Kind::Texture,
    }
}
fn slot(kind: Kind, counters: &mut [u32; 3]) -> (char, u32) {
    let (class, counter) = match kind {
        Kind::Uniform | Kind::ArgumentTable => ('b', 0),
        Kind::Read => ('t', 0),
        Kind::Write => ('u', 0),
        Kind::Sampler => ('s', 2),
        Kind::Texture => ('t', 1),
        Kind::Acceleration => ('t',0),
        Kind::Storage => ('u', 1),
    };
    let index = counters[counter];
    counters[counter] += 1;
    (class, index)
}
/// Resource numbering follows the installed layout, including bindings unused
/// by this entry. Eliminating shader code must never shift a later descriptor.
#[derive(Clone, Copy, Default)]
pub struct Layout {
    pub volume: bool,
    pub rays: bool,
    pub shadow_closures: bool,
}
/// BRDF and layer tables read by straight-segment surface closures.
pub const SHADOW_CLOSURE_BINDINGS: [u32; 2] = [13,18];
const SHADOW_BINDINGS: [u32; 1] = [66];
/// First group-1 buffer, after the complete retained resolve group-0 layout.
pub fn material_base(entry: &str, layout: Layout) -> u32 {
    let mut bindings = bindings(entry).to_vec();
    if layout.volume {
        bindings.extend([3,64,65]);
    }
    if layout.rays {bindings.extend([59,60,71]);}
    if layout.shadow_closures {bindings.extend(SHADOW_CLOSURE_BINDINGS);}
    bindings.iter().filter(|&&b| matches!(kind(b),Kind::Uniform|Kind::Read|Kind::Write|Kind::Acceleration)).count() as u32
}
/// Group 3 follows resolve resources, the material table, and the shadow tables.
pub fn hit_base(entry: &str, layout: Layout) -> u32 {
    let mut counters = [material_base(entry, layout) + crate::binding_abi::MATERIAL.len() as u32, 0, 0];
    for binding in SHADOW_BINDINGS { slot(kind(binding), &mut counters); }
    counters[0]
}
pub fn source(text: &str, entry: &str, layout: Layout) -> String {
    let mut bindings = bindings(entry).to_vec();
    if layout.volume {
        bindings.extend([3,64,65,66]);
    }
    if layout.rays {bindings.extend([59,60,71]);}
    if layout.shadow_closures {bindings.extend(SHADOW_CLOSURE_BINDINGS);}
    bindings.sort_unstable();
    let shadow_bindings = SHADOW_BINDINGS;
    let mut counters = [0; 3];
    let mut slots = Vec::new();
    for (dense, &binding) in bindings.iter().filter(|b| !shadow_bindings.contains(b)).enumerate() {
        let (class, index) = slot(kind(binding), &mut counters);
        slots.push((binding, dense as u32, 0, class, index));
    }
    // Each volume pass's group 1 is the material table (records, words and two
    // argument buffers plus the shader error word); group 2 follows those slots.
    if layout.volume && matches!(entry,"volume_receiver_support"|"volume_lighting" | "volume_visibility_world"|"volume_apply") { counters[0] += crate::binding_abi::MATERIAL.len() as u32; }
    for (dense, &binding) in shadow_bindings.iter().enumerate() {
        if bindings.contains(&binding) {
            let (class,index) = slot(kind(binding), &mut counters);
            slots.push((binding,dense as u32,2,class,index));
        }
    }
    let output = counters[1];
    counters[1] += 1;
    // Keep globals used only by other entries semantically available, assigning
    // distinct slots. Dead resources disappear before native code emission.
    for binding in 0..=71 {
        if !bindings.contains(&binding) {
            let (class, index) = slot(kind(binding), &mut counters);
            slots.push((binding, binding, 2, class, index));
        }
    }
    let mut result = String::new();
    let mut storage_textures = Vec::new();
    for line in text.lines() {
        if line.contains(",3)]]") || line.contains(&format!(",{PAGE_GROUP})]]")) {result.push_str(line);result.push('\n');continue;}
        if let Some(start) = line.find("[[vk::binding(") {
            let a = start + "[[vk::binding(".len();
            let b = a + line[a..].find(")]]").unwrap();
            let numbers: Vec<u32> = line[a..b]
                .split(',')
                .map(|s| s.trim().parse().unwrap())
                .collect();
            let (binding, group, class, index) = if numbers[1] == 1 {
                (0, 1, 'u', output)
            } else {
                let &(_, binding, group, class, index) =
                    slots.iter().find(|s| s.0 == numbers[0]).unwrap();
                (binding, group, class, index)
            };
            let mut declaration = format!(
                "{}[[vk::binding({binding},{group})]]{}",
                &line[..start],
                &line[b + 3..]
            );
            if let Some(a) = declaration.find(" : register(") {
                let b = a + declaration[a..].find(')').unwrap() + 1;
                declaration.replace_range(a..b, "");
            }
            let end = declaration
                .rfind(';')
                .expect("resolve resource declaration");
            // Vulkan's array declaration still requires a texture register class;
            // Metal wraps it in an argument buffer, whose slot is a buffer.
            let class = if class=='b' && declaration.contains("RWStructuredBuffer<") {'u'}
                else if class=='b' && (declaration.contains("Texture2DArray") || declaration.contains("StructuredBuffer<")) {'t'} else {class};
            declaration.insert_str(end, &format!(" : register({class}{index})"));
            if declaration.contains("RWTexture2D<") {
                storage_textures.push((index,declaration));
                continue;
            }
            result.push_str(&declaration);
        } else {
            result.push_str(line);
        }
        result.push('\n');
    }
    // Slang's Metal backend allocates storage textures from the free texture
    // slots in declaration order, despite their u-register semantics. Read-only
    // t-registers reserve the other slots, so order writable textures explicitly.
    storage_textures.sort_by_key(|(index,_)| *index);
    let mut source=String::new();
    for (_,declaration) in storage_textures {source.push_str(&declaration);source.push('\n');}
    source.push_str(&result);
    if entry == "resolve_fused" || entry == "resolve_fused_single" {source.insert_str(0,"#define VORK_RESOLVE_FUSED\n");}
    if entry == "resolve_fused_single" {source.insert_str(0,"#define VORK_RESOLVE_SINGLE\n");}
    source
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn unused_volume_ray_resources_preserve_late_resolve_bindings() {
        // The shader need not read light sampling or enable ray tracing. The
        // installed group still reserves its TLAS and alpha-table descriptors.
        let text = "[[vk::binding(67,0)]] StructuredBuffer<uint> sampling;";
        for entry in ["resolve_color", "post_source"] {
            let base=bindings(entry).iter().position(|&binding|binding==67).unwrap();
            for (layout, first) in [
                (Layout::default(), base),
                (Layout {volume: true, rays: false, ..Default::default()}, base+3),
                (Layout {volume: true, rays: true, ..Default::default()}, base+5),
            ] {
                let source = source(text, entry, layout);
                assert!(source.contains(&format!("[[vk::binding({first},0)]]")),
                    "{entry}: late binding shifted: {source}");
            }
        }
    }

    #[test]
    fn page_tables_follow_every_installed_volume_group() {
        // Page tables keep their own group; group 0 numbering is unchanged.
        let declarations = "[[vk::binding(0,4)]] ParameterBlock<Pages> pages : register(VORK_FROXEL_PAGES_REGISTER);";
        for coverage in [false, true] {
            let layout = Layout {volume:true, rays:true, shadow_closures:coverage};
            for entry in ["volume_receiver_support","volume_visibility_world","volume_lighting","volume_apply"] {
                assert!(source(declarations,entry,layout).contains(declarations));
                // Metal: group 0, the material table, shadow tables, then hits.
                assert_eq!(page_base(entry,layout), hit_base(entry,layout)+u32::from(coverage));
            }
        }
    }
}