Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

19.2 KB
Raw Blame
use std::collections::BTreeMap;

use napi::Result;
use wgpu::util::DeviceExt;

use crate::host::device::failure;
use crate::host::textures::material_is_cutout;

pub(crate) const TRIANGLE_FLOATS: usize = 9 * 4;
pub(crate) const INSTANCE_RECORD_BYTES: usize = 160;
pub(crate) const TRIANGLE_RECORD_BYTES: usize = 224;
const VERTEX_STRIDE_BYTES: u64 = 12;
const IDENTITY_TRANSFORM_3X4: [f32; 12] = [1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0];
const MAX_TLAS_INSTANCES: usize = 1 << 24;
const INSTANCE_RAY_VISIBILITY_MASK: u32 = 0x3F;

pub(crate) struct UnpackedTriangles {
    pub(crate) vertices: Vec<f32>,
    pub(crate) slot_map: Vec<u32>,
    pub(crate) opaque_count: usize,
}

pub(crate) struct CyclesAcceleration {
    pub(crate) tlas: wgpu::Tlas,
    pub(crate) blases: Vec<wgpu::Blas>,
    /// For each instance, the index into `blases` of the mesh it places; a transform update rebuilds the TLAS from it.
    pub(crate) instance_blas_indices: Vec<usize>,
    pub(crate) _vertex_buffer: wgpu::Buffer,
}

#[derive(Clone, Copy, PartialEq, Eq)]
struct BlasSliceSpec {
    triangle_offset: u32,
    opaque_triangle_count: u32,
    total_triangle_count: u32,
}

struct BlasBuildPlan {
    blas: wgpu::Blas,
    geometry_sizes: Vec<wgpu::BlasTriangleGeometrySizeDescriptor>,
    geometry_vertex_starts: Vec<u32>,
}

struct ParsedInstancePlacement {
    transform_row_major_3x4: [f32; 12],
    blas_plan_index: usize,
    cull_mask: u8,
}

fn read_u32_le(bytes: &[u8], offset: usize) -> u32 {
    let word: [u8; 4] = bytes[offset..offset + 4].try_into().unwrap();
    u32::from_le_bytes(word)
}

fn read_f32_le(bytes: &[u8], offset: usize) -> f32 {
    let word: [u8; 4] = bytes[offset..offset + 4].try_into().unwrap();
    f32::from_le_bytes(word)
}

/// Unpacks corner-plus-two-edges triangle rows into three 3D corners per triangle, placing opaque triangles before
/// alpha-cutout triangles so each hardware BLAS geometry has a uniform opacity flag.
pub(crate) fn unpack_triangles(triangle_data: &[f32], materials: &[f32], triangle_count: usize) -> UnpackedTriangles {
    let mut opaque_vertices: Vec<f32> = Vec::with_capacity(triangle_count * 9);
    let mut cutout_vertices: Vec<f32> = Vec::new();
    let mut slot_map: Vec<u32> = Vec::with_capacity(triangle_count);
    let mut cutout_slots: Vec<u32> = Vec::new();
    for (slot, triangle) in triangle_data.chunks_exact(TRIANGLE_FLOATS).enumerate() {
        let corner = [triangle[0], triangle[1], triangle[2]];
        let edge_first = [triangle[4], triangle[5], triangle[6]];
        let edge_second = [triangle[8], triangle[9], triangle[10]];
        let is_cutout = material_is_cutout(materials, triangle[3] as usize);
        let vertices = if is_cutout { &mut cutout_vertices } else { &mut opaque_vertices };
        vertices.extend_from_slice(&corner);
        vertices.extend((0..3).map(|axis| corner[axis] + edge_first[axis]));
        vertices.extend((0..3).map(|axis| corner[axis] + edge_second[axis]));
        if is_cutout {
            cutout_slots.push(slot as u32);
        } else {
            slot_map.push(slot as u32);
        }
    }
    let opaque_count = slot_map.len();
    slot_map.extend(cutout_slots);
    let mut vertices = opaque_vertices;
    vertices.extend(cutout_vertices);
    UnpackedTriangles {
        vertices,
        slot_map,
        opaque_count,
    }
}

pub(crate) fn create_vertex_buffer(device: &wgpu::Device, vertices: &[f32]) -> wgpu::Buffer {
    device.create_buffer_init(&wgpu::util::BufferInitDescriptor {
        label: Some("triangle corners"),
        contents: bytemuck::cast_slice(vertices),
        usage: wgpu::BufferUsages::BLAS_INPUT,
    })
}

/// Builds the scene BLAS (split into opaque and candidate cutout geometries) and single-instance TLAS.
pub(crate) fn build_acceleration_structure(
    device: &wgpu::Device,
    queue: &wgpu::Queue,
    vertex_buffer: &wgpu::Buffer,
    triangle_count: usize,
    opaque_count: usize,
) -> wgpu::Tlas {
    let mut geometry_sizes: Vec<wgpu::BlasTriangleGeometrySizeDescriptor> = Vec::new();
    let mut geometry_vertex_starts: Vec<u32> = Vec::new();
    let cutout_count = triangle_count - opaque_count;
    for (first_triangle, triangles_in_geometry, flags) in [
        (0, opaque_count, wgpu::AccelerationStructureGeometryFlags::OPAQUE),
        (opaque_count, cutout_count, wgpu::AccelerationStructureGeometryFlags::empty()),
    ] {
        if triangles_in_geometry == 0 {
            continue;
        }
        geometry_vertex_starts.push((first_triangle * 3) as u32);
        geometry_sizes.push(wgpu::BlasTriangleGeometrySizeDescriptor {
            vertex_format: wgpu::VertexFormat::Float32x3,
            vertex_count: (triangles_in_geometry * 3) as u32,
            index_format: None,
            index_count: None,
            flags,
        });
    }
    let blas = device.create_blas(
        &wgpu::CreateBlasDescriptor {
            label: Some("scene"),
            flags: wgpu::AccelerationStructureFlags::PREFER_FAST_TRACE,
            update_mode: wgpu::AccelerationStructureUpdateMode::Build,
        },
        wgpu::BlasGeometrySizeDescriptors::Triangles {
            descriptors: geometry_sizes.clone(),
        },
    );
    let mut tlas = device.create_tlas(&wgpu::CreateTlasDescriptor {
        label: Some("scene"),
        flags: wgpu::AccelerationStructureFlags::PREFER_FAST_TRACE,
        update_mode: wgpu::AccelerationStructureUpdateMode::Build,
        max_instances: 1,
    });
    tlas[0] = Some(wgpu::TlasInstance::new(
        &blas,
        IDENTITY_TRANSFORM_3X4,
        0,
        0xFF,
    ));
    let triangle_geometries: Vec<wgpu::BlasTriangleGeometry> = geometry_sizes
        .iter()
        .zip(&geometry_vertex_starts)
        .map(|(size, first_vertex)| wgpu::BlasTriangleGeometry {
            size,
            vertex_buffer,
            first_vertex: *first_vertex,
            vertex_stride: VERTEX_STRIDE_BYTES,
            index_buffer: None,
            first_index: None,
            transform_buffer: None,
            transform_buffer_offset: None,
        })
        .collect();
    let mut build_encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
        label: Some("build"),
    });
    build_encoder.build_acceleration_structures(
        std::iter::once(&wgpu::BlasBuildEntry {
            blas: &blas,
            geometry: wgpu::BlasGeometries::TriangleGeometries(triangle_geometries),
        }),
        std::iter::once(&tlas),
    );
    queue.submit(Some(build_encoder.finish()));
    let _ = device.poll(wgpu::PollType::wait_indefinitely());
    tlas
}

fn unpack_v2_triangle_vertices(triangle_bytes: &[u8], triangle_count: usize) -> Vec<f32> {
    if triangle_count == 0 {
        return vec![0.0; 9];
    }
    let mut vertices = Vec::with_capacity(triangle_count * 9);
    for index in 0..triangle_count {
        let base = index * TRIANGLE_RECORD_BYTES;
        let p0 = [
            read_f32_le(triangle_bytes, base),
            read_f32_le(triangle_bytes, base + 4),
            read_f32_le(triangle_bytes, base + 8),
        ];
        let edge1 = [
            read_f32_le(triangle_bytes, base + 16),
            read_f32_le(triangle_bytes, base + 20),
            read_f32_le(triangle_bytes, base + 24),
        ];
        let edge2 = [
            read_f32_le(triangle_bytes, base + 32),
            read_f32_le(triangle_bytes, base + 36),
            read_f32_le(triangle_bytes, base + 40),
        ];
        vertices.extend_from_slice(&p0);
        vertices.extend((0..3).map(|axis| p0[axis] + edge1[axis]));
        vertices.extend((0..3).map(|axis| p0[axis] + edge2[axis]));
    }
    vertices
}

fn create_blas_plan_for_slice(device: &wgpu::Device, spec: BlasSliceSpec) -> BlasBuildPlan {
    let opaque_count = spec.opaque_triangle_count as usize;
    let total_count = spec.total_triangle_count as usize;
    let cutout_count = total_count - opaque_count;
    let base_triangle = spec.triangle_offset as usize;
    let mut geometry_sizes = Vec::new();
    let mut geometry_vertex_starts = Vec::new();
    for (local_start, count_in_geometry, flags) in [
        (0usize, opaque_count, wgpu::AccelerationStructureGeometryFlags::OPAQUE),
        (opaque_count, cutout_count, wgpu::AccelerationStructureGeometryFlags::empty()),
    ] {
        if count_in_geometry == 0 {
            continue;
        }
        geometry_vertex_starts.push(((base_triangle + local_start) * 3) as u32);
        geometry_sizes.push(wgpu::BlasTriangleGeometrySizeDescriptor {
            vertex_format: wgpu::VertexFormat::Float32x3,
            vertex_count: (count_in_geometry * 3) as u32,
            index_format: None,
            index_count: None,
            flags,
        });
    }
    let blas = device.create_blas(
        &wgpu::CreateBlasDescriptor {
            label: Some("cycles mesh blas"),
            flags: wgpu::AccelerationStructureFlags::PREFER_FAST_TRACE,
            update_mode: wgpu::AccelerationStructureUpdateMode::Build,
        },
        wgpu::BlasGeometrySizeDescriptors::Triangles {
            descriptors: geometry_sizes.clone(),
        },
    );
    BlasBuildPlan {
        blas,
        geometry_sizes,
        geometry_vertex_starts,
    }
}

/// The object-to-world rows of the instance record that starts at byte `base`, as a hardware TLAS transform.
fn read_instance_transform(instance_bytes: &[u8], base: usize) -> [f32; 12] {
    let mut transform_row_major_3x4 = [0.0f32; 12];
    for float_index in 0..12 {
        transform_row_major_3x4[float_index] = read_f32_le(instance_bytes, base + float_index * 4);
    }
    transform_row_major_3x4
}

/// The ray-kind bits of `visibility_flags` the hardware culls on (the negative-scale bit is not one of them).
pub(crate) fn instance_cull_mask(visibility_flags: u32) -> u8 {
    (visibility_flags & INSTANCE_RAY_VISIBILITY_MASK) as u8
}

/// Rebuilds the TLAS of a session from a new instance table with the same instances in the same order: new transforms
/// and ray visibility, the same meshes. The BLAS are not touched. The pinned wgpu has no TLAS refit (`PreferUpdate` is
/// accepted and rebuilds), so a rebuild is the whole cost of moving an instance.
pub(crate) fn rebuild_cycles_tlas(
    device: &wgpu::Device,
    queue: &wgpu::Queue,
    acceleration: &mut CyclesAcceleration,
    instance_bytes: &[u8],
) -> Result<()> {
    let instance_count = acceleration.instance_blas_indices.len();
    if instance_count == 0 || instance_bytes.len() != instance_count * INSTANCE_RECORD_BYTES {
        return Err(failure(format!(
            "The instance table must hold the session's {instance_count} instances of {INSTANCE_RECORD_BYTES} bytes to rebuild the TLAS; got {} bytes.",
            instance_bytes.len()
        )));
    }
    for instance_index in 0..instance_count {
        let base = instance_index * INSTANCE_RECORD_BYTES;
        let visibility_flags = read_u32_le(instance_bytes, base + 116);
        let blas = &acceleration.blases[acceleration.instance_blas_indices[instance_index]];
        let placed = wgpu::TlasInstance::new(
            blas,
            read_instance_transform(instance_bytes, base),
            instance_index as u32,
            instance_cull_mask(visibility_flags),
        );
        acceleration.tlas[instance_index] = Some(placed);
    }
    let mut build_encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
        label: Some("cycles tlas rebuild"),
    });
    build_encoder.build_acceleration_structures(
        std::iter::empty::<&wgpu::BlasBuildEntry>(),
        std::iter::once(&acceleration.tlas),
    );
    queue.submit(Some(build_encoder.finish()));
    let _ = device.poll(wgpu::PollType::wait_indefinitely());
    Ok(())
}

/// Builds an empty masked-out 1-triangle BLAS + TLAS when a scene has zero instances or runs a lobe-only probe.
pub(crate) fn build_empty_cycles_acceleration(device: &wgpu::Device, queue: &wgpu::Queue) -> CyclesAcceleration {
    let vertex_buffer = create_vertex_buffer(device, &[0.0f32; 9]);
    let dummy_plan = create_blas_plan_for_slice(
        device,
        BlasSliceSpec {
            triangle_offset: 0,
            opaque_triangle_count: 1,
            total_triangle_count: 1,
        },
    );
    let mut tlas = device.create_tlas(&wgpu::CreateTlasDescriptor {
        label: Some("cycles empty tlas"),
        flags: wgpu::AccelerationStructureFlags::PREFER_FAST_TRACE,
        update_mode: wgpu::AccelerationStructureUpdateMode::Build,
        max_instances: 1,
    });
    tlas[0] = Some(wgpu::TlasInstance::new(&dummy_plan.blas, IDENTITY_TRANSFORM_3X4, 0, 0x00));
    let triangle_geometries: Vec<wgpu::BlasTriangleGeometry> = dummy_plan
        .geometry_sizes
        .iter()
        .zip(&dummy_plan.geometry_vertex_starts)
        .map(|(size, first_vertex)| wgpu::BlasTriangleGeometry {
            size,
            vertex_buffer: &vertex_buffer,
            first_vertex: *first_vertex,
            vertex_stride: VERTEX_STRIDE_BYTES,
            index_buffer: None,
            first_index: None,
            transform_buffer: None,
            transform_buffer_offset: None,
        })
        .collect();
    let mut build_encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
        label: Some("cycles empty accel build"),
    });
    build_encoder.build_acceleration_structures(
        std::iter::once(&wgpu::BlasBuildEntry {
            blas: &dummy_plan.blas,
            geometry: wgpu::BlasGeometries::TriangleGeometries(triangle_geometries),
        }),
        std::iter::once(&tlas),
    );
    queue.submit(Some(build_encoder.finish()));
    let _ = device.poll(wgpu::PollType::wait_indefinitely());
    CyclesAcceleration {
        tlas,
        blases: vec![dummy_plan.blas],
        instance_blas_indices: Vec::new(),
        _vertex_buffer: vertex_buffer,
    }
}

/// Builds one hardware BLAS per unique `InstanceRecord.blas_index` and one hardware TLAS over all `instance_count` instances.
pub(crate) fn build_cycles_acceleration_structure(
    device: &wgpu::Device,
    queue: &wgpu::Queue,
    instance_bytes: &[u8],
    instance_count: usize,
    triangle_bytes: &[u8],
    triangle_count: usize,
) -> Result<CyclesAcceleration> {
    if instance_count > MAX_TLAS_INSTANCES {
        return Err(failure(format!(
            "Instance count {instance_count} exceeds the hardware 24-bit custom index limit ({MAX_TLAS_INSTANCES})."
        )));
    }
    if instance_count == 0 || triangle_count == 0 {
        return Ok(build_empty_cycles_acceleration(device, queue));
    }

    let mut blas_lookup: BTreeMap<u32, (usize, BlasSliceSpec)> = BTreeMap::new();
    let mut blas_specs: Vec<BlasSliceSpec> = Vec::new();
    let mut placements: Vec<ParsedInstancePlacement> = Vec::with_capacity(instance_count);

    for instance_index in 0..instance_count {
        let base = instance_index * INSTANCE_RECORD_BYTES;
        let blas_index = read_u32_le(instance_bytes, base + 96);
        let triangle_offset = read_u32_le(instance_bytes, base + 100);
        let opaque_triangle_count = read_u32_le(instance_bytes, base + 104);
        let total_triangle_count = read_u32_le(instance_bytes, base + 108);
        let visibility_flags = read_u32_le(instance_bytes, base + 116);

        if total_triangle_count == 0 {
            return Err(failure(format!(
                "InstanceRecord[{instance_index}] has total_triangle_count == 0; pass at least 1 triangle per instance."
            )));
        }
        if opaque_triangle_count > total_triangle_count {
            return Err(failure(format!(
                "InstanceRecord[{instance_index}] has opaque_triangle_count ({opaque_triangle_count}) > total_triangle_count ({total_triangle_count})."
            )));
        }
        let end_triangle = (triangle_offset as u64) + (total_triangle_count as u64);
        if end_triangle > triangle_count as u64 {
            return Err(failure(format!(
                "InstanceRecord[{instance_index}] triangle range {triangle_offset}..{end_triangle} exceeds triangle_count ({triangle_count})."
            )));
        }

        let spec = BlasSliceSpec {
            triangle_offset,
            opaque_triangle_count,
            total_triangle_count,
        };
        let blas_plan_index = if let Some(&(existing_index, existing_spec)) = blas_lookup.get(&blas_index) {
            if existing_spec != spec {
                return Err(failure(format!(
                    "InstanceRecord[{instance_index}] reuses blas_index {blas_index} with mismatched triangle slice bounds."
                )));
            }
            existing_index
        } else {
            let next_index = blas_specs.len();
            blas_specs.push(spec);
            blas_lookup.insert(blas_index, (next_index, spec));
            next_index
        };

        placements.push(ParsedInstancePlacement {
            transform_row_major_3x4: read_instance_transform(instance_bytes, base),
            blas_plan_index,
            cull_mask: instance_cull_mask(visibility_flags),
        });
    }
    let instance_blas_indices: Vec<usize> = placements.iter().map(|placement| placement.blas_plan_index).collect();

    let vertices = unpack_v2_triangle_vertices(triangle_bytes, triangle_count);
    let vertex_buffer = create_vertex_buffer(device, &vertices);
    let plans: Vec<BlasBuildPlan> = blas_specs
        .iter()
        .map(|spec| create_blas_plan_for_slice(device, *spec))
        .collect();

    let mut tlas = device.create_tlas(&wgpu::CreateTlasDescriptor {
        label: Some("cycles scene tlas"),
        flags: wgpu::AccelerationStructureFlags::PREFER_FAST_TRACE,
        update_mode: wgpu::AccelerationStructureUpdateMode::Build,
        max_instances: instance_count as u32,
    });
    for (instance_index, placement) in placements.iter().enumerate() {
        tlas[instance_index] = Some(wgpu::TlasInstance::new(
            &plans[placement.blas_plan_index].blas,
            placement.transform_row_major_3x4,
            instance_index as u32,
            placement.cull_mask,
        ));
    }

    let blas_entries: Vec<wgpu::BlasBuildEntry> = plans
        .iter()
        .map(|plan| {
            let triangle_geometries: Vec<wgpu::BlasTriangleGeometry> = plan
                .geometry_sizes
                .iter()
                .zip(&plan.geometry_vertex_starts)
                .map(|(size, first_vertex)| wgpu::BlasTriangleGeometry {
                    size,
                    vertex_buffer: &vertex_buffer,
                    first_vertex: *first_vertex,
                    vertex_stride: VERTEX_STRIDE_BYTES,
                    index_buffer: None,
                    first_index: None,
                    transform_buffer: None,
                    transform_buffer_offset: None,
                })
                .collect();
            wgpu::BlasBuildEntry {
                blas: &plan.blas,
                geometry: wgpu::BlasGeometries::TriangleGeometries(triangle_geometries),
            }
        })
        .collect();

    let mut build_encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
        label: Some("cycles accel build"),
    });
    build_encoder.build_acceleration_structures(blas_entries.iter(), std::iter::once(&tlas));
    queue.submit(Some(build_encoder.finish()));
    let _ = device.poll(wgpu::PollType::wait_indefinitely());
    drop(blas_entries);

    let blases = plans.into_iter().map(|plan| plan.blas).collect();
    Ok(CyclesAcceleration {
        tlas,
        blases,
        instance_blas_indices,
        _vertex_buffer: vertex_buffer,
    })
}