systemless 0.101.0

High-Level Emulation for classic Macintosh applications
Documentation
//! Explicit test-support diagnostics; streaming observations never approve rollout.
use super::{triangle_area, PpcQ3RasterFrame, PpcQ3RasterPrimitive};
use std::{
    cell::{Cell, RefCell},
    fs::{File, OpenOptions},
    io::{self, Write},
    path::Path,
    time::Duration,
};

pub(super) struct RoutingTrace {
    file: RefCell<File>,
    selection_index: Cell<u64>,
}

impl RoutingTrace {
    pub(super) fn from_environment() -> Option<Self> {
        std::env::var_os("SYSTEMLESS_QD3D_ROUTING_TRACE")
            .map(|path| Self::create(Path::new(&path)).expect("create fresh QD3D routing trace"))
    }

    fn create(path: &Path) -> io::Result<Self> {
        let trace = Self {
            file: RefCell::new(OpenOptions::new().write(true).create_new(true).open(path)?),
            selection_index: Cell::new(0),
        };
        trace.write(serde_json::json!({
            "event":"metadata", "schema":1,
            "scope":"test-support routing and synchronous render requests; excludes CPU fallback execution and guest-memory commit; request elapsed includes first-use initialization, CPU preparation, submission and readback; logging perturbs execution; not hardware GPU time, physical frame pacing or production performance qualification"
        }));
        Ok(trace)
    }

    fn write(&self, value: serde_json::Value) {
        writeln!(self.file.borrow_mut(), "{value}").expect("write QD3D routing trace");
    }

    pub(super) fn work_estimate(&self, cpu_work: u64, tiled_work: u64, minimum_cpu_work: u64) {
        self.write(serde_json::json!({
            "event":"work_estimate",
            "selection_index":self.selection_index.get().checked_add(1).expect("QD3D trace sequence overflow"),
            "cpu_work":cpu_work, "tiled_work":tiled_work, "minimum_cpu_work":minimum_cpu_work,
            "maximum_tiled_work":super::Qd3dWorkEstimate::MAX_GPU_WORK,
            "maximum_tiled_to_cpu_ratio":super::Qd3dWorkEstimate::MAX_GPU_TO_CPU_RATIO,
            "scope":"production adaptive work estimates, not measured CPU or GPU time"
        }));
    }

    pub(super) fn selection(&self, frame: &PpcQ3RasterFrame, selected: bool) {
        let index = self
            .selection_index
            .get()
            .checked_add(1)
            .expect("QD3D trace sequence overflow");
        self.selection_index.set(index);
        let mut primitives = 0u64;
        let mut triangles = 0u64;
        let mut degenerates = 0u64;
        let mut maximum_lighting_work = 1u64;
        for draw in &frame.draws {
            maximum_lighting_work = maximum_lighting_work
                .max(1 + draw.lighting.as_ref().map_or(0, |l| l.lights.len()) as u64);
            for vertices in draw.vertices.chunks_exact(3) {
                primitives += 1;
                if draw.primitive == PpcQ3RasterPrimitive::Triangles {
                    triangles += 1;
                    degenerates += u64::from(triangle_area(vertices) == 0.);
                }
            }
        }
        let legacy_work = u64::from(frame.width)
            .saturating_mul(u64::from(frame.height))
            .saturating_mul(primitives)
            .saturating_mul(maximum_lighting_work);
        self.write(serde_json::json!({
            "event":"selection", "selection_index":index, "gpu_selected":selected,
            "width":frame.width, "height":frame.height, "draws":frame.draws.len(),
            "primitives":primitives, "triangles":triangles, "degenerate_triangles":degenerates,
            "texture_count":frame.textures.len(), "legacy_full_frame_work":legacy_work,
            "legacy_work_scope":"old full-frame estimate with maximum lighting count; not current tiled work"
        }));
    }

    pub(super) fn render_result(
        &self,
        result: &Result<Vec<u16>, String>,
        elapsed: Duration,
        indexed: bool,
    ) {
        self.write(serde_json::json!({
            "event":"render_result", "selection_index":self.selection_index.get(),
            "ok":result.is_ok(), "error":result.as_ref().err(),
            "pixels":result.as_ref().ok().map(Vec::len), "indexed":indexed,
            "request_elapsed_us":elapsed.as_secs_f64()*1e6
        }));
    }
}

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

    #[test]
    fn work_estimates_refer_to_the_next_selection_without_advancing_it() {
        let folder = tempfile::tempdir().unwrap();
        let path = folder.path().join("work.jsonl");
        let trace = RoutingTrace::create(&path).unwrap();
        trace.work_estimate(123, 456, 200_000);
        assert_eq!(trace.selection_index.get(), 0);
        let text = std::fs::read_to_string(path).unwrap();
        let row: serde_json::Value = serde_json::from_str(text.lines().nth(1).unwrap()).unwrap();
        assert_eq!(row["selection_index"], 1);
        assert_eq!(row["cpu_work"], 123);
        assert_eq!(row["tiled_work"], 456);
        assert_eq!(row["minimum_cpu_work"], 200_000);
        assert_eq!(row["maximum_tiled_work"], 512_000_000);
    }

    #[test]
    fn records_real_packet_work_and_degenerate_counts() {
        use systemless::systems::macintosh::loader::ppc::{
            PpcQ3GpuDraw, PpcQ3GpuFrame, PpcQ3GpuVertex,
        };
        let folder = tempfile::tempdir().unwrap();
        let path = folder.path().join("packet.jsonl");
        let trace = RoutingTrace::create(&path).unwrap();
        let vertex = PpcQ3GpuVertex {
            screen_x: 5.,
            screen_y: 5.,
            depth: 0.5,
            reciprocal_w: 1.,
            uv: [0.; 2],
            color: [1.; 4],
        };
        let frame = PpcQ3RasterFrame::from(&PpcQ3GpuFrame {
            width: 640,
            height: 480,
            viewport: [0, 0, 639, 479],
            clear_color: None,
            textures: vec![],
            draws: vec![PpcQ3GpuDraw {
                texture: None,
                blend: false,
                write_depth: true,
                vertices: vec![vertex; 1792 * 3],
            }],
        });
        trace.selection(&frame, true);
        let text = std::fs::read_to_string(path).unwrap();
        let packet: serde_json::Value = serde_json::from_str(text.lines().nth(1).unwrap()).unwrap();
        assert_eq!(packet["primitives"], 1792);
        assert_eq!(packet["triangles"], 1792);
        assert_eq!(packet["degenerate_triangles"], 1792);
        assert_eq!(packet["legacy_full_frame_work"], 550_502_400u64);
    }

    #[test]
    fn streams_selections_and_errors_without_overwriting_prior_evidence() {
        let folder = tempfile::tempdir().unwrap();
        let path = folder.path().join("routing.jsonl");
        let trace = RoutingTrace::create(&path).unwrap();
        let frame = PpcQ3RasterFrame {
            width: 640,
            height: 480,
            viewport: [0, 0, 639, 479],
            clear_color: None,
            textures: vec![],
            draws: vec![],
        };
        trace.selection(&frame, false);
        trace.selection(&frame, true);
        trace.render_result(
            &Err("injected render failure".into()),
            Duration::from_micros(42),
            false,
        );
        trace.render_result(&Ok(vec![0; 4]), Duration::from_micros(43), true);
        assert!(RoutingTrace::create(&path).is_err());
        let rows: Vec<serde_json::Value> = std::fs::read_to_string(path)
            .unwrap()
            .lines()
            .map(|line| serde_json::from_str(line).unwrap())
            .collect();
        assert_eq!(rows.len(), 5);
        assert_eq!(rows[0]["schema"], 1);
        assert_eq!(rows[1]["gpu_selected"], false);
        assert_eq!(rows[2]["selection_index"], 2);
        assert_eq!(rows[3]["selection_index"], 2);
        assert_eq!(rows[3]["ok"], false);
        assert_eq!(rows[3]["error"], "injected render failure");
        assert_eq!(rows[3]["request_elapsed_us"], 42.);
        assert_eq!(rows[4]["pixels"], 4);
        assert_eq!(rows[4]["indexed"], true);
    }
}