PenguinBox 0.2-beta — experimental Steel Battalion performance release

PenguinBox 0.2-beta — experimental performance release for Steel Battalion

Pre-release. Experimental. This build exists to put the Steel Battalion
performance work in front of people who actually play these games.

Focus: Steel Battalion (0x43430002) and Steel Battalion: Line of
Contact (0x43430009). Every other title is deliberately untouched by this
release — see "What this does not change".

---

The headline

In 0.1-beta the performance work shipped opt-in: you had to know the
environment variables existed and set them by hand, so almost nobody ran them.

In 0.2-beta those paths turn themselves on when you launch Steel Battalion
or Line of Contact. No environment variables, no launcher flags, nothing to
configure. Launch the game and you get the measured configuration.

The emulator prints what it decided, so you can confirm it:

perf-title: 0x43430009 — measured performance paths ENABLED (validated title)
present-dedup: skip recomposite of an unchanged display surface ON
nv2a: alias-surfaces ON (validated title)
nv2a: surf2tex-zerocopy ON (validated title)
nv2a: surf2tex-ext ON (validated title)
nv2a: surf2tex-feedback ON (validated title)

What's new since 0.1-beta

• Per-title auto-enable of the surface-as-texture stack (gather / alias /
  zero-copy / feedback) and the guest read fast path, for the two Steel
  Battalion titles.
• Composite de-duplication (present-dedup). The UI thread was asking the
  emulator for a fresh frame far faster than the game produces one, and each
  request re-composited an unchanged image: 41.8 composites per game frame,
  now 1.0. This removes roughly 12 ms per frame of GPU and CPU work.
• Per-frame capture instrument (XEMU_PROF_CAPTURE) — see "Reporting
  problems". This is how a report from you becomes something diagnosable.
• The application is now labelled PenguinBox — window title and app
  metadata. The underlying emulator is still xemu, and is still credited as
  such everywhere it should be.

What you should expect to see

Honest numbers, measured on one development laptop (Vulkan renderer):

• Steel Battalion — the heaviest scenes improved from 36.5 ms to 30.8 ms
  per frame, with the surface-download fallbacks that caused them going to
  zero. SB targets 30 FPS and drops to 20 when a frame misses its budget, so
  the practical effect is fewer drops to 20, not a higher ceiling.
• Line of Contact — the big win here already shipped in 0.1 (the
  surface-readback storm). 0.2 removes the composite overhead on top of it.

Please read this before reporting LoC as "only 20 FPS"

Line of Contact runs at 20 FPS on original Xbox hardware. It is capped
there in all three resolution modes, and the Steel Battalion Wiki's own
technical page documents named maps that drop below 20 on real hardware
because of the tree and building destruction. PenguinBox running LoC at 20 is
correct behaviour, not a performance problem. Menus run at 30 because the
cap is not engaged there — that is also what hardware does.

What is worth reporting: frames dropping below 20 (to 15 or lower),
especially somewhere the console held 20.

What this does not change

Every other game keeps stock behaviour. These paths are enabled only for
the two title IDs above, because those are the only titles they have been
measured and validated on. Turning them on globally would change rendering for
games nobody has checked.

If you want to try them on another title, they are still available by hand:

XEMU_SURF2TEX_EXT=1 XEMU_ALIAS_SURFACES=1 XEMU_SURF2TEX_ZEROCOPY=1 \
XEMU_SURF2TEX_FEEDBACK=1 XEMU_PRESENT_DEDUP=1

If you do that and find something good (or something broken), that is genuinely
useful — it is how a title gets added to the validated list.

If something looks wrong — bisecting without a rebuild

Each path can be forced back to stock individually, on this same build:

variable	turns off
XEMU_NO_SURF2TEX_FEEDBACK=1	sampling a render target while it is still bound
XEMU_NO_SURF2TEX_ZEROCOPY=1	borrowing a surface image instead of copying it
XEMU_NO_ALIAS_SURFACES=1	keeping large overlapped surfaces resident
XEMU_NO_SURF2TEX_EXT=1	the multi-surface gather copy
XEMU_NO_PRESENT_DEDUP=1	composite de-duplication

All five at once gives you stock rendering for a direct comparison. If one of
them fixes what you are seeing, that single line is the most valuable thing
you can put in a report.

Reporting problems

Set one variable and play normally:

XEMU_PROF_CAPTURE=1

The emulator writes nv2a-prof-<pid>-<timestamp>.csv to your home directory —
one row per frame, with the build commit, the timestamp and every relevant
setting recorded in its header, so it explains itself without us having to ask
you twenty questions. Send that file along with what you saw and roughly when.

Known issues in this build

• Line loops render with one edge missing (Vulkan). Line-drawn boxes, rings
  and reticles can appear open on one side. This is an upstream xemu bug in
  the Vulkan renderer, not introduced here, and it affects any title that draws
  line loops.
• Minor visual observations on Line of Contact are unconfirmed. The default
  paths were checked by eye and looked right, but nobody here has played enough
  LoC to be sure what is correct. If something in the cockpit looks off to you,
  you are better placed to judge it than we are — please say so.

Artifacts

The 0.2-beta binaries and source tarball have been withdrawn. Builds return with the next release candidate. The source for
this release is the penguinbox-0.2-beta tag in this repository.

PenguinBox is a fork of xemu, which is a fork of QEMU. The aggregate is GPL v2; see
LICENSE and COPYING, and the SPDX headers on individual files. The overwhelming majority of this software is the work of
those two projects and their contributors.

Status

Experimental. It is a pre-release because it should be judged by people who
know these games, on hardware we do not have, before anything here is treated
as settled.