Enhancements

The core recognises about a dozen games by CRC and applies the preset chosen for that title:

A compatibility row (the last one) is never withheld by the profile and cites the ticket for the real fix, so it can be retired. Since v3.8.0 RetroArch also shows an on-screen notice naming the presets applied when a game loads. Any option you set yourself always wins. virtualjaguar_pertitle_defaults turns the database off for stock behaviour. virtualjaguar_enhancement_profile (Auto, Quality, Performance) decides whether the expensive ones may apply: Auto skips them on 32-bit ARM and backs off if the audio buffer under-runs. Every row cites its evidence in titledb.c.

The blitter computes Gouraud shading with 16 fraction bits, then drops them in the 16-bit CRY write. virtualjaguar_true_color keeps them in a shadow framebuffer. Game-visible RAM stays bit-identical.

Stock 16-bit CRY, off

True colour, on

The blitter walks source textures in 16.16 fixed point, then rounds each output pixel to the nearest texel and discards the rest. virtualjaguar_internal_resolution (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. Nothing is interpolated or filtered.

It covers fractional-walk blits, the Object Processor’s scaled sprites including 8bpp CLUT objects, and both CRY and RGB16 video modes. The emulated machine never sees it: the stock framebuffer and savestate digests are identical at 1x and 2x, proven per title by hires_box_check and hires_state_digest.

Alien vs Predator, frame 6000 1x / 2x

Corridor wall magnified 6x

Val d’Isère, 46 MPH 1x / 2x

Which titles benefit

Share of 2x2 output blocks carrying real sub-pixel detail, measured in real gameplay and identical on both blitters. It is a coverage figure, not “N% better image”.

Recovery happens only where a source walk minifies. A corridor seen down its length recovers a lot. A wall pressed against the camera recovers little.

Where it does little or nothing

• Towers II magnifies its textures, so the half-step sample lands in the same texel. It measured zero non-uniform blocks over 985 million blocks of menu, navigation and dungeon frames, so it no longer turns 2x on by default. I-War is nearly the same: about 1.1-1.4% of blocks gain detail, mostly one-pixel speckle on its few textured objects. Its true colour setting is separate.
• Cybermorph and Checkered Flag almost never use a fractional source walk. Use True Color for Cybermorph instead.
• Iron Soldier 2 on CD is unverified: its gameplay could not be reached headlessly.

It helps some games, not all. 2x scales with screen area: Doom measured +13% frame time for the first stage and a further +1.5% to +7.4% for blit supersampling. At 1x the cost is nil.

virtualjaguar_texture_dump writes every unique blit source to <system>/vj_texdump/<CRC32>/ as a PNG named by a stable content hash. Redraw a tile, keep its filename, move it to vj_texpacks/<CRC32>/, and virtualjaguar_texture_replace presents it in place of the original. The option appears only when a pack exists for the loaded cartridge.

• Packs are true colour. A pack pixel with alpha below 128 keeps the stock pixel.
• 16bpp source tiles work at 1x and on the 2x surface. Indexed (8bpp or less) sources are not implemented yet and show the stock pixel.
• Replacement never writes the emulated machine, so savestates, rewind, run-ahead and netplay are bit-identical with or without a pack. A pack cannot desync a link game.

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, so pacing and pitch do not drift. Both also take a percentage such as 175% (25 to 400). Since v3.9.0 idle-skip stays active at any RISC scale, so a 2x overclock no longer emulates twice the spinning (Doom at 2x: 52 to 82 fps in the project’s headless harness); see Settings & performance.

v3.1.0 notes · v3.9.0 notes

CD read speed

virtualjaguar_cd_read_speed, HLE boot only: 1x (hardware-faithful), 2x (default), 4x, 8x or instant. Streaming reads keep fast transfers from overwriting in-flight game code.

cd-read-speed.md

Blit memoization

virtualjaguar_blit_memo skips a blit only when its whole input state provably matches an earlier identical blit, then replays the recorded writes. It is per title via the database, which currently has no rows for it, so nothing turns it on. It is not available for CD content.

blit-memo.md

Hooks and patches

Per-title enhancement hooks and your own vj_hooks.txt are checked byte-for-byte and apply all-or-nothing. They are off by default.

patching-a-game.md

Crash watchdog

virtualjaguar_crash_detect, on by default, matches known failure signatures and names the broken subsystem in your frontend log. Since v3.7.0 it also logs inframe_hang for a blit too large to ever finish, which per-frame checks cannot see, and since v3.8.0 it sees DSP runaways in HLE boot too.

crash_detect.c