Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

19.7 KB
Raw Blame
//! A persistent Intel Open Image Denoise device and filter (issue #1025). The OIDN shared library is opened at run time, so
//! the addon builds and loads without it. The device, the four image buffers and the committed "RT" filter stay alive
//! between calls and are rebuilt only when the image size, the set of guides or the settings change, so a warm call costs
//! the buffer writes, the filter and the read back.
//!
//! The C names and enum values come from `include/OpenImageDenoise/oidn.h` of OIDN 2.5.

use std::ffi::{c_char, c_int, c_void, CStr, CString};
use std::time::Instant;

use libloading::Library;
use napi::bindgen_prelude::Float32Array;
use napi::Result;
use napi_derive::napi;

use crate::host::device::failure;

type Handle = *mut c_void;

const FORMAT_FLOAT3: c_int = 3;
const BYTES_PER_PIXEL: usize = 12;
// Keeps width * height * 12 far below the range of usize, so the length checks cannot wrap.
const MAXIMUM_IMAGE_SIDE: usize = 65_536;
const ERROR_NONE: c_int = 0;

const DEVICE_NAMES: [(&str, c_int); 6] = [("default", 0), ("cpu", 1), ("sycl", 2), ("cuda", 3), ("hip", 4), ("metal", 5)];
const QUALITY_NAMES: [(&str, c_int); 4] = [("default", 0), ("fast", 4), ("balanced", 5), ("high", 6)];

/// How a device name becomes an OIDN device: a type, or a physical device index.
#[derive(Debug, PartialEq, Eq, Clone, Copy)]
enum DeviceChoice {
    Type(c_int),
    PhysicalIndex(c_int),
}

fn parse_device(name: &str) -> Result<DeviceChoice> {
    let lowered = name.trim().to_ascii_lowercase();
    if let Some((_, device_type)) = DEVICE_NAMES.iter().find(|(known, _)| *known == lowered) {
        return Ok(DeviceChoice::Type(*device_type));
    }
    if let Ok(index) = lowered.parse::<c_int>() {
        if index >= 0 {
            return Ok(DeviceChoice::PhysicalIndex(index));
        }
    }
    Err(failure(format!(
        "OIDN device {name:?} is unknown: pass \"cpu\", \"cuda\", \"hip\", \"sycl\", \"metal\", \"default\" or a physical device index."
    )))
}

fn parse_quality(name: &str) -> Result<c_int> {
    QUALITY_NAMES
        .iter()
        .find(|(known, _)| *known == name)
        .map(|(_, value)| *value)
        .ok_or_else(|| failure(format!("OIDN quality {name:?} is unknown: pass \"default\", \"fast\", \"balanced\" or \"high\".")))
}

/// The OIDN entry points this module calls, copied out of the library as plain function pointers.
struct OidnApi {
    new_device: unsafe extern "C" fn(c_int) -> Handle,
    new_device_by_id: unsafe extern "C" fn(c_int) -> Handle,
    set_device_int: unsafe extern "C" fn(Handle, *const c_char, c_int),
    commit_device: unsafe extern "C" fn(Handle),
    sync_device: unsafe extern "C" fn(Handle),
    release_device: unsafe extern "C" fn(Handle),
    get_device_error: unsafe extern "C" fn(Handle, *mut *const c_char) -> c_int,
    new_buffer: unsafe extern "C" fn(Handle, usize) -> Handle,
    write_buffer: unsafe extern "C" fn(Handle, usize, usize, *const c_void),
    read_buffer: unsafe extern "C" fn(Handle, usize, usize, *mut c_void),
    release_buffer: unsafe extern "C" fn(Handle),
    new_filter: unsafe extern "C" fn(Handle, *const c_char) -> Handle,
    set_filter_image: unsafe extern "C" fn(Handle, *const c_char, Handle, c_int, usize, usize, usize, usize, usize),
    set_filter_bool: unsafe extern "C" fn(Handle, *const c_char, bool),
    set_filter_int: unsafe extern "C" fn(Handle, *const c_char, c_int),
    commit_filter: unsafe extern "C" fn(Handle),
    execute_filter: unsafe extern "C" fn(Handle),
    release_filter: unsafe extern "C" fn(Handle),
    // Declared last: the pointers above stay valid only while the library is loaded.
    _library: Library,
}

/// Looks one entry point up by name.
///
/// # Safety
/// `Function` must be the exact `extern "C"` signature of the named OIDN function.
unsafe fn load_function<Function: Copy>(library: &Library, name: &str) -> Result<Function> {
    let symbol = library
        .get::<Function>(name.as_bytes())
        .map_err(|error| failure(format!("The OIDN library has no function {name} ({error}): it is not OIDN 2.5 or newer.")))?;
    Ok(*symbol)
}

impl OidnApi {
    fn open(library_path: &str) -> Result<Self> {
        // SAFETY: opening a shared library runs its initialisers; the caller names the official OIDN library.
        let library = unsafe { Library::new(library_path) }.map_err(|error| {
            failure(format!("Could not load the OIDN library at {library_path:?} ({error}): run `npm run fetch` in the denoise package, or pass libraryPath."))
        })?;
        // SAFETY: every signature below is the one declared in oidn.h of OIDN 2.5.
        unsafe {
            Ok(Self {
                new_device: load_function(&library, "oidnNewDevice")?,
                new_device_by_id: load_function(&library, "oidnNewDeviceByID")?,
                set_device_int: load_function(&library, "oidnSetDeviceInt")?,
                commit_device: load_function(&library, "oidnCommitDevice")?,
                sync_device: load_function(&library, "oidnSyncDevice")?,
                release_device: load_function(&library, "oidnReleaseDevice")?,
                get_device_error: load_function(&library, "oidnGetDeviceError")?,
                new_buffer: load_function(&library, "oidnNewBuffer")?,
                write_buffer: load_function(&library, "oidnWriteBuffer")?,
                read_buffer: load_function(&library, "oidnReadBuffer")?,
                release_buffer: load_function(&library, "oidnReleaseBuffer")?,
                new_filter: load_function(&library, "oidnNewFilter")?,
                set_filter_image: load_function(&library, "oidnSetFilterImage")?,
                set_filter_bool: load_function(&library, "oidnSetFilterBool")?,
                set_filter_int: load_function(&library, "oidnSetFilterInt")?,
                commit_filter: load_function(&library, "oidnCommitFilter")?,
                execute_filter: load_function(&library, "oidnExecuteFilter")?,
                release_filter: load_function(&library, "oidnReleaseFilter")?,
                _library: library,
            })
        }
    }

    /// Turns the device's pending error, or the global one for a null device, into a message.
    fn pending_error(&self, device: Handle) -> Option<String> {
        let mut message: *const c_char = std::ptr::null();
        // SAFETY: a null device asks for the global error; `message` is written by OIDN and valid until the next call.
        let code = unsafe { (self.get_device_error)(device, &mut message) };
        if code == ERROR_NONE {
            return None;
        }
        let text = if message.is_null() {
            "no message".to_string()
        } else {
            // SAFETY: OIDN returns a NUL terminated string.
            unsafe { CStr::from_ptr(message) }.to_string_lossy().into_owned()
        };
        Some(format!("{text} (OIDN error {code})"))
    }
}

/// What a committed filter was built for. A call with another key rebuilds the buffers and the filter.
#[derive(PartialEq, Eq, Clone, Copy)]
struct FilterKey {
    width: usize,
    height: usize,
    has_albedo: bool,
    has_normal: bool,
}

#[napi(object)]
pub struct OidnDenoiserOptions {
    pub library_path: String,
    /// `"cpu"` (default), `"cuda"`, `"hip"`, `"sycl"`, `"metal"`, `"default"` or a physical device index.
    pub device: Option<String>,
    /// `"default"`, `"fast"`, `"balanced"` or `"high"` (default).
    pub quality: Option<String>,
    pub clean_aux: Option<bool>,
    /// CPU thread count; absent or 0 lets OIDN choose.
    pub threads: Option<u32>,
}

#[napi(object)]
pub struct OidnDenoiseCall {
    pub width: u32,
    pub height: u32,
    /// Linear HDR radiance, three floats per pixel, rows top to bottom.
    pub color: Float32Array,
    pub albedo: Option<Float32Array>,
    /// Needs `albedo`.
    pub normal: Option<Float32Array>,
}

#[napi(object)]
pub struct OidnDenoiseResult {
    pub color: Float32Array,
    /// True when this call rebuilt the buffers and committed the filter (the first call, or a changed size or guide set).
    pub recommitted: bool,
    /// Buffer allocation, filter creation and commit; 0 when the committed filter was reused.
    pub commit_seconds: f64,
    pub write_seconds: f64,
    pub execute_seconds: f64,
    pub read_seconds: f64,
}

/// A device and filter kept alive between calls.
#[napi]
pub struct OidnDenoiser {
    api: OidnApi,
    device: Handle,
    quality: c_int,
    clean_aux: bool,
    device_seconds: f64,
    key: Option<FilterKey>,
    filter: Handle,
    color_buffer: Handle,
    albedo_buffer: Handle,
    normal_buffer: Handle,
    output_buffer: Handle,
}

// SAFETY: the handles are used only through `&mut self`, one call at a time.
unsafe impl Send for OidnDenoiser {}

fn name_to_c(name: &str) -> CString {
    CString::new(name).expect("names in this module have no NUL byte")
}

#[napi]
impl OidnDenoiser {
    #[napi(constructor)]
    pub fn new(options: OidnDenoiserOptions) -> Result<Self> {
        let device_name = options.device.as_deref().unwrap_or("cpu");
        let choice = parse_device(device_name)?;
        let quality = parse_quality(options.quality.as_deref().unwrap_or("high"))?;
        let api = OidnApi::open(&options.library_path)?;
        let started = Instant::now();
        // SAFETY: plain OIDN calls with valid arguments; a null device means creation failed.
        let device = unsafe {
            match choice {
                DeviceChoice::Type(device_type) => (api.new_device)(device_type),
                DeviceChoice::PhysicalIndex(index) => (api.new_device_by_id)(index),
            }
        };
        if device.is_null() {
            let reason = api.pending_error(std::ptr::null_mut()).unwrap_or_else(|| "no message".to_string());
            return Err(failure(format!("OIDN could not create the {device_name:?} device: {reason}. Pass device \"cpu\" or check the GPU driver.")));
        }
        let mut denoiser = Self {
            api,
            device,
            quality,
            clean_aux: options.clean_aux.unwrap_or(false),
            device_seconds: 0.0,
            key: None,
            filter: std::ptr::null_mut(),
            color_buffer: std::ptr::null_mut(),
            albedo_buffer: std::ptr::null_mut(),
            normal_buffer: std::ptr::null_mut(),
            output_buffer: std::ptr::null_mut(),
        };
        // From here a failure drops `denoiser`, which releases the device.
        if let Some(threads) = options.threads.filter(|count| *count > 0) {
            let setting = name_to_c("numThreads");
            // SAFETY: the device is valid and the name is NUL terminated.
            unsafe { (denoiser.api.set_device_int)(device, setting.as_ptr(), threads as c_int) };
        }
        // SAFETY: the device is valid.
        unsafe { (denoiser.api.commit_device)(device) };
        denoiser.check_device("commit the device")?;
        denoiser.device_seconds = started.elapsed().as_secs_f64();
        Ok(denoiser)
    }

    /// Seconds the constructor spent creating and committing the device (CUDA initialisation is most of it).
    #[napi(getter)]
    pub fn device_seconds(&self) -> f64 {
        self.device_seconds
    }

    #[napi]
    pub fn denoise(&mut self, call: OidnDenoiseCall) -> Result<OidnDenoiseResult> {
        if self.device.is_null() {
            return Err(failure("This OIDN denoiser is closed: create a new one with createOidnDenoiser."));
        }
        let width = call.width as usize;
        let height = call.height as usize;
        if width == 0 || height == 0 {
            return Err(failure("OIDN denoise needs a width and height of at least 1."));
        }
        if width > MAXIMUM_IMAGE_SIDE || height > MAXIMUM_IMAGE_SIDE {
            return Err(failure(format!("OIDN denoise takes a width and height of at most {MAXIMUM_IMAGE_SIDE}; got {width} by {height}.")));
        }
        let floats = width * height * 3;
        if call.normal.is_some() && call.albedo.is_none() {
            return Err(failure("OIDN takes a normal guide only together with an albedo guide: pass albedo too, or drop normal."));
        }
        check_length("color", call.color.len(), floats)?;
        if let Some(albedo) = &call.albedo {
            check_length("albedo", albedo.len(), floats)?;
        }
        if let Some(normal) = &call.normal {
            check_length("normal", normal.len(), floats)?;
        }
        let key = FilterKey { width, height, has_albedo: call.albedo.is_some(), has_normal: call.normal.is_some() };
        let byte_count = floats * 4;

        let commit_started = Instant::now();
        let recommitted = self.key != Some(key);
        if recommitted {
            self.release_session();
            self.build_session(key)?;
        }
        let commit_seconds = if recommitted { commit_started.elapsed().as_secs_f64() } else { 0.0 };

        let write_started = Instant::now();
        // SAFETY: each buffer holds `byte_count` bytes and each source slice was checked to hold as many.
        unsafe {
            (self.api.write_buffer)(self.color_buffer, 0, byte_count, call.color.as_ptr().cast());
            if let Some(albedo) = &call.albedo {
                (self.api.write_buffer)(self.albedo_buffer, 0, byte_count, albedo.as_ptr().cast());
            }
            if let Some(normal) = &call.normal {
                (self.api.write_buffer)(self.normal_buffer, 0, byte_count, normal.as_ptr().cast());
            }
        }
        let write_seconds = write_started.elapsed().as_secs_f64();

        let execute_started = Instant::now();
        // SAFETY: the filter is committed for this key. The sync makes GPU time count here, not in the read.
        unsafe {
            (self.api.execute_filter)(self.filter);
            (self.api.sync_device)(self.device);
        }
        self.check_device("run the filter")?;
        let execute_seconds = execute_started.elapsed().as_secs_f64();

        let read_started = Instant::now();
        let mut denoised = vec![0.0f32; floats];
        // SAFETY: `denoised` holds `byte_count` bytes.
        unsafe { (self.api.read_buffer)(self.output_buffer, 0, byte_count, denoised.as_mut_ptr().cast()) };
        self.check_device("read the result")?;
        let read_seconds = read_started.elapsed().as_secs_f64();

        Ok(OidnDenoiseResult { color: Float32Array::new(denoised), recommitted, commit_seconds, write_seconds, execute_seconds, read_seconds })
    }

    /// Releases the filter, the buffers and the device now instead of when the object is collected.
    #[napi]
    pub fn close(&mut self) {
        self.release_session();
        if !self.device.is_null() {
            // SAFETY: the device is valid and released once.
            unsafe { (self.api.release_device)(self.device) };
            self.device = std::ptr::null_mut();
        }
    }
}

fn check_length(name: &str, actual: usize, expected: usize) -> Result<()> {
    if actual == expected {
        return Ok(());
    }
    Err(failure(format!("OIDN denoise: `{name}` has {actual} floats but the image needs {expected} (3 per pixel): pass a Float32Array of width * height * 3.")))
}

impl OidnDenoiser {
    fn check_device(&self, action: &str) -> Result<()> {
        match self.api.pending_error(self.device) {
            None => Ok(()),
            Some(message) => Err(failure(format!("OIDN could not {action}: {message}."))),
        }
    }

    fn new_buffer(&self, byte_count: usize) -> Result<Handle> {
        // SAFETY: the device is valid.
        let buffer = unsafe { (self.api.new_buffer)(self.device, byte_count) };
        self.check_device("allocate an image buffer")?;
        if buffer.is_null() {
            return Err(failure("OIDN returned no buffer: the device is out of memory for this image size."));
        }
        Ok(buffer)
    }

    fn set_image(&self, name: &str, buffer: Handle, key: FilterKey) {
        let image_name = name_to_c(name);
        // SAFETY: strides of 0 let OIDN compute tightly packed float3 pixels.
        unsafe { (self.api.set_filter_image)(self.filter, image_name.as_ptr(), buffer, FORMAT_FLOAT3, key.width, key.height, 0, 0, 0) };
    }

    /// Allocates the buffers, creates the "RT" filter and commits it. On failure the partly built session is released by
    /// the next `release_session`, which `Drop` and `denoise` both run.
    fn build_session(&mut self, key: FilterKey) -> Result<()> {
        let byte_count = key.width * key.height * BYTES_PER_PIXEL;
        self.color_buffer = self.new_buffer(byte_count)?;
        if key.has_albedo {
            self.albedo_buffer = self.new_buffer(byte_count)?;
        }
        if key.has_normal {
            self.normal_buffer = self.new_buffer(byte_count)?;
        }
        self.output_buffer = self.new_buffer(byte_count)?;
        let filter_type = name_to_c("RT");
        // SAFETY: the device is valid.
        self.filter = unsafe { (self.api.new_filter)(self.device, filter_type.as_ptr()) };
        self.check_device("create the RT filter")?;
        self.set_image("color", self.color_buffer, key);
        if key.has_albedo {
            self.set_image("albedo", self.albedo_buffer, key);
        }
        if key.has_normal {
            self.set_image("normal", self.normal_buffer, key);
        }
        self.set_image("output", self.output_buffer, key);
        let hdr = name_to_c("hdr");
        let clean_aux = name_to_c("cleanAux");
        let quality = name_to_c("quality");
        // SAFETY: the filter is valid and the names are NUL terminated.
        unsafe {
            (self.api.set_filter_bool)(self.filter, hdr.as_ptr(), true);
            (self.api.set_filter_bool)(self.filter, clean_aux.as_ptr(), self.clean_aux);
            (self.api.set_filter_int)(self.filter, quality.as_ptr(), self.quality);
            (self.api.commit_filter)(self.filter);
        }
        self.check_device("commit the RT filter")?;
        self.key = Some(key);
        Ok(())
    }

    fn release_session(&mut self) {
        // SAFETY: each non-null handle came from the matching `new` call and is released once, then nulled.
        unsafe {
            if !self.filter.is_null() {
                (self.api.release_filter)(self.filter);
            }
            for buffer in [self.color_buffer, self.albedo_buffer, self.normal_buffer, self.output_buffer] {
                if !buffer.is_null() {
                    (self.api.release_buffer)(buffer);
                }
            }
        }
        self.filter = std::ptr::null_mut();
        self.color_buffer = std::ptr::null_mut();
        self.albedo_buffer = std::ptr::null_mut();
        self.normal_buffer = std::ptr::null_mut();
        self.output_buffer = std::ptr::null_mut();
        self.key = None;
    }
}

impl Drop for OidnDenoiser {
    fn drop(&mut self) {
        self.close();
    }
}

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

    #[test]
    fn device_names_map_to_types_and_numbers_to_indices() {
        assert_eq!(parse_device("cpu").unwrap(), DeviceChoice::Type(1));
        assert_eq!(parse_device(" CUDA ").unwrap(), DeviceChoice::Type(3));
        assert_eq!(parse_device("2").unwrap(), DeviceChoice::PhysicalIndex(2));
        assert!(parse_device("tpu").is_err());
        assert!(parse_device("-1").is_err());
    }

    #[test]
    fn quality_names_map_to_oidn_values() {
        assert_eq!(parse_quality("high").unwrap(), 6);
        assert_eq!(parse_quality("fast").unwrap(), 4);
        assert!(parse_quality("ultra").is_err());
    }

    #[test]
    fn a_missing_library_names_the_path_and_the_fix() {
        let error = OidnApi::open("definitely-not-an-oidn-library.so").err().expect("opening a missing library fails");
        let message = error.reason.to_string();
        assert!(message.contains("definitely-not-an-oidn-library"));
        assert!(message.contains("npm run fetch"));
    }

    #[test]
    fn image_lengths_are_checked() {
        assert!(check_length("color", 12, 12).is_ok());
        assert!(check_length("color", 11, 12).is_err());
    }
}