Physically-based lens flares

[The-E]

Implements physically-based camera lens flares using the matrix method from Lee & Eisemann, "Practical Real-Time Lens-Flare Rendering" (2013), with the iris/starburst synthesis ported from realflare's aperture kernels.

Every ordered pair of refractive surfaces in a lens prescription produces one two-reflection "ghost" image of the iris, and the starburst is the Fraunhofer transform of that same iris. Ghost enumeration, the per-ghost paraxial ray-transfer matrices and their coated-Fresnel tints are all computed once at table load, so a frame only has to draw one textured quad per ghost.

One camera, one lens

A mission is shot through one lens, and every sun in its background flares through it — that is what keeps two suns' flares consistent with each other instead of looking like they came through different glass. In precedence order:

Where	What it sets
$Default Lens: in lens_flares.tbl / *-lens.tbm	the lens every mission gets by default
$Camera Lens: in a mission's info section	that mission's lens (FRED + qtFRED background editor)
set-camera-lens	swaps it at runtime; <none> for no flares, <default> for the table's
lab override	live, for tuning only

set-lens-aperture / -grating / -scratches / -dust restyle the mounted lens's iris from a mission. They deliberately take no lens name, so a mission cannot edit a lens it isn't looking through. All lens edits are undone when the mission ends.

Per-sun opt-out is the pre-existing $NoGlare:, which the flare path already honours.

Backwards compatibility

Nothing changes for existing content. The shipped lens_flares.tbl leaves $Default Lens: unset, so a mod gets no flares until it opts in — either with one line in a *-lens.tbm or per mission. When a lens is mounted it suppresses that sun's legacy sprite $Flare: path, and if the lens has a starburst the bitmap sun glow is skipped too, so the old and new effects never stack.

The pass needs post-processing; with it off, or in a full nebula, or in VR (a per-eye camera artifact would be wrong), it simply doesn't run. Both renderer backends are covered — opengl_post_pass_lens_flare() and VulkanLensFlare — so this is not a Vulkan-only feature.

Structure

Four translation units behind one public header, graphics/lens_flare.h, with lens_flare_internal.h as the private interface between them:

• lens_flare_optics.cpp — ray-transfer matrices, ghost enumeration, coated-Fresnel reflectance
• lens_flare_aperture.cpp — the iris mask and the starburst that is its Fraunhofer transform (CPU FFT)
• lens_flare_table.cpp — lens_flares.tbl / *-lens.tbm parsing; holds no state
• lens_flare.cpp — module state, the camera lens, the texture cache, the per-frame build

The first two are pure functions of a prescription or an iris and touch no engine state at all. Rendering is one instanced draw per visible sun (the flare axis and tint are per-sun; the prescription, iris and starburst are not), sharing one texture bind for the whole pass, composited additively into the HDR scene colour immediately before bloom so bloom and the tonemapper treat the flare's energy like any other scene light.

Because the flare is fused into the pre-tonemap buffer, the SDR and HDR tonemappers would otherwise render an identically-tuned flare at very different brightness, so the HDR contribution is rescaled by Hdr_flare_headroom / LENS_FLARE_SDR_REFERENCE_WHITE, with SDR as the calibration reference.

Commits

1. Add physically-based lens flares — the engine feature, both backends, tables, tests
2. Expose the camera lens to mission designers and the lab — mission field, editors, sexps, lab panel

The first stands alone (it configures and builds without the second), so bisect stays clean.

Testing

• 18 unit tests covering the optics (analytic focal length, unimodular ghost matrices, coated-Fresnel edge cases), the FFT, the iris rasterizer's geometry and imperfection layers, table parsing of every aperture field, lens mounting/override/reset, and the sexp registration/argument-type tables.
• Verified in-game on both backends with two suns in frame, each flaring through the mounted lens at its own field angle, with Vulkan validation layers enabled and clean.
• Built warning-clean on Linux/GCC (Debug) with the tests enabled.

Not yet verified, and where review attention would help most:

• The FRED (MFC) changes — new IDC_CAMERA_LENS combo, fred.rc dialog resize, resource.h id — are Windows-only and have not been compiled here. CI's Windows leg is their first real test.
• Final visual sign-off on brightness calibration, and the HDR path in particular, is still in progress.
• Table syntax documentation for the wiki is written but not yet published.

🤖 Generated with Claude Code