Fix orthographic projection rendering blank due to reversed depth ordering

When near > far was passed to Mat4::orthographic_rh, the positive z
coefficient caused back faces to win depth testing, producing zero
lighting output. Fix the original call site, add a runtime warning
for reversed depth, document the near < far convention, and add a
dedicated test for orthographic lit rendering.

Author: schell

crates/renderling/src/bvol.rs

@@ -490,8 +490,8 @@ impl BoundingSphere {
         }
     }
 
-    /// Returns an [`Aabb`] with x and y coordinates in viewport pixels and z coordinate
-    /// in NDC depth.
+    /// Returns an [`Aabb`] with x and y coordinates in viewport pixels and z
+    /// coordinate in NDC depth.
     pub fn project_onto_viewport(&self, camera: &CameraDescriptor, viewport: Vec2) -> Aabb {
         fn ndc_to_pixel(viewport: Vec2, ndc: Vec3) -> Vec2 {
             let screen = Vec3::new((ndc.x + 1.0) * 0.5, 1.0 - (ndc.y + 1.0) * 0.5, ndc.z);
@@ -658,10 +658,10 @@ mod test {
             .with_msaa_sample_count(4)
             .with_lighting(true);
         let _camera = stage.new_camera().with_projection_and_view(
-            // TODO: BUG - using orthographic here renderes nothing
-            // Mat4::orthographic_rh(-10.0, 10.0, -10.0, 10.0, 10.0, -10.0),
-            crate::camera::perspective(256.0, 256.0),
-            Mat4::look_at_rh(Vec3::new(-3.0, 3.0, 5.0) * 0.5, Vec3::ZERO, Vec3::Y),
+            // Fixed: was `near=10, far=-10` which reversed depth ordering.
+            // Using `near=0.1, far=20` ensures correct depth testing.
+            Mat4::orthographic_rh(-3.0, 3.0, -3.0, 3.0, 0.1, 20.0),
+            Mat4::look_at_rh(Vec3::new(-3.0, 3.0, 5.0), Vec3::ZERO, Vec3::Y),
         );
         let _lights = crate::test::make_two_directional_light_setup(&stage);
 
@@ -713,6 +713,71 @@ mod test {
         img_diff::assert_img_eq("bvol/bounding_box/get_mesh.png", img);
     }
 
+    /// Verifies that an orthographic projection with correct `near < far`
+    /// produces visible lit output.
+    ///
+    /// The original bug was that `orthographic_rh(-10, 10, -10, 10, 10, -10)`
+    /// (note: `near=10 > far=-10`) reversed the depth mapping, causing back
+    /// faces to win the depth test and produce zero lighting output.
+    ///
+    /// The fix is to use `near < far`, matching the convention of glTF, wgpu,
+    /// and every major rendering engine.
+    #[test]
+    fn orthographic_projection_lighting() {
+        let ctx = Context::headless(256, 256).block();
+        let view = Mat4::look_at_rh(Vec3::new(-3.0, 3.0, 5.0) * 0.5, Vec3::ZERO, Vec3::Y);
+
+        // Helper: render a lit unit cube and return the number of bright
+        // pixels (any RGB channel > 10).
+        let render = |projection: Mat4, label: &str| -> usize {
+            let stage = ctx
+                .new_stage()
+                .with_background_color(Vec4::ZERO)
+                .with_msaa_sample_count(4)
+                .with_lighting(true);
+            let _camera = stage
+                .new_camera()
+                .with_projection_and_view(projection, view);
+            let _lights = crate::test::make_two_directional_light_setup(&stage);
+            let white = stage.new_material().with_albedo_factor(Vec4::ONE);
+            let _prim = stage.new_primitive().with_material(&white).with_vertices(
+                stage.new_vertices(
+                    crate::math::unit_cube()
+                        .into_iter()
+                        .map(|(p, n)| Vertex::default().with_position(p).with_normal(n)),
+                ),
+            );
+            let frame = ctx.get_next_frame().unwrap();
+            stage.render(&frame.view());
+            let img = frame.read_image().block().unwrap();
+            img_diff::save(&format!("bvol/ortho_lighting_{label}.png"), img.clone());
+            let bright = img
+                .pixels()
+                .filter(|p| p.0[0] > 10 || p.0[1] > 10 || p.0[2] > 10)
+                .count();
+            bright
+        };
+
+        // Correct orthographic: near=-10, far=10 (near < far)
+        let ortho_bright = render(
+            Mat4::orthographic_rh(-10.0, 10.0, -10.0, 10.0, -10.0, 10.0),
+            "ortho_correct",
+        );
+
+        // Perspective for reference
+        let persp_bright = render(crate::camera::perspective(256.0, 256.0), "perspective");
+
+        assert!(
+            persp_bright > 100,
+            "Sanity: perspective should have bright pixels, got {persp_bright}"
+        );
+        assert!(
+            ortho_bright > 100,
+            "Orthographic projection (near=-10, far=10) should produce visible lit output, got \
+             only {ortho_bright} bright pixels (perspective had {persp_bright})"
+        );
+    }
+
     #[test]
     fn aabb_intersection() {
         let a = Aabb::new(Vec3::ZERO, Vec3::ONE);

crates/renderling/src/camera.rs

@@ -27,7 +27,10 @@ pub mod shader;
 /// let target = Vec3::ZERO;
 /// let up = Vec3::Y;
 /// let view = Mat4::look_at_rh(eye, target, up);
-/// assert_eq!(renderling::camera::default_perspective(width, height), (projection, view));
+/// assert_eq!(
+///     renderling::camera::default_perspective(width, height),
+///     (projection, view)
+/// );
 /// ```
 pub fn default_perspective(width: f32, height: f32) -> (Mat4, Mat4) {
     let projection = perspective(width, height);
@@ -46,6 +49,12 @@ pub fn perspective(width: f32, height: f32) -> Mat4 {
     Mat4::perspective_rh(fovy, aspect, znear, zfar)
 }
 
+/// Creates a right-handed orthographic projection matrix.
+///
+/// ## Note
+/// When constructing orthographic projections, `near` must be less than `far`
+/// to ensure correct depth testing. Reversed depth (`near > far`) will cause
+/// back faces to be drawn over front faces, producing incorrect lighting.
 pub fn ortho(width: f32, height: f32) -> Mat4 {
     let left = 0.0;
     let right = width;
@@ -62,6 +71,11 @@ pub fn look_at(eye: impl Into<Vec3>, target: impl Into<Vec3>, up: impl Into<Vec3
 
 /// Creates a typical 2d orthographic projection with +Y extending downward
 /// and the +Z axis coming out towards the viewer.
+///
+/// ## Note
+/// When constructing orthographic projections, `near` must be less than `far`
+/// to ensure correct depth testing. Reversed depth (`near > far`) will cause
+/// back faces to be drawn over front faces, producing incorrect lighting.
 pub fn default_ortho2d(width: f32, height: f32) -> (Mat4, Mat4) {
     let left = 0.0;
     let right = width;
@@ -100,10 +114,8 @@ mod tests {
             const THRESHOLD: f32 = 1e-3;
             assert!(
                 distance < THRESHOLD,
-                "Forward vector is incorrect\n\
-                forward: {forward}\n\
-                expected: {expected_forward}\n\
-                distance: {distance}, threshold: {THRESHOLD}"
+                "Forward vector is incorrect\nforward: {forward}\nexpected: \
+                 {expected_forward}\ndistance: {distance}, threshold: {THRESHOLD}"
             );
         }
     }

crates/renderling/src/camera/cpu.rs

@@ -9,8 +9,10 @@ use super::*;
 
 /// A camera used for transforming the stage during rendering.
 ///
-/// * Use [`Stage::new_camera`](crate::stage::Stage::new_camera) to create a new camera.
-/// * Use [`Stage::use_camera`](crate::stage::Stage::use_camera) to set a camera on the stage.
+/// * Use [`Stage::new_camera`](crate::stage::Stage::new_camera) to create a new
+///   camera.
+/// * Use [`Stage::use_camera`](crate::stage::Stage::use_camera) to set a camera
+///   on the stage.
 ///
 /// ## Note
 ///
@@ -63,7 +65,10 @@ impl Camera {
     /// let target = Vec3::ZERO;
     /// let up = Vec3::Y;
     /// let view = Mat4::look_at_rh(eye, target, up);
-    /// assert_eq!(renderling::camera::default_perspective(width, height), (projection, view));
+    /// assert_eq!(
+    ///     renderling::camera::default_perspective(width, height),
+    ///     (projection, view)
+    /// );
     /// ```
     pub fn set_default_perspective(&self, width: f32, height: f32) -> &Self {
         self.inner
@@ -90,7 +95,10 @@ impl Camera {
     /// let target = Vec3::ZERO;
     /// let up = Vec3::Y;
     /// let view = Mat4::look_at_rh(eye, target, up);
-    /// assert_eq!(renderling::camera::default_perspective(width, height), (projection, view));
+    /// assert_eq!(
+    ///     renderling::camera::default_perspective(width, height),
+    ///     (projection, view)
+    /// );
     /// ```
     pub fn with_default_perspective(self, width: f32, height: f32) -> Self {
         self.set_default_perspective(width, height);

crates/renderling/src/camera/shader.rs

@@ -41,7 +41,35 @@ impl CameraDescriptor {
         self.projection
     }
 
+    /// Set the projection and view matrices for this camera.
+    ///
+    /// ## Note on depth ordering
+    /// The rendering pipeline uses `CompareFunction::Less` for depth testing.
+    /// This requires that the projection matrix maps closer objects to
+    /// *smaller* z_ndc values. For orthographic projections created with
+    /// `Mat4::orthographic_rh`, this means `near` must be less than `far`.
+    /// If `near > far`, the depth mapping is reversed and back faces will
+    /// be drawn over front faces, producing incorrect (typically black)
+    /// lighting output.
     pub fn set_projection_and_view(&mut self, projection: Mat4, view: Mat4) {
+        // The z column of the projection matrix determines the depth mapping
+        // direction. A positive z coefficient (projection.z_axis.z > 0)
+        // indicates reversed depth (closer objects get larger z_ndc), which
+        // will cause incorrect results with the standard
+        // CompareFunction::Less depth test. This typically happens when
+        // `near > far` is passed to `Mat4::orthographic_rh`.
+        #[cfg(cpu)]
+        {
+            let z_coeff = projection.z_axis.z;
+            if z_coeff > 0.0 {
+                log::warn!(
+                    "Projection matrix has a positive z coefficient ({z_coeff}), indicating \
+                     reversed depth mapping. This will cause incorrect depth testing (back faces \
+                     drawn over front faces) with the standard CompareFunction::Less. For \
+                     orthographic projections, ensure near < far."
+                );
+            }
+        }
         self.projection = projection;
         self.view = view;
         self.position = view.inverse().transform_point3(Vec3::ZERO);
@@ -111,7 +139,8 @@ impl CameraDescriptor {
         (self.z_far() - self.z_near()).abs()
     }
 
-    /// Returns the normalized forward vector which points in the direction the camera is looking.
+    /// Returns the normalized forward vector which points in the direction the
+    /// camera is looking.
     pub fn forward(&self) -> Vec3 {
         (self.z_far_point - self.z_near_point).alt_norm_or_zero()
     }