WIP: perf(host): skeletal animation maths on host code, bit for bit the game's (HOS_NATIVE_ANIM) #1909
Labels
No labels
area/accessibility
area/audio
area/input
area/install
area/menu
area/renderer
area/saves
area/tooling
area/upscaling
beanstalk: approved
beanstalk: failed
beanstalk: needs approval
beanstalk: running
beanstalk: tested
ci: approved
good first issue
gpu/amd
gpu/igpu
gpu/intel
gpu/nvidia
help wanted
kind
bug
kind
chore
kind
docs
kind
feature
kind
performance
kind
question
needs measurements
platform/linux
platform/macos
platform/steam-deck
platform/windows
preview
priority
critical
priority
high
priority
low
regression
risk
high
risk
low
risk
medium
status
blocked
status
confirmed
status
duplicate
status
invalid
status
needs-info
status
wontfix
ci: approved
No milestone
No project
No assignees
4 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
MagicBeanDev/Longshot!1909
Loading…
Reference in a new issue
No description provided.
Delete branch "snaildev99/Longshot:perf/native-animation"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Summary
Five of the game's skeletal animation routines run as native host code by default (
HOS_NATIVE_ANIM=0runs the translated code), giving the game's results bit for bit: every byte written, every FPSR flag, every register the callers read. A call the host cannot prove exact runs the game's translated routine, with nothing written by the host.The goal is less CPU work for the same frame: these routines run every frame for every animated character, the blends and the curves on the executor threads. With nine rewrite branches on together (this one among them, merged in a test tree; named in the baseline below, the cloth and particle effect rewrites are not among them), the game used 2.7 % less CPU standing and 2.4 % less turning in Castle Town's Market at a 60 fps cap, 4.1 % / 4.0 % less on the executor threads. This branch's own share of that has not been measured alone: the Test Farm request asks for it.
The routines it answers (guest addresses):
f_814f6c60: the additive blend of one bone's animation into its 80-byte bone record (the rotation from three angles through the sine table, two rotation-matrix rows, scale and translation, all times the weight).f_814f7080: the same blend when the rotation may be a quaternion.f_814f0620: one bone's animation curves at the current frame, with the whole call tree below it: the frame wrapped by the pre / post modes (clamp, repeat, mirror, relative repeat), the key search for float, s16 and u8 frames, the cubic, linear, one-key-a-frame and step segments for float, u16 and u8 keys, and the segment cache records. The tables of segment functions are read at run time; a function the host does not know declines the bone.f_814f5430: a bone's rotation (a quaternion, or three angles through the game's sine / cosine polynomial) as three matrix rows, for animations that are not blended.f_81500200: the skinning matrix palette's two loops (each smooth-skinned matrix the bone's world matrix times its inverse bind, each rigid one the world matrix's rows), hooked at two places inside the function; the calls before and after the loops stay translated.How:
nx2/oot_patches.py(ANIM_FUNCS,ANIM_PLACES,patch_anim) putsif (hos_anim_<addr>(c, f_<addr>)) return;first in the four leaf routines and the two label hooks intof_81500200, in the supported build only.host/oot_anim.cgates each call: FPCR / FPSR inside the translator'sRECOMP_FPX_OPEN, every byte read and written inside guest memory, no output over an input the routine still reads.host/anim_kernels.cdoes the arithmetic as the game's instructions do it, in their order: FMADD / FMSUB / FNMSUB fused, FMUL then FADD apart, each product through an empty asm so-ffp-contract=fastcannot fuse it; every value read or made must be zero or of a magnitude where flush-to-zero and Arm's tininess rule cannot change a bit, else the call declines before any write. Without SSE4.1 and FMA3 every call declines.Read first:
host/anim_kernels.c(anim_blend_euler,blend_tail,anim_bone_curves),host/oot_anim.c, theHOS_NATIVE_ANIMblock ofnx2/oot_patches.py,tests/test_anim_kernels.py.No code here is ported from another project.
Testing
Tested: Windows 11, RTX 3090 (NVIDIA 610.88), Ryzen 9 5900X. In the game, in a test tree that merges nine rewrite branches, this one among them, on main
068fb8eb(test/rewrites@ e614ef49 on my fork; this code as at 7a4ae874): a check run withHOS_NATIVE_ANIM=check(every call the host takes is also run translated and the two compared), about five minutes in the Market and Hyrule Field: 0 different. Answered by the host: the curves 7,390,153 of 7,536,640 calls (98 %; the rest declined for their inputs), the rotation rows 1,703,936 of 1,703,936, the blend 3,538,944 of 3,538,944, the quaternion blend 1,769,472 of 1,769,472, the skinning palette 131,072 of 131,072 (the counters as last logged; they log every 65,536 calls). Then the CPU measurement in Measurements, with the switch on. This head includes later fixes and is not built or played.Offline, against the game's own code: an AArch64 emulator (Unicorn) runs the game's routine on its image (its own tables and callees) and the host kernel runs the same case; compared are every byte the routine writes, FPSR, and the callee-saved registers. Built three ways each: x86-64-v3, x86-64-v3 with
-ffp-contract=fast(same results), x86-64-v2 (declines every call).f_814f6c60f_814f7080f_814f0620(sequences of up to 30 calls carrying the cache)f_814f5430f_81500200's loops (5.78 million matrices)The cases: realistic bones and edge values anywhere (NaN, infinities, subnormals, FLT_MIN, the conversion limits), changed table entries, outputs laid over inputs, every FPCR mode and FPSR state. Run again on the earlier branch's host files with the same seeds and sizes: the same counts, 0 mismatches in all three builds. The later fixes at this head have not been verified by these runs.
Game-free tests before the later fixes:
tests/test_anim_kernels.py(blend 200,000 and quaternion blend 200,000 cases, rotation rows 200,000, palette 2,000 skeletons / 154,365 matrices, curves 222,336 evaluations against plain curve maths in binary64 on inputs where every step is exact; the declines; built as built, with-ffp-contract=fastand without FMA) andtests/test_oot_anim.py(each hook placed once and only in the supported build, idempotent; off / on / check for every hook) pass. Of the 45 tests run (those two,tests/test_switch_table.pyand every test that readsnx2/oot_patches.pyornx2/entry_hooks.py,tests/test_patch_hooks_defined.pyamong them) 40 pass; the five others fail the same way on maina104182bon this PC:test_dev_packs,test_high_fps_fixes,test_libc_hooks,test_lift_cache("...and the others still by their code"),test_song_note_cue. The fulltests/run_all.pywas not run. ruff clean.Still to test:
kokiri-start): this PR withHOS_NATIVE_ANIM=0against unset (on), the game's CPU seconds at a 60 fps cap (on a PC that holds 60 there) and the frame times uncapped, expecting the same frame rate or better with less CPU time and the characters animating as without the switch (@Beanstalk linux, amd).HOS_NATIVE_ANIM=check, expecting everyanim:line to endDIFFERENT 0(@Beanstalk linux).HOS_NATIVE_ANIM=checkand then=1, expecting noDIFFERENTand characters animating as on main (by hand).Measurements
Verdict: less CPU for the same frame, measured with the nine on together: the whole game process 2.7 % less standing and 2.4 % less turning in the Market at a 60 fps cap, the executor threads (where these routines run) 4.1 % / 4.0 % less. With the hooks built in and the switches off, -0.3 % / -0.2 % against plain main: inside the runs' spread, so no cost measured with the switch off. This branch's own part is not separated: the Test Farm request asks for this PR alone, switch off against on. Offline, against the translated routine in the old form (every register in the context): the blend 4.4 times, the quaternion blend 6.2 to 6.6 times, the curves 2.1 to 2.4 times for bones of 8 to 12 curves (1.4 times at 4), the rotation rows 7.6 times, the palette 8.0 times a smooth matrix.
Baseline: three builds from scratch of two trees, the default hot list: plain main
068fb8eb(Before), and the test treetest/rewrites@ e614ef49 on my fork, which is main068fb8ebwith nine rewrite branches merged (the seven maths units, the maths library, animation, bounds, crowd, visibility, glue, the effect triggers with the six-channel reverb, and the solver; the cloth and particle effect rewrites are not among them; this branch as at 7a4ae874), lifted withA64_FPXKEEP=0(a lift-time change of another branch left out): once with no switch set, once with the nine's switches on (HOS_NATIVE_ANIM=1and the other eight's). Main has since moved toa104182b; the numbers are main 068fb8eb's, and the farm request measures this PR alone on current main.Setup: Windows 11 (build 22631), Ryzen 9 5900X, RTX 3090, 3840x2160; child Link in the Market, hands-free through
scripts/longshot_ctl.py; the frame rate capped at 60, which all 15 runs held; each run 30 s standing, then 30 s turning the camera; the three variants (with two more of another change) interleaved over three rounds, the PC otherwise idle. CPU seconds a second of play (cores busy on average) from the processor's cycle counter, per thread; the median of three runs.068fb8ebBaseProcExecutor*), standingmkw_vk capture copy, standingmkw_vk capture copy, turningThe process includes the renderer's threads (about 1.4 cores), which the nine do not touch. The capture copy thread's rise is in Risks.
Offline speed, one call (
bench.pyin my tools: the translator's copy of each routine at the hot list's flags without PGO, in the old form with every register in the context, against the kernel plus the hook's own tests; outputs compared equal first; best of 7; Ryzen 9 5900X). These are against the old form, not main's form with registers in locals; for these vector-heavy routines main's form was not produced. A hooked function is written in the old form on main too.f_814f6c60f_814f7080f_814f0620and belowf_814f5430f_81500200(the whole function against the kernel and the copy)The shares are self time in a Market profile and two route profiles (Kakariko and Death Mountain Trail) of earlier builds.
The switch
HOS_NATIVE_ANIM(new, run time, on by default; its row ingpu/vk/switches.def):0off (every hook returns at once); unset or1on;checkruns the host kernel into a copy, then the translated routine for real, compares, and logs any difference (slow). A start lineanim: the skeletal animation maths (...) on the host (HOS_NATIVE_ANIM), and a line every 65,536 calls of a routine, from the check run:It ships on: docs/dev/standards.md has a switch ship at its value from the first push, never off because it is new, and the measurement with the rewrite branches together says on.
HOS_NATIVE_ANIM=0gives main's lifted code. This PR's own measurement (the farm request) can still turn it off before it leaves WIP.Risks
What could break: a kernel that is not exact would animate a bone differently from the Switch (a pose, a skinned vertex). Checked as in Testing; every kernel declines what it cannot prove (a float mode outside the translator's gate, a value near the flush-to-zero edge, a key or table it does not know, memory outside the guest's, an output over an input) and the translated routine runs.
A cost seen: with the nine on, the renderer's
mkw_vk capture copythread (it copies guest memory the game marked as written) used 0.009 to 0.017 more cores in the measured runs (+10 % standing / +18 % turning), against 0.09 to 0.10 cores less on the executors. The hooks now preserve the translated stores' marking groups; which of the nine caused the measured rise is not determined, and this head has not been measured. Taken into account in the whole-process figures above.Turning it off:
HOS_NATIVE_ANIM=0.After updating: nothing changes for a player: saves,
longshot_options.iniand the caches as before. The five hooked functions are written by the translator with their registers in the context (as every patched function is), which changes their lifted code; with the switch at=0the measured cost was within the runs' spread.Checklist
Ready for review
main; the title is a Conventional Commit.068fb8eb, checked and measured; this head is not built or played.)mise run testpasses (any failure that also fails onmainis named). (45 tests run, the branch's own and every one that reads the patch files: the five failures fail on main too; the full suite not run.)main, or Measurements says why there is nothing to measure. (Measured against main with the nine on; this PR alone waits for the Test Farm.)third_party/untouched; nothing GPL-incompatible.When it applies
gpu/vk/switches.def. (The row is there; on by default,=0gives main's lifted code; this PR's own measurement can still turn it off.)tests/that reads changed source is updated, not weakened. (tests/test_anim_kernels.pyandtests/test_oot_anim.pyare new.)Assisted-by:/Co-Authored-By:trailers.Ready to merge
main, measured again or a comment says why the numbers still hold.🤖 Generated with Claude Code
Tested in game: This head is not built or played; the same code, merged into a test tree on main
068fb8eb, ran on Windows 11 (RTX 3090, Ryzen 9 5900X): HOS_NATIVE_ANIM=check in the Market and Hyrule Field, 0 different over about 14.5 million calls the host answered, then a CPU measurement at a 60 fps cap with nine rewrite branches on, this one among them (the whole process -2.7 % standing, -2.4 % turning).@Beanstalk linux, and amd: this PR in the child Market and in Kokiri Forest (the repo save kokiri-start), HOS_NATIVE_ANIM unset against HOS_NATIVE_ANIM=1, a few minutes each. Measure the game's CPU seconds with the frame rate capped at 60 (on a PC that holds 60 there), per thread if you can (the executor threads are where it lands), and the frame times uncapped. Expect the same frame rate or better with less CPU time, characters animating as without the switch, and "anim:" lines in the log with the switch on. Then one Market run with HOS_NATIVE_ANIM=check: every "anim:" line should end "DIFFERENT 0".
@snaildev99 only members of
BigBeanscan start the farm.One of them can approve this request by reacting 👍 to it or to this comment.This request was forf874073, and the PR has changed since (1607f1f), so a 👍 no longer approves it. Comment@Beanstalkagain to ask for the new commit.Possibly related, for context:
Recommendation: Request changes. The palette hook can copy to an unchecked guest destination, and the change has no isolated measurement showing that its default or its switch-off cost is acceptable. The reported gain combines nine branches and does not establish this branch’s benefit.
This adds native implementations of five skeletal animation paths, with translated fallbacks and a comparison mode. The potential gain is lower animation CPU time; the costs include additional arithmetic and hook code, altered lifted functions even when disabled, and potentially coarser GPU write tracking. The destination check and measurement gaps need addressing before merge.
Does it help: Unproven. The PR reports 2.7% and 2.4% less whole-process CPU in standing and turning Market runs, but those figures include nine rewrite branches on an older base. There is no isolated current-base result, uncapped frame-time or 1% low comparison, or measurement of this branch’s switch-off cost.
Other systems: The paths run on animation executor threads and mark guest memory for the renderer; the combined test saw the capture-copy thread rise by 0.009–0.017 cores, with the responsible branch undetermined. Linux, AMD, Steam Deck and this head in the game remain untested. CPUs without SSE4.1 and FMA decline the kernels but still execute the hooks; their cost is unmeasured.
Switches: HOS_NATIVE_ANIM is added as a runtime developer switch: unset or 0 is off, 1 enables the kernels, and check compares against translated execution. Its table row is present, but the off default was chosen pending measurement, contrary to the project rule requiring a measured default from the first push.
Reviewed:
f8740738feagainsta104182b40: Read AGENTS.md, CONTRIBUTING.md, the PR template, relevant standards, the diff for the switch, header and patch integration, host/oot_anim.c, and portions of host/anim_kernels.c. Skimmed the tests and commit history; the large combined output was truncated, so the kernels and tests were not read fully. The rest of nx2/oot_patches.py and the generated game routines and callers were not read in full. docs/review-checklist.md and ../Tooling/AGENTS.md were absent.; nothing run (a code review).Checked and fine:
Blocking (to change before merge)
Suggestions (the author may take or leave)
Testing: No code, tests, builds or project scripts were run for this review. The author reports 40 of 45 selected tests passing, with five also failing on the base; the full suite and an in-game run of this head remain outstanding.
Overlaps and merge order: Not checked; the network is closed.
Automated code review by BeanBot (gpt-6.1-terra), on the pull request's opening. Nothing was run; a maintainer decides.
@ -104,6 +104,7 @@ SW(HOS_MOVIE_PACE, kill, bool, "on: a 60 FPS cap is raised for a movie's pictureSW(HOS_MUTEX_TRACE, diag, int, "0: off", "Logs mutex waits longer than <ms>, with the thread that held the mutex.")SW(HOS_MUTEX_WATCH, diag, string, "off", "Logs every operation on the mutex at that guest address (hex) and its condition variables' signals.")SW(HOS_MW_WAKE, kill, enum, "only changes to objects linked into a multi-wait wake WaitAny", "=all: every event, semaphore or queue change wakes every WaitAny, as before.")SW(HOS_NATIVE_ANIM, attempt, enum, "off: the skeletal animation maths run as lifted", "1 runs the additive blends of a bone's animation (f_814f6c60, f_814f7080) a bone's animation curves (f_814f0620) a bone's rotation rows (f_814f5430) and the skinning palette's loops (f_81500200) on host code where it gives the game's bits exactly, the rest lifted; check runs both on every call and logs any difference (slow). An anim: line every 65536 calls counts the calls (host/oot_anim.c).")The off default is pending measurement, but the switch standard requires a measured default from the first push. Please measure this branch alone on the current base, including switch-off and frame-pacing costs, and choose the default from those results.
@ -0,0 +251,4 @@return 0;}if (!took) return anim_count(s, WHY_INPUT), 0;if (bytes) {The kernel does not validate the destination range. A nonempty palette outside or crossing the guest window makes this return NULL, then memcpy uses it. Check the whole output range before accepting the kernel result and test that case.
@fiix
@fix
I changed this pull request by bringing it up to date: the new head is
1607f1f0e5. I rebased it ontomain(a764653726).Conflicts resolved
Left for the author
Nothing was built or run: check the change. It will be reviewed again.
Automated fix by BeanBot (gpt-6.1-terra), asked for by HumanBean. Nothing was run; a maintainer decides.
f8740738fe1607f1f0e5Recommendation: Request changes. The palette hook can crash on an unchecked destination, and check mode can miss differences in guest state. The reported CPU savings combine nine rewrites, leaving this branch’s gain and switch default unproven.
Adds native skeletal animation for eligible blends, curves, rotation rows and skinning palettes, with translated fallback. The kernels could reduce executor CPU time, at the cost of more arithmetic and ABI logic to maintain, extra hook calls with the switch off, and potentially more renderer capture work with it on.
Does it help: Unproven. Three interleaved Windows 11 runs per variant on a Ryzen 9 5900X and RTX 3090 reported 2.7% less process CPU standing and 2.4% less turning in the Market at 60 fps, with executor CPU down 4.1% and 4.0%. Those results combine nine rewrites on
068fb8eb. The combined tree with switches unset was within the runs’ spread. Offline speedups of 1.4× to 8.0× compare against the older context-register translation. This head needs isolated measurements againsta764653726, including switch-off overhead, average fps, 1% lows and median and p99 frame times.Other systems: Executors share the animation counters, and animation writes feed the Vulkan capture mirror. The combined run reports 0.009–0.017 more cores on capture copy (+10–18%) with attribution still open. Curve results mark the entire span between offsets, including any untouched pages between them. NVIDIA Windows evidence comes from the older combined tree. AMD, Linux, Steam Deck and the rebased Windows build lack game evidence. Builds without SSE4.1 or FMA decline the kernels but retain the hooks. The patch changes generated C and adds host compilation. The Windows guest window can contain reserved, uncommitted pages. Saves, options, audio and input have no direct edits, and the lift cache already keys on oot_patches.py.
Switches: Adds HOS_NATIVE_ANIM as a runtime developer switch with a switches.def row. Unset or 0 is off, 1 enables native answers, and check compares against translated execution. The parser actually treats any other enabled value as on unless it starts with c or C. The off default is provisional and lacks the measurements the project requires from the first push.
Reviewed:
1607f1f0e5againsta764653726: Read AGENTS.md, CONTRIBUTING.md, the PR template and developer standards, the commit series, all seven diffs, all three new host files, both new tests, and all changed sections of nx2/oot_patches.py. Read relevant guest-range, write-tracking, thread-lifetime, FP gate, CPU target, patching, splitting and build code. Skimmed unchanged portions of the patch pipeline and the switch table. Reviewed the supplied comments, stale review and reported runs. docs/review-checklist.md and the adjacent Tooling checkout were absent. Generated game routines, callers and offline harnesses were unavailable, so their ABI and exactness claims could only be checked against the supplied evidence.; nothing run (a code review).Checked and fine:
Blocking (to change before merge)
1607f1f0e5.Waiting on the author (a run, a measurement or a decision; no edit does it)
Suggestions (the author may take or leave)
Testing: Read-only review. The author reports 40 of 45 selected checks passing on the previous base, with five failures also seen on main. The offline comparisons report zero mismatches on accepted cases, and the older nine-branch Windows tree reports zero output differences during about five minutes in the Market and Hyrule Field. No supplied result establishes a full build, suite, CI pass or game run for
1607f1f0e5.Overlaps and merge order: #1899 uses the same native rewrite pattern for bounds but has no direct routine overlap in the supplied context. No merge order established.
Automated code review by BeanBot (gpt-6.2-sol), asked for by BeanBot, after its fix. Nothing was run; a maintainer decides.
@ -105,6 +105,7 @@ SW(HOS_MOVIE_PACE, kill, bool, "on: a 60 FPS cap is raised for a movie's pictureSW(HOS_MUTEX_TRACE, diag, int, "0: off", "Logs mutex waits longer than <ms>, with the thread that held the mutex.")SW(HOS_MUTEX_WATCH, diag, string, "off", "Logs every operation on the mutex at that guest address (hex) and its condition variables' signals.")SW(HOS_MW_WAKE, kill, enum, "only changes to objects linked into a multi-wait wake WaitAny", "=all: every event, semaphore or queue change wakes every WaitAny, as before.")SW(HOS_NATIVE_ANIM, attempt, enum, "off: the skeletal animation maths run as lifted", "1 runs the additive blends of a bone's animation (f_814f6c60, f_814f7080), a bone's animation curves (f_814f0620), a bone's rotation rows (f_814f5430) and the skinning palette's loops (f_81500200) on host code where it gives the game's bits exactly, the rest lifted; check runs both on every call and logs any difference (slow). An anim: line every 65536 calls counts the calls (host/oot_anim.c).")Measure this head alone against its base with the switch off and on. Include frame pacing, capture-copy CPU, clean-build cost and memory before choosing the default.
@ -0,0 +358,4 @@static inline uint64_t table_fn(AnimMem mem, Reads *r, uint64_t slot, uint64_t off) {const uint8_t *s = rd(mem, r, slot, 8);if (!s) return 0;const uint8_t *e = rd(mem, r, u64at(s) + off, 8);Validate the adjustment word too. A known function pointer with a changed adjustment can use a different curve address in the lifted call.
@ -0,0 +430,4 @@}}r[0x1c] = 0; /* (a full search: from an estimate, then a scan) */const int32_t est = arm_sdiv((int32_t)((uint32_t)(w9 - w13) * nk), w12 - w13);Cast before subtracting. A large negative s16 search frame and a positive first key can overflow the signed subtraction before the cast.
@ -0,0 +165,4 @@if (took) { /* (every record, and each result's last value, against what the lifted routine left) */for (uint32_t i = 0; i < plan.n; i++) {int last = 1;for (uint32_t j = i + 1; j < plan.n; j++) last &= plan.off[j] != plan.off[i];Offsets 8 and 10 overlap without being equal. Compare the final bytes after replaying the planned stores in order, or decline partial overlaps.
@ -0,0 +221,4 @@anim_inside = 1;lifted(c);anim_inside = 0;anim_compare(s, took, mine, d, 48);Compare the promised guest state as well as bytes. A wrong x0 or an extra FPSR flag currently passes this check. The palette needs the equivalent check for x10.
@ -0,0 +242,4 @@const int mode = anim_mode();if (!mode || anim_inside) return 0;if (!RECOMP_FPX_OPEN(c)) return anim_count(s, WHY_FLOAT_MODE), 0;if (!palette_scratch && !(palette_scratch = (uint8_t *)malloc(PALETTE_MAX * 48))) return 0;This heap block survives thread exit. Give the 48 KiB scratch thread-owned storage or release it when the worker exits.
@ -0,0 +252,4 @@}if (!took) return anim_count(s, WHY_INPUT), 0;if (bytes) {uint8_t *const d = (uint8_t *)hos_guest_range(out, bytes);A nonempty palette outside or crossing the guest window reaches memcpy with NULL. Validate the full destination and add both boundary tests. The announced fix is absent at this head.
@ -0,0 +453,4 @@(tmp / f).write_text((ROOT / "host" / f).read_text(encoding="utf-8"), encoding="utf-8")exe = tmp / ("fixture.exe" if os.name == "nt" else "fixture")# (x86-64-v3 where the compiler takes it: the kernel needs SSE4.1 and a fused multiply-add, as the game's build has)v3 = ["-march=x86-64-v3"] if subprocess.run([cc, "-march=x86-64-v3", "-x", "c", "-c", "-o", os.devnull, "-"],Compiler acceptance of -march=x86-64-v3 does not establish CPU support. Gate both new tests’ native fixtures with a runtime feature probe and keep the decline test runnable.
HOS_NATIVE_ANIMis now on by default (dbba1dce), as docs/dev/standards.md asks: a switch ships at its value from the first push, not off because it is new.HOS_NATIVE_ANIM=0gives main's lifted code. The row's kind iskill, unset reads as on (env_on_or), and the test runs it unset and=1(on),=0and=off(off) andcheck; it fails when the old read is put back. Title and description updated to match.@fix
dbba1dceedb17bedef8bRecommendation: Approve. The standalone performance gain and the correctness of this head in game remain unproven. The requested comparison, cross-platform game runs, and clean-build measurements are still needed. Nothing blocking is left: what remains is for the author before merging (below). Recommend approval; not approved on the forge.
What
@fixchangedI changed this pull request: the new head is
b17bedef8b. I rebased it ontomain(b62932a960).Conflicts resolved
Changed
Changed in part (the rest is for the author)
Left for the author
Nothing was built or run: the checks run again on the new head.
The change moves five skeletal animation routines to native host code when it can establish exact results, falling back to translated code otherwise. It adds validation and maintenance complexity in pursuit of lower CPU use.
@fixwill do (2)nx2/build.py:1898: Limit the bitmap flag to host files that need it if the broader rebuild or compilation cost is material.Before merging, for the author (3) (a run, a measurement or a decision; it doesn't hold the recommendation)
nx2/build.py:1898: Measure clean game build time and size against the base. The change adds compilation flags to every host source and adds two host compilation units, but no build measurement is reported.Checks: they run again on this head; a failure shows on the pull request.
Also noticed (1; not asked for, not blocking)
More: does it help, other systems, switches, what was read
Does it help: Unproven for this PR alone. The author measured 2.7% less whole-process CPU while standing and 2.4% less while turning with nine branches enabled together; those figures do not isolate this change.
Other systems: The hooks affect animation and guest-memory marking on Windows and Linux. The earlier Windows test tree reported zero differences in check mode, but this head has not been built or played on either OS, including AMD coverage.
Switches: HOS_NATIVE_ANIM is new and defaults on; 0 disables the hooks and check compares host results with translated results. Its default is not yet supported by a standalone measurement.
Reviewed:
b17bedef8bagainstb62932a960: Read the repository rules, contribution guide and pull request template, the latest fix diff, tests/anim_test_support.py, host/oot_anim.c, and the changed regions of host/anim_kernels.c and its tests. The remaining code and the much larger base-to-HEAD diff were not read in full.; nothing run (a code review).Checked and fine:
Testing: No commands from the project or tests were run. CI has not yet run on this head.
Overlaps and merge order: none found
Automated code review by BeanBot (gpt-6.1-terra), asked for by BeanBot, after its fix. Nothing was run; a maintainer decides.
Recommendation: Request changes. By its own header, the kernels are written from the game's disassembled instructions, and parts of them follow it closely: instruction address ranges, the game's register names, branch mnemonics. CONTRIBUTING.md's Licensing section rules out decompiled game code, so that has to be settled first. Apart from that the code is careful, but its gain alone is unmeasured, and this head hasn't run in the game.
The change runs five of the game's skeletal animation routines (the two bone blends, a bone's curves, its rotation rows and the skinning palette loops) as host code that gives the game's exact bits, and falls back to the lifted routine for any call it can't prove. For players, that means less CPU per animated character, with nothing visible changing. The code is careful (a decline writes nothing, every range and overlap is tested before a write, products are kept unfused where the game rounds them), but it adds about 1,200 lines of bit-exact maths to maintain, so it needs a measured gain to justify it.
Does it help: Unproven. The figures are -2.7 % process CPU standing and -2.4 % turning (executor threads -4.1 % / -4.0 %), Market at a 60 fps cap, 3 runs each, Windows 11, Ryzen 9 5900X / RTX 3090. They come from
test/rewriteswith nine branches on together, on main068fb8eb, so they don't isolate this PR. The offline factors (1.4x to 8x a call) are measured against the old context-register form, not the current lift. There is also no uncapped frame time or 1 % low figure. The Test Farm request named in the description is for an older commit (Beanstalk says to ask again).Other systems: All of it runs on the executor threads, which every OS and GPU vendor shares. Vendor and driver can't change the kernels' results, because they are host-CPU maths. A CPU without FMA3/SSE4.1 declines every call but still pays for the hook's entry tests. That cost is unmeasured, but the hooks-in, switch-off run was within the spread. The kernels' writes feed the GPU mirror's write marks. The combined run saw
mkw_vk capture copyrise by 0.009 to 0.017 cores (+10 to 18 %), with no attribution yet, and this head now copies the lifted marking groups. That rise belongs in this PR's own measurement. Memory: the palette scratch is now a 48 KiB_Thread_local, plus the curves' 10.5 KiBAnimCurvesPlan, and that TLS is paid by every thread in the process, not only animation threads (see Suggestions). Build: the lifted code of 5 functions changes (the lift cache keys onoot_patches.py), two host files are added, andMARK_BITMAPnow goes on every host compile. Only files that useA64_MARKbehave differently, which on main means onlyhost/oot_anim.c, but the flag change rebuilds every host object once.Switches:
HOS_NATIVE_ANIM(new,kill, on by default;=0gives main's lifted code,checkcompares). On is the right default for a change whose exactness is this well tested (offline Unicorn comparisons against the game's own code, 0 mismatches, with broken copies caught; 0 different in the in-game check run at an older head), and the standards say not to ship a switch off just because it is new. Its own measurement still has to confirm on. If that run shows no gain past noise, the answer is to remove the hooks, not to turn the default off. Theswitches.defrow matches the read (env_on_or(…, 1); anything starting withcmeans check).Reviewed:
b17bedef8bagainstb62932a960(main@origin, the PR's own base, no rebase needed). Read in full:host/anim_kernels.c,host/anim_kernels.h,host/oot_anim.c, thenx2/oot_patches.pyandnx2/build.pychanges, thegpu/vk/switches.defrow,tests/anim_test_support.py,tests/test_mark_bitmap_host.py. Skimmed for what they run:tests/test_anim_kernels.py,tests/test_oot_anim.py. They compile local fixtures in temp dirs and download or delete nothing outside them. I did not check the kernels' operation order against the game's instructions or the lifted text off_81500200(which registers follow the palette label); for those the PR's offline and in-game check runs are the evidence. Nothing run (a code review).Fixed in this review: nothing pushed (the push to the head branch was refused here). Both fixes are below as suggestions with their diffs.
Checked and fine:
anim_kernels.c:763); the s16 search subtracts unsigned (:433); the palette scratch no longer leaks (oot_anim.c:280); the fixtures check CPU support at run time (tests/anim_test_support.py); and the default is now on.anim_bone_curveschecks the whole value span (mem(ra, rn)) and the cache records before it accepts, sohos_guest_rangein the store loop can't return NULL.Reads), and values sharing bytes are written in the game's order, so the final bytes are the game's.cvttss_si64; the table index is bits 24 to 31 (at most entry 255 of 4096 bytes); the fraction conversion is exact.rdcovers nk + 1), and theidx + 2neighbour stays at or below nk.HOS_NATIVE_ANIM=checkisn't read as off (env_value_offdoesn't take it), so check mode does run.patch_anim/patch_anim_placesare idempotent and declare before use;report()warns when a routine isn't hooked exactly once.Blocking (to change before merge)
host/anim_kernels.csays it is "Written from the game's instructions (main+0x14d6c60 ...)" (line 2), and the code follows that disassembly rather than the behaviour::98(main+0x14d6c88..0x14d6d18),:117,:141,:178,:212,:237;:117("the game's names: si0 s3, co0 s1, si1 s5, co1 s2, si2 s16, co2 s0") and:124(r17, r18, r4, r0);search_intat:398-448(w9,w12,w13,w14,w16;:412"(b.hs / b.ge …)"), andsearch_f32at:478and:514("(b.pl)");:165(ORN),:247(FRINTN),:260(FMLS),oot_anim.c:151(SMADDL).The blends, rotation rows and palette are vectorised, so they aren't one C statement per Arm instruction. The searches come close to that, and all of it is derived from the dump by the header's own account. The maths underneath is public and standard: a sine-table lookup with linear steps, Euler and quaternion to rotation matrix, cubic Hermite segments, a binary/linear key search, and a matrix palette. What is needed is either a rewrite from that behaviour (names from meaning, no register names, address ranges or instruction-by-instruction comments, the operation order stated as a fact the offline comparisons check), or a maintainer's ruling that a bit-exact reimplementation like this is acceptable. The same question was raised on sibling 1911. The license box in the checklist is ticked, and it can't be ticked as things stand.
Suggestions (the author may take or leave)
host/anim_kernels.c:357(BeanBot's point from1607f1f0, still open):table_fnreads only the pointer of a (pointer, adjustment) entry. The game's call reads both, so a known function with a nonzero adjustment, or a virtual entry, is taken while the game would call it with a movedthis. The game's static tables have zero there, so this only hardens the kernel. It only adds a decline, the fixtures' tables are zeroed so the tests still hold, and it records the 16 bytes as read for the overlap test. The commit I made (not pushed):host/oot_anim.c:228(nit): the comment "none lands on another's, or the kernel declined" isn't what the kernel checks. Values may share an offset (the check code'slasthandles exactly that). Better: "no value lands on a record or on anything the routine reads, or the kernel declined; values may share bytes, and then the later one's stay, as in the game".host/oot_anim.c:211-222: check mode compares the curve values only where offsets are equal. Two values that partly overlap (offsets 8 and 10) report a false DIFFERENT. That is a false alarm, never a miss. Comparing the final byte image would fix it.host/oot_anim.c:171-180, 260-268: check mode compares bytes, not FPSR. Saving FPSR before the lifted call and comparing it after would make the in-game check cover the "raises no flag but IXC" promise, which today rests only on the offline runs.host/oot_anim.c:280and:202: about 59 KiB of_Thread_localis allocated for every thread in the process, including renderer, audio and driver threads. A lazily allocated buffer for each executor thread, or stack scratch on the executor threads (the curves'Readsis already about 8 KiB on the stack), would keep it on the threads that animate. The new run can show whether it matters.=0and unset, interleaved, several runs; CPU at the 60 cap per thread (executors andcapture copy), uncapped average, 1 % lows and frame times; on this PC and on Linux/AMD. Ask the Test Farm again for the current head.Testing: At this head: none in the game; CI has run only the light jobs. "Guide screenshots" is failing and "PR description" was cancelled, and neither touches this diff. The Python source checks were skipped. Earlier evidence: the author's Windows / RTX 3090 check run at 7a4ae874 in a nine-branch tree (0 different, about 14.5 M host-answered calls), and the offline Unicorn comparisons. Missing: this head built and played (
check, then on), Linux, an AMD PC, and the measurement above. Any of those holds the merge.Overlaps and merge order: the same
nx2/build.pyMARK_BITMAPchange andtests/test_mark_bitmap_host.pyare in 1898, 1899, 1900, 1902, 1903, 1904 and 1910. Whichever merges first carries it, and the others drop it on rebase. Each sibling also appends a block at the end ofpatch_file()and a row inswitches.def, so they conflict trivially with each other. 1905, 2001 and 2036 touch the same files; 1911 doesn't. None of them hooks the same routines. Any order works; the first one to merge should own the shared bitmap commit.@ -0,0 +1,807 @@/* (longshot) host/anim_kernels.c: native kernels for the game's skeletal animation. What each promises and the floatrules they share: anim_kernels.h. Written from the game's instructions (main+0x14d6c60 ...), not from any source.Licensing: by this header, the kernels are written from the game's instructions. CONTRIBUTING.md rules out decompiled game code. Rewrite them from the behaviour (standard maths, names from meaning), or get a maintainer's ruling; see the summary.
@ -0,0 +114,4 @@_mm_set1_ps(1.0f / 16777216.0f));const __m128 CO = fma4(&k, E2, F, E0); /* (co0, co1, co2, 0) */const __m128 SI = fma4(&k, E3, F, E1); /* (si0, si1, si2, 0) *//* the rows (main+0x14d6cf0..0x14d6d50; the game's names: si0 s3, co0 s1, si1 s5, co1 s2, si2 s16, co2 s0):The game's register allocation (s3, s1, s5, ...) is used as the variable map here. That is the disassembly, not the behaviour.
@ -0,0 +358,4 @@static inline uint64_t table_fn(AnimMem mem, Reads *r, uint64_t slot, uint64_t off) {const uint8_t *s = rd(mem, r, slot, 8);if (!s) return 0;const uint8_t *e = rd(mem, r, u64at(s) + off, 8);Suggestion: the entry is (pointer, adjustment) and the game's call reads both. Read 16 bytes and decline a nonzero adjustment: return e && !u64at(e + 8) ? u64at(e) : 0; It only adds a decline, and the fixtures' zeroed tables still pass.
@ -0,0 +409,4 @@const int32_t idx = i32at(r + 8);if (idx < 0 || (uint32_t)idx > nk) return 0;const int32_t w16 = E(idx);if (!LE(w16, w9) || w16 == w9) { /* (b.hs / b.ge: the key at idx is at or past the frame: the one before?) */This search uses the game's registers as variable names (w9, w12, w13, w16) and its branches (b.hs / b.ge) as conditions: a transcription of the routine.
@ -0,0 +225,4 @@return 1; /* (the lifted routine ran: its result stays) */}if (!took) return anim_count(s, WHY_INPUT), 0;/* (the game's writes, in its order: a curve's record, then its value; none lands on another's, or the kernel declined) */Nit: values may share bytes (the check above handles equal offsets). Say: no value lands on a record or on anything read, or the kernel declined; where values share bytes, the later one's stay, as in the game.
@ -0,0 +277,4 @@/* f_81500200's loops. A thread's own scratch for the palette (1,024 matrices; more is left to the lifted loops), and incheck mode what the kernel made, compared at the label after the loops with what they made */#define PALETTE_MAX 1024static _Thread_local uint8_t palette_scratch[PALETTE_MAX * 48];About 59 KiB of TLS (this and the curves' plan) is allocated for every thread in the process, not only the executors. Consider lazy scratch for each executor thread, or stack scratch.
View command line instructions
Checkout
From your project repository, check out a new branch and test the changes.