concinnity-device 0.19.53

//! Planar reflection for flat reflectors (water surfaces + glass panes). Each
//! frame, when ray tracing is off, the scene is rendered a second time from the
//! camera reflected across each reflector plane (mirror view + oblique near-plane
//! clip so geometry behind the plane never leaks in) into a dedicated target; the
//! reflective surface then samples that target projectively for a sharp,
//! scene-correct reflection instead of the blurry box-projected probe cube.
//!
//! One mirror render per DISTINCT plane. Water is a single horizontal plane; glass
//! panes can be vertical or angled, and a world can hold several at different
//! planes. Each is a full scene re-render, so the number of mirror renders is
//! budgeted (`MAX_PLANAR_PLANES`): near-coplanar reflectors share one render (one
//! wall of windows = one plane), and reflectors past the budget fall back to the
//! probe cube (logged at init, see `metal/init`). The plane -> slot grouping is
//! the pure, unit-tested `gfx::planar_reflection::assign_planar_slots`.
//!
//! Each plane gets a DEDICATED mirror cull against its reflected-camera frustum,
//! so geometry visible only in the reflection (behind or beside the main camera,
//! outside its frustum) is captured, not just the main camera's visible set. The
//! reflected view-proj carries the oblique near-plane clip, so the extracted
//! frustum also rejects geometry behind the reflector. The GPU cull kernel
//! re-runs into that plane's own mirror ICB (`encode_mirror_cull`), which the
//! face render executes. The matrices + frustum come from the pure, unit-tested
//! `gfx::planar_reflection` + `gfx::frustum`.

#![deny(unsafe_op_in_unsafe_fn)]

use super::error::allocation_failed;
use concinnity_core::gfx::frustum::Frustum;
use concinnity_core::render::error::RenderResult;
use concinnity_core::render::planar_reflection;
use concinnity_core::transform::mat4_inverse;
use concinnity_core::transform::mat4_mul;
use objc2::rc::Retained;
use objc2::runtime::ProtocolObject;
use objc2_metal::{MTLDevice, MTLPixelFormat, MTLTexture, MTLTextureType, MTLTextureUsage};

use super::context::MtlContext;
use super::descriptors::TextureDesc;

// Clip the reflection a hair toward the kept (camera) side of the plane so
// geometry exactly on the surface is not lost to near-plane precision.
const PLANAR_CLIP_BIAS: f32 = 0.02;

// The engine capacity ceiling for distinct reflection planes (water + glass): the
// count the mirror-target set + mirror ICB slots below are sized to. Single-sourced
// from `gfx::planar_reflection` so the three backends stay in lockstep by
// construction. The per-frame budget passed to `assign_planar_slots` at init can be
// lower under a quality preset / GPU tier (fewer full-res mirror passes on weaker
// hardware), never higher; reflectors past the active budget fall back to the
// box-projected probe cube.
pub(in crate::metal) const MAX_PLANAR_PLANES: usize = planar_reflection::MAX_PLANAR_PLANES;

// Per-frame planar reflection render targets for one plane, sized to the render
// resolution. MSAA color + depth (rendered into, then resolved) plus a
// single-sample resolve the reflective shader samples. The mirror pass reuses
// the main pipelines, so it carries their sample count: at one sample there is
// no `msaa_color` and the pass draws straight into `resolve`.
pub(in crate::metal) struct PlanarReflectionTargets {
    pub(in crate::metal) msaa_color: Option<Retained<ProtocolObject<dyn MTLTexture>>>,
    pub(in crate::metal) depth: Retained<ProtocolObject<dyn MTLTexture>>,
    pub(in crate::metal) resolve: Retained<ProtocolObject<dyn MTLTexture>>,
}

// The set of distinct reflection planes for the world, each with its own render
// targets. `planes[i]` is the world-space plane (`[nx, ny, nz, d]`, n unit) that
// renders its mirror into `targets[i]`; a water surface or glass pane samples the
// resolve of the slot it was assigned at init (see `assign_planar_slots`). The
// plane geometry is recomputed (oriented toward the camera) per frame, but the
// count + each reflector's slot are fixed at init. Rebuilt on resize alongside
// `targets.hdr` (the planes carry over).
pub(in crate::metal) struct PlanarReflectionSet {
    pub(in crate::metal) targets: Vec<PlanarReflectionTargets>,
    pub(in crate::metal) planes: Vec<[f32; 4]>,
}

// Build the planar reflection targets at `width`x`height`. Color + depth match
// the main pipeline's attachment formats + sample count so `encode_main_into_face`
// binds the standard pipelines; the resolve is shader-readable.
pub(in crate::metal) fn create_planar_targets(
    device: &ProtocolObject<dyn MTLDevice>,
    width: u32,
    height: u32,
    sample_count: u32,
) -> RenderResult<PlanarReflectionTargets> {
    let multisampled = sample_count > 1;
    let color = if multisampled {
        let desc = TextureDesc {
            kind: MTLTextureType::Type2DMultisample,
            format: MTLPixelFormat::RGBA16Float,
            width: width as usize,
            height: height as usize,
            sample_count: sample_count as usize,
            usage: MTLTextureUsage::RenderTarget,
            ..Default::default()
        }
        .build();
        Some(
            device
                .newTextureWithDescriptor(&desc)
                .ok_or_else(|| allocation_failed("planar MSAA color target"))?,
        )
    } else {
        None
    };
    let depth = {
        let desc = TextureDesc {
            kind: if multisampled {
                MTLTextureType::Type2DMultisample
            } else {
                MTLTextureType::Type2D
            },
            format: MTLPixelFormat::Depth32Float,
            width: width as usize,
            height: height as usize,
            sample_count: sample_count as usize,
            usage: MTLTextureUsage::RenderTarget,
            ..Default::default()
        }
        .build();
        device
            .newTextureWithDescriptor(&desc)
            .ok_or_else(|| allocation_failed("planar depth target"))?
    };
    let resolve = {
        let desc = TextureDesc {
            format: MTLPixelFormat::RGBA16Float,
            width: width as usize,
            height: height as usize,
            usage: MTLTextureUsage(MTLTextureUsage::ShaderRead.0 | MTLTextureUsage::RenderTarget.0),
            ..Default::default()
        }
        .build();
        device
            .newTextureWithDescriptor(&desc)
            .ok_or_else(|| allocation_failed("planar resolve target"))?
    };
    Ok(PlanarReflectionTargets {
        msaa_color: color,
        depth,
        resolve,
    })
}

// Build a `PlanarReflectionSet` with one set of targets per plane in `planes`,
// each at `width`x`height`. `planes` is the deduplicated representative list from
// `assign_planar_slots`; an empty slice yields no set (the caller stores `None`).
pub(in crate::metal) fn create_planar_set(
    device: &ProtocolObject<dyn MTLDevice>,
    width: u32,
    height: u32,
    sample_count: u32,
    planes: &[[f32; 4]],
) -> RenderResult<PlanarReflectionSet> {
    let mut targets = Vec::with_capacity(planes.len());
    for _ in planes {
        targets.push(create_planar_targets(device, width, height, sample_count)?);
    }
    Ok(PlanarReflectionSet {
        targets,
        planes: planes.to_vec(),
    })
}

impl MtlContext {
    // Render the scene reflected across each plane in the planar set into that
    // plane's target, reusing this frame's cull ICB + bindless buffers. A no-op
    // (returns Ok) when no set exists. Each plane is oriented toward the camera so
    // the oblique near-plane clip keeps the camera's side (a no-op for water above
    // the surface; flips a glass pane's normal when viewed from its back). Encoded
    // on `cmd_buf` before the transparent pass that samples the resolves;
    // command-buffer order + Metal's texture hazard tracking order each resolve
    // before its sample.
    pub(in crate::metal) fn encode_planar_reflections(
        &self,
        cmd_buf: &ProtocolObject<dyn objc2_metal::MTLCommandBuffer>,
        params: &super::graph_exec::GraphFrameParams,
    ) -> RenderResult<()> {
        let Some(set) = self.planar_reflection.as_ref() else {
            return Ok(());
        };

        // Recover the (jittered) projection from this frame's view-projection so
        // the mirror render shares the main camera's projection + jitter, keeping
        // the reflection aligned with the reflective fragment's screen-space sample.
        let proj = mat4_mul(params.vp, mat4_inverse(self.view.matrix));
        for (slot, (plane, targets)) in set.planes.iter().zip(set.targets.iter()).enumerate() {
            let oriented = planar_reflection::orient_plane_toward(*plane, params.cam_pos);
            let m = planar_reflection::planar_matrices(
                self.view.matrix,
                proj,
                params.cam_pos,
                oriented,
                PLANAR_CLIP_BIAS,
            );

            // Re-cull against this plane's reflected-camera frustum so geometry
            // visible only in the reflection (behind or beside the main camera,
            // outside its frustum) is captured. The reflected view-proj already
            // carries the oblique near-plane clip, so its extracted frustum also
            // rejects geometry behind the reflector.
            let mirror_frustum = Frustum::from_view_projection(m.view_proj);
            // The GPU cull kernel re-runs into this plane's mirror ICB, which
            // the face render executes. A frame with no cull records has no
            // mirror to fill, and the face render then draws nothing.
            let icb_override = match (params.object_buffer, params.draw_args_buffer) {
                (Some(object_buffer), Some(draw_args)) => {
                    self.encode_mirror_cull(
                        cmd_buf,
                        object_buffer,
                        draw_args,
                        &mirror_frustum,
                        m.eye,
                        slot,
                    )?;
                    self.cull.mirror_slots.get(slot).map(|s| s.icb.as_ref())
                }
                _ => None,
            };

            self.encode_main_into_face(
                cmd_buf,
                crate::metal::draw::main::FaceTargets {
                    color_msaa: targets.msaa_color.as_deref(),
                    depth: &targets.depth,
                    resolve: &targets.resolve,
                    resolve_slice: 0,
                },
                crate::metal::draw::main::MainPassCamera {
                    elapsed: params.elapsed,
                    vp: m.view_proj,
                    view: m.view,
                    cam_pos: m.eye,
                },
                crate::metal::draw::main::GpuFrameBuffers {
                    object_buffer: params.object_buffer,
                    bindless_tex_args: params.bindless_tex_args,
                    deformed_skinned: params.deformed_skinned,
                    counts: self.draw_record_counts(),
                },
                icb_override,
            )?;
        }
        Ok(())
    }
}