Enhancements
None of this was on the hardware. Where an option is off, output is bit-identical to stock. Full list: libretro docs.
True colour shipped v3.2.0
The blitter computes Gouraud shading with 16 fraction bits, then throws
them away in the 16-bit CRY write.
virtualjaguar_true_color keeps them, in a shadow
framebuffer. Game-visible RAM stays bit-identical.
Internal resolution 2x complete v3.3.0
The blitter is the Jaguar's rasterizer, and it walks source textures
with 16.16 fixed-point steps, then rounds each output pixel to the
nearest texel and throws the rest away.
virtualjaguar_internal_resolution (1x default,
2x, restart required) re-samples those same walks at double
density into a shadow surface. The extra pixels are source data
the hardware sampled past. No interpolation or filtering is
involved.
As of v3.3.0 the pipeline is complete. Supersampling covers fractional-walk blits (Stage 2), the Object Processor's scaled sprites (Stage 3, SCBITOBJ) including 8bpp CLUT objects, and both CRY and RGB16 direct video modes render the recovered detail to the screen.
The RGB16 renderer mattered more than it sounds. Measured across about 3,000,000 scaled calls, Val d’Isère and Primal Rage are 100% RGB16: before v3.3.0 an entire class of titles produced supersampled content and then threw it away at scanline time. The CLUT extension is what reaches 2D games at all. Scaled CLUT objects are 81% of the truly-scaled pixels in International Sensible Soccer and 76% in Val d’Isère.
The emulated machine never sees any of it. The stock framebuffer stays
bit-identical and savestate digests match between 1x and
2x. Both are proven per-title by committed tooling,
hires_box_check
and
hires_state_digest,
rather than asserted.
Doom and JagDoomEX
Doom is CRY-mode and blit-rendered, so it exercises the Stage 2 path. So does the JagDoomEX romhack: the per-title database recognizes it by its patched CRCs and enhances it identically. The frame below is from the attract demo, machine-selected for the highest measured sub-pixel density in the run, 13.9% of 2x2 blocks.
Which titles benefit, measured
The number is the share of 2x2 output blocks carrying genuine sub-pixel detail. It is a coverage figure, not “N% better image”. Every scene below was screenshot-verified in real gameplay, and is identical on both blitter engines.
| Title | Scene | Blocks with real sub-pixel detail |
|---|---|---|
| Alien vs Predator | textured corridor, standing still | 30.6% |
| Alien vs Predator | same level, walking into a door | 13.0% |
| Skyhammer | in-mission cockpit, city flight | 3.4-17.7% |
| Doom | E1M1 gameplay | 8.7% |
| Missile Command 3D | Original 3D gameplay | 5.0-5.9% |
| Val d’Isère Skiing | downhill run (new in v3.3.0: RGB16 + scaled CLUT) | 2.5-7.2% (was 0.0000%) |
| International Sensible Soccer | match kickoff (scaled CLUT sprites) | 0.1-0.6% (was 0.0000% outside 16bpp scenes) |
The AvP spread is the honest shape of this feature. A corridor viewed down its length is minification-heavy and recovers a lot. A wall pressed against the camera is magnification-heavy and recovers little. Stage 2 recovers information only where the source walk minifies.
Which titles it does nothing for
Three census candidates measured a true 0.0000%, for three different reasons.
- Towers II: zero non-uniform blocks across 1.17 billion rendered pixels. Its content is information-theoretically flat for this feature.
- I-War and Towers II: they magnify their textures. 81% of I-War's qualifying walks consume less than one texel per pixel, so the half-step sample lands inside the same texel and there is nothing to recover. Information-theoretic, not a bug.
- Cybermorph and Checkered Flag: effectively none of their blits use a fractional source walk, 13 and 8 qualifying blits out of roughly 1.7 M each, and Cybermorph re-measured 0.0000% on v3.3.0 even with true colour on. There is nothing for this feature to hook into. Use True Color there instead, which is why the per-title defaults ship it for Cybermorph.
Iron Soldier 2 on CD is unverified, not zero: its gameplay could not be reached headlessly. This helps some games. It does not help all of them.
The cost
2x scales with screen area, so budget for it on a handheld.
Stage 1 measured Doom at +13% frame time, and Stage 2 adds
roughly +1.5% (Doom) to +7.4% (Missile Command 3D) on top of that. At
1x the cost is nil and the output is bit-identical.
HD texture dump and replacement shipped v3.4.0
Both halves of a texture-pack pipeline.
virtualjaguar_texture_dump writes every unique blit source
the game uses to <system>/vj_texdump/<CRC32>/
as a PNG named by a stable content hash: FNV-1a 64 over format,
dimensions and raw source bytes.
The palette is deliberately excluded from that hash. The Jaguar blitter never sees one, and a key the replacement pipeline cannot discriminate would strand every pack drawn against it. The identity contract is frozen in docs/texture-dump.md.
Redraw a tile, keep its filename, move it one directory over to
vj_texpacks/<CRC32>/, and it presents in place of the
original. Packs are true colour. Nothing quantises back to CRY, and a
pack pixel with alpha below 128 keeps the stock pixel. Replacement rides
the true-colour shadow framebuffer and never writes the emulated
machine, so savestates, rewind, run-ahead and netplay stay bit-identical
with or without a pack. A pack cannot desync a link game.
Tier 1 covers 16bpp source tiles at 1x through straight-copy blits, the sprite and UI class the dump mode was built around. Indexed sources (tier 2) and Stage 2 hi-res surfaces (tier 3) are designed but not implemented; those entries are skipped and the stock pixel presents. The replacement option only appears when a pack directory exists for the loaded cartridge.
Clock scaling
virtualjaguar_m68k_clock_scale runs 0.5x to 3x, and
virtualjaguar_risc_clock_scale 0.5x to 2x. Bus latencies
stay in wall time at any scale, so pacing and pitch do not drift. CI
proves it at non-1x scales.
CD read speed
virtualjaguar_cd_read_speed runs from 1x
(hardware-faithful) to instant, on the HLE path. Streaming reads keep
fast transfers from stomping in-flight game code. Regression-tested.
Crash watchdog
virtualjaguar_crash_detect, default on, matches known
failure signatures each frame. Your frontend log names the subsystem
that broke.
Per-title defaults shipped v3.2.0 and later
virtualjaguar_pertitle_defaults, default on, applies
known-safe presets for recognized games: 2x for Doom and Alien vs
Predator, true colour for Cybermorph, 2x plus true colour for I-War
and Skyhammer, and more as titles
are verified. A preset only touches options you have left at their
defaults. Any option you set yourself always wins. Disable it for stock
behaviour on every title.
Blit memoization shipped v3.3.0
Some titles re-render a bit-identical scene every engine cycle while the
player is idle. virtualjaguar_blit_memo skips a blit only
when its entire input state provably matches an earlier
identical blit, and then replays the recorded writes. Output is
bit-identical by construction, and a verify mode executes every
would-be skip and checks it.
Enabled per title via the enhancement database, which currently carries no rows for it: the mechanism ships ahead of the data, so nothing turns it on by default. 2,546,482 corpus verifications, zero divergences.