Module scene 

Scene / camera / projection helpers.

The register macros in regs are the only thing that actually touches the GTE; everything here is a convenience layer that bundles the ~8 writes a typical 3D frame needs into named functions. All functions are safe – the macros they wrap already contain the unsafe { asm! } internally, and there’s nothing we can do with a bad matrix value that would be undefined behaviour (worst case: the projected vertex is garbage).

Typical frame:

scene::set_screen_offset(160 << 16, 120 << 16);
scene::set_projection_plane(200);
let rot = Mat3I16::rotate_y(angle);
scene::load_rotation(&rot);
scene::load_translation(Vec3I32::new(0, 0, 0x4000));
for v in vertices {
    let p = scene::project_vertex(v);
    draw_point(p.sx, p.sy);
}

Structs

AabbClipPlane

Four-byte-aligned plane record used by the GTE AABB clip batch.

ClassicNormalizedVector

A direction scaled to Q12 unit length by normalize_classic_q12_scheduled, with the squared lengths it came from.

ProjectTripleInFlight

In-flight RTPT kicked by start_project_triple; read collects the three projected results.

Projected

Result of a single perspective-projected vertex – screen-space (x, y) in pixels plus the MAC3 depth used for ordering-table inserts. Projected is Copy + trivially packed so the caller can collect per-vertex results into an array and rasterise later.

TransformProbe

Result of transform_vertex_probed: the live-schedule transform output plus post-op hazard evidence.

Functions

aabb_outside_clip4Deprecated

Renamed to is_aabb_outside_clip4.

average_cached_z3

Reload three cached projected depths into the GTE SZ FIFO and compute OTZ.

average_cached_z4

Reload four cached projected depths into the GTE SZ FIFO and compute OTZ.

average_z3_ordering_depth

Compute AVSZ3’s saturated OTZ result from three cached projected depths.

average_z4_ordering_depth

Compute AVSZ4’s saturated OTZ result from four cached projected depths.

average_z_triangle

Read the last three projected Z values and compute their average via AVSZ3 (weighted by ZSF3). Returns OTZ – the depth key most renderers use for ordering-table inserts.

classic_ordering_depth3_from_sum

Scale a three-depth sum into the classic 2,048-slot OTZ domain.

classic_otz3_from_sumDeprecated

Renamed to classic_ordering_depth3_from_sum.

classify_aabb_clip4

Classify a signed-integer AABB against four planes loaded by load_aabb_clip4.

compose_rotation_scheduled

Compose two Q12 rotation/scale matrices with the GTE’s scheduled MVMVA path.

error_flags

Read the GTE FLAG register. Non-zero indicates at least one error bit fired during the last op (overflow, saturation, divide overflow). Useful for debug prints on a frame that looks wrong.

is_aabb_outside_clip4

Return whether a signed-integer AABB is outside any selected plane loaded by load_aabb_clip4.

is_screen_triangle_back_facing

Back-face test for three already-projected screen-space vertices.

load_aabb_clip4

Load four clip-plane normals for classify_aabb_clip4 and is_aabb_outside_clip4.

load_background_color

Load the background-color bias (BK, control 13..=15).

load_far_color

Load the far-color bias (FC, control 21..=23) used by depth-cue interpolation.

load_light_color_matrix

Load the light-color matrix (LCM, control 16..=20).

load_light_matrix

Load the light-direction matrix (LLM, control 8..=12).

load_rotation

Load the rotation matrix into the GTE’s RT control registers (0..=4).

load_translation

Load the translation vector (TR, control 5..=7).

normalize_classic_q12_scheduled

Scale a Q12 direction to length 4096 with a 192-entry reciprocal square root table, the classic fixed-point way.

project_triangle

Project three vertices as a batch via RTPT – one GTE call, three results out of the SXY FIFO + SZ FIFO. Slightly faster than three successive project_vertex calls because RTPT shares setup.

project_triangle_scheduled

Project three vertices with a lower-overhead MIPS register schedule.

project_vertex

Load v into the V0 input slot (data registers 0 and 1) and run RTPS to project it. Returns the screen-space pair + depth so the caller can immediately use the result.

project_vertex_scheduled

Project one vertex with a lower-overhead MIPS register schedule.

rtpt_kickDeprecated

Renamed to start_project_triple.

screen_area

Signed screen-space area of a triangle – the same value GTE NCLIP writes to MAC0: SX0*(SY1-SY2) + SX1*(SY2-SY0) + SX2*(SY0-SY1). Positive = front-facing, <= 0 = back-facing/degenerate.

screen_area_and_average_cached_z3_scheduled

Run hardware-safe NCLIP and AVSZ3 for an already-projected indexed triangle.

screen_area_and_classic_ordering_depth3_scheduled

Run hardware-safe NCLIP and compute the classic 0x155-scaled OTZ from three cached depths without disturbing the GTE depth FIFO.

screen_area_and_unpack_model_face_scheduled

Run hardware-safe NCLIP while unpacking one aligned model-face record.

screen_area_mac0_scheduledDeprecated

Renamed to screen_area_scheduled.

screen_area_scheduled

Run a hardware-safe NCLIP for an already-projected triangle.

set_average_z_weights

Set the AVSZ3/AVSZ4 averaging weights (control 29, 30). Typical values: ZSF3 = 0x555 (= 1/3 in 0.12), ZSF4 = 0x400 (= 1/4).

set_depth_cue

Set the depth-cue coefficients DQA / DQB (control 27, 28). Depth-cue outputs IR0 = DQA/H + DQB, scaled to 0..0x1000.

set_projection_plane

Set the projection-plane distance H (control 26). Larger H = longer focal length = narrower FOV.

set_screen_offset

Set OFX and OFY (control 24, 25) – the screen-space offsets applied post-divide. Values are 15.16 fixed point; 160 << 16 = 160.0 px.

start_project_triple

Load V0..V2 and issue RTPT without reading results, so the caller can overlap the GTE op with scalar work for the previous triple.

transform_vertex

Transform one vertex by the currently loaded RT/TR matrix without perspective projection. Returns MAC1/2/3 in view-space units.

transform_vertex_probed

Hazard-hunt instrument (keep): one MVMVA on the DELIBERATELY UNPADDED pre-HWB-011 schedule (V0 writes 1-2 instructions before the op – the schedule that trips the silicon MTC2-commit hazard), with evidence reads appended strictly AFTER the op: a settled MAC1 re-read and a TRX/TRY/TRZ readback. This is the live evidence channel that decoded the vertex explosion; it stays in the SDK so the next hardware mystery starts from a proven instrument. Not for production paths – use transform_vertex_scheduled, whose schedule carries the console-confirmed hazard gap.

transform_vertex_scheduled

Transform one vertex with a lower-overhead MIPS register schedule.