dolphin-emu.org - Last entries

Dolphin Progress Report: Release 2407 and 2409

2024-09-04T16:35:36+00:00

After an exciting round of feature articles, it's Progress Report time once again! However, a lot has changed. Dolphin has finally left the 5.0 era behind, and has entered the Release Era. Not only did we get our first release in eight years, but we also established a commitment to continuous releases going forward.

For the Reports, things will be more or less the same, but with a few changes.

Progress Reports are now also release changelogs. We'll be going over the notable additions and changes between each release in every Progress Report going forward, rather than within a range of dates. As such, the name of the Reports will reflect the release accompanying it - if you want the new features, just update to the version at the top or higher and you'll have them! (However, since 2407 had a release article without a changelog, this Report will be covering the changes in both Release 2407 and Release 2409.)

That also means that the next release is happening right now! Accompanying this report is Dolphin 2409. It is now rolling out via our updater, and is available for download here on our website.

But there was also another feature article since our last Report. Dolphin now has RetroAchievements support!

For those waiting for it to show up in a release build, the wait is now over. Throughout the past couple of months, we've ironed out one major issue alongside many smaller issues with RetroAchievements. The first iteration of RetroAchievements in a release build is stable, but not all that flashy. The groundwork is there for future improvements, but many features and options are yet to be finished. As well, Android support is still deadlocked with a few issues. Please pardon our progress!

We have a bunch of cool statistics from the RetroAchievements team regarding the launch, however, we need to get on with the Report! So just click this handy link to be taken to the bottom of the Report if you'd like to read more!

But before we get to the Notable Changes, we have a couple of things to cover.

Google Play Update Delay¶

Last month, we got a surprise email from Google Play saying that Dolphin doesn't comply with their policies because it "installs, but doesn't load". We have gotten emails like this before regarding Android TV, presumably because someone at Google tried to install Dolphin on one out of the vast majority of Android TV devices that don't meet Dolphin's hardware requirements, but this is the first time we've gotten a rejection for Android as a whole. Seeing as Dolphin generally does load correctly on devices that are able to install it, we're not quite sure what happened here.

What does this mean for Dolphin? Dolphin is still available on Google Play, but the next update we release has to be manually checked by Google before it becomes available to users. Because of this, it will take longer than normal for the 2409 release to show up on Google Play, but any updates after that should be smooth sailing again. If you're impatient and want the latest version of Dolphin right now, it's available on this website as always!

Visual Studio Twenty-Twenty-Woes¶

During the rollout of the latest release, a lot of people updated Dolphin for the first time in a while! But for some of our Windows users, when they fired up Dolphin 2407 for the first time they were met with a silent crash. They reached out to us, and the support vanguards on our Discord quickly found a solution - reinstalling the 64-bit Microsoft Visual C++ redistributable for Visual Studio 2022 got Dolphin working for them once again.

We're not entirely sure why exactly this happened. But we have a theory.

The Visual C++ 2022 Redistributable is a runtime library that contains everything needed to run programs compiled with Microsoft Visual Studio 2022. However, Visual Studio 2022 is not static: there are many subversions, and it gets regular updates. These updates should be backwards compatible with any other version of Visual Studio 2022. It would be madness to make a change to Visual Studio 2022 that breaks compatibility with Visual Studio 2022's own runtime libraries. However, Microsoft did exactly that.

In Visual Studio 2022 v17.10.0, Microsoft made a non-backwards compatible change to std::mutex::lock. This was reported to Microsoft, however, the issue report was marked as "Closed - Not a Bug". Apparently this was intended!

This puts us, as an application that uses Visual Studio, into a weird place. We set up an automated process to update our Visual Studio builder to new subversions as they come out, confident that it will never break anything. It's just subversions. So we have told our Windows users that all they need to run Dolphin is the Visual C++ 2022 Redistributable, confident that it would work. However, Visual Studio automatically utilized the new version of std::mutex::lock when compiling our Windows builds. If a user is running an older version of the Visual C++ 2022 Redistributable before that new version of std::mutex::lock was implemented, they may download and run our program and see a silent crash. And of course, if we ask them if they are using the Visual C++ 2022 runtime, they'll say yes, because they have it installed.

According to Microsoft, this is our problem. Their expectation is for applications to be distributed with installers that will include the redistributable and install it with the app if required. However, they hand out the redistributable to users precisely for applications like us that ship without an installer. It's not like what we're doing is novel. And perhaps Microsoft should have made it fail in a way that communicates to the user that they need to update the redistributable, instead of just crashing silently? Or perhaps just include the Visual C++ 2022 runtime libraries in Windows Update so every user is guaranteed to have the latest version and applications don't even need to worry about it?

...Anyway, unfortunately, we don't have a great solution for this issue. We could disable our automated update process for our Visual Studio builder, but there are security benefits to keeping it, so this is something we'd rather not do. For now, all we can tell our Windows users is that if you run a new version of Dolphin and encounter a crash, redownload and reinstall Visual C++ 2022 Redistributable. As always, we have a link to the redistributable on our download page.

On a happier note, it's time for our Notable Changes!

Notable Changes¶

All of the changes below are available in Release 2409.

5.0-21462 - Windows: Remove rounded corners on emulation render window by Filoppi¶

When Windows 11 released in late 2021, it brought the first major visual overhaul to Windows since Windows Phone from 2010. Gone were the sharp edges, bold colours, and dense squares of the Live Tile era, and in their place were soft tones, spacious design, and friendly round edges.

However, as part of this new aesthetic, Windows 11 applies round edges everywhere, even to game windows! Pixels that your computer spent your hard-earned money rendering are now hidden in windowed mode by default.

At 200% UI scale, Windows 11's rounded corners obscure 112 pixels! With an 8x native window, 0.0005% of your pixels cannot be viewed! What?!

This was unacceptable!

Recognizing this travesty, Filoppi came to the rescue and saved our pixels. By configuring DWM_WINDOW_CORNER_PREFERENCE in our Windows builds, all pixels that Dolphin renders (on Windows 11 and in windowed mode) are now once again free to be seen by our illustrious eyeballs.

Now Windows 11 users in windowed mode can savour every single pixel of this beloved masterpiece.

If only such relief could be bestowed upon our macOS users as well...

A few years ago we introduced our custom balloon tooltips. Rather than have a large description area permanently taking up space or a terrible native tooltip defined by the OS, we created our own custom tooltips that gave us the best of both worlds.

Rather than taking up all this space all the time...

Modern tooltips let us only display it when required!

They have been serving us well since. However, after they were rolled out for the graphics area of our config, they haven't really been touched since then. Now that's changing, and our Balloon Tooltips are finally getting some much needed love and a wider rollout!

First is 5.0-21123, which reworked how they are drawn to resolve many longstanding quibbles with the tooltips.

The corners on the tooltips have always been a bit.. off.

Now they are much improved!

Next is 5.0-21635, which added tooltips to the Interface tab of Config.

And finally 2407-130, which rolls out our tooltips to the General tab of Config!

Dentomologist is still chipping away at the tooltips, so expect them to continue to improve and be applied to more windows over time!

2407-103 - Cached Interpreter 2.0 by mitaclaw¶

After the merge of "Cached Interpreter 2.0", we've seen some misinformation floating around emulation communities regarding what the cached interpreter is and what this change has brought. So for the Progress Report, we felt it was prudent to take a deep dive, and properly explain a bunch of concepts we've been putting off for years now. Strap in everyone, we're going deep!

The primary task of CPU emulation is translation: we take code that was originally designed for a specific type of CPU and translate it into something that a different type of CPU can understand. This is not free. Even ignoring the work involved in the act of translating in and of itself (more on that later), having to account for hardware differences means that the resulting translated code will usually be many times larger and more complex than the original code was on the original hardware. As such, there are many different approaches to CPU emulation.

Interpretation is the most basic and literal CPU translation method. An interpreter decodes each individual instruction from the emulated architecture (guest), then translates that into the instructions (plural) that allow the host to perform the same work. And yes, it translates one instruction at a time. This is extremely accurate (able to preserve all nuance) and very straightforward, making interpreters the perfect entry point for most emulators and a fallback for other translation methods. However, interpreters are so straightforward that they have barely any wiggle-room for optimization. Interpreters will always be costly.

Recompilation gives us that wiggle-room. By translating the code in blocks rather than per instruction, recompilers can peek into what the code is doing and reimplement troublesome code in ways that are faster for the host hardware. However, reimplementation often causes inaccuracy, and correcting for that without sacrificing speed leads to ballooning complexity. Making a recompiler both fast and accurate can easily take thousands of hours from passionate engineers.

There are many different types of recompilers, but we're just going to focus on the primary recompiler type that Dolphin uses: JITs.

Just-In-Time Recompilation (JIT) recompiles small blocks of code while the program is running. A JIT will fetch blocks of code from the program, analyze and reimplement as much as it can, then pass the JITed code to the host system to be processed and ready just before the program needs to consume those blocks.

"Just-In-Time" is literal.

This is an accurate representation of how JITs work.

The live analysis that JITs perform is overhead. While modern JITs will mitigate this somewhat by caching JITed code blocks, the analysis is still work, which some other recompilation techniques avoid. However, JITs have many benefits. By recompiling blocks of code while the program is running, JITs are able to adapt to whatever the program is doing and don't need to rely on assumptions. This allows for maximum optimization potential, even in self-modifying programs!

With that, we've covered the two most common CPU emulation techniques. Generally, there is nothing inbetween these two options. Emulator authors make an interpreter first, and use it as a reference for building a recompiler. And that's it. Recompilers are so much faster than interpreters that making an interpreter faster is largely irrelevant.

There are several reasons for this. For example, interpreters can't place guest registers into the host registers, so any time the emulated CPU wants to read its registers, an interpreter has to fetch the registers' contents from host system memory, which is two orders of magnitude slower. Also, for Dolphin, our interpreter has the MMU enabled at all times, and the constant memory manipulation is even slower in the interpreter than it is for a JIT!

However, what slows down interpreters the most is branching.

In computer science, a branch is the act of diverging from the current flow of instructions. If a CPU is executing instructions sequentially, it can process them very very fast. But if an unpredictable branch occurs, the CPU will need to stop everything, flush all its pipelines, and spend the next 10-20 cycles building them back up again before it can resume processing. Branching is one of the most expensive low level operations in computing! As such, modern CPUs do everything they possibly can to improve branch performance, with branch prediction and speculative branch execution trying to get ahead of any branches and keep the pipelines flowing. These features are so important that improved branch prediction is one of the primary reasons why a 2024 CPU core at 4ghz is faster than a 2004 CPU core at 4ghz. It's that significant.

By operating on each instruction from the guest, one at a time, an interpreter will need to branch very frequently - several times for even a single instruction. And these branches are usually unpredictable, directly hurting what makes modern CPUs fast. With all factors combined and in a worst case scenario, a single instruction from the guest could take over a hundred cycles for our interpreter to decode! This occurs millions of times per second, thrashing our host CPU.

Interpreters are simple, straightforward, and readable, but they are fundamentally inefficient. A recompiler will always be faster, so there is little incentive to make an interpreter faster. Except, perhaps, for fun.

Nine years ago, degasus had a fun idea. How fast could an interpreter be made (while still being an interpreter) if we applied a bunch of ideas from JITs? The result of this little experiment was the Cached Interpreter.

With a JIT, code is collected into blocks and recompiled into host-specific machine code all together. This allows the JIT to reimplement some of the code to be faster for the host, but also allows the JIT to cache these JITed code blocks, so that any time code is reused, the JIT will just jump to the cache and skip the analysis for a speedup.

Dolphin's Cached Interpreter borrows this idea. Code is collected into blocks exactly like a JIT. However, rather than recompile it into JITed machine code, which is specific to the host and may be reimplemented, the code block is instead translated into an intermediate representation - code which stores the decoded instructions as "commands" that can be compiled into machine code that the host CPU can run.

This benefits our Cached Interpreter in many ways. Just like a JIT, the code blocks can be cached. Any time code reappears, the Cached Interpreter can just reuse the already decoded version in the cache, skipping the decode and all its associated branching. The act of interpreting in blocks rather than per instruction also reduces branching outright, down to roughly one branch per command, and makes branches more predictable too. This also reduces the cost of fetching instructions through the MMU, and brings several other benefits from the JIT, such as Idle Skipping. *

All combined, the Cached Interpreter was over twice as fast as our interpreter when it released! However, it was still an order of magnitude slower than our JITs. For most users, it was more or less irrelevant. However, the Cached Interpreter has found its niches. As it is still an interpreter, it retains the impeccable accuracy that interpreters provide, as well as the ability to run on any architecture - it's our interpreter, but faster. As such, it has become a useful tool for testing and JIT development. Plus, in situations where JIT recompilers are unavailable, the substantial speedup versus the standard interpreter is always welcome.

But what if the Cached Interpreter could be taken further?

Fast forward to 2024, and mitaclaw and Sam-Belliveau got into a competition to see just how optimized the Cached Interpreter could be. Eventually they merged their efforts, in what mitaclaw dubbed Cached Interpreter 2.0.

This change brought many optimizations to the Cached Interpreter, but the biggest change by far was variable sized commands. Previously, the commands inside the Cached Interpreter's intermediate representation had a fixed size, but mitaclaw and Sam-Belliveau realized that by allowing the commands to be any size, the most common bookkeeping commands could be bundled together into a single command. This significantly reduces the number of bookkeeping commands in total, further reducing the amount of branching in our Cached Interpreter.

Just how big of an impact could these optimizations have? Let's get to the numbers!

With a 10 to 25% uplift, the Cached Interpreter is better than ever! It's also now 3 to 4 times faster than the interpreter, and in games with lots of idle loops to skip, such as Cave Story, Cached Interpreter leaves our interpreter in the dust. However, our JITs are still MUCH faster in every scenario, so its role in Dolphin is unchanged. The Cached Interpreter still cannot serve as a JIT alternative. And according to mitaclaw, further optimizations had a negligible impact on its performance. Dolphin's Cached Interpreter will likely not see another significant performance bump again.

Nevertheless, for the niches where the Cached Interpreter thrives, it is now faster than it has ever been.

2407-165 - macOS: Embed the Updater into DolphinQt's app bundle by OatmealDome¶

One of the best things about macOS is application bundles.

On Windows, programs are largely intended to bring their own dependencies. However, each program will need many different files in many different and bizarre places, so much so that it is standard to ship a dedicated program whose only purpose is to place or remove all of the disparate files an application needs to function. If something goes wrong with this process, good luck.

Linux, on the other hand, works more like code - dependencies are separate from the program and should be linked, not duplicated. However, dependencies will need to be installed along with the application, so Linux has package managers to install applications and any dependencies that are needed. While this is certainly better than the backwards-compatibility mess that is Windows, installing a single application in Linux still results in installing lots of things in lots of places.

macOS is different. It has something called application bundles. All apps on macOS (with the exception of command-line tools and scripts) are distributed in the bundle format. Application bundles are really just regular folders that follow a very specific structure with their contents. They allow all of an application's files and dependencies to be grouped together in a single folder, nice and neat. To the user, however, the bundle is shown as a single icon and they never see or know about all of the files inside. This allows for one of the best things about bundles - the process of installing or uninstalling an app is just... drag and drop. That's it. And to run the application, just double-click the bundle as if it were the application itself.

This is the best!

However, for the past several years Dolphin on macOS has shipped not one, but two bundles - Dolphin, and Dolphin Updater. The updater didn't do anything if you double-clicked it, and would just give an error; it was intended to be used only by Dolphin itself. Unfortunately, this has occasionally caused confusion with users. After all, the majority of macOS apps are distributed as a single bundle. Why does Dolphin have two?

It's just not the same.

Fortunately, this has now been fixed. When creating the main Dolphin bundle during a build, we now insert the updater bundle inside of it! Whenever we need to perform a Dolphin update, we just load the updater bundle from within the main Dolphin bundle, create a copy of it in a separate temporary location, and run that. With this change, the user only ever sees one bundle when installing Dolphin for the first time. Glorious single drag and drop installation has been achieved!

Hurray!

2407-173 removes all remnants of the separate updater bundle if any are present. If you have previously installed both Dolphin and the updater to your Applications folder, by the time you are reading this the separate Dolphin Updater will likely already be gone. If not, update and it will be removed.

Note: A bug was fixed in 2407-111 which caused the updater to crash on startup on some Macs. If you are using an older build of Dolphin, you may need to update your copy of Dolphin manually first.

Zelda HLE Pikmin Fixes - 2407-177 and 2407-225 by flacs¶

Audio emulation has gone through an interesting transformation throughout the many eras of Dolphin. In the release era, HLE (High Level Emulation) audio is pretty much universally used for almost everything. Over the course of time, almost every gap in accuracy between HLE and the more in-depth LLE (Low-Level Emulation) has been closed up. Infamous HLE audio bugs like the screeching in Star Wars: Rogue Squadron games? Solved. The Grand Star hang in Super Mario Galaxy? Long gone.

It has been a massive struggle to get HLE audio to this point. Back in the old days, you had a choice to make - potentially broken audio (or even no audio in some games!) with HLE, or deal with the massive performance demand that came with getting proper audio using LLE. This all started to change back in the 3.5 era, when massive rewrites hit Dolphin's audio code.

Why does this all matter? Well, users didn't like LLE audio, and these massive rewrites to HLE audio had tons of benefits. The problem with HLE audio is that Dolphin has to correctly handle the functions of every revision of every microcode in order for things to work. Pikmin and Pikmin 2 use what we call the "Zelda Microcode". This microcode is used in games like the Zelda games (except Skyward Sword), the Super Mario games and Luigi's Mansion.

The problem with this is that pretty much every game uses a different version of the microcode. This meant that in order to emulate each game, you had to figure out what functions they supported, and how to emulate them correctly. For example, all of the microcode revisions will have functions to control volume, but earlier microcodes might have bugs that need to be emulated, later microcodes might have additional features, like controlling volume individually for different things. Apply this to everything, and it becomes apparent how much of a pain in the rear this can be.

In order to get these massive rewrites merged, support for each individual microcode wasn't necessarily perfect. Upon testing, the games sounded mostly correct, and the various problems of old-HLE audio were fixed. However, there were minor issues spread across the various games. Originally, New-Zelda-HLE had issues with the volume of echoes in Mario Kart: Double Dash. This was a known issue when it was merged, but was deemed acceptable due to all the other improvements.

The only difference between that and Pikmin and Pikmin 2 is that their small issues seemed like they were never going to be addressed. In fact, most users didn't even realize there was a problem. They were by and large playable, and unless you played the game recently on console, you wouldn't know that some menu sounds were the wrong pitch, or there were missing sounds for puffs of smoke in the opening cutscene. Thankfully, when New-Zelda-HLE was merged, the issues we did discover were archived, and flacs saw them and investigated them while looking for more audio issues to fix.

Your browser does not support the audio element.

The incorrect pitch on the save sound has bothered musically-inclined users for years!

Your browser does not support the audio element.

Oh sweet relief.

Your browser does not support the audio element.

The explosions here are too quiet, getting lost in the engine rumble.

Your browser does not support the audio element.

Emulated properly, they pop and snap as explosions should.

These may seem minor, but back in the day there were hundreds of issues like these due to HLE audio's imperfect emulation of the microcode. It seems almost surreal that, in most cases, HLE audio and LLE audio are now indistinguishable.

2407-228 - VideoCommon: Force Display List Alignment by flacs¶

Once upon a time, Dolphin bugs were obvious: a simple screenshot was all it took to convey just how broken Dolphin was in a particular title. Grey Zelda, Spider-man as a flying box, uwu Kirby, Batman as a flying crotch, on and on. However, once Dolphin's fundamental inaccuracies were resolved in the 3.5 and 4.0 eras, that largely became a thing of the past. Today, we have to use fifologs and automation to catch changes, and carefully pixel-peep against console to verify that something is in fact actually incorrect.

Wallace and Gromit in Project Zoo bucks this trend. The game's shadows looked fairly good on console, but in Dolphin? They could ƒ^&%ing explode.

Well, this is a fine how do you do, isn't it, Gromit?
_{PHOTOSENSITIVITY WARNING. Click to play.}

We had no idea why the shadows in this fairly obscure game would sometimes fail so catastrophically, but something was clearly very wrong, so in 2013 we added a patch to remove these shadows from the game. It was an extreme solution, but the game had an extreme problem, so we did what we could to at least make the game playable. It was certainly better than the video above. But as time passed, the developers who investigated the problem moved on, and these troublesome shadows slowly faded from memory...

Ten years later, flacs happened to notice that Project Zoo's shadows were still broken, and looked into the issue. They soon spotted something suspicious: the game's display list (a group of GPU commands stored for later execution) wasn't aligned. Rather than prevaricate about the bush, flacs went straight to hardware testing and quickly adapted the triangle test homebrew to use display lists.

Turns out that hunch was spot on target! Wallace and Gromit in Project Zoo submits display lists unaligned, and Dolphin was erroneously processing them exactly as they were submitted. The hardware aligns the memory address by dropping its lower bits. So for example, the game would point toward 0x80fc9b04, and Dolphin would start executing from there (getting bad opcodes) when hardware would drop the lowest 5 bits as it was 32-byte aligned and start at 0x80fc9b00. By not forcing alignment, Dolphin thought the game wanted to render random garbage and told the GPU driver to render it, which the GPU driver would try its best to do. Sometimes this only resulted in minor visual bugs, other times it would utterly explode as shown above.

With a very small change to Dolphin, we can now render these shadows just fine, and yet another hardware quirk is being emulated correctly.

While it didn't come in the 4.0 or 5.0 eras, Wallace and Gromit in Project Zoo is finally free from emulation issues. We hope.

2407-236 - Android: Fix and enable input device sensor input by JosJuice¶

Last year, JosJuice rewrote our Android controller input handling from scratch. This rewrite replaced the old Java input handler with a brand new one written in C++ that more closely matched how Dolphin's PC input handlers work. Not only did this clean up some crusty old code with known problems, but it also unlocked dozens of "new" features for our Android users that were previously only in our desktop builds!

However, one very significant feature that was a part for that overhaul last year was disabled when the overhaul eventually landed - sensor input (accelerometers and gyroscopes) from external controllers, a feature available in Android 12 and up. During the final testing of the input rewrite, JosJuice received reports that using controller sensors could make Dolphin crash when navigating between screens. Because their phone was stuck on Android 11, they couldn't test the feature themselves, and decided that rather than hold off the rewrite to address the issue, it was best to just disable external sensors for the time being and continue the rollout without it.

With over a year passed since then, dreamsyntax showed up with not only willingness to investigate the crash, but also the needed hardware. The first step: Finding out why the crash is happening. The reports from a year prior included a stack trace showing where in the code the crash occurred, and JosJuice had used this information to theorize that when Dolphin turned off unused sensors to save battery, Android would start notifying Dolphin about a sensor that Dolphin never had asked to be notified about. dreamsyntax was able to replicate the crash and get a match stack trace, and then managed to take a step beyond the old investigation by figuring out the root cause of the crash. The sensor that Dolphin didn't recognize wasn't actually a new sensor - it was a new object representing the same sensor as before. The cause of the bug was that Dolphin checked if two sensor objects were literally the same object (referential equality) rather than checking if the objects had the same content (structural equality).

With that, it was time for the second step: Properly fixing the issue. dreamsyntax began by making a quick solution to check that their approach was correct, but alas, Dolphin was still crashing! It turned out there was a second crash that nobody had discovered until now because the other crash always happened first! Somewhere within the code of Android itself, a ConcurrentModificationException was being thrown when Dolphin turned sensors off. dreamsyntax couldn't quite make sense of why this was happening, but with all the information he had gathered, JosJuice once again stepped into the picture. They discovered that the cause of the crash was a simple coding mistake in the operating system itself - removing objects from a list while looping through the list - and implemented a workaround for this crash and a proper solution for the earlier crash. Finally, dreamsyntax tested the change to make sure motion controls were now working properly.

With the issues now solved, sensors from external controllers are available for mapping in Dolphin on Android! The sensors in controllers such as the DualShock 4 can now be used to better emulate motion in Dolphin. Keep in mind that the feature only works for controllers your version of Android has sensor support for. If you're using Android 11 or older, sensors aren't supported for any controllers at all.

Last Month's Contributors...¶

Special thanks to all of the contributors that incremented Dolphin 349 commits in the final days of the 5.0 era, and 279 commits after Release 2407!

The First Month of Dolphin RetroAchievements¶

The RetroAchievements team has shared with us a bunch of statistics for the first month of RetroAchievement support in Dolphin! And there's a lot of interesting bits in here. Enjoy!

General Statistics¶

Total Unlocks: 860,290

Total Hardcore Unlocks: 815,944

Total Points Earned: 5,864,862

Total Hardcore Points Earned: 5,558,151

Total Sessions: 284,432

Top Ten Games with the Most Players¶

Game	Players
Super Mario Sunshine	2532
Super Smash Bros. Melee	2230
Mario Kart: Double Dash!!	1908
Luigi's Mansion	1148
Legend of Zelda, The: The Wind Waker	1084
WarioWare, Inc.: Mega Party Games!	946
Kirby Air Ride	893
Legend of Zelda, The: Twilight Princess	888
Animal Crossing	847
Pikmin	758

Top Ten Most Mastered Games¶

Game	Masteries
Super Mario Sunshine	284
Piglet's Big Game	195
Magical Mirror Starring Mickey Mouse	172
Pokemon Channel	163
~Hack~ Samus Goes to the Fridge to Get a Glass of Milk 3D	152
Winnie the Pooh's Rumbly Tumbly Adventure	144
~Hack~ Luigi's Mansion Beta Restoration	140
Legend of Zelda, The: The Wind Waker	120
Wario World	112
WarioWare, Inc.: Mega Party Games!	101

Top Ten Most Beaten Games¶

Game	Times Beaten
Super Mario Sunshine	626
WarioWare, Inc.: Mega Party Games!	551
Luigi's Mansion	505
Super Smash Bros. Melee	339
Dance Dance Revolution: Mario Mix	305
Pokemon Channel	297
Mario Kart: Double Dash!!	297
Pikmin	273
Legend of Zelda, The: The Wind Waker	243
Naruto: Clash of Ninja	232

Unlocked: RetroAchievements Come to Dolphin

2024-07-15T20:54:59+00:00

Dolphin's users are always looking for new ways to play their favorite games. And when a project called "RetroAchievements" started gaining popularity for adding achievements into retro games, users started wondering if Dolphin would ever add support for the project. Unfortunately for them, Dolphin isn't a retro game emulator. We're a modern emulator that emulates two recent Nintendo consoles! RetroAchievements wouldn't make sense-

Ah shi-

RetroAchievements Dolphin Launch Announcement!¶

That's right, it's finally here. RetroAchievements integration has come to Dolphin. Now you can play some of your favorite GameCube games with full achievement sets that are automatically recorded to your RetroAchievements account. Much like modern "achievements" or "trophies", RetroAchievements sets essentially amount to a list of tasks and goals that may go above and beyond simply beating the game.

For their GameCube launch day, they've gone all out, with over 100 different titles on launch. This ranges from some of the most popular GameCube games, to obscure gems, terrible games, and even a few game mods!

The Legend of Zelda: The Wind Waker
Final Fantasy Crystal Chronicles
Super Mario Sunshine
Harvest Moon: A Wonderful Life
Super Smash Bros. Melee
Baten Kaitos Origins
Kirby Air Ride
Star Fox Assault
Metal Gear Solid: The Twin Snakes
Mario Golf: Toadstool Tour
Luigi's Mansion
Metroid Prime
Star Wars: Rogue Squadron II: Rogue Leader

For a full list of games, check out the RetroAchievements GameCube Library with more on their way soon! Want to get hunting right away? RetroAchievements integration is available in Dolphin 2407-68 and newer, which can be found on our downloads page. This will give us a chance to work out some of the kinks before it reaches most of our users in the next release update.

Activating RetroAchievements¶

By default, RetroAchievements are disabled in Dolphin. To activate integration, you have to log into your RetroAchievements.org account in Dolphin's new "Achievements" window that's located under the "Tools" dropdown. If you don't have one, you can create a free account on their website.

Logging in, tracking, and settings are all contained within one window!

Once you're logged in and RetroAchievements Integration is enabled, the next time you load a game with RetroAchievements support, you'll get access to achievements and much more. And that's basically everything you need to know. But, if you're interested in what RetroAchievements can do and how it works, continue reading as we go into more detail.

Achievement Lifestyle¶

No matter how you play, RetroAchievements can fit into your style. You can passively gather achievements just by playing through the game, with every set guaranteed to have progression achievements that follow along with the main story or goals of the game. If you do beat the game, the game will be marked as beaten on your RetroAchievements account.

On the other hand, you could also take a more active style of Achievement hunting. At any time, you can visit the gamepage on retroachievements.org or through the Achievements menu in Dolphin on the Progress Tab. There you can see what achievements you have, which ones you're missing, and how to obtain any of the achievements. This can be an excellent way to find new challenges in a game you've played through many times before.

Some achievement sets might be daunting.

Note that in order to get all of the achievements in some games, you might need to start over with a fresh savefile. Some games, like Luigi's Mansion have multiple save slots so this isn't really a problem. But games like 1080 Avalanche and Super Smash Bros. Melee require starting from a fresh save for many achievements.

Don't worry, though! You can always create a new savefolder for Dolphin, backup saves, or use a new memory card file if you want to start fresh without losing savedata.

Finding the Right Challenge¶

Each RetroAchievement has a score assigned to it. When you collect that achievement, the score of that achievement gets added to your account. Achievements score anywhere from 1 point to 100 points. Single point achievements tend to be easy, sometimes are things that you can't skip, or they might be some kind of funny easter egg. On the other hand, 100 point achievements are some of the most daunting tasks imaginable within that game and can take serious dedication and practice to accomplish. Make sure to pay attention to how many points an Achievement is when picking one to hunt down. You might bite off more than you can chew!

The game you play also shapes the kinds of achievements you get. Games like Harvest Moon: A Wonderful Life will challenge your time management and min/maxxing skills. Meanwhile, F-Zero GX will be mostly about going fast.

F-Zero GX is home to a lot of high octane achievements, and getting them will be no easy feat.

Some achievements will actively let you know when they're available. These kinds of achievements are called "Challenge Achievements" and are often achievements that can be failed without actually losing in the game. When you've fulfilled the necessary conditions to trigger a challenge, a small challenge icon will show up in the bottom right. For more information, check the Progress tab of the Achievements window to get a full rundown on the challenge.

Active challenges jump to the top of the achievements window and show a small icon in the lower right of the game window to denote it is active.

Sometimes there might be multiple challenges going at once.

Old School Mentality¶

Dolphin provides a ton of convenience features that can help with getting some tricky achievements. Using savestates and slowdown can turn the greatest of challenges into a cakewalk. But what if you really wanted a grand challenge, and wanted show your friends that you beat it legitimately without any extra assistance? That's where Hardcore mode comes in.

In the RetroAchievements menu, you can enable Hardcore mode and it will lock out those features while you're hunting achievements. This gives a more console-authentic experience that can put you to the ultimate test.

You can achieve any achievement in softcore mode.

But, hardcore mode gives fancy gold borders.

Hardcore mode also enables another RetroAchievements feature: Leaderboards. Leaderboards will automatically record your best times and high scores across various games. What each game measures is up to the developer of the achievement set, but the game will let you know when a leaderboard attempt is active. If you think you're better than all of your friends at Mario Golf: Toadstool Tour, prove it! Are you a time trial demon in Mario Kart: Double Dash!!? Show it.

RetroAchievements will automatically record your times in compatible games!

There are a variety of leaderboards across the plethora of launch titles. No matter what kind of player you are, there's likely a leaderboard or two that'll fit your style. You can take a look at the game pages at retroachievements.org to see the various leaderboards.

A Cooperative Experience¶

With Discord presence support, RetroAchievements can also give live updates of your current position in a game directly to discord. Use this to race friends, or just to show off where you're at in your game. These live updates are context dependant. For instance, in The Legend of Zelda: Twilight Princess RetroAchievements tracks things like chests opened, heart pieces, bugs collected, etc, while in Super Mario Sunshine it keeps track of things like shine count and blue coins.

See your current progress directly in Dolphin through the RetroAchievements window.

Or, show off your progress on discord with Rich Presence support.

If you're a more private gamer or hiding from work, as per usual, the Discord Rich Presence features can be disabled.

Multi-Sets¶

Some achievement sets are designed to be played together! Whether the achievement set itself marks certain achievement lines as multiplayer compatible, or sometimes you'll have an entire set designed around multiplayer. In those cases, you can have multiple people on the same computer work toward the goal, or you can use Dolphin's netplay!

Netplay with GBAs and RetroAchievements? Yep! Final Fantasy Crystal Chronicles has a separate "Multi" set full of multiplayer achievements.

Multiplayer achievement sets test your ability to communicate and cooperate with friends. If you're a solo gamer worried about multiplayer achievements preventing you from getting a game's "Mastery", don't! Any achievements that require multiplayer are moved to a subset that isn't required for game mastery.

Achievement Unlocked - Marrying Two Massive Projects¶

Integrating RetroAchievements with Dolphin was not the smoothest of projects. Given the ancient codebases of these two projects (dating back to 2003 for Dolphin, 2013 for RetroAchievements,) there were a lot of growing pains to get everything to play together nicely. And even through it's functional at this point, there's still a lot of cleanup and maintenance that will have to be done post launch.

One of the things that helped was the PCSX2 implementation of RetroAchievements, which acted as a base for the developers who worked on the Dolphin version of the implementation. As well, their own achievement creation library had to be ported over to work with Dolphin's memory handling.

From there, it's been a massive 18 month journey implementing things to get it ready. Without pushing from those passionate about RetroAchievements support (and them also putting the work in,) this could not have happened. There were a lot of roadblocks and close calls with the implementation, and a lot of concessions in order to make things work. This generated a lot of pull requests that needed review, and there were a lot of difficult decisions to make over what to allow and what needed to be done. Code review stages actually took a significant amount of time, due to some of the difficult problems that had to be tackled with memory access and management.

During this process, a secondary build of Dolphin was being developed that worked with their integrated achievement creation system. That way, while RetroAchievements was implemented into Dolphin builds, teams of achievement creators could get to work on developing the achievement sets you see today. Developing these achievement sets was no easy task - depending on the game, an achievement set could take dozens, if not hundreds of hours of work. GameCube games can dynamically allocate memory, use pointers, swap memory between RAM and ARAM, and in some cases like Star Wars: The Clone Wars, change the Block Address Tables whenever it wants. It all makes for a difficult job that takes a lot of testing.

Your favorite game missing an achievement set? Complete the Jr. dev program for RetroAchievements and become an achievement developer!

Without these builds, developing achievements would have been nearly impossible, and even with these special additions to Dolphin, there were still a lot of headaches. One headache that they learned to avoid very quickly was of Dualcore. While it may lure you in with its promises of performance, the workload for creating achievements made it even more unstable than normal. Thankfully, this only affected the development of achievements; users will be able to utilize Dualcore mode and its speedups without additional worry.

As such, achievements don't cause much of a performance overhead. While there is always a cost to checking memory, we haven't observed any noticeable performance impacts.

The biggest limitation with RetroAchievements in Dolphin actually comes from how we display them. In order to display achievements, the notification system had to be adapted to ImGUI, which is not the ideal solution for their GUI, but it's the solution that we had. Worse yet, because Dolphin doesn't support asynchronous presentation, the framerate that in-game overlays/notifications show up at depends on the actual game's current framerate. This is normally fine in typical gameplay, but if an achievement shows up during as loading screen that has few or no rendered frames, you won't be able to see it in the game window. It's just a case of Dolphin not being designed for this use-case.

Issues like these can be addressed in the future, and we don't think of them as game breaking. As is another omission from this initial launch. Specifically, we didn't target Dolphin on Android. While Dolphin on Android is the same core emulator as its desktop counterpart, there is significant work that would be needed to adapt the RetroAchievements dialogues and settings to Android. Additionally, we ran into some networking issues on Android that are going to require specific attention, and with the desktop release already taking so much effort, we decided it'd be best to hold off. If you're an Android user looking forward to RetroAchievements, don't worry - it will happen. We just can't promise when yet.

Wait! What about Wii?¶

Are the teams planning to do Wii RetroAchievements? Yes, both sides are open to it, and somewhere down the line work will begin. But right now, our focus is on getting GameCube RetroAchievements working, and continuing to address various issues and limitations post launch. Eventually, efforts will shift toward Wii RetroAchievements, but it might be a while.

Congratulations - You've Mastered This Article¶

And that's that! We've gone over all of the major notes for using RetroAchievements in Dolphin. For more information on RetroAchievements, across all consoles, check out their site and documentation for information on supported emulators and various issues.

Starting today, there will be a GameCube launch event, and some of us within the Dolphin team will be attending. This could be your chance to compete against us on the leaderboards, while obtaining a RetroAchievements badge for completing and mastering games.

Special thanks has to go to all of the developers (from both projects!) that put up with the many headaches that came up during the lengthy development process. As well, we'd like to thank the additional volunteers in the RetroAchievements community that worked on the achievement sets for this launch. Without them, there wouldn't be any achievements to, well, achieve! But now that the launch is finished, there's only one thing left to say.

Happy hunting, everyone!

Dolphin Releases Announcement

2024-07-02T07:47:50+00:00

On the 24th of June, 2016, Dolphin 5.0 was released. The product of a long and hard transition period, the fundamental inaccuracies that plagued Dolphin for over a decade had successfully been undone, and Dolphin was now free of its burdens to swim forward into a new era of accuracy and performance.

Eight years have passed since that great release, and we have seen the dividends of that effort time and time again. Dolphin has seen constant updates, with new features and enhancements coming side by side with bug fixes and stability improvements. Users are now able to upgrade without fear, knowing that even in the unlikely event of a bug it will be fixed within hours. And of the thousands of titles that Dolphin can run, the number that do not function can now be counted on one hand!

All of this was achieved without a new release. In fact, Dolphin has been in the 5.0 era longer than any other, and with almost twenty-two thousand commits over the past eight years, the 5.0 era now makes up over half of Dolphin's entire commit history! But users haven't forgotten our past releases. They have been waiting for years, patiently anticipating when our next release may arrive.

That wait ends today.

However, the purpose of our old stable builds is now no longer relevant to Dolphin Emulator. We no longer need a benchmark to compare against or an anchor to ground us. We have grown beyond them. So in leaving the 5.0 era behind, we are also leaving behind that release scheme and all it offered. In exchange, we're not just giving you a release today, but also a commitment to continuous releases from now on. The long drought of Dolphin releases is no more and will never happen again!

Welcome to a new era of Dolphin Emulator - the Release Era!

Announcement¶

We are pleased to announce that Dolphin has adopted a rolling release cycle! Building upon our highly successful "beta builds", we will have a release every few months, with a Progress Report launched alongside as a changelog. These are proper release builds however, with the full infrastructure and support that comes with them. They are tagged as releases in Git, allowing our distribution partners to properly support us and our users. Our new releases can receive hotfixes, so if any issues arises we can release small updates instead of a full on new release. And, of course, every release will advance Dolphin's version number.

However, our new releases are fundamentally different from our prior releases, so we didn't want to just add a number to our last release. As such, we are abandoning the X.0 release numbering and moving to a new date-based versioning scheme!

Accompanying this article is our first rolling release - Dolphin 2407! This release is available for download immediately, for Windows x86-64, Windows ARM64, macOS, and Android from our official website: dolphin-emu.org.

Here are the details of the new rolling release scheme:

The first two digits are the year, and the second two are the month. 2407 codifies a release from July 2024.
All subsequent dev builds after a release will be numbers added on to it. For example, 144 commits after 2409 would result in dev build 2409-144.
Our next release will be 240X. Yes, it will be in just a few months from now!
Hotfix releases will have the addition of a suffix. For example, a single hotfix to Dolphin 2409 would be "Dolphin 2409a".
Beta builds are being replaced by releases. All users in the beta update track will be moved to the new release track.

A New Look!¶

To herald and symbolize this new era, we also have a new logo! MayImilae, the designer of our previous logo and long term Dolphin blog writer and contributor, has refreshed our logo for the modern day!

For comparison, here's our previous logo.

Here is the explanation of the design, in her own words.

Dolphin's 2013 logo was designed at the start of a transition. Dolphin was leaving its buggy past behind and committing to doing it right, even if it meant ripping out tons of working code. So gone was the silly peace sign mario, and in its place I made a sharp, edgy, serious, on-trend logo to symbolize Dolphin's new future as a serious emulator. And yea, that's carried us through all this way! However, Dolphin is more mature now. It's stable, confident and comfortable in its place. So for the refresh, I wanted to return to the original design and make it timeless, but also more fun, more colorful, and make it a little gentler and thicker.

And finally address all the things that were bugging me for ten years.
MayImilae

This new logo has already been rolled out in our system and brands Dolphin 2407! However we couldn't get every little logo replaced before the release, so the few that remain will be cleaned up soon.

The new logo was designed with variation in mind! Expect to see it in many styles and colors.

But why not 6.0?¶

As we leave the 5.0 era behind, we feel the need to address what might have been - 6.0. While we lightly touched on the reasons above, we know that won't be enough for those who waited so long for something that we kind of didn't deliver. However, to explain this properly we're going to need to go in depth, and tell the story of Dolphin's releases.

When Dolphin was a closed source project, beginning in 2003, it benefited from being made by excellent programmers. Code from that era is of the highest quality and has stood the test of time. For example, most of our interpreter has not even been touched in over 15 years! It has been added to, but very little of the interpreter code from that period has been altered. But there was only so much that a handful of quality coders could do in their spare time. It took years for Dolphin to approach even a proof of concept, let alone become an actual working emulator with decent features and game compatibility. So in 2008, the founders of Dolphin decided to enter the wild world of open source.

With the floodgates open, contributions poured in. In just a couple of years, Dolphin became a full blown emulator, with tons of new features and the ability to play most games! But the move to open source was not without its drawbacks. While Dolphin was getting the help of hundreds of new developers, the code quality of the project plummeted. The tools available at the time simply didn't allow for quality development.

Back when Dolphin went open source, modern development platforms like GitHub didn't exist!* There were no pull requests. There was no way to easily review code and an accompanying forum for discussing the changes before they were checked in or merged. Instead, all development was handled through IRC and Google Code, which was more of an issue tracker with a bolted on hosting service than a development platform in the modern sense.

In this era, to submit a change to Dolphin developers would show their change to a developer with commit access in IRC and ask them to merge their patch. This was a form of review, but it was slow, cumbersome, and overwhelming for maintainers. So once a developer was known to the project, a maintainer would give that developer commit access and they could just commit anything without review from that point forward.

Today, this would be considered irresponsible and reckless. But at the time, we had little choice. With terrible tools, difficult to impossible review processes, and a desperate need for contributions, Dolphin flew open the doors and allowed thousands of changes without review.

That decision proved to be highly effective in the short term, and Dolphin exploded in functionality and capability. But code of all quality was being let into the project, both good and bad, and the health of Dolphin's codebase slowly declined. After a few years, Dolphin began to buckle. By 2010, Dolphin was buggy and unstable, and development builds would often break for days at a time! With no access to modern tools, Dolphin needed something to ground itself in the raging sea that was open source in the late aughts.

Dolphin needed an anchor.

And so, Dolphin adopted the Stable Release model. In that release formula, a new Stable Release must have all regressions since the last release resolved, no matter how minor. This would allow releases to serve as a benchmark, a minimum standard that Dolphin would never fall below and would always improve upon with each new release. This meant that no matter how chaotic the development process may be, users knew that if they went from release to release, Dolphin would always be better in every way.

However, Dolphin is a volunteer project, and everyone is committing their free time. To get volunteers to drop their fun projects and work on tedious regression fixes, Dolphin used feature freezes.

During a feature freeze, all merges are halted except bugfixes. Once all of the regressions from the previous release are resolved, Dolphin would launch a Stable Release, and then feature merges would reopen. By holding developers' fun projects hostage, feature freezes coerced developers to contribute to the bug hunt. After all, the more developers pitched in and fixed bugs, the sooner their cool project could get merged into Dolphin! And it worked. Bugs were fixed and Stable Releases were launched. However, feature freezes were miserable and costly. During a freeze, Dolphin's development would stall for months at a time, morale would plummet, new developers were repulsed, and sometimes long-term developers would get tired of it all and just leave.

Of course we hoped to find a better way, and with each Stable Release we tried some variation or alternative to feature freezes. None of them succeeded. After 5.0's feature freeze alternative failed so badly that we had to restart the release process over from scratch, we had had enough, and made a collective decision to put releases away for a while. No one wanted to deal with a feature freeze again.

Fortunately, we have not needed to. The transition to stability that 5.0 crowned, combined with the advent of modern development tools, has completely changed our development process. Now, every change is reviewed and checked before it is merged. Rather than hurry through messy development and then clean up after, cleanliness and stability is our every day! We no longer need to periodically stop everything and clean up our mess! We no longer need Stable Releases!

Theoretically, we could have just... not prepared a release ever again. We could have stayed in the 5.0 era forever! However, there are a lot of benefits to releases - for infrastructure, support, and distribution. We wanted to take advantage of those. But we were not going to do a Stable Release again. So after much deliberation and a lengthy development process, we have adopted a rolling release model.

And to codify just how vastly different our new releases are from our previous ones, we also adopted a new versioning scheme. Gone are the X.0 numbers, and with it, 6.0.

Credits¶

Approximately six hundred people contributed to Dolphin in some manner during the 5.0 era. There are far too many people to list all of them individually in this article, so we're going to call out the groups that have made Dolphin what it is today!

Dolphin would never have gotten to where we are today without the hundreds of developers who have volunteered to make Dolphin better. The 5.0 era saw many long awaited features like Ubershaders, the Unification of VideoCommon, Hybrid XFB, MotionPlus Emulation, the Qt user interface, Bluetooth Passthrough, many new graphics backends, and much much MUCH more! This was only possible because of the tremendous effort of the brilliant engineers who volunteer their time to Dolphin!

The great vanguards of support, our Discord moderators and support staff have been assisting users for years, even before our Discord was official! The sheer quantity of users that our Discord is able to help boggles the mind.

The core pillar of support remains our forum. Filled with over a decade of history and our support veterans, our forum is where our support staff go for support.

Our Wiki team maintains and curates our greatest collective of knowledge for how games perform. Thousands of games are recorded, with thousands of bugs (mostly fixed), workarounds, and game quirks, and tens of thousands of user testing reports!

Dolphin is available in 29 different languages! This is entirely thanks to the members of our translation team, who volunteer their free time to regularly keep our translations up to date.

And of course, this article wouldn't be possible without our blog team! We're not going to praise ourselves beyond that, it's weird.

We will however take a moment to specifically call out those who made this release happen!

delroth championed and planned out our new release scheme, and then reworked our infrastructure to get Dolphin ready for it. He retired before it was all complete, but this release was largely his project, and it would have never happened without him!
OatmealDome picked up where delroth left off, implementing delroth's release proposal and carrying it to the finish line!
Of course Android would require special attention. JosJuice sorted out all of the kinks and got our Android builder ready for Android's first ever Dolphin release!
mbc07 readied our wiki for the biggest release change in its history.
MayImilae commented on the new release plan, with interest. Also she designed the new logo, helped coordinate the launch, and wrote this article.

Dolphin Progress Report Tenth Anniversary Special: February, March, and April 2024

2024-04-30T07:21:16+00:00

In late 2012, Dolphin moved to a brand new website - dolphin-emu.org. With complete control of our own home and infrastructure for the first time, we noticed the accessibility to users that it gave us. Not only did we get a new home, but we also got a platform, one that allowed us to communicate directly to our users! We used it to great effect, explaining big changes to the emulator such as tev_fixes_new, getting ahead of controversy when we removed the popular D3D9 graphics backend, calling out broken drivers, and more! The Dolphin Blog was born!

However, we quickly realized that while single dedicated articles were great for big changes, Dolphin was improving all the time and tons of important and/or interesting changes were being overlooked simply because they weren't "big enough" to warrant a feature article. We needed something that would let us cover the continuing development of the emulator. Something like, a periodical article filled with a collection of notable changes, so we could report on the progress of Dolphin within a set window of time. And after much experimentation, we built a format to fulfill this role, and released the first of its kind to the world on the 30th of April, 2014.

Ten years ago today, the first Dolphin Progress Report was launched! Since then, our blog has exploded in popularity, and tens of thousands of people read every Report! And in that time, we've made 79 Dolphin Progress Reports, with 797 Notable Changes, 54 special sections, and 301,807 words! Thanks for reading!

As the writers of the Dolphin blog, we are proud of what we have accomplished here. We've highlighted tons of cool changes, educated our users (and ourselves!) on how Dolphin works, we've helped reel in fresh talent for the emulator, we've helped people get into universities and launch their careers, and even helped a few people meet their life partners! Progress Reports have been so impactful, that they have reached far beyond Dolphin. The once novel concept of emulator Progress Reports has become a standard means of user communication throughout emulation!

But of course, ten years is a long time, and we've changed along the way and will continue to change over time. The Reports may grow or shrink, become more or less frequent, structure and style may change, and writers may come and go. And truth be told, this is hard, and we nearly reached the breaking point a few times along the way. But no matter what happens, as the writers of the Dolphin Blog, it is our goal and our hope that for as long there are Notable Changes being made to Dolphin, there will be Progress Reports to feature them!

Speaking of which, anniversary or not, this is a Progress Report. We have Notable Changes to cover! So without further ado, please enjoy the Tenth Anniversary Dolphin Progress Report, and the last Dolphin Progress Report of the 5.0 era.

Surprise!¶

OK, a little further ado. We have prepared a little something to celebrate this Anniversary. Enjoy!

Now back to our regularly scheduled Dolphin Progress Report.

Notable Changes¶

5.0-21264 - Core: Fix IPL device m_cursor overflow by JosJuice¶

In March 2024, Geotale found a crash in Dolphin and drilled it down to its root cause. GameCube software runs on the metal - it has absolute control of the hardware without any operating system whatsoever. In order to save console-wide settings, such as mono versus stereo audio, the GameCube stores 64 bytes of data in a battery-backed SRAM chip. Whenever a game boots, it will read the battery-backed SRAM and collect these settings without asking the user to set stereo sound over and over again. Normally, games don't try to read or write beyond the 64 byte mark, but if they for some reason were to do that, Geotale found that Dolphin would access memory beyond the end of the memory buffer it allocates for SRAM data.

ElectrifiedStrawberry then wrote up a bug report about the issue to relay it to the Dolphin developers. Upon seeing the report, JosJuice quickly realized that the bug might be exploitable by specifically crafted software to take control of Dolphin, and fixed the problem by adding a bounds check. As far as we know, nobody has tried to exploit this bug yet, but to be on the safe side, we decided to release an out-of-schedule Beta release just a few days later to get the fix out to users.

How come one missing bounds check can open up for exploits of this magnitude? If you've read about differences between different programming languages, one term you might have come across is memory safety. Even the White House talked about it recently! In a memory safe language, trying to access memory beyond the end of a buffer or trying to access memory using a pointer that doesn't even point to valid memory to begin with is either impossible or handled in an orderly way. For instance, Java raises an ArrayIndexOutOfBoundsException or NullPointerException respectively for these situations, and the programmer can either write code to handle these exceptions in whatever way they prefer, or ignore the exceptions and have the program crash. But Dolphin is written in C++, which isn't memory safe. While nowadays there are languages that target both memory safety and good performance, like Rust, back when Dolphin was started in 2003, all the available memory safe languages came with notable performance penalties. And when emulating a cutting-edge console like the GameCube, you need all the performance you can get!

In C and C++, going beyond the end of a buffer or using an invalid pointer is formally undefined behavior, meaning literally anything could happen. In practice, usually one of two things happens. If you try to access memory that the operating system considers to be invalid, the program normally crashes. While that may be unpleasant for the user, it's safe in the sense that there's no way for an attacker to exploit the behavior. On the other hand, if you try to access memory that the operating system thinks your program should be allowed to access... then the program accesses that memory. This is exactly what happens in the bug Geotale found. If you go beyond the buffer allocated for SRAM data, you'll start accessing other parts of Dolphin's memory, which are valid memory regions but were never intended to be accessed by the emulated software! As mentioned before, we're not aware of anyone having created an exploit for this, but because Dolphin stores lots of important data after the SRAM buffer and because the emulated software can freely mix reads and writes and can skip over addresses it isn't interested in, it's likely that it would be possible to create an exploit that escapes out of the emulated console.

While in theory a program written in C or C++ can be memory safe if carefully written to avoid bugs, writing a large program without bugs occasionally slipping in is really, really hard, bordering on impossible. So unfortunately, there's a risk of bugs like this being found lurking when someone unearths a part of Dolphin's code that hasn't been touched in a long time. But when bugs like this are found, we take them seriously and move to fix them.

5.0-21145 - Improve window presentation at native resolution by Filoppi¶

Last year, Cristian64 noticed that there were black lines always present to the right and bottom of the image whenever Dolphin was in Windowed mode. They looked into it, and found some errors in how Dolphin's aspect ratio correction interacts with our presentation. They posted their findings in our discord, Filoppi whipped up a fix, and that was merged in 5.0-20048. With that, the cursed black errant pixels were removed from the edges of the screen!

Fast forward to today, and Filoppi noticed that some titles at 1x Native were softer than they should be.

Four Swords Adventures was nice and crisp at 1x Native.

But at some point, something was making it softer than it should be on the vertical axis.

Bisecting the issue, he traced it back to 5.0-20048, his own change! It turns out that the previous presentation fixes brought our old friend floating point rounding errors into the party! There are many opportunities for small floating point rounding inaccuracies throughout Dolphin's presentation and aspect ratio correction code, and sometimes (depending on the game and its native resolution) these could add up to incorrectly make Dolphin think that scaling the image by one pixel was necessary. This was the cause of our blurring! Apparently the errant pixel borders Dolphin had previously were accidentally shielding Dolphin against this kind of error.

Since realistically* there should never* be a case where scaling by a single pixel is correct*, Filoppi fixed this with a simple exception - if Dolphin decides to scale by a single pixel, pass through the unscaled image instead. Problem solved! Now Four Swords Adventures and any other affected games are properly crisp at 1x Native once again.

_{* Next time on the Dolphin Progress Report...}

5.0-21162 - BranchWatchDialog: A Total Replacement for CodeDiffDialog by mitaclaw¶

While Dolphin's primary purposes of preservation and enhancement are focused on play, as an emulator we can grant DEEP access to GameCube and Wii hardware and software. Dolphin can be a powerful utility for GameCube and Wii modding and reverse engineering! This change adds a new debugging feature called the Branch Watch, a powerful new tool that enables better code searching than ever before!

Since this is a feature by developers for developers, we're not going to hold back. Let's get technical!

Back in April of 2022, the Code Diff Tool was added to the Code View widget. Created by TryTwo and dreamsyntax, the Code Diff Tool aimed to replicate a feature of the popular program Cheat Engine called "Ultimap."

What if you could do cheat searches, but on program flow? Ultimap is the way for Windows applications.

The way the former Code Diff Tool worked was by recycling a JIT profiling feature that had been inaccessible since the removal of DolphinWX in June of 2018. By differencing the number of times a block of recompiled code has run since the last time you checked, it was possible to track down sections of the original code that execute only when an action is performed in the emulated software.

Unfortunately, the recycled JIT profiling feature was in no way built for what the Code Diff Tool was trying to do, leading to some limitations. The Code Diff Tool was not compatible with the Interpreter due to the Interpreter not being a JIT (obviously), nor was it compatible with the pseudo-JIT we call the Cached Interpreter due to that JIT lacking the profiling feature. It was also susceptible to JIT cache clears happening out of its control, interfering with progress in any ongoing diff. For semi-arbitrary design reasons, the Code Diff Tool required debugging symbols to operate. A diff would only include recompiled blocks of code associated with the starting address of a debugging symbol, which was problematic when the start of a function may never be recompiled as its own block due to branch following optimizations in the JIT(s). Additionally, the same segment of the original code could be recompiled multiple times, potentially resulting in misleading run counts. Finally, any changes to debugging symbols over the course of a diff would cause some diff results to be unrecognized when checking what has been run since the last check.

Naturally, these limitations were frustrating to work with, but it was mitaclaw who finally grew frustrated enough to try to do something about it. He first set off to improve the Code Diff tool, but eventually he came to the conclusion that JIT profiling data wouldn't cut it any more; Dolphin needed a new component built for the purpose. Thus, the Branch Watch was born.

The job of the Branch Watch is to receive information from the emulated CPU about every executed branch's origin, destination, and PowerPC instruction. It also receives implicit information about the current address translation mode as well as if a conditional branch is taking its true path or false path. After an optimized associative lookup, an entry added to or found in one of the BranchWatch's "Collection" containers will have its hit count incremented by one. From the user-facing Branch Watch Tool, it is then possible to direct the Branch Watch to perform some differencing (not unlike the former Code Diff Tool would) to collate references to the "Collection" containers' entries that meet a given criteria into a separate list - the BranchWatch's "Selection" container. This "Selection" container is what can be seen in the user-facing Branch Watch Tool. The whole process makes viewing the information sufficiently thread-safe, allowing for real-time updates (every 100 ms) to the Branch Watch Tool's interface.

Implementing all of this was a breeze for the interpreter, and support naturally came to the Cached Interpreter as it's barely a JIT. Support for the proper JITs was not so simple. A branch might not be recompiled at all due to the aforementioned branch following optimization. The JITs also have idle loop detection, which can cause specific branches to be recompiled differently. The x86_64 JIT also supports merging PowerPC comparison instructions and PowerPC conditional branch instructions into a single x86_64 instruction that does both. The most involved JIT-ism to support was an optimization for a looping pattern commonly seen when invalidating memory with the dcbx family of instructions. After relentlessly hunting down every corner case, and with JosJuice's invaluable guidance on writing safe recompiler code, the JITs were finally able to match the Interpreter perfectly.

So many buttons and boxes... where to begin?

The new Branch Watch Tool comes with a robust set of options and features to empower code searching. It is possible to filter candidate branches by address and debugging symbol (both at the origin and destination), by true path or false path (for conditional branches), and even by 12 different instruction kinds. When replacing a tool with existing users, it's imperative to leave no feature behind. The authors of the former Code Diff Tool were given council to make sure features from the former Code Diff Tool were not forgotten, such as saving and loading in-progress searches (including an auto-save feature) and "inspecting" results by modifying instructions to stub functionality (previously done inspections are marked with a bold red font). All-in-all, the new Branch Watch Tool should be able to satisfy everyone by providing a superset of features previously available.

If you would like to take the new Branch Watch Tool for a spin, look for the "Branch Watch" button in the Code View widget and check out the Branch Watch Tool's help message tutorial found under Tool > Help. As an aside for non-debugging users, we assure you that this new feature should have zero performance implications for recompiled code when not in use.

5.0-21164 - Corrected Custom Aspect Ratio by Filoppi¶

The previous Progress Report saw the introduction of the Custom Aspect Ratio setting, allowing users to set any arbitrary aspect ratio they want! However, we ended that section by warning that the new Custom aspect ratio option bypassed our aspect ratio corrections, and the image would be slightly distorted basically all the time.

Fortunately, Filoppi wasn't through with this feature, and the custom aspect ratio setting now has Dolphin's aspect ratio corrections! If you are using an ultra-wide screen code, you can just set a Custom Aspect Ratio to match your screen and/or code and it will just work, without need to worry about or compensate for subtle aspect ratio issues!

However, if you liked the old behavior, you can use the new "Custom (Stretch)" option, which still does not have any aspect ratio correction.

5.0-21194 - Implement IR passthrough for Emulated Wii Remotes by AdmiralCurtiss¶

Ever since Dolphin added its own Wii Remote driver that allowed for using the Wii Remote as a configurable controller in Dolphin, one of the biggest questions has been "When is Infrared Support coming?" Dolphin's Wii Remote driver could do just about anything with the Wii Remote, include using it to simulate almost all Wii Remote functions and even passthrough the battery level to the emulated game. But, when it came to infrared, there was no way to properly handle it on a standard Wii Remote, and you'd be forced to use the "Real Wii Remote" setting or Bluetooth Passthrough if you wanted to use a sensor bar for infrared data.

"Connect Wii Remotes for Emulated Controllers" uses Dolphin's very own Wii Remote driver to give the machine a mappable controller.

"Point Passthrough" is a new feature for Dolphin's Wii Remote driver that allows you to use a real sensor bar with the emulated Wii Remote option.

Some of you may be scratching your head after reading that, as there is a way to get the Wii Remote pointer working with Dolphin's Wii Remote driver. However, that method of getting the pointer working doesn't use infrared at all, it simply simulates the Wii Remote's pointer direction using the MotionPlus gyro (and is compatible with non-Wii Remotes that have a gyro) and uses that to reasonably simulate the controller's position in 3D space, from which Dolphin can calculate where the Wii Remote is pointing. This is what lets players easily play games like Super Mario Galaxy on modern controllers with gyro capabilities.

There are some limitations to this, and people with Wii Remote hardware have long been asking for real infrared support with our Wii Remote driver. Unlike real infrared, which has a physical reference in space, gyro infrared suffers from drifting and you have to manually recenter it (usually with a button combo on the controller) once in a while. In most games this isn't too bad, but if you're doing a lot of rapid movements, gyro aiming can fall apart fast! There are also some cases where the gyro simulation didn't produce accurate enough results. Here are some of the best examples where infrared support makes a big difference.

Features¶

Netplay - In netplay, only emulated controllers can be used due to the strict requirement of absolute determinism. This means you cannot fall back to using the "Real Wii Remote" or the Bluetooth Passthrough settings. However, since 5.0-11684 physical Wii Remotes were still usable on netplay through connecting Wii Remotes for emulated controllers. A lack of infrared support meant that using a real Wii Remote on netplay had the hard requirement of having MotionPlus if you were using the pointer. This also meant any game that requires precise pointer controls would not work. We'll have some examples later.
Savestates - Saving the state of the emulator is always a perilous task. Each of Dolphin's methods of handling Wii Remotes affects savestates differently.
- Bluetooth Passthrough makes things very difficult, because we use a real hardware Bluetooth Adapter directly - and we cannot save the state of that physical device. There is limited savestate support, but it requires the user to get the adapter to match the state it was in when the savestate was made. You could accomplish this by connecting the same Wii Remotes in the same order with the same attachments and hope that Wii Remotes are using the same reporting mode as when the savestate was made. Otherwise? It'll deadlock.
- Real Wii Remotes aren't as bad, but users aren't exactly thrilled by our softlock workarounds. As mentioned above, Wii Remotes have various reporting modes, and because we're dealing with a physical device outside of the emulator, we can't simply restore it to the state it was in when the savestate was made. In order to prevent potential softlocks with Wii Remotes, Dolphin will disconnect and reconnect Wii Remotes on loadstate. This resets the state of the Wii Remote to ensure they match, but results in a small delay on loadstate and the game potentially complaining that the controller was disconnected. It may sound annoying, but it is also greatly increases the stability of savestates for Wii games.
- Emulated Wii Remotes have none of these problems, as the thing the game is directly communicating with is within Dolphin's ecosystem. This means that Dolphin can just restore the state of the emulated Wii Remote, without the need for any workarounds or mitigations for softlocks. This is because the "physical" controller just communicating through our driver to our emulated controller. With the new Point (Passthrough) feature, you can get the full benefits of a real sensor bar and savestates all at once. Perfect for speedrun practice or getting past a difficult pointer puzzle.

Game Specific¶

Super Paper Mario - This game in particular asks a lot of the Pointer, having you swap between pointing at the screen and pointing off screen. Gyro Point struggles with pointing far off screen, so oftentimes users would have to map the hotkey "hide pointer" in order to get the game to behave in a reasonable manner. With a real sensor bar, it just works.
The Legend of Zelda: Skyward Sword - This is a rather funny case that really messes with our Gyro Pointer. Skyward Sword already uses the gyro for its pointer, using infrared only for a reference point and for active recalibration to combat drift during play. This means when Dolphin is using the gyro to generate the pointer position, Skyward Sword is using our emulated point in space to correct for gyro drift, yet our emulated point in space is from the same gyro that it is trying to recalibrate. Calibrating a gyro to itself results in a lot of wonky pointer behavior, but users have made it work with complex control schemes and copious recentering. Using a real sensor bar with emulated Wii Remotes gets the game behaving just as it does on the Real Wii Remote options.
Trauma Center, Another Code R, WarioWare: Smooth Moves and other precision pointer games - Unlike the other situations, there wasn't an easy workaround for these games when using Gyro Point. These games have various levels where you're required to push the Wii Remote toward the screen or pull it away from the screen. While games can use the accelerometer for this, they also use the sensor bar's two clusters of lights as a reference point. When you push the Wii Remote closer, the two clusters separate more, and that's how the game can tell the Wii Remote is closer to the screen. Gyro Point has no way of handling this currently, and the only way to make this work without a real sensor bar is to map a bunch of emulated movements to the controller. While this is possible, you get a very different experience and using a real sensor bar keeps it simple and authentic.

Limitations¶

With this major update to the emulated Wii Remotes, the bridge between Real Wii Remotes and Emulated Wii Remotes shrinks further. Considering that we still have three different ways of connecting Wii Remotes, one may question when it'd be time to simplify things. Unfortunately, Emulated Wii Remotes still have a few shortcomings that make Real Wii Remotes a necessary option.

While things like battery life work, unfortunately physical Wii Remote Speakers aren't supported on the Emulated Wii Remote. Many users (and developers) may argue speaker data doesn't work properly even on Real Wii Remote, but one feature that is definitely missing on Emulated Wii Remotes is the Wii Remote Eeprom. This Eeprom could store a small amount of data, usually for Miis. Real Wii Remote does support this, but this might be very complicated to support within our driver.

If you want to try out infrared support, it's automatically mapped correctly when loading Dolphin's default Wii Remote profile. To try it out, go to the Motion Input tab and disable the standard "Point" setting that uses the Gyro, and enable Point (Passthrough). That will allow you to use your real sensor bar.

The settings may look complicated, but Dolphin will set everything up itself to work with your Wii Remote.

HDR Enhancements: 5.0-19931 - Add AutoHDR post process shader by Filoppi and 5.0-21232 - Add HDR to Metal + Perceptual HDR by samb¶

HDR is currently very challenging to demonstrate in browsers. Frustrated, the blog authors resorted to old memes. We apologize in advance.

Several months ago, Filoppi's 5.0-19716 - Support Accurate NTSC/PAL Color Spaces was merged, which gave Dolphin the ability to properly emulate the gamma and color space of the GameCube and Wii. The difference isn't significant, and since it results in slightly reduced brightness and saturation it could be considered undesirable, hence it being off by default. But more accuracy is more accuracy, and even subtle improvements are important for a mature emulator such as Dolphin!

However, to facilitate accurate gamma and color spaces, Dolphin needed more control over the host display. Ironically, this required Dolphin to support HDR. High Dynamic Range is typically used to display a larger color space, yet this feature was using it to limit the color space to accurate levels. Regardless of the reasoning, this change added the HDR Post-Processing feature to Dolphin.

What happened next was easy to see coming.

In 5.0-19928, Filoppi added an HDR enhancement shader to Dolphin! A "slimmed down port" of Filoppi's prior Reshade shader, our AutoHDR shader is designed to be additive - it expands highlights into HDR luminance while leaving the rest of the image unmodified. This gives games a bit more pop while still mostly maintaining their original SDR look.

AutoHDR has several options to allow users to dial in the experience.

Shoulder Pow - Modulates the Auto HDR highlights curve. Low values bleed a bit into midtones to give a gentle, soft edge around the HDRified highlights, while high values only brighten the hightlights for pin sharp edges.
Shoulder Start Alpha - Determines how bright the source SDR color needs to be before it can be used to generate fake HDR highlights
HDR Display Max Nits - Sets the maximum brightness of the HDR highlights

If you want to closely follow the original look of the game but add a little HDR pop, AutoHDR is for you! Do note however that GameCube and Wii games have very primitive lighting models, more primitive than what AutoHDR was originally designed for. More often than not, our AutoHDR shader will benefit from tweaking for each individual game's lighting quirks.

For a bit more pop, samb's 5.0-21232 brings PerceptualHDR, a much more HDRy enhancement option! PerceptualHDR uses a logarithmic approach to its inverse tonemapping curve. This results in brightness and saturation scaling that looks more "natural" to the eye, though less accurate. It also has the side effect of making it very tolerant of the poor lighting models of GameCube and Wii titles, and reducing the need for customization! It also has higher saturation and brightness overall, with a more "HDR look". However, PerceptualHDR significantly changes the look of the game, and is definitely not for those pursuing accuracy.

The two shaders have very different looks and goals, neither one is "better" than the other. AutoHDR is very conservative, trying to enhance but respect the original look. Plus it is very customizable, allowing it to adapt to any game's lighting. Meanwhile, PerceptualHDR throws out the original look for all the HDR pop it can offer! While it is generally more tolerant, it is also not customizable (outside of amplification), so if a game doesn't work well with it you're basically out of luck, but AutoHDR can be adjusted to match. Whichever shader you use is up to you and what you'd like out of an HDR enhancement!

To demonstrate these differences, we're going to need to go into the High Dynamic Range!

HDR Block¶

Click the image below to enter the HDR Block, an addendum article where we use cutting edge browser features to show you actual HDR comparisons rendered in your very own browser!

You'll need an HDR display to see the differences, so if you are using an SDR display, feel free to skip.

CLICK THE IMAGE BELOW TO ENTER THE WORLD OF

Welcome back to the land of SDR! Take a moment to readjust your eyes if you need to. Maybe use some eyedrops.

Now that we have established the differences and options, it's time for us to temper your expectations.

The GameCube and Wii are entirely SDR consoles with very basic lighting models that were designed for small and dim displays. They are absolutely not designed for HDR. By dragging them kicking and screaming into high dynamic range, we are putting these games that have no idea what HDR is in charge of an absurdly powerful display technology.

Our HDR enhancements are not magic. Expect quirks and problems.

For example, there is no concept of "paper-white" in these games. While our HDR enhancement shaders differ in their approach and the inverse tone mapping of middle values, the extremes are the same - complete black in SDR space will be complete black in HDR space, and complete white in SDR space will be the maximum HDR output of the shader or your display. If you crank your display brightness to the max, turn on an enhancement shader and crank it to the max, and launch a game that has an entirely white screen, you could be bombarded with thousands of nits of brightness. And guess what console starts every single game with a solid white screen - the Nintendo Wii!

When MayImilae first tested PerceptualHDR, she maxed out her display brightness and the amplification setting, then launched a Wii title.
This was her experience.

You can easily flashbang yourself with these features, so use this power responsibly.

Furthermore, if you are using an HDR display without calibrating it, any time you view SDR content you are already experiencing inverse tone mapping. Most current generation displays, televisions and phones especially, don't care about accurate SDR recreation and by default boost saturation and brightness way beyond SDR spec. They are already turning SDR content into HDR content by default!

As such, you may turn on AutoHDR or PerceptualHDR and see a dimmer and duller appearance than you had without any HDR enhancements. If this occurs, our HDR enhancements' inverse tone mapping is more conservative than what you are used to!

The world of HDR is a varied and wild place. With "HDR" spanning everything from 300 nits peak brightness to 10,000, and from 8-bit dithered 50% DCI-P3 to 12-bit 100% Rec2020 reference monsters, HDR can be very different things depending on your display. Our HDR enhancements add to your existing tools for customizing inverse tone mapping on your HDR display, and you will need to use all of the tools available to you for best results. HDR is like that.

That being said, if you are ok with experimenting, HDR has a lot to offer as an enhancement. When everything lines up, these HDR enhancements can improve the game's visuals on a scale similar to raising internal resolution! Games like Super Mario Galaxy and Sonic Colors look great with these enhancements! HDR is messy and complicated and a pain, but when everything lines up and it works correctly, there is nothing quite like it.

While our Post-Processing shaders will appear on all platforms, our HDR Post-Processing feature is currently only available in our desktop Qt interface, and requires HDR to work. Functionally, that means that currently our HDR enhancements can only be used on Windows, macOS, and a tiny subset of Linux (that includes the Steam Deck OLED).

To use these shaders, have an HDR screen and enable HDR. Then turn on HDR Post-Processing...

And select an HDR Post-Processing Shader!

HDR Post-Processing is currently not available on Android.

5.0-21253 - Implement Modem Adapter by fuzziqersoftware¶

The GameCube was released in the early days of the ubiquitous internet. In 2001, dial-up was still a normal way to go online, but broadband was increasingly spreading its tendrils throughout the globe, and our chronically-online doom-scrolling future was already well on its way to consuming us all. To facilitate experimenting with this terrifying new frontier, the GameCube had an accessory port on the bottom that could fit the GameCube BroadBand Adapter (BBA), a 10/100mbps ethernet adapter that allowed the GameCube entry to the information superhighway!

The BroadBand Adapter Instruction Booklet walked users through the arduous installation process.

Since it was an addon accessory for an experimental feature, it saw limited support in the GameCube lineup. Some games used the BBA for its LAN mode, allowing players to connect multiple GameCubes together locally for crazy high player numbers while avoiding that whole scary internet thing. But a select few games dove right into the Online mode, requiring an internet adapter and an internet connection! The iconic Phantasy Star Online MMO franchise survived the fall of the Dreamcast this way.

However, while the BBA is reasonably well known amoungst GameCube enthusiasts, there was another accessory that could go into that port - The GameCube Modem Adapter. This was a 56kbps dial-up modem alternative to the BBA. While it lacked the LAN mode, the Modem Adapter granted more or less the same online features as the BroadBand Adapter, just... worse. All online-mode games that supported the BroadBand Adapter also supported the Modem Adapter, so users were expected to just pick the internet adapter that matched their connection and access the same online content. Though, with some mild variation in user experience.

Except, for one game. There is one game that requires the GameCube Modem Adapter, and does not work with the BroadBand Adapter! This game is Phantasy Star Online Episode I & II Trial Edition. The final version of PSO I & II supports the BBA, but its Trial does not. Dolphin only supported the BroadBand Adapter, so for the entirety of Dolphin's existence, PSO I & II Trial Edition required game modification to be playable in Dolphin!

This change resolves that. fuzziqersoftware, a developer behind PSO reverse engineering tools and PSO custom servers, has implemented tapserver-based Modem Adapter emulation in Dolphin! By combining modem adapter emulation with a compatible custom server, Phantasy Star Online Episode I & II Trial Edition is playable in Dolphin for the very first time without action replay codes or game patches!

Not only is this a win for preservation of this interesting era of GameCube hardware and PSO development, it's also a mark off the very short list of GameCube games that cannot be played in Dolphin without modification.

5.0-21345 - JitCache: Software Profiling Restoration by mitaclaw¶

As was mentioned earlier in this Progress Report, software JIT profiling is one of a small group of debug features left inaccessible by the transition from DolphinWX to DolphinQt. The underlying feature had a partial return as the component powering the Code Diff Tool, before that tool was replaced with the Branch Watch Tool shown previously. Following this, mitaclaw decided he must restore software JIT profiling to its former glory - it's the least he could do after leaving it abandoned once again. It's unlikely this feature will have many users, even among Dolphin's developers, but it's good to see an old feature get rekindled rather than extinguished.

Here it is resurrected in DolphinQt.

And for the first time, Android!

Last Month's Contributors...¶

Special thanks to all of the contributors that incremented Dolphin from 5.0-21090 through to 5.0-21460!

We are now maintaining three social media presences: Mastodon, Bluesky, and Twitter!

The content on these accounts will largely mirror each other. Our Mastodon is our flagship social media presence, it is strongly under our control (literally living on our servers) and truest to our open source philosophy. Twitter is our oldest account, with over a decade of history! Hopefully that will continue. And finally, our Bluesky is brand new! Feel free to follow us on whichever you'd like!

Why Dolphin Isn’t Coming to the iOS App Store¶

In early April, Apple shocked the emulation community by updating their App Store Guidelines to permit retro game console emulators on the App Store. While there was some initial debate over whether the new guidelines only permitted "officially-developed" emulators, community-made emulators soon began appearing on the App Store. The floodgates were open.

Ever since this happened, one question we've been frequently asked is "when will Dolphin come to the App Store?"

Unfortunately, due to other restrictions set by Apple, we are not able to release Dolphin on the App Store. This also applies to app marketplaces in Europe, like AltStore PAL.

The GameCube and Wii both use a PowerPC-based CPU, while most modern devices use x86-64 (Intel & AMD) and AArch64 (ARM) based processors. To be able to run GameCube and Wii machine code, Dolphin uses a Just-in-Time (JIT) recompiler to translate it into code that our modern CPUs can understand. This works well on all of our supported platforms.

There's just one problem: Apple does not allow third-party apps to use JIT recompilers on iOS and iPadOS.

Dolphin does have both the Interpreter and Cached Interpreter, which are JIT-less methods for emulating the CPU. However, they are many times slower than Dolphin's JITs, making them unusable for actually playing games.

Click to see our Cached Interpreter race our JIT on an iPhone 15 Pro Max!
_{For longer versions of these videos with sound: Interpreter, JIT}

There is one very narrow exception to the "no JIT" rule on iOS - alternative web browsers in Europe. This is because many web browsing engines utilize JITs to speed up JavaScript execution. As allowing alternative browsers is required in Europe under the Digital Markets Act (DMA), Apple gave these apps a special exemption in iOS 17.4. However, Dolphin is not a web browser, and Apple has very specific requirements that they use to check whether an app is really a web browser or not. JITs in web browsers are also subject to additional security requirements, such as separating the JIT into its own isolated and locked down process. This is extremely problematic for Dolphin, which expects everything to be included in one process. While retooling Dolphin to work within these constraints is theoretically possible, it would require a large architectural redesign and a significant amount of effort just for one platform. Apple may also just choose to ban our app in the end anyways for pretending to be a web browser.

After reading about web browsers being able to use JIT recompilers, you may be wondering "why not just make a version of Dolphin that runs in a web browser?" Well, easier said than done! To make a usable web version of Dolphin, someone would need to write a brand new JIT targeting WebAssembly and add WebGL support to our OpenGL video backend. While we don't want to say that a web version of Dolphin is completely impossible, working on one just isn't in any of our plans at the moment.

Another suggestion we've received is that we should use ahead-of-time compilation (AOT) on these platforms. This would involve re-compiling all of a game's code to AArch64 in advance, which lets us avoid having to generate the code on the actual device with a JIT. Unfortunately, having to rely solely on AOT compilation would likely cause several compatibility problems. These issues largely stem from the fact that games are freely able to self-modify their code. Some EA games, for example, store their code compressed on disc, and then decompress it at runtime. Other games are even able to generate entirely new code with a JIT of their own! The official Nintendo 64 emulator used in Virtual Console releases is one notable example of this, as it includes a JIT for emulation of the Nintendo 64's MIPS-based CPU. Since we aren't able to know with certainty what code will be executed before the game runs, it isn't feasible to use an AOT recompiler as the sole method for emulating the CPU.

As such, barring Apple having another sudden change of heart or some other miracle, an iOS App Store release is off the table for Dolphin.

Dolphin Progress Report: November and December 2023, January 2024

2024-02-10T04:11:38+00:00

With the conclusion of the holiday season, it's time for us at the blog to get back to work. And this time around, we have a smattering of changes covering just about everything you could imagine. For those looking to enjoy some of the latest homebrew with DSP-HLE, Dolphin now has support for the latest homebrew microcodes! For retail games, we also have a minor update to the Zelda-HLE microcode to fix a missing effect that's long overdue.

In some more important news, for those of you having disk space issues when running Dolphin on Windows since the last beta, a fix is now available. And for those looking for the clearest picture possible, Dolphin's mipmap heuristic has been backed down to allow for higher resolution mipmaps across more textures. And of course, if you're wanting that perfect image, Custom Aspect Ratios will allow for easier use of ultra-widescreen hacks and more!

Add to all of that a huge bugfix for older revision Steam Decks, another chapter in the Bounding Box saga, seeing a classic in an all new way, and yet another chapter in broken GPU drivers, and you've got yourself a Dolphin Progress Report.

Enjoy.

Notable Changes¶

5.0-20353 - DSPHLE: Support 2023 libaesnd uCode by Pokechu22¶

libasnd and libaesnd are open source DSP microcodes for the GameCube and Wii, and are the standard DSP microcodes used by homebrew. When Pokechu22 reimplemented the libasnd and libaesnd microcodes in DSP-HLE back in 2022, we knew that if they were to ever be updated, the new versions would not automatically work in DSP-HLE. This is due to how DSP-HLE itself works - rather than emulating the DSP hardware and running the microcodes directly, DSP-HLE runs reimplementations of the microcodes themselves, made in C++. Thanks to a tremendous amount of work, this is just as accurate as the hardware-emulating DSP-LLE, yet many times faster. However, since DSP-HLE doesn't actually run the microcodes, Dolphin checks the hash of the microcode in the game to know what to use. If the hash of the game's microcode doesn't match any of the reimplemented microcodes, DSP-HLE will fallback to the reimplemented AX microcode, and in the case of homebrew probably not emit any sound at all.

This occurred in 2023, when libaesnd saw an update to address a few minor issues. These small fixes meant a new microcode version with a brand new hash which Dolphin did not recognize, resulting in audio not working under DSP-HLE in titles that used the new version of libaesnd. Specifically, it was the latest versions of the Sonic Mania Wii decompilation port that brought this update to our attention. As a fairly new project in active development, they are consistently updating their microcodes, and they are the first software we are aware of to use the new updates.

Thankfully, the updates to libaesnd were relatively minor and Pokechu22 mostly just had to document what was changed and add the 2023 hash to the libaesnd code paths in DSP-HLE. With that, users can enjoy Mania's Chemical Plant Zone theme in DSP-HLE once again!

Sonic Mania running in Dolphin, with sound in DSP-HLE!

5.0-20880 - Zelda-HLE: Fix Reverb Volume Factor by flacs¶

Sticking to the theme of DSP-HLE, we have a microfix from longtime contributor flacs. This in particular targets the missing reverb effects noticed in Mario Kart Double Dash!!. These effects were noted to be broken way back in 2015 but was marked as low priority amidst a massive Zelda-HLE rewrite. When the rewrite was complete, this bug remained as a minor issue.

flacs returned and has been hammering down bugs in all quadrants. This one turned out to be rather simple. The reverb volume was erroneously being multiplied by current volume twice, resulting in the effect becoming incredibly quiet. While the bug reporters originally thought the reverb was missing, they actually just weren't listening hard enough for it!

Once this oversight was fixed, the effect started working as intended.

5.0-20517 - Implement Send Mail by Sketch¶

Have you ever had an important work email that you needed to send right now but all you had at your disposal was an emulated Wii? This is a position I think we can say every single one of us have been at some point, but unfortunately in the past there was nothing you could do about it.

Thankfully, Sketch took note of the plight of our users and has been slowly working through the Wii Mail system, and while it's not entirely complete, those registered with the WiiLink service can send messages to other Wiis and even emails directly from Dolphin!

To get to this point, it's been a rather long ride, and a ton of the legwork was already done for WiiConnect24 emulation. Soon, we're hoping to have full parity between using WiiLink on a console and Dolphin, though there are still some missing features on the Dolphin side of things.

5.0-20589 - Rewrite LazyMemoryRegion by AdmiralCurtiss¶

Last Progress Report, we described a performance optimization that had the annoying side effect of taking up 32 GiB of disk space on Windows. Now AdmiralCurtiss has rewritten the code used on Windows to avoid side effects of this kind.

To summarize the problem from last time: Dolphin needed a 32 GiB memory allocation to efficiently keep track of where recompiled code was located. Most of it didn't need to be backed by real memory, but whenever Dolphin wanted to access a particular location, real memory had to be allocated on the fly so the access wouldn't fail. In the solution described in the previous Progress Report, we handled this by asking the operating system to allocate pages for us as needed. This worked well on almost every OS, but on Windows we ran into the problem that the system would force the page file to grow to match our huge 32 GiB allocation, in case we try to access all 32 GiB.

With the new solution, we're handling things more manually on Windows. AdmiralCurtiss's initial idea was to mimic what the operating system was doing by setting up a signal handler that runs when Dolphin tries to access an address that isn't backed by real memory – something Dolphin is already doing for the tried and tested fastmem optimization – and then allocating some real memory when the signal handler runs. But because Dolphin only writes to the 32 GiB region from two pieces of code, both of which run relatively infrequently, Progress Report reader PJB3005 was able to come up with a simpler solution that AdmiralCurtiss then implemented. Instead of using a signal handler, Dolphin now manually checks if it needs to allocate any real memory before it writes to the 32 GiB region. Parts of the 32 GiB region that aren't yet backed by real memory are pointed to a read-only page filled with zeroes, so that nothing will go wrong if Dolphin tries to read from a location that hasn't been written to.

Now Dolphin users on Windows are able to benefit from the JIT Block Lookup performance optimization without worrying about Windows making their page file balloon. Issues like not being able to download large files while Dolphin is running will no longer occur.

On operating systems other than Windows, Dolphin is still using the old approach where the OS allocates real memory on the fly, since we've only seen problems with that approach on Windows.

5.0-20745 - Disable Arbitrary Mipmap Detection by Default by iwubcode¶

As part of the essential hack that is raising Internal Resolution, Dolphin adjusts the mipmap level of textures. Mipmapping is the process of swapping to lower resolution versions of textures if they would appear too small in the final image. This is an old graphics staple - using maximum resolution textures everywhere leads to severe aliasing and moire on distant textures and textures at oblique angles. However, this is resolution dependent, and mipmap targets set for 480p will be intensely blurry at 4K. So Dolphin adjusts the mipmap levels to match the increased Internal Resolution, significantly improving overall texture quality of the final image.

However, some GameCube and Wii titles use mipmap shenanigans for effects, and by changing the mipmap levels, we were breaking these tricks. To have our high resolution cake and eat it too, in 2017 we added Arbitrary Mipmap Detection, a heuristic that attempts to detect mipmap mischief and drop to a more accurate mipmap implementation for only the textures involved in these effects. The result is that the specific textures used for these effects will be blurrier, but as it is correcting broken effects and should only affect the specific textures involved, it's a win win. Theoretically.

Galaxy 2 reads the mipmap level to control this fog effect in the sky.

Without Arbitrary Mipmap Detection, the fog is gone and the clouds repeat infinitely.

Unfortunately, this heuristic has proven to be problematic. It often has false positives, incorrectly detecting mipmaps as being used for effects and needlessly using blurrier versions.

With Arbitrary Mipmaps, the back of the ship in Skies of Arcadia is much blurrier than it should be.

Without Arbitrary Mipmap Detection, the ship is considerably crisper.

To account for this, in 2018 we added the Arbitrary Mipmap Detection toggle. On by default, this option gave anyone who was having trouble with the heuristic the ability to simply turn it off, and avoid any problems it may cause. It was a simple solution, and it has remained ever since.

Fast forward to late 2023, and iwubcode asked a question that shook us all: "how many games use arbitrary mipmaps for effects?" In the resulting back and forth, we realized the number of games that utilize mipmap hijinks is... not a lot. To our knowledge, only Nintendo used this technique. Of course these were games by Nintendo, titles that are flagships of the GameCube and Wii lineup, like Super Mario Galaxy and The Legend of Zelda: The Wind Waker. However, by being such core titles, we realized that the importance of detecting these effects was overestimated. As far as we are aware, a couple dozen games use the trick, and thousands of games do not. Considering just how common and pernicious false positives are with the heuristic, having the heuristic on by default for every game was probably causing more harm than good.

So we have decided to change that. Arbitrary Mipmap Detection is now off by default. From now on it will only be enabled by default in known cases, via our GameINI system. If you happen to spot any issues that are resolved by turning on Arbitrary Mipmap Detection, please let us know and we'll add it to the list of known mipmap tomfoolery.

5.0-20785 - Support Custom Aspect Ratios by Filoppi¶

Dolphin's Widescreen Hack is both amazing and terrible in equal measure. By expanding the View Frustum, it allows Dolphin to able to render any game at any aspect ratio, and thus fill any screen without stretching the image! However, the Widescreen Hack is only performed on the Dolphin side, and doesn't affect the game's logic at all. Frustum Culling, screenspace 2D graphics, and more are entirely unmodified. The result is large blank areas in the expanded space, stretched 2D elements, and aberrant pop-in are simply the reality of the Widescreen Hack.

Fortunately, we have an alternative - game-specific aspect ratio cheat codes. By editing the game itself through our cheat system, all of these quirks can be addressed and a much better result can be achieved.

Wasn't this room supposed to have walls?

Through the power of action replay codes, geometry is no longer being culled and we don't have to worry about pop in!

However, aspect ratio codes require the user to configure their aspect ratio. For example, to run Ralf's 16:9 Aspect Ratio code for Wind Waker, a user must set Dolphin's aspect ratio to Force 16:9. Simple enough.

But what happens if your display is an UltraWide? 21:9 codes are fairly common, but there is no "Force 21:9" option. To work around this, 21:9 display users can set the aspect ratio to "Stretch to Window" and enter fullscreen. This does the job, but this has some issues. Ultrawide aspect ratios are less a standard and more of a suggestion, so even within the 21:9 category, the actual ratios vary. In the real world, our little workaround usually results in minor distortion.

But worse still is Super UltraWide. 32:9 aspect ratio codes are few and far between, making the workaround above unviable. The best option available for 32:9 users was to combine a 21:9 code, windowed mode, and Stretch to Window Size, then very carefully size the window so that there was no stretching. Not great.

This works, but you have to hide the Windows Taskbar, Windows will not let you move the titlebar of the window off screen if you don't have a secondary monitor, it's a lot of faff to set up, and it requires you to void your wallpaper for the best result. It's not a great experience.

Filoppi decided that this will not do, and added a new Custom Aspect Ratio option to Dolphin. Using this feature, you can effectively force Dolphin's aspect ratio to whatever you want. Now, Super UltraWide screen users can enjoy 21:9 in fullscreen without any fuss or distortion!

Set up a 21:9 code, configure a Custom Aspect Ratio of 21:9, and just enter fullscreen like normal! It's that easy!

Plus, this change allows any aspect ratio on any display, so if you have a 16:9 display and want to play 21:9 on your OLED TV or something, you can do that! In fact, if a theorectical retro port to the GameCube or Wii has an incorrect aspect ratio, this could even be used to correct it! We haven't actually found any of those yet, but it's an intriguing possibility.

To use this feature, just set the Aspect Ratio to "Custom", and configure the ratio to whatever you like!

However, as we do whenever we give dangerous new powers to users, we must exit with a word of caution. The GameCube and Wii were never exactly 4:3, 5:4, or 16:9. Yes, on hardware. It was the days of analog displays and their crimes were all going to be overscanned away anyway, so game developers had no reason to care about being exact. Back when Dolphin assumed standard aspect ratios, every. single. game. was off to some degree. Remember the Melee shields?

This is the hell we used to live in.

This was a tremendous headache for us, and to resolve it required months of effort from very skilled engineers, testers, esports communities, and more. It was an enormous undertaking.

The result of all that work is that Dolphin reads the exact Aspect Ratio the game is instructing the console to scan out and displays precisely that. And to make sure users see it without distortion, all of our aspect ratio modes used these corrections, with only Stretch to Window bypassing it. Well, now there is a second way to bypass it. A Custom Aspect Ratio will give you exactly what you enter, no matter what. So if you are playing in ordinary 4:3 or 16:9, and you configure the custom aspect ratio to 4:3 or 16:9, you are bypassing Dolphin's aspect ratio adjustment and you will be distorting the image in all cases.

Please use this power responsibly.

PLEASE.

5.0-20849 - VideoCommon: Apply "Force 24-bit Color" to EFB Copies by flacs¶

"Force 24-bit Color" is an enhancement that reduces banding by forcing the emulated hardware to the highest bitdepth possible. However, there were some cases where turning on the enhancement did not improve banding at all! This change fixes that, but to explain why, we're going to have to get technical.

To understand this problem, we need to go over how post-processing works on the GameCube and Wii. This first paragraph may be a little familiar, but bear with us. While rendering, the ArtX GPU in the GameCube and Wii rasterizes to the "Embedded Frame Buffer" (EFB), a 2MiB chunk of extremely fast working memory that resides in the GPU itself. While some basic post-processing can be applied while the frame is in the EFB, any effect that involves reading then distorting the frame cannot be done while it is in the EFB. So for most post-processing effects, games will execute an EFB Copy to transfer the frame to main memory, then read the frame as a texture from which to render again on top of. However, the consoles primarily render in 6-bits per channel RGBA6, but cannot read a texture in that format. To deal with this discrepancy, it is common for games to convert the frame to 8-bits per channel RGBA8 during the EFB Copy to maintain full visual quality.

However, a fullscreen image at RGBA8 is HUGE for this hardware. Assuming a 640x480 render target, that would be 9830400 bits, or 1.17MiB! And for post-processing effects, multiple renders need to be made! The GameCube's Main Memory is only 24MiB, and the game needs to live in that space too. So many games opt to EFB Copy some images into main memory in the RGB565 format. A 640x480 RGB565 image is only 4915200 bits in size, or 0.59MiB. That's half the size!

But of course, this came at a cost. Most games render in RGBA6. 6-bits per channel is 64 values per color, for 262144 total possible colors (ignoring the alpha channel). RGB565 has two channels at 5-bits (32 values per color), combining to a total of 65536 total possible colors. RGB565 has significantly fewer colors making banding much worse, and it is missing the alpha channel entirely, limiting its uses. However, when the benefit was halving an image's RAM usage on a chronically memory-starved machine, this was a option that many developers utilized.

A certain brave developer tried to maximize visual quality by switching between RGBA8 and RGB565 EFB Copies depending on how much memory was available. This was the equivalent of playing hot potato with a hand grenade. Click the explosion above to read that story!

And now we return to Dolphin. In Dolphin, we support the original RGBA6 that games usually render with, and all other formats for rendering and EFB Copies. However, the hardware we are running on is almost guaranteed to be 8-bits per channel RGBA8 or better, so we have an enhancement called Force 24-bit Color. This mode forces the emulated console into a hybrid RGBA8-ish mode where the color channels are 8-bits per channel, and the alpha channel remains at 6-bits. This is mildly inaccurate, but it is not that far removed from what the console can do, and it substantially reduces banding. It's a relatively safe enhancement that can significantly improve image quality.

However, for Luigi's Mansion, Force 24-bit Color did not affect banding at all.

This was the game with Default settings.

And here it was with Force 24-bit Color. Yes they are not the same image, we are sure.

flacs noticed this discrepancy and looked into it. Force 24-bit Color forces the initial render to use the RGBA8 mode. However, Force 24-bit Color did nothing to EFB Copies, which every frame will undergo at least once! If the game used the typical option of EFB Copying into RGBA8, then Dolphin would take an RGBA8 image and EFB Copy it into an RGBA8 image, and the enhancement would still be in effect. But if the game chose to go with RGB565 (or RGB5A3... we're not going to talk about that one), Dolphin would follow the game's instructions and decimate the RGBA8 rendered image into RGB565, completely destroying the enhancement in the process!

Due to the color compromises, most games use RGB565 sparingly, saving it for secondary post processing of effects that only partially cover the screen. Most of the time, the RGB565 pieces of an image would be difficult to spot. Not so with Luigi's Mansion, as it EFB Copies the entire framebuffer in RGB565! This decimates the entire screen, rendering Force 24-bit Color effectively useless!

So flacs has corrected this oversight. Now, whenever Force 24-bit Color is enabled, EFB Copies will also use RGBA8 within Dolphin. Thanks to this change, we can see Luigi's Mansion as we never have before!

Click/Tap and hold to see the banding improvement Force 24-bit Color can now achieve!

Force 24-bit Color will be improved in any title that uses lower quality EFB Copy formats such as RGB565. Players using the feature should look for reduced banding in their favourite titles! However, most games only use these lower quality EFB Copy modes for part of the screen, so most titles that are improved will see a less dramatic change than Luigi's Mansion.

5.0-20923 - Steam Deck: Pad out feature report to 64 bytes by endrift and ArcaneNibble¶

In the previous Progress Report, we covered 5.0-20148 - Periodically Re-enable Steam Deck Gyro. Current versions of SteamOS will try to shut down gyros that it thinks are not being used. This gave us a lot of issues, so this change addressed this by making Dolphin re-enable the gyro on Steam Decks roughly once per second.

However, due to SteamOS quirks, it's not easy for users to run Development builds on Steam Decks. Most Steam Deck users get Dolphin builds through Flatpaks of our Beta builds. So while the change was tested by the developers before being merged, it was only after the Report and the Beta release that the Flatpaks were updated and this change was finally able to reach wide adoption in users' hands.

And almost immediately, we started to get reports of doubled inputs in the latest version of Dolphin. Uh oh.

The author of the change, ArcaneNibble, immediately retested and couldn't reproduce it. And yet reports kept pouring in. So more of our developers tried it, and they couldn't reproduce it either. A few of our users and testers tried it, and weren't able to reproduce it either. Yet more and more reports kept pouring in. What was happening!?

This back and forth continued for weeks, until finally, we stumbled upon the answer. Older Steam Decks were affected, and newly built Steam Decks were not. It turns out that the Steam Deck LCD had a major revision in the fall of 2023! The revision completely changed the Deck's internals, with significantly different PCBs and component parts! And sure enough, the Deck's Steam Controller controller chip was refreshed too. Steam Decks made before fall of 2023 use an Atmel controller, while Steam Deck LCDs made after fall of 2023, and all Steam Deck OLEDs, use a Renesas controller. Once we realized this potential source, we asked users to run a command that reported the controller in their Deck. In all of our samples, Steam Decks with Atmel controllers always had the issue, and Decks with the Renesas controller never had it.

Now that we knew how to reproduce the issue, we asked developers who work on the Deck for help. endrift, mGBA author and Dolphin contributor, has been working on the Deck a lot lately. She came in and worked with the author of the change for a thorough debugging. It turns out, ArcaneNibble made an tiny oversight and didn't fill in one value.

Broken Code:

const unsigned char pkt[] = {0x00, 0x87, 0x03, 0x30, 0x18, 0x00};

Working Code:

const unsigned char pkt[65] = {0x00, 0x87, 0x03, 0x30, 0x18, 0x00};

ArcaneNibble forgot to pad the packet size of the feature report packet. That's it. Here's endrift explaining what happened:

When Steam tells the Steam Deck (or previously the Steam Controller) to change a setting, it uses something called a HID feature report. Feature reports can be up to 64 bytes long in USB 2.0, and the size of a device's report is described in the suitably named report descriptor, which is specified by the HID standard.

Feature reports can be split out into up to 256 different IDs, each of which can have a separate size as described in the descriptor. However, for a dynamic system like the Steam Deck, sometimes devices just define a longer-than-used 64 byte report size and just pad the end out with zeroes, then define the ID outside of the descriptor.

Steam always sends a fully padded 64 byte report, in accordance with the report descriptor. However, by sending a feature report with less than 64 bytes, the implementation on the USB device end gets confused. Quite possibly later feature reports get misinterpreted as a result, and one of these misinterpreted reports from Steam causes this issue.

However, Renesas chips don't appear to get confused and just internally assume the report should be padded to 64 bytes even when fewer are sent.
endrift

This resulted in Atmel controllers entering a glitched state where they operated in both "Lizard Mode" (the default fallback controls for when Steam is not running) and normal mode at the same time, doubling every input. Renesas controllers, on the other hand, were entirely unaffected.

So endrift tested a fix and made a quick PR, and now the double input issue is resolved! While the solution may have ended up being very simple, this bug was a very difficult one to identify. It took the entire Dolphin Steam Deck community chasing this bug for us to figure it out and get it sorted. Thank you to everyone who reported and helped us chase this sneaky bug!

5.0-20941 - SDL: Add GameController API, cleanup by SuperSamus¶

SuperSamus has given our SDL input backend some love. First, they added support for the GameController API, an abstraction that allows consistent mapping across different controllers. Users will be able to switch controllers, i.e. a DualSense to a Switch Pro Controller, seamlessly without remapping! SuperSamus also cleaned up our SDL input backend, cleaning up a bunch of workarounds for old SDL versions that are no longer applicable to our current SDL2 input backend. SDL is now better than ever before, on all operating systems!

In fact, as of this change SDL has once again been enabled by default in our Linux builds! SDL has come a long long way.

5.0-20961 - Only initialize Bounding Box if supported by GPU/driver by AdmiralCurtiss¶

"Renderer" was an abstraction in Dolphin's code that functioned as an interface for video plugins. However, when the video plugins were merged with Dolphin's code and became video backends, Renderer became a dumping ground, filling up with tons of miscellaneous code and features. So, last year, Phire set off with the mission to kill Renderer entirely, refactoring enormous amounts of Dolphin's graphics code.

Kill Renderer moved a lot of code around.

We covered Kill Renderer here on the blog, both because it was a huge achievement, but also because any change that touched that much of Dolphin's codebase was likely to have unforeseen consequences. And that is what we come to today.

After Kill Renderer, we received reports from users on very old GPUs that Dolphin no longer worked for them. Now, any game they attempted to run would fail to start, with the error "Failed to create BoundingBox Buffer."

This occurred after running Super Smash Bros. Brawl. That game doesn't even use Bounding Box!

After Kill Renderer, Bounding Box was always initialized whether the hardware supported it or not. This doesn't affect most of our userbase, as >99% of our users' hardware supports the feature, but for any hardware that doesn't support Bounding Box, this regression completely broke Dolphin!

AdmiralCurtiss looked into this and made a quick fix. As of this change, Dolphin will perform the same as it did before Kill Renderer on those GPUs - Dolphin runs again and games work, but if a user attempts to run a Bounding Box title, they are in for a buggy good time.

Mario refuses to be associated with the Intel HD Graphics 3000.

Now that's an air ship.

Unlike the GameCube, Intel HD Graphics 3000 cannot handle this many sprites at once.

Notice for Nvidia Users¶

We've received reports of texture corruption in D3D11 on Nvidia GPUs with their latest drivers. This is still developing, as we have yet to properly isolate and analyze this, but we believe it to be some sort of driver issue. For now, we recommend Nvidia users avoid our D3D11 backend.

Last Month's Contributors...¶

Special thanks to all of the contributors that incremented Dolphin from 5.0-20349 through to 5.0-21088!

Dolphin Progress Report: August, September, and October 2023

2023-11-25T15:44:10+00:00

This past October, Dolphin turned 20 years old since its initial release to the public as an experimental GameCube emulator. It's been a long ride, with twists and turns. I don't know if anyone back in 2003 expected Dolphin not only to still be under active development 20 years later, but to also support the GameCube's successor in the Wii.

You might be wondering, where is all the pageantry? The honest truth is that things aren't ready yet. We have a few massive changes on the horizon that we wanted to be ready for the 20th anniversary, but that date was not an excuse to release something in a broken and incomplete state. For now, development will continue as normal, but we promise that there is some excitement to be had on the horizon.

In the meantime, we have some great changes for you this in Dolphin Progress Report!

Notable Changes¶

5.0-19886 - Add Custom Dark Style for Windows by AdmiralCurtiss¶

The waiting game is over. After much discussion and work, AdmiralCurtiss bit the bullet and added a dark mode to Dolphin. Some of you may be wondering right now, Wait, didn't Dolphin already have dark mode? Yes. Also no.

Essentially, on macOS, Android, and Linux, Dolphin has supported dark mode for years. On those platforms, if your system is configured to dark mode, Dolphin will switch to darker colors to match without requiring any input from the user. It is completely seamless on macOS and Android, and has been since early 2020, nearly four years ago. Dolphin on Linux has supported dark mode for even longer, however it may or may not work out of the gate depending on the packaged Qt defaults and other Linux quibbles. If you're a Linux user, you know the dance.

Dark mode has been effortless in macOS for years now.

Android too!

However, the above fails to mention a very significant operating system that we support - Windows. As that is nearly half of our userbase, a lot of our users were missing out on nihilistic bliss. There were many reasons why we didn't support dark mode on Windows until now, but the core of the matter is our desktop GUI toolkit - Qt.

While Qt 5 supported automatic dark mode switching on macOS and Linux, it did not respond to the Windows dark mode setting at all. But there was a lot of demand for the feature, so Qt promised that a solution was in progress. For us as an application that uses Qt, we could have bodged together some sort of dark mode switching ourselves, but it would have inevitably been jank and weird. So upon hearing that Qt was working on it, we decided to wait for their solution. That eventually came with Qt 6.5, which indeed delivered automatic dark mode switching on Windows as promised... in their new "Fusion" style. The Windows-matching QWindowsVistaStyle Dolphin has used for years was abandoned and will not be getting dark mode at all. Qt gave many reasons for their decision (spoiler: Windows be Windowsing), but fundamentally, they did what they thought was best given the circumstances.

With Qt's unexpected move to a new style, we had to make some decisions. Do we adopt the new Fusion style, affecting all of our Windows users both light and dark, or do we use the switching they built into Qt 6.5 and create something ourselves? So people experimented, with nearly a half dozen pull requests of all kinds! We tried Fusion, but the look of the style proved to be unpopular. So we started experimenting with custom styles of our own, with multiple people going different directions and bikeshedding for months.

The end result is a hand-crafted dark mode alternate QWindowsVistaStyle created by our very own AdmiralCurtiss. It is what we had hoped Qt's default support for dark mode on Windows would have been - Dolphin on Windows, but dark.

The same Windows Dolphin style you know...

Can now go dark!

Now every platform we support now has dark mode and automatic switching! Of course it will switch automatically, but on Windows you can manually select between our dark and light styles and even custom user styles with the new Style dropdown in Config → Interface. This replaces the old Custom User Style control, combining our official styles and custom user style controls in one place.

5.0-19939 - Implement Output Resampling (Upscaling/Downscaling) by Filoppi and samb¶

For years now, whenever a user has asked us for settings that would give them the best image quality possible from Dolphin, there's been a familiar back and forth. In response to the question, we'd tell them to set Dolphin's Internal Resolution to match their screen (following our recommendations in the GUI), set Anisotropic Filtering to x16, and use 4x or 8x SSAA (Super Sample Anti-Aliasing).

On a sufficiently-capable gaming PC, that combination will give pristine visual quality. However, users would counter our recommendation by saying that since SSAA runs at a higher resolution than the screen and uses downsampling for its resolve, why can't they just do the same by raising Dolphin's Internal Resolution higher than their screen? And we'd reply by reminding them that Dolphin didn't have its own output resampling, and the basic downsampling from the GPU meant that their idea would create more aliasing rather than less.

Believe it or not, this is using 4xSSAA. The Internal Resolution in this shot is much higher than the screen, and the GPU's basic bilinear downscaling is so sharp it creates new aliasing.

This song and dance has happened dozens of times, enough that we would remind users about this whenever new Internal Resolution options were added. However, as of this change, things are different. Dolphin now has its own Output Resampler! With Area, Bicubic, Sharp Bilinear and more, users can now take upscaling and downscaling into their own hands. In fact, as far as we know no other game, emulator, or even GPU driver implements such an advanced and comprehensive resampler!

B-Spline, Catmull-Rom, and Mitchell-Netravali, oh my!

Has this changed our recommendation for the best possible visual settings? Not really. While you can use output resampling to create a "DIY SSAA" that can meet SSAA's visuals, hardware SSAA is faster at equivalent fidelity (on an Nvidia GPU). SSAA is an easy recommendation.

However, performance was never the point. Output Resampling is an extremely powerful new tool that was built to give users control of Dolphin's final look. From an especially soft and temporally stable image, to razor sharp pixels, to the highest fidelity imaginable, our new output resampling features can do it all! There's a lot to cover here, so let's get started.

What is Output Resampling?¶

Before we continue, let's briefly go over the basics for any readers who are unfamiliar with these topics. Whenever rendering at a resolution that doesn't match the render window, the pixels of the game's output must be resampled (effectively remapped) into a new image that matches the new pixel grid. For example, a 1x Native (640x528) frame in a 1920x1080 canvas must be scaled up to fill the canvas. As it is not a 1:1 ratio and not even an integer multiplier, we can't just directly translate pixels from our output onto pixels of the screen, it must be resampled during upscaling. With the familiar Bilinear upscaling, it will fill the canvas by interpolating the source pixels into the new pixel grid, for a consistent, though soft, resulting image.

If we run a game in 4:3 at 1x native in a window with Auto-Adjust Window Size, we get razor sharp pixels thanks to direct pixel mapping. At least, as close to direct mapping as is possible for the GC/Wii.

But this configuration is quite small on a 1080p screen.

If we enter fullscreen, the game is much larger. However...

Our pixels are now soft. This is because the ~480p pixel grid has been interpolated into the 1080p pixel grid of our display.

The GameCube and Wii were built with analog displays in mind, where exactness simply didn't exist. Every game is close to a standard aspect ratio but subtly nonstandard, and frustratingly uniquely subtly nonstandard. Plus, widescreen is achieved by just.. making the pixels wider, not adding more of them, so that means non-square pixels are a factor too! To accurately recreate these games on modern displays, we have no choice but to account and adjust for these behaviors, which we do by resampling the image. As such, any time you play a game in Dolphin, the image you are seeing will have been resampled at least a little in all cases.

Resampling is unavoidable in Dolphin.

Without an internal output resampler, Dolphin has been entirely reliant on host GPU's provided resampling for this important task. It's... not amazing. The GPU Bilinear Resampler was designed to be fast and simple, and not necessarily to have the best visual resolve.

The GPU provided bilinear resampling a 1x native image into 1080p gives a soft result, but not an especially clean or great one. It does the job.

Downscaling a 6x native image to 1080p is similarly "meh". Despite using four times the pixels of 3x native (which is close to our 1080p canvas), it's not much better. But it did downsample it for us.

Despite all this, resampling hasn't been a huge issue for us. After all, Dolphin's GPU load is pretty low* and we are always* CPU limited, so with GPU power to spare*, users should just run at the Internal Resolution that we recommend for their screen and call it a day. With modern devices, even a phone can do that*. And they probably even have enough spare GPU power to add antialiasing for an even better result! Despite all those asterisks, that is still usually the case, if all you care about are high resolutions and crisp antialiased lines. However, not everyone wants that. And even in 2023, there are still cases where not everyone can achieve that. This is where Output Resampling comes to its own.

What are the resample options?¶

Our Output Resampler is extremely comprehensive with many different possible settings and use cases. Here are some of the options and some ways that you can use them.

Area is a resampler that samples every pixel on the screen for the maximum possible sample count. It is built for downsampling, with a soft resolve to combat aliasing, shimmer, and moire issues inherent to downscaling. It can be used for upsampling though, to curious results.

By sampling all the pixels, the Area downsampler is extremely sharp when upsampling.

When downsampling, Area's soft resolve helps smooth edges of textures and polygons alike.

Upsampling isn't really what Area is intended for, but is does give an interesting result - an extremely sharp look, akin to Sharp Bilinear. However, we recommend Sharp Bilinear over using Area this way, as Sharp Bilinear is explicitly designed for upscaling pixel art titles and has lower GPU usage than Area. Experiment with it yourself and compare!

Downsampling is where Area shines. The frick ton of samples and softened resolve allows Area to avoid the downsample aliasing that Bilinear and other resamplers experience. In fact, by combining the area resampler with MSAA and an Internal Resolution much higher than your screen, you can create a DIY SSAA.

Add in some MSAA and the Area downsampler can match SSAA's exceptional picture quality.

However, SSAA is a graphics driver feature that is optimized with your GPU to make it surprisingly efficient, for a brute force technique anyway. A DIY SSAA cannot be faster than a hardware optimized solution! But by being within the users' control, Area provides a lot of interesting downsampling options that we have not had before. Furthermore, SSAA is not so optimal everywhere and may not even be available for everyone. More on that later.

Bicubic uses cubic spline interpolation for its resolve. It comes in three flavors: B-Spline (soft), Catmull-Rom (sharp), and Mitchell-Netravali (medium).

B-Spline is an exceptionally soft upsampler. With extreme temporal stability and minimal noise, B-Spline can give an extremely clean and stable result.

If you ever wanted Dolphin to use a modern display's pixels for a soft image rather than just more and sharper pixels, the softness of B-Spline is for you!

B-Spline's downsampling is kind of inbetween Area and Bilinear.

Add SSAA to 1x Native B-Spline for a silky smooth resolve! All of the detail is still there, but the source pixels have melted into light and shapes. Be sure to click/tap this image, it's something else.

On the opposite end of the spectrum is Catmull-Rom, an extremely sharp upsampler.

Now THIS is a different look for Dolphin! Click/Tap the image for detail!

Downsampling, Catmull-Rom's sharpening is still present and gives some highlights around pixels, but it is significantly weakened.

Mitchell-Netravali is inbetween these two extremes.

For upsampling, Mitchell-Netravali kind of looks like B-Spline and Catmull-Rom combined. It is both softer and sharper than Bilinear.

When downsampling, Mitchell-Netravali more or less just looks like Bilinear, but with a tiny bit of sharpening added on. It's fine.

Sharp Bilinear was previously added to Dolphin as a post processing filter, and now has joined the suite of output resamplers. As we have already covered Sharp Bilinear quite recently, we won't be going into detail here. But in summary, Sharp Bilinear is a best-of-both-worlds combination of Bilinear and Nearest Neighbor, allowing nearest neighbor pixel clarity without its shimmering artifacts. It is primarily designed for upsampling low resolution sprites, but it can be used to upsample 3D graphics if you want unnaturally sharp jaggies. It is not intended for downsampling.

Sharp Bilinear is extremely sharp and ready to upscale pixel art!

It's not made for downsampling, but downsampling Sharp Bilinear... looks like Bilinear. Also it is extremely close to the Mitchell-Netravali image above!

Click the image above to be taken to our previous coverage on Sharp Bilinear. It has animations and everything!

When is Output Resampling Better than Existing Solutions?¶

Output Resampling is primarily focused on providing visual options for players, and it typically isn't outright superior to existing solutions. However, it is very powerful, and during testing, we found several scenarios where Output Resampling is able to create a better result than what was possible before.

EFB Copy Brute Forcing¶

Some games use a large EFB effect that is particularly expensive, and have to render it at a fraction of the game's output resolution. A classic example is the mirrored surface of Fountain of Dreams in Super Smash Bros. Melee.

The mirrored surface is rendered at 1/8th the resolution of the rest of the image!

We don't have to worry about the hardware limitations that lead to these decisions, but the consequences of their choices affect us even today: as these effects are rendered proportional to the game's rendering resolution, they scale proportionally too. No matter what Internal Resolution multiplier we use, the mirrored pool in Fountain of Dreams will always be 1/8th of that. As such, the only way to increase the resolution of these effects relative to the screen (without modding the game) is to increase the Internal Resolution way beyond the screen resolution. But as we have already talked about thoroughly in this section, this will introduce aliasing with the GPU bilinear resampler. Users simply had to deal with this - it was either aliasing or a low resolution reflection.

Until now! Using our Output Resampler (specifically Area), we can raise the Internal Resolution as much as we want without adding aliasing!

Fountain of Dreams can now be seen in perfect clarity!

_{Smash 64 is that you?}

Upsampling to a Close Resolution¶

As mentioned previously, resampling is basically unavoidable in Dolphin due to quirks of the GameCube and Wii. However, if you use the Internal Resolution recommendations we have our in GUI (such as 3x Native for a 1080p screen), the GPU Bilinear Resampler will be good enough that switching to our Area resampler will give only marginal improvements even for pixel peepers. But not everyone has a system powerful enough to run at our recommendations for their screens, and they may have to settle with the highest Internal Resolution their hardware can manage. Depending on their circumstance, our Output Resampler could help them achieve a better image than was possible before.

A good example of this is resampling a 2x Native (1280x1056) 16:9 title into a 1920x1080 canvas. 2x Native nearly matches a 1080p screen vertically (1056 → 1080), but it has significantly fewer pixels horizontally (1280 → 1920).

The GPU Bilinear Resampling clearly exposes the resolution difference, with much softer pixels horizontally.

Our Area resampler gives a sharper and more consistent result under the same circumstances. This is most clear on Pit's rings in the left half of this image.

This benefit of our Output Resampler is highly situational, but it can improve Dolphin's image quality on lower end systems. Experiment and see what works best for you!

Downsampling on Platforms where SSAA is Unviable¶

SSAA has pristine visual quality and surprisingly good performance for a brute force solution. However, that doesn't matter if your system doesn't support SSAA! In desktop land we have been spoiled by SSAA being near universal, but Dolphin's mobile users are now over half of our userbase, and SSAA is uncommon on mobile SoCs. Furthermore, SSAA may be present but not optimal. Adreno in particular hates SSAA! A DIY SSAA made with Output Resampling may be just what a user needs on those platforms.

Unfortunately, our Output Resampler is not yet available on Dolphin Android. We tried our best to hunt down some non-Android devices that lack SSAA or have poor SSAA performance, but the best we had on hand was a 2019 Surface Pro X. While its Adreno GPU absolutely hated SSAA as predicted, it was too weak to serve as a good demonstration.

Once this feature arrives on Android, we have loads of powerful Android tablets to try this on. Stay tuned!

5.0-20193 - Expose Resolutions Multipliers Up to 12x (~8k) by Filoppi¶

Now that we have proper downsampling, we've decided to increase the maximum Internal Resolution exposed by default in our desktop Qt GUI from 8x Native to 12x Native (8K). This will allow users of 4k displays to increase the Internal Resolution beyond their screen for downsampling purposes without editing INIs. For the twelve of you with an 8k panel, now you don't need to set MaxResolution at all! Unless you want to, 8k users tend to have silly hardware so do whatever you want.

That's a lot of pixels.

However, just because Dolphin shows 12x Native in the GUI does not mean that your computer can achieve it. 12x Native is 48,660,480 pixels, or 48.7 megapixels. Currently most computers will run out of VRAM before reaching 12x Native! Statistically speaking your computer will not run this resolution at fullspeed. Use this power responsibly!

This change only applies to our desktop Qt GUI, and does not affect Dolphin on Android. We do not need to explain this.

5.0-20199 - Use LZ4 for SaveState Compression/Decompression by Malleo¶

If you're in the TAS community or relying on constant savestate usage for your project, this is a huge optimization that might make your life a lot easier. Malleo noticed that Dolphin was using LZO for savestates, which has a good compression ratio, but is quite a bit slower than LZ4 when it comes to decompression. By moving Dolphin's savestate compression to LZ4, savestate loading is now ~72% faster.

For the casual users, savestate loads are now snappier. For speedrunners this will make practicing a single trick over and over again take a little less time. But for people using hundreds, thousands, or tens of thousands of savestate loads for TAS creation or AI projects, the savings really start to add up.

This is the kind of work that will be much faster now!

5.0-19415 and 5.0-20126 - Improve JIT Block Lookup Performance by krnlyng¶

To run game code that's been designed for the GameCube and Wii's PowerPC CPU, Dolphin's JIT translates PowerPC machine code into machine code that your computer can run natively. Once a chunk of code has been translated, the resulting code block is stored in Dolphin's JIT Cache so that the code doesn't have to be translated all over again if it needs to run again later.

Usually when we optimize the JIT, the improvement is in how the code gets translated. But this time, krnlyng has improved how quickly Dolphin can start executing the next block after a block is done running. Or to be more specific, how quickly Dolphin can do it in the case where it doesn't know in advance which block comes next.

To find out what block to run, Dolphin has a large table that maps emulated code addresses to the corresponding block of translated code. Before krnlyng's changes, this table was 256 KiB, and doing lookups in the table worked as follows:

Dolphin grabs the lowest 16 bits of the current emulated code address. This results in a number from 0 to 65,535.
The number calculated in the previous step is used as an index in the table. Dolphin reads the table at that index and gets a pointer to JIT block metadata.
Dolphin checks that the pointer isn't 0, and then reads the JIT block metadata. If the pointer is 0, the code hasn't been translated yet, so Dolphin has to go and translate it before it can continue.
Dolphin checks that the emulated code address stored in the JIT block metadata matches the current emulated code address. Sometimes, the address might not match because two different emulated addresses have been mapped to the same index in the table. In that case, Dolphin has to use a much slower piece of code to find the right block.
Dolphin checks that the IR and DR bits of the MSR register match. We'll skip the details, but this is very similar to the previous step.
Dolphin gets the pointer to the translated code from the JIT block metadata, and jumps to it.

After the changes, Dolphin has a new table that's 32 GiB in size, and doing lookups in it works as follows:

Dolphin takes the entirety of the current emulated code address and prepends the MSR bits that were mentioned earlier. This results in a number from 0 to 17,179,869,183.
Dolphin reads the table at the index calculated in the previous step and gets a pointer directly to the translated code.
Dolphin checks that the pointer isn't 0. Like before, a 0 means that Dolphin has to stop what it's doing and go translate the code.
Dolphin jumps to the pointer.

This not only gets rid of the problem of different emulated addresses sharing the same index in the table, but also lets us skip reading the JIT block metadata entirely! But you may have an important question: How the heck is Dolphin going to fit a 32 GiB table into RAM when many computers and all phones have less total RAM than that?

In reality, Dolphin isn't asking the operating system for 32 GiB of real memory. Instead, it sets up 32 GiB of address space and asks the operating system to only allocate memory as needed. The first time Dolphin tries to access any given section of the 32 GiB table that isn't backed by real memory, the operating system allocates a small chunk of memory on the fly and fills it with zeroes. In the end, this new table can use a few more megabytes of memory than the old table, but nowhere even near 32 GiB.

In an ideal world, that would be all we have to say about the new solution. But for Windows users, there's a special quirk. On most operating systems, we can use a special flag to signal that we don't really care if the system has 32 GiB of real memory. Unfortunately, Windows has no convenient way to do this. Dolphin still works fine on Windows computers that have less than 32 GiB of RAM, but if Windows is set to automatically manage the size of the page file, which is the case by default, starting any game in Dolphin will cause the page file to balloon in size. Dolphin isn't actually writing to all this newly allocated space in the page file, so there are no concerns about performance or disk lifetime. Also, Windows won't try to grow the page file beyond the amount of available disk space, and the page file shrinks back to its previous size when you close Dolphin, so for the most part there are no real consequences... unless you like to download large files while running Dolphin.

We will look into improving the situation on Windows, but for the time being, please don't be alarmed if you see a sudden decrease in available disk space when running Dolphin.

5.0-20201 - Increase FarCode/NearCode Cache Sizes by dreamsyntax¶

When playing certain games for an extended time, Dolphin's JIT Cache has an annoying tendency to run out of space. The most prominent example is of games like Metroid Prime 2: Echoes where the game can dynamically load code into different places in memory. An even more difficult case is N64 Virtual Console games, like The Legend of Zelda: Ocarina of Time which use a recompiler to generate code on the fly. Once either the FarCode or NearCode cache is full, they must both be flushed, wiping both old and current data in the cache. This forces the JIT to rebuild all the code the game currently is running on the fly, leading to a noticeable stutter that cannot be avoided.

A huge step that mostly remedied this situation was merged back in 2021 which allowed Dolphin to evict code from the JIT Cache that the game itself invalidated. However, It wasn't a perfect solution. Dolphin was reliant on the game invalidating code, but sometimes games just don't, especially if they happen to be a trashfire like True Crime: New York City. Also it couldn't actually defragment evicted code, meaning that the longer the game was running, the more fragmented the caches would become. If there was no longer enough space to fit a chunk of code, a full flush would be required. Back in 2021, we mentioned that the ability to just use a bigger JIT Cache was still on the table, but we were worried about its ramifications and hoped it would not be necessary.

Fast forward to today, and dreamsyntax made a proposal to expand the JIT Cache. As part of it, they showcased a game that blew away all of our tricks: Shadow the Hedgehog. It generates just enough code that it created a consistent, rhythmic, annoying stutter due to the JIT Caches filling up and flushing every 15 - 30 minutes.

The pauses. Are very. Consistent.

dreamsyntax showed that enlarging the JIT Cache completely eliminated the JIT Cache flushes in Shadow the Hedgehog, and showed many other games that benefitted from it as well. They made a compelling case, so with a little hesitation, we pulled the trigger. As of this change, the JIT Cache has been enlarged!

However, all of the things we were worried about with a larger JIT Cache, such as longer more severe stutters, just didn't happen. The JIT Cache flush stutters that we have observed take the same amount of time, yet they happen MUCH less frequently if ever. In fact, the potential to have a cache flush stutter is now pushed so far into a play session that it is outside the usual play session for most users! Players may never see a JIT Cache flush stutter again as of this change! It makes us feel a little silly that we were so hesitant to enlarge the cache.

So far it appears that this is the JIT Cache flush stutter solution we have all been waiting for. Hopefully that holds true, as any further improvements to the JIT Cache from here will be much harder.

Note: This change only applies to our x86-64 JIT, and does not affect our AArch64 JIT for ARM systems. Due to architectural differences, raising the AArch64 JIT Cache size beyond 128 MiB would require special solutions.

5.0-20148 - Periodically Re-enable Steam Deck Gyro by ArcaneNibble¶

In the latest version of SteamOS, the gyro is disabled whenever SteamOS thinks the gyro is not being used. This includes situations like opening the Steam Deck's menus, which users might do quite frequently! For Dolphin, this would make the gyro suddenly stop working for unknown reasons, with no clear way to reenable it. We're not sure why this behavior changed, but we have no choice but to find some way to deal with it.

ArcaneNibble came up with a clever workaround. Rather than try to detect when the gyro is enabled/disabled, Dolphin will try to re-enable the gyro roughly every second or so. If it's already enabled? No harm, no foul. If it's disabled, it'll usually get re-enabled quickly, hopefully before the player even noticed it was disabled.

This will make playing some of your favorite Wii games on the latest version of SteamOS a lot more enjoyable, without you having to worry about the motion controls suddenly breaking for previously unknown reasons.

5.0-20097 and 5.0-20109 - Allow Widescreen Heuristic to be Modified Per-Game by OatmealDome and Billiard¶

As an emulator for consoles in the 4:3 to 16:9 transition, players can expect to encounter many different aspect ratios as they play their library in Dolphin. So users don't have to change our aspect ratio setting with each game, we have a widescreen heuristic which detects how wide of an image the game is rendering and sets Dolphin accordingly.

The widescreen heuristic works magically! ....usually.

Unfortunately, being a heuristic, Dolphin is effectively making an informed guess as to what aspect ratio the game wants. And sometimes, a game is able to fool our heuristic and create wildly inconsistent results!

Oh no.

Metroid Prime 2, Pokémon Colosseum and a few other games render certain effects with a viewport size that tricks our heuristic!

Unfortunately, we couldn't fix this by just changing what threshold the heuristic uses, as this would create false negatives - situations where the heuristic should have changed the aspect ratio but didn't. Regressions would be inevitable. Fortunately, there is a very simple solution available to us - our GameINIs. As of this change, the parameters used by our widescreen heuristic can be be overridden by our GameINIs. If we know a game is problematic for our heuristic, we can tweak how the heuristic behaves for that game without affecting any other games!

With that said, none of our GameINIs have had any parameters added yet. For the time being, you'll still run into problems in games like Pokémon Colosseum, but now that we have a workable system we can move forward with figuring out what parameters are needed for each problematic game.

5.0-20041 - Add Support for Touchscreen Latching (Toggle) Buttons by ThunderousEcho¶

Sometimes playing certain games in Dolphin on a touchscreen feels like an impossible challenge that would require another couple of hands and maybe a few extra fingers. For our touchscreen gamers, ThunderousEcho comes in with the ability to change various buttons on the touchscreen to be toggled instead of having to hold them down. This is known as a latching button, and is effectively the same as a toggle button in Dolphin's input system for physical controllers.

Simply tap the button once to have it "held" and then tap it a second time to release it. This is a simple addition, but it opens up the touchscreen controls a lot to be able to play more games on a touchscreen device. If you don't have a controller for your phone/tablet, or just prefer the single device form factor, latching might be the feature you need to play your favorite game.

You can find the feature in the side menu, under Overlay Controls > Latching Controls.

5.0-20001 - Another PanicAlert Deadlock Fix by JosJuice¶

If you're a veteran of the Dolphin Progress Reports, you're well aware of the eternal battle with PanicAlerts and the seemingly random deadlocks they can cause in combination with certain settings. Thankfully, another one bites the dust as JosJuice fixes a hang that could happen when pressing the "Ignore for this session" button in a PanicAlert.

Is this the end of the PanicAlert deadlocks? Has our lovable villain finally been felled in such an anti-climatic manner? Find out next time on Progress Report Z.

Last Month's Contributors...¶

Special thanks to all of the contributors that incremented Dolphin from 5.0-19872 through to 5.0-20347!

Dolphin Progress Report: May, June, and July 2023

2023-08-13T05:59:25+00:00

It has been a bit of a tumultuous summer for the project, but now things are returning to normalcy. For those who somehow missed it, the Dolphin on Steam project has ceased after contact between Valve and Nintendo. Though we disagree with their stance and decision, we respect Valve's right to impose whatever restrictions they want within their private storefront. Please read the full article for details.

Fortunately, all that means is that nothing is going to change. We're going to continue working hard to improve Dolphin and make it the best emulator it can be.

Speaking of which, we hope you enjoy this Dolphin Progress Report!

Notable Changes¶

5.0-19611 - Implement Custom Driver Support by K0bin¶

GPU drivers for Android devices have come a long way from the nightmare they once were, but they still lag behind their desktop counterparts in many ways. Missing features, performance problems, and plain old bugs are still plentiful on Android drivers. Furthermore, while drivers are improving over time, these improvements rarely make their way to existing devices, which is considerably worse than desktop. However, for Dolphin, Android GPU drivers are now at least good enough to work most of the time. There may be bugs or issues, but usually you'll get an image and the emulated title will function.

Emulators for newer consoles weren't so lucky, however, and Android drivers have been an intense pain point for them. This spurred ByLaws to take action and develop the library libadrenotools, which lets apps temporarily switch out the system driver for a user-provided driver. libadrenotools has tremendously improved the experience of emulating newer consoles on Android devices, as not only does it allow loading of newer versions of official drivers, but it also allows the loading of unofficial open source drivers that are substantially better than their official counterparts. Specifically of note is Freedreno Vulkan, also known as Turnip. It's a custom driver primarily for Adreno 600 GPUs (though support for Adreno 700 GPUs is in development as well) that is by far the most complete Vulkan driver available for Adreno.

K0bin saw all of the improvements that libadrenotools and Turnip granted other emulators and realized that Dolphin could take advantage of them too. With this change, libadrenotools is now integrated into Dolphin, allowing Android users to choose which Vulkan GPU drivers they prefer. While Android driver issues were not as critical for us, the Freedreno driver is a breath of fresh air. Tons of Vulkan issues that have plagued our Adreno users are gone when using it.

For unknown reasons, paletted EFB copies are among the broken features on Adreno.

Turnip just works.

If your GPU is among those supported, Turnip offers an opportunity to get a driver that's much closer to desktop quality. However, we've only been talking about compatibility and bugs so far. How does Turnip compare to the official drivers in performance? Well, performance can be better, but it isn't always going to be. Sometimes the more complete implementation of features allows Dolphin to go faster than other drivers, sometimes the fact it's able to emulate things in a more complete manner means that the game might run a little slower. And, of course, the driver might not implement all features optimally, causing some variations that are out of the control of Dolphin.

Using an older phone, we can compare the Turnip driver to the latest supported Adreno driver and compare performance. We also compared to the Adreno OpenGL driver - as Turnip is for Vulkan only. All tests were done at 1x internal resolution in order to test the raw efficiency of the driver to keep maximum performance.

The results vary quite a bit, with a different driver being faster for each game! However, for the most part performance is pretty similar between the different backends with the main benefit being that Turnip mostly just works. While there are the occasional bugs, much like with the official Adreno drivers, overall Turnip provides a more consistent experience. And with it under active development, the problems we have seen are likely to get fixed.

A Note to Non-Adreno Users¶

There is nothing fundamentally Adreno-specific about loading custom drivers. Unfortunately for users with other GPUs, there aren't any viable custom drivers at this time. If custom drivers do show up for these devices, we'll be able to update Dolphin to load them.

5.0-19274 - Add WiiConnect24 Support via WiiLink by Sketch¶

When WiiConnect24 shut down so suddenly just over ten years ago in June of 2013, there was a thought among Dolphin developers that WiiConnect24 would never be emulated - at least in Dolphin. For nearly 10 years, that remained true. However, a lot of the core features of WiiConnect24 were still missing in Dolphin, and setting it up required use of third party tools to patch channels.

In the latest builds of Dolphin, users can now enable WiiConnect24 directly in Dolphin's GUI, allowing you to use the Forecast Channel, Nintendo Channel, and soon the News Channel and Everybody Votes Channel directly in the system menu without the need for patching channel files. This is all thanks to Sketch (aka noahpistilli) who is both implementing critical features in Dolphin's Network/KD and reimplementing the servers which the channels themselves communicate with as the lead developer of WiiLink.

This marriage between the two sides of development has led to a WiiConnect24 revolution within Dolphin, and more features will be coming online in the future.

Here is a short demonstration video of the Forecast Channel made in Dolphin with WiiLink, showing the many cities that the channel supports! With the Wii console set to the United States, a total of 904 cities are available to view!

With Dolphin adding support for WiiLink, does this mean RiiConnect24 will not work in Dolphin? Of course not! The same methods used to patch channels with RiiConnect24 will continue to work in the latest versions of Dolphin.

Choosing between WiiLink and RiiConnect24 for a default service was not an easy task. RiiConnect24 has been an invaluable part of the WiiConnect24 preservation scene and will continue to work in Dolphin. However, with Sketch working on both the server side (WiiLink) and the client side (Dolphin), compatibility and stability is currently higher with WiiLink. As well, there are some features of RiiConnect24 that use cIOS features that do not currently work in Dolphin that are handled without cIOSes in WiiLink.

Something to keep in mind is that Dolphin's priority is to emulate WiiConnect24 to the best of its ability. Currently, Sketch is reimplementing WiiConnect24 features in a manner that would work alike to the original WiiConnect24 servers. We are aware that some bugs/inaccuracies in Dolphin's implementation of Network/KD that, when fixed, will require changes from RiiConnect24 in order to maintain compatibility.

We also request that users who have used the RiiConnect24 VFF downloader delete any VFF files created by it, as well as disable the downloader. The VFFs created by it are made to never expire, meaning new files will never be downloaded by Dolphin. To locate these, click File -> Open User Folder and then navigate to Wii/title/00010002/484146xx/data for the Forecast Channel and Wii/title/00010002/484147xx/data for the News Channel, where xx is 45 for NTSC-U consoles, 50 for PAL and 4a for Japanese. If you're having problems with WiiLink/RiiConnect24 on the latest builds and have used the VFF downloader in the past, that may be the source of your troubles.

Note for those who want to use an unmodified Nintendo Channel: Cheats must be enabled in order for the channel to work.

5.0-19448 - Android - Disney Infinity Base Support by deReeperJosh¶

If everyone is being honest, there probably isn't much point to this feature, at least right now. The only game that supports the Disney Infinity Base on the Wii is Disney Infinity, possibly the crown jewel of the Disney Trio of Destruction. There is no existing desktop computer that can run the game full speed given how Dolphin currently emulates the game. For phones, the situation is even worse.

Note the FPS in this screenshot. Disney Infinity will not even get close to fullspeed on any device currently available, so don't get your hopes up.

But, maybe some day, some AArch64 JIT improvement and/or some future phone will somehow emulate Disney Infinity at a playable framerate. Whenever that happens, future Android users will be able to emulate the Infinity Base and get in game without the need for physical hardware.

5.0-19554 - Android - Fix Trigger Detection Issue by JosJuice¶

After the release of the input handling rewrite a few months ago, there have been a few growing pains. A rather annoying one for many users was an issue causing trigger inputs from certain controllers to simply be ignored in the menu. More frustratingly, you could actually manually add them if you knew your way around the advanced mapping options!

This turned out to be relatively easy to fix in the end, though. The input handling rewrite brought a lot of code from the PC version of Dolphin to the Android version, including a piece of code that is designed to skip over button inputs in case a gamepad provided both a button input and an axis input for a trigger at the same time. But the affected controllers on Android were doing something that the PC version of Dolphin had never ran into: each trigger provided two axis inputs. Because the code wasn't expecting this, both of the inputs were getting skipped by accident. With the cause of the problem known, JosJuice was able to change the code to let both inputs through.

Users that suffered from this regression should be able to configure their controllers directly in the GUI again in the latest Play Store release.

5.0-19863 - Add Filesize Checks to Check NAND by AdmiralCurtiss¶

With the Wii NAND coming more to the forefront with some of Dolphin's latest features, Check NAND has been seeing a lot more usage. The long-story-short of it is that the Wii File System is extremely tempermental and prone to breaking, so back in the day leoetlino created a feature that allowed Dolphin to check the Wii NAND for certain common problems and automatically fix them.

Check NAND was mostly a tool used to fix the NAND to get the Wii Shop and Dragon Quest X working - as even the slightest problem with the NAND would prevent them from booting. However, it wasn't designed to fix everything, and it'll often say no problems found when in fact there are critical problems with the NAND.

Enter AdmiralCurtiss. Having debugged an issue where a user's NAND was "overfilled" due to spurious files being placed in the NAND directory, they decided that it was time to expand the scope of Check NAND a bit more. In the latest versions of Dolphin, Check NAND will now make sure that the NAND size is within the bounds of the Wii NAND.

On a modern computer with terabytes of storage, you might think that the Wii NAND being limited to just 512MB is a bit archaic and that Dolphin should just allow any NAND size. And we technically do - you can keep adding things to the NAND even if it is over that maximum size. Unfortunately, the Wii System Menu and many games have checks to make sure that the NAND isn't getting close to full. Even if we tell the Wii it has way more NAND space, it is hardcoded to use exactly 512MB, with certain portions of it being reserved.

In the past, Dolphin has tried to lie to the emulated Wii about the size of installed files, saying that they were one block no matter how big they were, but this just caused other problems and we ran into other limitations even in situations where that hack did seem to help. So for now, we're handling things as accurately as possible in order to make sure users don't jeopardize their Wii Save Data.

It's possible there is some magic combination of hacks that could maybe trick the emulated Wii into supporting more/bigger files, but so far we haven't found it. And considering how many people run into the Wii's paltry NAND size limits, a hack like this wouldn't see much resistance into being merged as an option.

5.0-19716 - Support Accurate NTSC/PAL Color Spaces by Filoppi¶

The GameCube and Wii were designed with analog CRT televisions in mind. In this era, "close enough" was the rule of the day. For example, each region had their own slightly different color spaces and gamma targets. Games almost never accounted for these differences, so how each game would appear varied slightly from region to region! To emulate this, Filoppi (helped by Lilium) has implemented a suit of color space and gamma correction settings.

Dolphin's color correction provides several color space options. Using these profiles, you can now set Dolphin to match the colour space of any given region and either make it match how you remember it in your region, or just see how your game would look in an entirely different region!

This is the unmodified color space. Click/Tap and hold to see the NTSC-M color space.
The difference is VERY subtle.

Something a little more impactful from these changes is gamma correction. Most GameCube games (and some Wii games) targeted a gamma value of roughly 2.35. Modern televisions and monitors normally use a value of 2.2, which can result in these games looking a tiny bit brighter than they would have (by default) on hardware of the day.

This is the normal image. Click/Tap and hold to see the gamma corrected version.
The gamma corrected version has subtly crushed blacks for a slightly spookier vibe.

While it's possible for users to adjust their monitor's settings, and some games come with built-in gamma correction, Filoppi added gamma correction to the color space features within Dolphin's settings in order to streamline the experience.

Note that these settings and features have not been ported to the Android version of Dolphin yet, however that is in progress.

Last Month's Contributors...¶

Special thanks to all of the contributors that incremented Dolphin from 5.0-19370 through to 5.0-19870!

What Happened to Dolphin on Steam?

2023-07-20T08:11:32+00:00

Well that blew up, huh? If you follow emulation or just gaming on the whole, you've probably heard about the controversy around the Dolphin Steam release and the Wii Common Key. There's been a lot of conclusions made, and while we've wanted to defend ourselves, we thought it would be prudent to contact lawyers first to make sure that our understanding of the situation was legally sound. That took some time, which was frustrating to ourselves and to our users, but now we are educated and ready to give an informed response.

We'd like to thank Kellen Voyer of Voyer Law for providing us with legal council for this matter. And to be clear, all of the analysis below is specifically regarding US law. Without further delay, let's begin.

What actually happened?¶

First things first - Nintendo did not send Valve or Dolphin a Digital Millenium Copyright Act (DMCA) section 512(c) notice (commonly known as a DMCA Takedown Notice) against our Steam page. Nintendo has not taken any legal action against Dolphin Emulator or Valve.

What actually happened was that Valve's legal department contacted Nintendo to inquire about the announced release of Dolphin Emulator on Steam. In reply to this, a lawyer representing Nintendo of America requested Valve prevent Dolphin from releasing on the Steam store, citing the DMCA as justification. Valve then forwarded us the statement from Nintendo's lawyers, and told us that we had to come to an agreement with Nintendo in order to release on Steam. Considering the strong legal wording at the start of the document and the citation of DMCA law, we took the letter very seriously. We wanted to take some time and formulate a response, however after being flooded with questions, we wrote a fairly frantic statement on the situation as we understood it at the time, which turned out to only fuel the fires of speculation.

So, after a long stay of silence, we have a difficult announcement to make. We are abandoning our efforts to release Dolphin on Steam. Valve ultimately runs the store and can set any condition they wish for software to appear on it. But given Nintendo's long-held stance on emulation, we find Valve's requirement for us to get approval from Nintendo for a Steam release to be impossible. Unfortunately, that's that. But there are some more serious matters to discuss, some that are much bigger than Dolphin's Steam Release.

What about the key?¶

Over the past few weeks, a lot has been said about Dolphin including the Wii Common Key. As you may know, Wii games are encrypted, and the Wii uses the "common key" that is burned into the console to decrypt Wii discs. Wii software does not have any access to the key whatsoever, however, some smart engineers and a pair of tweezers was all it took to extract the key. If you haven't heard this story before, we highly recommend checking out the 25c3 presentation on the actual Tweezer Exploit that gave Team Twiizers its original name. It's an incredibly entertaining video that's worth your time. If you aren't familiar with Team Twiizers, perhaps you know them under their modern name: fail0verflow.

The extraction of the Wii Common Key did not elicit any kind of legal response from anyone. It was freely shared everywhere, and eventually made its way into Dolphin's codebase more than 15 years ago (committed by a Team Twiizers member no less).

These keys have been publicly available for years and no one has really cared. US law regarding this has not changed, yet a lot of armchair lawyers have come out talking about how foolish we were to ship the Wii Common Key. Fueling this is Nintendo's letter to Valve, which cites the anti-circumvention provisions of the DMCA (17 U.S.C. § 1201), particularly because Dolphin has to decrypt Wii games.

Wii and Nintendo GameCube game files, or ROMs, are encrypted using proprietary cryptographic keys. The Dolphin emulator operates by incorporating these cryptographic keys without Nintendo’s authorization and decrypting the ROMs at or immediately before runtime. Thus, use of the Dolphin emulator unlawfully “circumvent[s] a technological measure that effectively controls access to a work protected under” the Copyright Act. 17 U.S.C. § 1201(a)(1). Distribution of the emulator, whether by the Dolphin developers or other third-party platforms, constitutes unlawful “traffic[king] in a[] technology . . . that . . . is primarily designed or produced for the purpose of circumventing a technological measure . . . .” 17 U.S.C. § 1201(a)(2)(A).³
Nintendo's Letter to Valve

This sounds extremely bad at a glance (and we certainly had a moment of panic after first reading it), but now that we have done our homework and talked to a lawyer, we are no longer concerned.

We have a very strong argument that Dolphin is not primarily designed or produced for the purpose of circumventing protection. Dolphin is designed to recreate the GameCube and Wii hardware as software, and to provide the means for a user to interact with this emulated environment. Only an incredibly tiny portion of our code is actually related to circumvention. Additionally, GameCube games aren't actually encrypted at all, and Dolphin can also play homebrew and is used in the development of game mods. There are even homebrew and mods that specifically target Dolphin as its own platform, given that it has the ability to emulate more memory and processing power than is possible on the original consoles. That's why there are "Dolphin modes" in many modern homebrew games!

Considering that only a small fraction of what we do involves circumvention, we think that the claim that we are "primarily for circumvention" is a reach. We do not believe this angle would be successful in a US courtroom, if it were ever to come to that. The reason the lawyers representing Nintendo would make such a leap is because they wished to create a narrative where the DMCA's exemptions do not apply to us, as these exemptions are powerful and widely in our favor. Of particular note for Dolphin is the reverse engineering exemption in 17 U.S.C. § 1201(f) which states that:

...a person may develop and employ technological means to circumvent a technological measure, or to circumvent protection afforded by a technological measure, in order to enable the identification and analysis under paragraph (1), or for the purpose of enabling interoperability of an independently created computer program with other programs, if such means are necessary to achieve such interoperability, to the extent that doing so does not constitute infringement under this title.
17 U.S.C. § 1201(f)(2)

Dolphin is an independently created computer program that is circumventing Wii disc encryption for interoperability with Wii software. According to this exemption, this does not constitute infringement under 17 U.S.C. § 1201. This exemption even allows distribution of information collected through circumvention, like encryption keys, if it is for software interoperability.

The information acquired through the acts permitted under paragraph (1), and the means permitted under paragraph (2), may be made available to others if the person referred to in paragraph (1) or (2), as the case may be, provides such information or means solely for the purpose of enabling interoperability of an independently created computer program with other programs, and to the extent that doing so does not constitute infringement under this title or violate applicable law other than this section.
17 U.S.C. § 1201(f)(3)

17 U.S.C. § 1201(f) is a significant legal protection for emulation in the US, and it is why Nintendo has yet to legally challenge any emulator with the DMCA anti-circumvention clauses despite the law going into effect 25 years ago. Unless a court rules that our understanding of the law is incorrect, we have every reason to believe that our decryption of Wii game discs is covered by this exemption.

After this situation blew up, we received many requests, and even some demands, to remove all Wii keys from our codebase. We're disappointed that so many people on YouTube and social media didn't even consider that maybe the team had done their research and risk analysis before including the keys, and just assumed that now that it was "pointed out to us" we would remove them. However, we do not think that including the Wii Common Key actually matters - the law could easily be interpreted to say that circumventing a Wii disc's encryption by any means is a violation. As such, it is our interpetation that removing the Wii keys would not change whether the exemption in 17 U.S.C. § 1201(f) applies to us or not.

In fact, we think that offloading decryption tasks onto a potential 3rd party application would make the situation worse for everyone. As such, we believe leaving the keys as they are is the best course of action.

And to all the armchair lawyers out there, the letter to Valve did not make any claims that we were violating a US copyright by including the Wii Common Key, as a short string of entirely random letters and numbers generated by a machine is not copyrightable under current US copyright law. If that ever changes, the world will be far too busy to think about emulation.

What happens now?¶

We do not believe that Dolphin is in any legal danger. We can look to the end of the message Valve forwarded to us to show this. After all of the scary language, Nintendo made no demands and made only a single request to Valve.

We specifically request that Dolphin’s “coming soon” notice be removed and that you ensure the emulator does not release on the Steam store moving forward.
Nintendo's Letter to Valve

In the end, Valve is the one running the Steam store front, and they have the right to allow or disallow anything they want on said store front for any reason. As for Nintendo, this incident just continues their existing stance towards emulation. We don't think that this incident should change anyone's view of either company.

As a silver lining, some of the features being developed for the Steam release will still work in Dolphin's normal builds, and are still being developed. One of the features we are most excited for is a full "Big Picture" GUI that can be used directly with a controller. That is still going to happen regardless of a Steam release, alongside several smaller features that were meant to be quality of life improvements for Steam builds.

The last thing we'd like to do before signing off is thank the developers who put a lot of effort into the Steam release. OatmealDome in particular was the architect of Dolphin's Steam Integration, working with Dolphin's infrastructure and Steam to take it from theory all the way to a fully-functional version of Dolphin. We'd also like to thank delroth for the immense amount of CI work the past few months, which gave OatmealDome a solid foundation to build from. Finally, MayImilae put in a large amount of media work toward the Steam release despite also working on a major upcoming feature.

Dolphin on Steam Indefinitely Postponed

2023-05-26T23:19:02+00:00

It is with much disappointment that we have to announce that the Dolphin on Steam release has been indefinitely postponed. We were notified by Valve that Nintendo has issued a cease and desist citing the DMCA against Dolphin's Steam page, and have removed Dolphin from Steam until the matter is settled. We are currently investigating our options and will have a more in-depth response in the near future.

We appreciate your patience in the meantime.

Dolphin Progress Report: February, March, and April 2023

2023-05-21T07:27:22+00:00

It's been a hectic past few months for the project. In addition to the upcoming release on Steam, a lot of focus has gone into other major features. While not everything has landed yet, two very important changes to Android did arrive, one of which has been in the works for a couple years!

We're talking about a large scale rewrite to Dolphin's Android Input Handling that will eventually allow it to match the feature set users on Desktop Dolphin builds enjoy. Android users also get another major quality of life upgrade - Dolphin is now a Document Provider on Android. This means you can use Dolphin to directly copy files into and out of its per-app directory on the latest versions of Android.

In this report, we'll be going through both of these and several other important changes. Enjoy!

Notable Changes¶

5.0-18920 - Rewrite Android Input Handling by JosJuice¶

Over ten years ago, back in the ancient time known as "late 2012", Sonicadvance1 started development on a new Dolphin JIT that could run on ARM processors. Back then it was an incredibly bold move - there were no ARM devices that even had a prayer of running Dolphin close to full speed. It was a forward thinking project that took on many incredibly difficult hurdles.

While today the ARM JIT is mostly used on Android phones, the early ARM JIT development was done on development boards and Chromebooks running Linux. Phones simply didn't have the features/speed to even hope to run Dolphin at that point. However, once phones began to appear with the bare minimum featureset required to run Dolphin, Sonicadvance1 began work on porting Dolphin to Android using the new ARM JIT. And thus, a new challenge appeared for Sonicadvance1 - Android itself.

One of the biggest annoyances with Dolphin on Android comes from Android's interfaces being written in Java versus Dolphin's being written in C++. In order to bridge these two languages together, we have to use JNI (Java Native Interface). In order to go the path of least resistance and get things working, Sonicadvance1 decided to just make a quick reimplementation in Java. It was less code overall at the time and meant things could be working more easily. Less time spent working on input meant more time working on the fun parts.

However, the quick implementation that Sonicadvance1 threw together just... remained, with feature after feature bolted onto it over a decade. This is how Dolphin's Android's Input fell into such a problematic state. Plus, it was separate from Dolphin's C++ input implementations, so any improvements had to be manually ported over. Most of the time the latest input features simply wouldn't come to Dolphin Android.

To rectify this situation, Android's entire Input system had to be ripped out and started anew.

Android Controller Support Reborn¶

For the past couple of years, users have been desperately asking for improvements to Dolphin's Touch Controls and Android Controller Support. We've continually turned them away, promising that work was being done on it. While it was possible to hack improvements into the Java implementation, it would have been a temporary band-aid fix. These fixes would then have to be thrown out if a proper fix was ever to come into fruition, which we knew was coming.

Behind the scenes, JosJuice has been slowly removing all of the Java reimplementations of C++ parts of Dolphin on Android and moving them over to JNI. While there were multiple parts of Dolphin reimplemented in Java, input handling was one of the biggest and most convoluted. It proved to be a much more difficult task than the other sections.

Part of the problem is that input handling in Dolphin is complicated. We have to give users options to deal with motion controls, infrared, controller orientation, swapping attachments, swapping controllers, and more. Depending on what kind of controller you have, you might need entirely different features to play through a game. Worse yet, you might need entirely different settings to play two different games.

The project to port the handling over to JNI so we can use the C++ implementation directly has been a multiyear endeavor. And while the initial work has been merged, not everything is fully complete yet. JosJuice had to move out some parts of it in order to keep the pull request reviewable and to avoid regressions that haven't been hammered out quite yet. Still, the JNI port of Dolphin's input handling already has a ton of long requested features!

The Advanced Input Page finally reaches Android greatly opening the door for more advanced input schemes.

You can change controller settings while emulation is running.
You can save and load input profiles. (The old feature of per-game mappings is replaced by per-game input profiles.)
Advanced input expressions.
You can map your device's accelerometer and gyroscope to whatever you want, not just Wii Remote motions.
Support for many new device sensors. (How about the ambient light level, or the hinge angle of a foldable phone?)
If a device or gamepad has multiple motors, you can now choose between them for rumble. (Requires Android 12 or later.)
You can set many boolean and numeric controller settings that weren't available on Android before, like Relative Input.
The Sideways Wii Remote setting, the numeric settings for Wii Remote pointing, and the setting for disabling accelerometer/gyroscope pointing have been moved from the in-emulation settings to the regular settings.
The touchscreen controller type setting has been overhauled. Users can now choose between all controllers 1-4, but selecting a Wii Remote extension is now done in the regular settings.
Separate gamepads are never treated as a single gamepad anymore.
Dolphin no longer mixes up buttons and axes that have the same ID.
Possibly fixes for various issues with detecting axes.

Because Android now uses the same input core as desktop builds, this will allow newer input features to hit Android builds at a more consistent rate. This does come with one caveat - all configurations for the old Android Input will no longer work on new builds, meaning users will have to reconfigure controllers under the new system.

5.0-18922 - Android: Implement Document Provider Support by K0bin¶

With Scoped Storage and the per-app directories in modern versions of Android, modifying Dolphin's user contents has gotten a lot harder. The days of just having a typical "User Directory" in an easy-to-access place on Android are gone. We're stuck using gated per-app directories that only Dolphin can access. The problem with that, is that if you want to modify those files to add a Texture Pack or Riivolution mod, you more or less have to use a computer or something that bypasses Android's restrictions altogether!

In an effort to mitigate these problems, JosJuice added the ability for users to import/export the entire user directory via zip files. Unfortunately, it seems many Android distributions use non-standard zip formats that our basic implementation couldn't handle for unknown reasons. A better long-term solution was needed.

Thankfully, other emulators have run into the same issues as us and have come up with some rather robust solutions. K0bin implemented Document Provider Support to allow file managers with that feature to access Dolphin's per-app directories!

Document Provider Support allows easier access to per-app directories.

5.0-19234 added some further improvements, as well as a distinction between "debug" and "release" builds in order to reduce confusion when handling user directories.

5.0-18957 - Fix Wii Remote Disconnect Deadlock by Dentomologist¶

A common complaint with using Real Wii Remotes for Emulated controllers is that if the Wii Remote were to suddenly disconnect from Dolphin, sometimes the entire emulator would go down with it! Because the problem wasn't especially consistent, tracking it down was annoying until Dentomologist came up with a fairly consistent method of triggering the crash.

Once reproducing the crash was sorted out, they found a potential deadlock with device population while debugging it. By putting safeguards to prevent this deadlock, Dentomologist fixed the crash and now disconnecting Wii Remotes should be quite a bit safer.

5.0-18576 - Kill Renderer by phire¶

Not all big changes are supposed to have an immediate impact. Kill Renderer is something, that if implemented correctly, should cause nothing to change for the time being. It's just a step toward some more important changes down the line, and the reason that it is necessary requires us to dive into Dolphin's history and learn a bit about this mysterious "renderer".

Renderer exists because Dolphin was originally a plugin based emulator, much akin to the Nintendo 64 emulators being developed during that era, and Renderer was the abstraction interface for those plugins. Though Dolphin moved away from plugins fairly quickly, Renderer managed to stick around, consuming work that really should have been elsewhere in the emulator.

This design philosophy did have some limitations, but for the most part it stayed out of the way. At least, until phire began working on a feature called asynchrounous presentation. Right now, all logic in Dolphin's output (including various GUI element like ImGui) are based on the framerate of the game. This is what causes Dolphin's overlays to look "choppy" in low FPS games (like in True Crime: New York City) and causes them to completely freeze during periods when a game stops outputting frames (such as during static loading screen or fadeout). Asynchorous presentation would allow us to decouple our output from the game's framerate, correcting all of those issues and paving the way for future goals.

One of those goals is to improve our framepacing. Outside of the very specific circumstance where your display happens to closely match the game's framerate, our framepacing is horrendous. While Freesync/Gsync monitors can mostly mitigate this, most monitors aren't happy with the locked 29.97, 50, or 25 framerate of many supported games. We can't really do much about this when presentation is locked to the game's framerate, so asychronous presentation will be the foundation of our efforts to improve our framepacing.

Kill Renderer is not asynchronous presentation, but it is a major step in that direction. We're highlighting it here because it is a major change to Dolphin's core, and while it shouldn't have any userfacing changes, we've already found and fixed a couple of major (and minor) bugs caused by the change.

5.0-18953 - Portal of Power - Support TrapTeam Audio by deReeperJosh¶

This is a quick update to our Portal of Power emulation. Skylanders: Trap Team introduced a speaker on the portal that could play various audio clips throughout the game.

Understanding the audio packets was a bit complicated, so the emulated portal skipped over this feature initially, but given a little more time, deReeperJosh was able to figure out how it worked and borrowed some code from Dolphin's support for Wii Remote Speaker output in order to make it play over the user's speakers.

Trap Team Audio Demonstration Directly from the Developer.

5.0-19334 - Implement Infinity Base by deReeperJosh¶

Speaking of figurine portals, the Portal of Power wasn't the only USB portal on the Wii. And with deReeperJosh already kneedeep in USB portal work, they set their sights on another "portal" accessory for Wii. This time, it'd be the Disney Infinity Base. Disney Infinity was Disney's answer to the Toy Portal fad that hit during the 7th generation of consoles. By leveraging Disney's vast array of characters, settings, and overall brand, they set out to leverage that into a collectable figurine game.

Unlike Skylanders, which had an overall story and most figurines just inserted a new character or item, Disney Infinity uses "Playsets" that have campaigns around their various properties. You can then play through that campaign with character figures from that playset. Disney Infinity for Wii supports the original six playsets.

Each playset presents unique gameplay and characters.

Probably the more interesting part of Disney Infinity is the Toybox. Here you can mix and match things you've unlocked from the campaigns to create your own levels.

Disney Infinity might be a unique game, but it's been one that's hard to justify emulating with Dolphin. Not only is this a more limited version of the game compared to other releases, this is the crown jewel of the Disney Trio of Destruction. It currently brings the most powerful machines to their knees, even more so than Cars 2. Worse yet, it's seen even less attention from developers because of the need to have external hardware and figurines to even boot into gameplay!

None of those things stopped deReeperJosh from diving in to reverse engineer the base. Fresh from their work in Skylanders, they put what they learned from the last one in action. In truth, the Infinity Base works roughly the same as the Skylander's Portal. A lot of what we explained last progress report stands. The figurines only contain a little bit of data on them, and all of the main content is already on the disc. Now, the Infinity figures (and discs) do contain a little bit more data than Skylanders figures, but the end result is the same. These are just little wireless NFC chips in these figures/discs, and the portal reads them to see what figure is on and the game loads the appropriate content off of the disc, maybe with high scores or mini-game progress with the particular figure's game saved back onto it in some cases.

deReeperJosh just had to reverse engineer the communication between the base and the Wii and leverage the same GUI used for the Portal of Power. It ended up being a fairly painless process overall, and now you can emulate the Infinity Base in Dolphin! ...That doesn't make Disney Infinity particularly playable due to performance issues, but is one more step in the right direction.

Note: The GUI isn't quite finished on Dolphin Android yet, so the feature isn't available yet there. Not that it'd be too useful considering that Disney Infinity suffers from severe performance issues even on high-end desktops.

New Post Processing Shaders¶

While Dolphin may not be known for having the most robust Post Processing shader support, over the last couple of months a few interesting shaders were added that some users might find rather nice to use in specific cases.

5.0-18503 from AdmiralCurtiss ports over sharp bilinear to Dolphin.

Older consoles didn't output square pixels. The CRT displays they were designed for can produce an image with arbitrary horizontal scaling on the signal, so every console would have different pixel aspect ratios, even varying per title! Our modern displays don't work this way - they instead use a fixed pixel grid that can't cleanly reproduce these non-square pixels. The most common solutions to handling this in emulation has been the use of Nearest Neighbor and Bilinear Filtering. Both have their compromises.

Say we have a 4x4 grid of pixels. Scaling it up with nearest neighbor scaling is fine if the aspect ratios match.

But if those pixels are intended to be in a 5:4 aspect ratio? When we scale these up with nearest neighbor, the pixel colums are now uneven. In motion the pixels would appear to "change size" as they move across the screen, which is very distracting.

Bilinear scaling will have even pixel columns and thus will appear consistent in motion. But it's also very soft.

Here it is in practice in a pixel art title you may be familiar with.

Scaling with nearest neighbor will give you a sharp image, but it introduces artifacts. For example, the "shimmering" shown here in the floor tiles. This is a result of unevenly sized pixel columns as they scroll across the screen.

Bilinear scaling will give solid, reliable results no matter what is going on with the pixel ratios or scaling values. But it will be soft, which is not always an appealing look for pixel art.

But one day, someone had an idea: why not both? Sharp Bilinear is a combination of both Nearest Neighbor and Bilinear filtering that attempts a best-of-both-worlds result by using the strengths of both filtering techniques.

First the image is scaled up with Nearest Neighbor to an exact integer multiple of the input that is at least the desired target resolution. In this case, it is wider than our target due to the aspect ratio mixmatch.

Then, that output is bilinearly scaled to the target resolution. This can produce a sharp result without uneven pixels.

Here's our pixel art title again to show it in action. Sharp Bilinear is sharp, but without shimmering and other artifacts!

Sharp Bilinear is made for 2D graphics and specifically pixel art. But nothing says you can't apply it to 3D graphics as well!

Dolphin scales bilinearly, so running fullscreen at 1x Native on a 8k panel gives a soft image.
_{Even this is sharper than console output. Console has additional blur passes that we skip, and that's before analog fuzz and potential interlacing.}

With Sharp Bilinear, you can have the unnaturally sharp jaggies you crave! This isn't accurate (in fact it's about as accurate as high Internal Resolutions are) but if you like this look, enjoy.

Of course, at higher-than-native Internal Resolutions, Sharp Bilinear doesn't really do anything for 3D Graphics.

Another Post Processing Shader that's been a part of Dolphin's history just won't die. That's right, we have the glorious return of the legendary ASCII Art Shader from the ashes of removal. And who would go through the effort to fix it up for modern Dolphin? Well, none other than it's original creator and long-time Dolphin contributor degasus! While they're not as active around the project, they couldn't stand to let such an injustice stand and returned to active development to right this incredible wrong. 5.0-19109 marks the return of the ASCII Art Shader!

At a distance everything seems normal. But if we take a closer look...

It was ASCII Art all along! At 8k, the ASCII blocks can build a 2x Native image, then add additional detail with the ASCII characters!

This isn't just a straight port of the original - degasus has optimized the shader to run on modern graphics cards that support subgrouping. If you have a supported GPU, the shader is now actually somewhat performant! 8k and 60fps is now possible! (on an RTX 4090)

With this change, it is likely that degasus will return to slumber, at least until the next time we try to remove the ASCII Art Shader.

A Sixth Bounding Box Game!¶

This is a momentous occasion for us all. After the discovery of Ultimate Spider-Man's usage of bounding box, we thought that it was going to be the feature's last dance. Yet, somehow someway, despite the GameCube and Wii no longer seeing retail games, bounding box has found a way.

Solitaire and Mahjong joins the ranks of known bounding box titles after remaining anonymous for many years. It was just obscure enough that it escaped our issue tracker... at least for a time. But eventually, no matter how weird, how unassuming, or how obscure the game is, someone tests it. And if there is an issue, we can only hope that they report it to us.

The user in question didn't know that it was a bounding box issue, but by bringing up this game's broken nature to developers, we were finally able to take a look and see why it wasn't working. At first, pokechu22 thought that the issue may be XFB related, and JMC47 wondered if NAND issues were causing the save files to be hard to click.

But nope, it turned out that the menus were powered by bounding box. A helpful log message kindly pointed this out at boot, but went unnoticed through early testing.

E[Video]: BBox shall be used but it is disabled. Please use a gameini to enable it for this game.

This game being broken for all of these years was simply due to the default setting of bounding box being set to disabled.

This game had a very gray look on old builds.

But with bounding box enabled, things are finally rendering correctly.

Users also reported a "performance" regression with this game, but thankfully that turned out to be a false positive. Essentially, we changed the default values given to a game when Bounding Box was disabled, which caused the game's behavior to change. While 5.0-14326 did cause a severe performance regression in this game, turning on bounding box to cause the correct values to be sent fixes it completely. This bisect should have pointed us to this game having a Bounding Box issue, but no one realized it at the time. After all, there were only five Bounding Box titles, and this wasn't one of them! Oops.

Solitaire and Mahjong now joins Paper Mario: The Thousand Year Door, Super Paper Mario, Magical Mirror Starring Mickey Mouse, Disney's Hide and Sneak, and the aforementioned Ultimate Spider-Man as our bounding box titles.

To prevent yet another game from sneaking through, pokechu22 added "bounding box reads" to Dolphin's Usage Statistics. If any users run into this in the future while having Usage Statistics enabled, we'll know about it.

Last Month's Contributors...¶

Special thanks to all of the contributors that incremented Dolphin from 5.0-18501 through to 5.0-19368!

Coming Soon: Dolphin on Steam!

2023-03-28T05:12:11+00:00

We are pleased to announce our great experiment - Dolphin is coming to Steam! Our store page is now live, and you can visit it with the handy widget below. However, due to how Steam works, you won't be able to download the emulator through Steam just yet. Feel free to wishlist us to be notified when Dolphin is available to download on Steam!

When we launch on Steam, we'll have a feature article detailing the process and features of the Steam release. We're pleased to finally tell the world of our experiment. This has been the product of many months of work, and we look forward to getting it into users' hands soon!

Dolphin Progress Report: December 2022 and January 2023

2023-02-12T07:28:09+00:00

We've got a lot of exciting news and features packed into this Progress Report. On top of the normal emulator development, Dolphin's infrastructure has seen a massive overhaul. While most of the work has gone into optimizing our backend and hardware to meet new demands, users may notice some upgrades to user facing features like the Dolphin Wiki and FifoCI.

Some focus on the infrastructure doesn't mean there was a slowdown in progress for the actual emulator, though! A bevy of new contributors to the project mixed with the efforts of stalwarts has brought together some massive new features no one will want to miss. Headlining this Progress Report is a massive new performance hack called VBI Skip. If you're on a weak device that can't consistently play a game full-speed, VBI Skip is a powerful tool that can help make the game more playable and keep audio crisp and clear. If you're looking for higher performance overall, a ton of Vulkan optimizations and general emulator optimizations have given Dolphin a pretty large performance increase. A new option called Cull Vertices on the CPU can also greatly improve the framerate in many games.

If you're instead looking to enjoy some unique games, the Skylanders games can now be played without needing a physical Portal of Power connected. You can even use your own figurine data to continue where you left off with powerful Skylanders!

We have a lot to get through... but first.

It's that time again - we have to warn users of a rather annoying problem that can decimate Dolphin's performance, particularly in mobile devices. The culprit this time is NVIDIA based Optimus laptops - users have been reporting that the discrete NVIDIA graphics card has been giving them a fraction of the performance of Intel's onboard graphics!

We're unsure of what is wrong and haven't been able to determine exactly when it started happening. However, if you find that Dolphin is suddenly running slower than before, you can work-around the issue! Simply add Dolphin to the 3D Settings in the Nvidia Control Panel and set our Power Management setting to "Prefer Maximum Performance." That has been the only way to consistently fix performance.

A global Maximum Performance Profile does not work, you can only work around the issue by creating a profile specifically for Dolphin Emulator and setting it to Maximum Performance.

We also have one more announcement to make. For Android users who want the latest development builds on their phone without wanting to wait, we now have an Open Testing Program on the Play Store app.

Selecting this option will keep your Dolphin up to date with the latest development builds. This means you'll have access to the latest optimizations and features immediately, without having to wait for the next beta update. However, as with our development builds on desktop, there is always the risk of bugs and/or regressions slipping in and going unnoticed for a bit. If you want to live on the bleeding edge, Dolphin's Open Testing Program is here.

Now with all of that out of the way, let's finally get on with December and January's Notable Changes.

Notable Changes¶

5.0-18271 - Video Hack - VBI Skip by Sam-Belliveau¶

It's very rare that we merge a rather egregious hack. But when one shows up with such potential to drastically improve playability with a minimal impact on maintenance, it was a bit too much to pass up on. The entire story around how this change came out is rather strange.

The key thing to note is that Sam-Belliveau had a stress-inducing final exam and college applications quickly approaching during all of this. Thankfully for all of us, their only solace for procrastination was messing with Dolphin. One of the things they were working on was improving Dolphin's throttling, which led to them messing with what happens when a frame was presented. They then ended up messing with the timing of Vertical Blank Interrupts (VBIs). This is going to be a huge simplification, but they are essentially interrupts timed to the Vertical Blanking Interval on a CRT television (also abbreviated as VBI, though more commonly as VBLANK). Since the Vertical Blanking Interval is how a CRT understands the start/end of each frame, the GameCube, being designed for analog televisions, uses an interrupt to track these and also uses said interrupt to mark of the start/end of each frame internally.

During this experimentation, Sam-Belliveau's experimented what would happen if Dolphin simply ignored or skipped a Vertical Blanking Interrupt when Dolphin was lagging. While their goal was to improve framepacing, the result they got when testing Wii Sports Resort was something no one expected.

Despite running at ~45 FPS, the game audio was sounding crisp and clear in our first glimpse of the hack in action. Enable audio to see why this turned heads when it was shown off.

Sam-Belliveau announced what was discovered with a longer version of the video above. It displayed a game lagging significantly while maintaining crisp audio and snappy controls. This turned a lot of heads, and the feature was quickly given the name VI Skip. ...but that was too close to Video Interface which we regularly abbreviate to VI, so we renamed it to VBI Skip for clarity.

A hack like this would normally be a bigger controversy, but the method in which it worked made it a lot more enticing. The initial version of VBI Skip was only 11 lines of code! Additionally, it would only activate itself if Dolphin was lagging. And just because VBI Skip is active doesn't mean game logic will slowdown - some games can instead frameskip instead, depending on how the game works.

Developers were initially skeptical about the compatibility of a hack like this. Thankfully, Sam-Belliveau quickly unleashed it for everyone to test. And while VBI Skip doesn't directly improve framerate, it can drastically improve the playability of a game that isn't running at full speed.

To see the pure potential of VBI Skip, we can show a compatible game with an underpowered device. For example, Crash Bandicoot: Wrath of Cortex is far too demanding for a Pixel 3a featuring an Adreno 615. The opening cutscene makes this readily apparent.

The framerate tanks and audio lags as the poor Pixel 3a can't keep up.

However, Crash Bandicoot is compatible with VBI Skip and can give the weak device a fighting chance to run the game.

Though it isn't as smooth as it should be, the game runs at a playable speed, without slowing down or distorting the audio. Note however that the framerate is still lower, but due to the limited motion in this cutscene it isn't as as obvious here as it would be in game.

VBI Skip is a powerful tool for weaker devices, especially in games that struggle. Paper Mario: The Thousand Year Door's Bounding Box effects are torture for weaker phones, but VBI Skip gives them a fighting chance. It's obviously not perfect, but the mixture of slowdown and frameskip keeps the game fairly playable.

During Bounding Box effects like the boat flip, this poor phone ends up skipping a lot of VBIs!

But here comes the rather interesting part of this. We once had a frameskip implementation, but it only worked under very specific conditions, didn't actually improve performance much at all, and was completely broken for years before it was ultimately removed. Dolphin's developers were convinced that due to the complexity of the GameCube and Wii, a frameskip-like hack was effectively impossible for Dolphin. Yet, here is VBI Skip accomplishing the same feature with higher compatibility and bigger gains, all while dynamically activating and deactivating itself depending on if Dolphin is lagging. Why does VBI Skip work where frameskip did not?

No one knows.

Veterans of the Dolphin project said that VBI Skip should run games at half speed or crash outright. Developers from outside of the project called it "disgusting." We even had friends at PCSX2 quickly hack in the feature and test the PS2 version of Crash Bandicoot: Wrath of Cortex, where the game immediately froze. And yet the majority of games in Dolphin are okay with this egregious hack, and we have no idea why. There are some theories that the environment the games were developed under did something to make them tolerant of this, but we genuinely do not know why VBI Skip works at all.

But it does.

However, though this hack is an amazing thing that shouldn't exist but does... it isn't without flaws. It works for a lot of games but not all games. And because the hack itself is quite simple and we don't have a great understanding of why VBI Skip works, there isn't much that we can do about it.

The good news is that VBI Skip tends to fail rather obviously when it isn't compatible with a game, making it easy to flag down those games and disable the feature. For instance, both The Legend of Zelda: The Wind Waker and Twilight Princess stop rendering if VBI Skip is active in-game. This is because they don't actually use Vertical Blanking Interupts, but instead use shadow registers to manage their own timings for presentation. Wind Waker in particular is extremely touchy. The game's developers went so far as to lock the PAL version of the game to 30 FPS in PAL50, just so they wouldn't have to touch those timings!

Other games, like many in the Need for Speed series, have a strange "dynamic" framerate that doesn't play nicely with the hack - causing even worse lag.

VBI Skip is also compatible with some games that you might not expect. For instance, it can be used in Dual Core sensitive titles like Star Wars: Rogue Squadron III that tend to reject a lot of Dolphin's other performance hacks.

Overall compatibility is actually surprisingly good, though we're sure that more edge-cases and potential issues will crop up through wider testing. More quirks are bound to be found now that VBI Skip is out in the wild, but we are confident enough in our early testing to push it through so that users can try it out. We know a lot of our users are on limited hardware and this is a feature that can turn a painful experience into an enjoyable one.

Note: VBI Skip was originally named VI Skip. However, during the process of writing this article we realized just how easy it was to confuse with VIdeo Interface (VI), and after consulting with samb and other developers, we decided to rush to rename it to VBI Skip. As a consequence, the beta build that is being released along side this Progress Report still lists it as VI Skip. However, it was changed in 5.0-18628 so dev builds reflect this change, and all subsequent beta builds will call it VBI Skip. We apologize for any confusion this may have caused, but we decided that this was the best course of action to limit confusion long term.

5.0-18086 - New FrameTime/VBlank Analyzer + Graph by Sam-Belliveau¶

Did you notice the branch name that Sam-Belliveau's was on during the first video with VBI Skip? And did you see that frametime graph that was being used to check for framepacing? Well that was what Sam-Belliveau was working on when they discovered VBI Skip. In fact, VBI Skip was actually merged afterwards, and the initial changes made for measuring framepacing were actually integral towards implementing the hack.

The new graphs are powerful and give developers a bigger picture on performance and framepacing.

For most users, the new graphs are a bit overkill. However, there are some other new features to our performance statistics display that might give users a better idea of how they're performing. The most notable of which is a new "speed" display that actually will tell you what your current performance and what your potential maximum performance would be without having to disable the framelimiter. These features can be enabled in the performance statistics section of Graphics Settings -> Advanced on desktop builds and now Android builds as well.

5.0-18299 - Implement Emulated Skylanders Portal of Power by deReeperJosh and mandar1jn with code relicenced to GPLV2+ for Dolphin from RipleyTom¶

Together, these games make up four adventure platformers with hundreds of unique characters and a racing game. Regardless of the type of game, at the center of each game, the key to playing them revolves around figurines you can get called "Skylanders" which enter the game through a USB device called the Portal of Power.

Does your Portal of Power look this cool?

There were ~450 different figurines and 172 base characters and 39 magic items. The Trap Team portal also features a speaker that boss characters could taunt you through. Some figurines could even unlock new areas in games.

For all the potential of a game like this, there is a cruel reality to it. The figurines are simply containers for the Near Field Communication (NFC) chips that get read by the portal. They hold very little data: just an ID, character stats, and the applied hat. All of the real data is on the disc. The game just uses the ID to "unlock" that content and give the illusion that the figure is being sucked into the game. However, this is more than just a gimmick. The Skylanders games will not allow you to play without a figurine - they are a fundamental part of ~~their business model~~ the game. They even went as far as to gate significant features behind specific figurines!

In Dolphin, setting up a Skylanders game was a unique experience. Dolphin has long supported the physical Skylanders Portal of Power. It was a little cumbersome, but once set up, Dolphin's USB HID implementation allows users to play their IRL figures in Dolphin just as the game was designed. However, this feature was unavailable on Android, making the Skylanders series inaccessible to our Dolphin Android users.

deReeperJosh has been requesting support for several years hoping to be able to enjoy the games on Dolphin without having to dig out their portal every time. Using the RPCS3 Emulated Portal of Power implementation as the basis for a Dolphin implementation, deReeperJosh took matters into their own hands to try to bring an Emulated Portal of Power over to Dolphin. A lot of the code from RipleyTom's RPCS3 implementation was used at the core of the change but deReeperJosh still had a lot of work to do to make it work within Dolphin. mandar1jn provided expertise along with tools that allowed for testing data from the generated figurines and comparing them to figurine data from a real portal.

Using the new emulated Portal you can create blank Skylanders, or load real figurine data complete with save progress.

For Dolphin on Android users, deReeperJosh decided to put in some extra work after the initial merge and as of 5.0-18497, the emulated portal GUI has been ported over to Android. Considering that USB HID passthrough isn't available on Android, this is the only option for playing these games. For our Android users, the feature is located Options -> Wii and has to be enabled there.

All of this together results in the arrival of a long requested feature. Again, we have to thank RipleyTom for the original implementation for RPCS3 and allowing the code to be licensed under GPLv2+ for Dolphin.

Note: As with all electronics, Skylanders figurines have a chance of failure, resulting in a useless figurine. While Skylanders figurines don't have batteries and are powered by the portal itself, their NFC chips do have a slight failure rate and they are likely only guaranteed to a certain number of read/writes before failure.

5.0-18355 - Allow Dolphin to Manually Cull Vertices on the CPU by TellowKrinkle¶

Normally, this would be a headlining feature of most Progress Reports. But you know, VBI Skip. Still, we couldn't let the juggernaut in the room completely drown out this excellent performance improvement.

For many years, the Metroid Prime games and their insane way of drawing the map with a mixture of line-width, point-size, and triangles has decimated performance on modern GPUs. The way they alternate between lines, points, and triangles makes our batching optimizations inapplicable, forcing Dolphin to use a tremendous number of draw calls in order to emulate what the games are doing. This isn't an isolated incident, either, The Legend of Zelda: Twilight Princess does a similar thing when drawing its own minimap, just on a much more damaging level to the point where developers initially patched it out directly in Dolphin's source code!

TellowKrinkle noticed that a lot of these triangles weren't actually getting used, suggesting that these extra triangles may have been trying to avoid a hardware bug. If Dolphin could somehow detect this, we could reduce the number of draw calls significantly and reduce the performance impact of these tremendously damaging scenes. And thus, Cull Vertices on the CPU was born.

In cases where games are using a lot of triangles but not all of them are actually visible, Cull Vertices on the CPU can ease the drawcall bottleneck. Unlike some of the existing solutions to make these maps faster, such as disabling geometry shader support in old builds or the famous Hyrule Field Speed Hack, Cull Vertices on the CPU doesn't actually result in any graphical glitching. This allows players to finally run Hyrule Field at full speed without having to compromise the look of the minimap.

The "Hyrule Field Speed Hack" patch greatly reduces the number of draw calls but affects the look of the minimap.

With CPU Cull on and the patch disabled, the minimap will look correct while still delivering a sizeable performance increase.

For people on lower-end hardware, the "Hyrule Field Speed Hack" patch is still faster than CPU Culling because it removes some triangles/lines/points that are actually visible. But, if you want the minimap to look correct, CPU Cull is an effective alternative for higher end devices. Without either of these options, the game is left incredibly slow in Hyrule Field and Faron Woods.

Twilight Princess has to be considered an extreme example. After all, there were already targeted hacks and patches toward its difficult rendering method. But, a game doesn't have to be doing something exceptional to see improvements from Cull Vertices on the CPU. Densha de Go! sees significant benefits simply because it isn't very optimal with culling vertices, and Dolphin usually saves more than enough draw calls to gain a sizeable performance boost in every zone of the game.

As a train driver, I'm always on time but I never stop.

There is the case where a game is so optimized that Dolphin trying to cull vertices on the CPU actually ends up lowering performance because it isn't saving enough draw calls to make back the CPU overhead. As such, it is no accident that Super Mario Galaxy shows up slower on the graph above with CPU culling enabled. It takes an extra ~2 - 3% of CPU performance to analyze things and try to cull vertices, and we just don't gain enough in this game in most areas.

Because we can't guarantee this option will be faster in most games, we've decided to default CPU culling to off. It's a safe feature that won't cause crashes or graphical issues, but we wanted to give it a trial period where users can enable it and see how it affects their favorite games.

For games that see a huge benefit, we've currently enabled it by default via GameINI.

5.0-18192 - Emulate PPC Datacache by mkwcat¶

Proper CPU dcache emulation was something that none of us were really expecting. After all, dcache emulation was going to be very slow, and most uses of dcache emulation were caused by game bugs. Patching the games was not only easier in most cases, but also didn't come with the hefty performance penalty that correctly emulating those bugs would entail.

But none of that mattered to mkwcat. They were on a different kind of mission. They were on a personal challenge to crack into CTGP-R's anti-emulation/cheat security. For those that don't know, CTGP-R is a prestigious Mario Kart Wii mod where many top players compete for the fastest time trial times. On top of being a trusted closed garden for time trial competition, CTGP-R also has hundreds of custom tracks and many new offline and online game modes.

While Dolphin developers usually focus on officially released titles, we occasionally get issue reports regarding popular mods that users want to run in Dolphin. These issues are usually treated as valid - after all, these mods and romhacks run on the real console, so it doesn't seem unreasonable to try to make sure they are emulated properly when possible. CTGP-R ended up a special case - the developers absolutely did not want Dolphin running their mod. They went as far as to add features to their hack to detect and prevent Dolphin from running it.

This decision by the CTGP-R developers wasn't entirely unwarranted. They wanted to have a closed, trusted environment where players could run time-trials and be confident that the times they were running against weren't cheated. They saw the ability to run the mod on Dolphin as a huge security liability, and took measures to make sure it didn't happen. There are other listed reasons, but this was the main crux of the issue. Because of the situation, we told users we had no intention of going out of our way to emulate the mod.

With both CTGP-R and Dolphin's developers turning them away, Dolphin's users took matters into their own hands.

Given the situation, our users have developed a bit of animosity toward the CTGP-R project. After all, the MKWii mod is going out of its way to make sure it doesn't run under emulation. But if you travel back to when a lot of development was happening, their fears of cheating aren't exactly unfounded.

Back when Wiimmfi was new and the Nintendo Wi-Fi Connect services had just shut down, Dolphin was a very popular tool to go onto Mario Kart Wii and cheat. It was way easier to do this on the emulator than to do it on the console. And if you got banned on Dolphin, it was a lot easier to spoof a new console ID than on a real Wii.

The early days of Wi-Fi replacement servers were rife with users using item hacks, timer hacks, and more.

Dolphin's easy to access cheat system meant that users could create and enable cheats for just about anything, and just as easily take them online.

Thankfully, Wiimmfi didn't end up completely banning Dolphin users, but instead mandated more authentication for Dolphin users that required such steps as using a real Wii NAND dump and a seven day wait period for all new users. Considering how much work and thought Wiimmfi developers have gone through in order to make things fair for players online, it's hard to fault CTGP-R developers for their stance.

However, times change, and over the years Dolphin's emulation has improved dramatically. While developers never directly targeted CTGP-R, overall improvements of Wii emulation brought Dolphin closer to being able to run it. In fact, by the time mkwcat showed up, their goal wasn't even to get CTGP-R running on Dolphin. They were simply examining some of the anti-hacking and anti-emulation code in the executable, and realized that Dolphin wasn't very far from being able to run it.

I decided to take a look at it in detail and figure out what specific parts of the code were not being emulated properly. I found I could make four instruction patches to get it to at least boot, but there was one particular issue with the UPMC registers not mirroring the PMC registers which was not easy to simply patch out, so I decided to fix the issue in Dolphin itself.

After seeing the icache implementation, I thought it was feasible to adapt it into a data cache, and it really was. After only a few hours iirc I was able to make it accurate enough to emulate CTGP's boot stage correctly using Interpreter, though it broke everything else from working properly.
mkwcat

A few weeks later, a user from the Mario Kart Wii community mentioned a branch of Dolphin that could run CTGP-R by implementing dcache emulation. This caught the eye of Dolphin's developers, and a discussion soon took place which then pulled in the branch's creator, mkwcat. Realizing there was interest in dcache emulation from the main project, they submitted a pull request and after a lengthy review process, dcache emulation hit Dolphin.

The first step to running CTGP-R in Dolphin is going through a painfully long installation process.

Before you go installing CTGP-R in Dolphin, please remember that dcache emulation is incredibly expensive. Only on the most powerful of computers will you manage to get decent speed on tracks in time trial mode. Even if you can reach full speed in sections, because memory operations are so much more expensive, expect stutters whenever anything is loaded.

And for those with nefarious intentions, don't even try to use Dolphin to cheat in CTGP-R. While Dolphin can boot and run CTGP-R, the mod still has additional layers of detection that are able to detect Dolphin and prevent the submission of times and ghosts. As well, Dolphin openly announces itself to mods with a special device Wii mods can access.

Once in game, the single player more or less works. To help performance, you can disable dcache emulation after completing the boot process by saving state, turning off dcache, loading Mario Kart Wii, and then loading the savestate you made in CTGP-R.

Outside of CTGP-R, dcache emulation can also be applied to other dcache sensitive titles if you want to run them without hacks/patches applied. This includes games like Ten Pin Alley 2, Resident Evil 2, Resident Evil 3, Dead to Rights, and Casper's Scare School: Spooky Sports Day.

This also allows Disney Infinity and Cars 2 to boot without any special hacks. However, performance is reduced even more than normal. As such, for any dcache sensitive game with an existing patch, we highly recommend that players use our included hacks when possible.

5.0-18242 - Change default user directory location to AppData on Windows and 5.0-18238 - Menubar: Add action which opens the user folder by OatmealDome¶

Dolphin's Global User directory has stayed in the same place on Windows since it was first introduced with the launch of Dolphin 4.0. Placed within My Documents, we wanted to keep the User directory in an easily findable place because it stores more than just save files. Users can find screenshots, resource packs, logs, configurations, and more all within the Global User Directory. While many of our users do use Portable Mode or move the directory themselves, most users simply use the default setup.

When this choice was made, My Documents was the perfect choice. It was a mixture of an easy to find spot and a fairly safe spot where the user isn't going to accidentally delete their save data. Unfortunately, the ever changing landscape of computers has made using My Documents more of a headache than it is worth.

One of the biggest problems is Microsoft's very own OneDrive. While OneDrive may be good at backing up files, it is an absolute nightmare to use with Dolphin. Emulating the Wii NAND often has Dolphin making lots of small writes to a lot of files. However, OneDrive will lock down any files it is currently backing up, even if Dolphin is still using it. In extreme cases, OneDrive can actually cause Wii games to stop booting on a Windows PC, and cause savedata loss in GameCube games.

The other problem is a recent(ish) wave of malware that would encrypt important files on your computer and require you to pay a fee to get them unencrypted. Again, Dolphin's handling of Wii NAND emulation with tons of small writes to a lot of files in My Documents makes machine learning based anti-virus/anti-malware programs go on alert and block writes. This can cause Wii games to not boot and end up corrupting the NAND. We've let these vendors know about the problem, and they were more than happy to whitelist us. However, due to simple hash-based whitelisting procedures, every new build of Dolphin would have to be whitelisted separately after being reported by a user. This was not great.

The only way to alleviate these problems was for Dolphin to place its files where these applications expected programs to keep their files - AppData. This hidden folder is basically the Windows catch-all place for programs to keep their stuff, and Windows has strong restrictions in place there to limit programs to only their own little nook. Thanks to those protections, antivirus programs know that they don't need to watch AppData as closely, and have explicit exceptions for the folder. OneDrive also doesn't back up this folder (outside of specific files), so it will never interfere with writing files there. AppData is the only place like this on Windows. While we like the accessibility of My Documents, we had no choice but to move our default global user directory location to AppData to get these applications to stop bothering us and our users.

For those of you who are using My Documents with no problems, don't worry. We aren't going to change anything. If Dolphin (even new builds) see the Global User Directory in My Documents, it will continue to use it as normal. However for new Windows installs of Dolphin, the AppData directory will be chosen instead.

Because the AppData folder is a hidden directory that can be hard to find, we've added a new option to the Menu Bar that will open a file browser window directly in the Global User Directory. We hope that this compromise eases some of the inconveniences of the new location.

Handy! But be careful in there - that's where your saves and settings are stored.

5.0-18025 - Add Option for Force Nearest Or Linear Texture Filtering by leo60228 and AdmiralCurtiss¶

This is another long awaited option that has been debated for quite a while. Originally submitted by leo60228 nearly three years ago, the ability to force various texture filtering modes has been up for debate ever since.

The biggest question was about the value of the feature. Games already set texture filtering on their own - and with Manual Texture Sampling, we can emulate that to a very exact degree. Forcing it to render differently could not only cause bugs, but could make games look blurry or pixelated.

However, as time went on and we saw more user feedback, AdmiralCurtiss determined the feature did have some merit and decided to rebase the original changes and reorganize the GUI in order to make it cost less space.

The old Anisotropic Filtering menu has been repurposed for all texture filtering features!

While giving users the ability to customize the look of the games they are playing is a definite perk, the reason for finally giving users this control is that it presents a work around for game bugs. Usually, a game developer making games on the GameCube will choose whatever texture filtering is best for the game. However, there are many cases where the original developer choose poorly, and presenting this option allows users to correct it. There are even cases where a game is outright broken on console due to texture sampling issues, and forcing nearest neighbor can actually work-around those defects!

Sexy Poker has texture defects even on console, but they're incredibly visible in Dolphin at higher resolutions.

Forcing Nearest Neighbor can erase the defects allowing you to immerse yourself into this legendary card game.

If you're looking for a more notable example than the venerable Sexy Poker, the GameCube version of Sonic CD in Sonic Gems Collection is significantly blurrier than the Playstation 2 version because everything is bilinearly filtered in the internal emulator. While some users may prefer that, most players have deemed it to be a flaw. By forcing nearest in Dolphin, you can finally have the crisp pixels you crave in the GameCube version.

Even Digital Foundry complained about how blurry Sonic CD looks on GameCube.

At least now you can choose to change one of the port's differences.

One of the reasons we chose to finally present forcing nearest texture filtering is because we already had a feature for forcing linear texture filtering. This "Force Texture Filtering" option was added long long ago to work around a quirk of two premiere Nintendo titles - New Super Mario Bros. Wii and The Legend of Zelda: Skyward Sword.

Skyward Sword's shading gets chunky at higher than native internal resolutions.

Forcing linear texture filtering resolves this issue.

Now the existing "Force Texture Filtering" option has been collected together with all the other texture filtering controls in one place, ready for users to adjust as they see fit.

5.0-18017 - JitARM64 - Implement AccurateNaNs by JosJuice¶

This is a change with a rather funny story behind it, and actually goes back several years. Jump back to June of 2015 and AccurateNaNs was being implemented for our x86-64 JIT. Essentially, it makes emulation of NaNs (Not A Number) more accurate by having our own custom handlers for them rather than just letting the host processor handle it. This is slower, but is necessary to prevent calamities like this one in Dragon Ball: Revenge of King Piccolo

If you remember this, then you're truly one of the OGs of the Dolphin Blog. Note that you have to defeat all the enemies to proceed, but some of them are sent to a far away place...

However, this was never implemented in our AArch64 JIT for ARM 64-bit processors. Because, quite frankly, it didn't need it. The NaN behavior on AArch64 matched PowerPC closely enough that these games just worked without needing special handling.

But wait, the title of this section is Implement AccurateNaNs on AArch64. What changed?

Well, AArch64 and PPC NaN handling aren't exactly the same, it was just getting good enough results at the time. But Dolphin recently changed how we handle FMA (Fused-Multiply Add) instructions in order to fix online desyncs between real console and Dolphin in Inazuma Eleven GO: Strikers 2013.

Unlike the Dragonball issue, this one effected both our x86-64 JIT and our AArch64 JITback in the day!
_{Click/Tap to play. Click HERE for a higher quality version.}

This fix was applied to both JITs, and no one was the wiser that we had inadvertently broken Dragon Ball: Revenge of King Piccolo. Some FMA instructions invert the sign of output, but only if the output is not NaN. The Inazuma FMA fix changed how we handle FMA instructions just enough, that on AArch64 the sign of NaNs for nmadd / nmsub instructions were inverted, breaking Revenge of King Piccolo. A user reported that the game was broken to some very confused developers, but considering we had seen this exact bug before in our x86-64 JIT, it was just a matter of fixing it in the other JIT. As our resident AArch64 JIT maintainer, JosJuice was pulled into action to implement Accurate NaNs on ARM.

Because emulating NaNs in this manner is a slight performance reduction, it is only enabled in one title currently: Dragon Ball: Revenge of King Piccolo.

5.0-18257 - Remove Boot from DVD Backup by MayImilae¶

Unlike many other consoles from the era, the GameCube and Wii use modified DVDs that can't be read by conventional DVD drives used on desktops. These modified DVDs are physically identical to normal DVDs, but Nintendo partnered with Panasonic, one of the creators of DVD, to slightly modify the sector format and error correction. A regular DVD drive doesn't understand this format and thinks every single sector is corrupted, never returning any data to your computer. This differs from many Playstation and Playstation 2 emulators, which can directly run original games

Yet despite that fact, Dolphin had the ability to boot from the host computer's DVD drives. This was implemented so Dolphin could read GameCube and Wii games burned to DVD backup discs. And yes, that requires a user to rip their games from their Wii, then burn them back onto blank DVD media.

Why would anyone want to do that? Back in the early through mid 2000s, drive space was much more limited than what we have today. The average hard-drive size was just 120 GB. Even if you bought that drive just for GameCube and Wii emulation, as few as 14 uncompressed Wii dumps would fill that entire drive! Burning backup discs may have been a hassle, but using cheap DVD media to free up space on an expensive hard drive made a lot of sense at the time.

Don't mixup backup discs and real discs! Thankfully, our discs are certified.

Unfortunately, playing games on a DVD backup wasn't a great experience. Dolphin wasn't designed to read from slow optical media. Even in 2003 hard drives were leaps and bounds faster than any optical drive, so Dolphin assumes that storage will never be a bottleneck. If for some reason storage is a bottleneck, Dolphin will halt entirely and wait for the storage to catch up. This appears as a stutter to the end user. If a game only read from the disc at explicit loading screens this would not be an issue, but most games do smaller loads at a regular basis throughout play. And some games, like Metroid Prime, constantly load from the disc during gameplay, introducing persistent stutter that can make playing the game a nightmare.

Another problem is that DiscTracK (DTK) audio games will have problems keeping up with the expected timings. Same for streaming videos, like those found at the start of Metroid Prime 2. We were unable to find a disc drive that could keep up, and in games like Ikaruga this can lead to hangs.

With the cost of hard drives now far below the cost of equivalent stacks of DVDs and multi-terabyte mass storage hard drives becoming the norm, the motivation to burn GC/Wii backups to discs has evaporated. In fact, most new computers forgo a DVD drive entirely! The only reason to use DVD backups with Dolphin in the modern era was to preserve the aspect of inserting a game into the system, but when the performance is so lackluster and the feature is confusing, the costs just didn't add up.

In the end, a mixture of poor performance and the fact it was confusing users into thinking Dolphin could boot nonbackup discs lead to the feature's removal. Does that mean the ability to play DVD backups is gone forever? Maybe not. After the feature was removed, a few diehard users of the feature spoke up on its behalf. In response to that, a list of improvements needed for the feature to return was written and that's where we stand for now.

5.0-18171 - IndexGenerator: Fix off-by-one in GetRemainingIndices by Pokechu22¶

This is a longstanding bug in Dolphin that has gone hidden in almost every game. A Vertex Loader Cleanup by degasus unknowingly introduced an off-by-one error into the vertex loader. Oddly enough, this causes error spam in Super Mario Sunshine during the Red Coin Field secret area.

Dolphin veterans are all too familiar with this secret stage.

Because nothing was visibly broken, this issue went mostly unnoticed. At least, not until a strange European only racing game arrived on our issue tracker. Pocoyo Racing is a licensed racing game based off of the kid's show Pocoyo. If you play Mario Kart Wii with tilt controls, you'll be right at home in this simple racing game aimed at children. However, when booting this game in Dolphin, things won't look quite right on the Ocean tracks.

The vertex issues provided intangible obstacles that made driving the track slightly more difficult.

Unlike Super Mario Sunshine, the fixes to the Vertex Loader Cleanup back then did not fix this issue, meaning it's remained dormant for a decade. However, thanks to a user stumbling upon this weird bug in this weird game, we were able to get a look at the issue manifesting and were able to locate the problem and repair it. Namely, IndexGenerator was broken for large numbers of vertices in one draw call, which is the function that gives a unique number to each unique vertex. Using the visible error in Pocoyo Racing, Pokechu22 quickly narrowed down the problem and solved the issue.

The game finally looks right in the latest Dolphin builds.

This also fixes the error log spam in Super Mario Sunshine when it renders the grass special stage.

5.0-17833 - Fix normal/tangent/binormal with Index3 Set by Pokechu22¶

This is a change that we missed from the last Progress Report, but thought it might be interesting to those that love seeing edge of emulation style of fixes. It was reported the several lighting effects in Quake GX (a homebrew port of Quake Shareware to the Wii) were broken in Dolphin. What made these effects interesting was that they were achieving normal mapping on the Wii.

Though the glorious bastards at Factor5 implemented bump mapping without any assistance from the hardware, this homebrew takes it even further by implementing full normal mapping. Dolphin was fully capable of emulating the effects, except it was getting confused by Quake GX having normalindex3 enabled in the vertex format. It wasn't actually doing anything with this, so simply disabling normalindex3 would fix the bugs.

Even though it looks alright at a glance, some of this demo's coolest effects were completely missing.

You can see reflections of light on the walls and other normal mapped effects.

However, that wasn't a good enough solution for Pokechu22 who dove in to fix the bug correctly. Through hardware testing, they determined the behavior of normal/tangent/binormal with Index 3 being set in order to fix the Vertex Loader to generate these cases correctly.

Last Month's Contributors...¶

Special thanks to all of the contributors that incremented Dolphin from 5.0-17997 through to 5.0-18498!

Announcing the Official Dolphin Discord

2023-01-07T03:27:15+00:00

Over the past four years, the Community Dolphin Discord Server, which was unaffiliated with the project itself, has become a fantastic community that has been providing support and a hub for Dolphin users. While it started out small, the server now boasts over 10,000 users and several of Dolphin's developers interact and help users directly on the server. The immediate nature of Discord is beneficial in that it allows for quick bug reports and support for various issues. Many users in the Discord community are experts in specific facets, like tricky controller mappings, motion controls, netplay, and more.

It has become an important pillar of the Dolphin community and Dolphin development, as a new generation of developers have originated from the Discord server. Recognizing its importance, many of the veteran developers have started monitoring the server as well, providing support and getting feedback for new fixes and experimental changes. It also allows developers and support staff to walk unsure users through making better bug reports on the issue tracker.

So we as a project have discussed among ourselves and with the Community Dolphin Discord members, and have come to a conclusion. The unofficial Dolphin Discord is already a core pillar of our community. It's about time we embraced it. We are pleased to announce that the Dolphin Discord is now the Official Dolphin Discord Server!

What's Changing¶

Since the Dolphin Discord server is already a major part of our community, less is changing than you might think. Obviously those maintaining the Discord community are doing a good job and have built it into an important part of Dolphin's community.

However, as things become bigger, sometimes unwritten rules need to be written down. As such, we've established a Code of Conduct for the expected behavior of both developers and the community alike. Because the Dolphin IRC channels were mostly isolated and had limited interaction, there wasn't really a need for this. Any problems were promptly kicked out and few users made their ways into the annals of the IRC network. With the Dolphin Discord Server, this changes. It is easily accessible for users and we don't want situations where users or developers are uncomfortable with the conduct of others.

The community members who built the thriving community of the Discord server will continue in their roles as administrators of the community. However, they will be getting a little help, as some of the Dolphin developers have joined the Discord staff.

What Isn't Changing¶

Dolphin's main home for development is the #dolphin-dev IRC channel. IRC is a decentralized communication service that will continue to exist for the foreseeable future. While we have had to change servers now and again, we always had the option of hosting our own server until the end of active development if worst came to worst.

Discord, on the other hand, is a proprietary service that could disappear at any point. They could change their Terms of Service to say that emulation isn't allowed and boot us all off tomorrow if they wanted. They could even be suddenly bought and burned to the ground out of nowhere. As such, none of our core services will ever rely on Discord. If for any reason the Discord server disappeared, development would continue as per usual.

The Dolphin Wiki, Issue Tracker, and Website will all be unaffected by this, save for the fact that the website now has a direct link to the Discord server. As for our forums, there are no plans to change them. While they may not have the quick response times of Discord, they're a support and communication platform that we have complete control over, and they are better for longer form reports and responses.

As for users on the Discord, you probably won't notice anything different. Maybe a few new faces as more developers migrate over and some new channels to display some infrastructure changes.

Next Steps¶

The new state of Dolphin's chat channels still leaves things more fragmented than they should be. We know that some of our newer developers are more comfortable with newer communication platforms and prefer using Discord over IRC. And Discord might also make some of our users and developers uncomfortable: it is after all a for-profit proprietary service, with an unclear business model, and primarily managed by a U.S. corporation.

We're in the process of evaluating Matrix for Dolphin's community. Matrix is an open-source decentralized chat platform, akin to Discord or Slack in its supported features, but similar to IRC in its openness. It would provide to our users and developers an open alternative to Discord but without the quirks and outdated customs of IRC. Matrix can be used to bridge other chat platforms as well, allowing us to fix the fragmentation problem of our development chat.

We don't know yet when we will be able to get this implemented. But if Discord is not to your liking, know that something is on the horizon to give you more options!

No, not that Matrix!

In the end, this decision wouldn't have been possible without the community admins of the Discord server past and present. They have done an incredible job building and running this community. This includes all of their current administrators and moderators such as SirMangler and Tech Dunk, along with those that have retired like AlexApps. We know there have been a lot of support staff on the server that have helped ease our workload over the years by helping walk users through problems and setup.

We hope that our endorsement and adoption of the Dolphin Discord server will help it grow further, and for those that stayed away because it wasn't official, you need not stay away any longer.

Dolphin Progress Report: September, October, and November 2022

2022-12-21T09:43:56+00:00

As we hit the holiday season, our Progress Report might be considered a bit late. A two month report became a three month report as we realized just how much work we had to catch up on. While the usual summer burst of activity didn't come, it seems instead everyone poured their time in throughout the autumn months! There's so many features, performance improvements, quality of life updates, and more that had to be considered.

We're going to have to skip out on some of the smaller updates this time around because there are so many big hitters. For instance, if you hate shader stuttering, Dolphin's Ubershaders have gotten a new tool that helps smooth out issues on Vulkan, D3D12, and Metal thanks to Dynamic Vertex Loaders that help reduce/remove pipeline compiles during gameplay.

If you're on a weaker device that stays away from Ubershaders... maybe after these optimizations you might finally be able to make the leap. Raw performance in Dolphin is up across the board thanks to many optimizations to the GPU emulation thread (which is emulated on CPU). Because this optimization affects the very core of Dolphin, pretty much every game should be faster, with a few select games seeing improvements of roughly 50%!

If you're looking to play with friends, we have some good news on that front as well. Dolphin's "experimental" Wii Remote Netplay support has finally received some much needed attention that may help it break free of that experimental moniker in the coming months.

And, for our Android users, a lot of the performance improvements also affect tablets and phones, but we also have a special treat only for you. The Android GUI has also seen a huge overhaul that should make it easier to use and easier on the eyes. And for those having problems with particular games using features Dolphin can't reasonably emulate, we have a few presents from an old friend to patch them up.

We could go on and on, but you know what time it is. Please enjoy these Notable Changes!

Notable Changes¶

5.0-17613 - Implement Missing Features for WiiConnect24 Support by noahpistilli¶

And after all of the changes and features we mentioned in the intro, we neglected to mention our headline change for this report. It's almost fitting - WiiConnect24 came and went without leaving much of a mark in the gaming world. It was touted as a new way to be connected to the internet 24/7, with access to up to date information from the comfort of your couch. You could see the weather, the latest news, receive messages (with pictures!) and more through the WiiConnect24 service. Even if your console wasn't on, the disc tray would glow blue if you have a new message, a Wii Update, or something else awaiting you for the next time you booted things up.

By 2013, the unending march of technology had already consumed much of the usefulness of the service, and everyone expected it to slowly fade away. But to our surprise, on 13 April 2013 Nintendo announced the closure of WiiConnect24 in late June, only 44 days away. At the time Nintendo Wii Wi-Fi Connectivity Support was in its infancy. Our mastery of NAND and IOS features was simply not good enough to support WiiConnect24, and many of its channels didn't even run in Dolphin at the time. When WiiConnect24 disappeared, we were years away from being able to support it. As much as it pained us, we were unable assist in the efforts to preserve WiiConnect24.

The sudden passing of WiiConnect24 put its many supported channels, promotional demos, cheesy videos and advertisements at risk of disappearing forever.

However, there was another option for testing and preserving WiiConnect24 - the actual Wii. From the early days after WiiConnect24's closure, preservationists and reverse engineers have been chipping away at reviving many of the channels and features seemingly lost. For international/default channels, RiiConnect24 offers good support across a lot of channels. For players looking for some Japanese exclusive channels, WiiLink has been slowly building support for these obscure channels that offer up some neat experiences that never saw the light outside of Japan.

Some efforts have been made by the RiiConnect24 developers to bring their service to Dolphin, but these have been a bit hacky. They have workarounds to get certain channels working within Dolphin, though it required a lot of setup in order to prepare VFFs (Virtual FAT Filesystems) that the channels used to store WiiConnect24 data. It was not user friendly, as it was difficult to set up, had limited functionality, and could easily break at any time.

Sketch, WiiLink project lead and RiiConnect24 contributor, realized that direct support in Dolphin would be a boon to both projects. It would open up their replacement services to more users and also make it easier to debug issues. But of course, it was easier imagined than executed. Sketch identified three major challenges that blocked WiiConnect24 emulation: support for VFF files, implementing some of the missing IOS functions, and figuring out the many fields of nwc24dl.bin and what they do.

Figuring out nwc24dl.bin was a reverse engineering job. We mentioned that WiiConnect24 titles could download updates while the Wii was in standby mode. How often it checked among other important things is stored in nwc24dl.bin. Emulating the standby feature is thankfully unnecessary, as WiiConnect24 channels also check for updates while the actual Wii is running and when you load them. Because Dolphin doesn't support the Wii's background scheduler, the only check it could possibly support is on channel boot.

Once the many fields of nwc24dl.bin were reverse engineered and understood so it could be HLE'd, the next thing that needed to be handled was actually downloading the data needed for these channels. To do this, an IOS function called DownloadNowEX needed to be supported. This is a download handler that can download anywhere from 1 to 32 files. If it is downloading more than one file in a single task, these files are called "subtasks" and there is a flag set in memory saying this download is a subtask and how many files it needs to download. Many of the channels take advantage of the subtask functionality, and the News Channel will download 24 subtask files when it updates!

These files that are downloaded now need to be packed into VFF files for use by the channels. Thankfully, Dolphin already has to handle the FAT filesystem thanks to SD cards and whatnot, so Sketch could get a jump start on support by copying code from there. But this wasn't an easy task, and actually supporting the VFF files required a little bit of finessing. The headers on the files were mostly undocumented and needed some digging into. However, once that was taken care of, Sketch streamlined the solution with AdmiralCurtiss's help.

With these changes, WiiConnect24 channels like the News Channel, Forecast Channel, and others can resume service in Dolphin!

WiiConnect24 is working in Dolphin at long last!

Is the situation perfect? Absolutely not. Like we said, Dolphin doesn't support background updates, so on their very first boot most of these channels will error out. After that they should work normally as long as the NAND stays intact. The other thing to note is that Dolphin currently doesn't have a way to redirect WiiConnect24 requests. That means users will need to patch the channels to seek out the third party servers.

If you're into weird era specific features, connecting to these services is absolutely worth the time. Just to give you a taste of what you can find, here is a clip from Nintendo Week 7 Dec 2009, captured from Dolphin using RiiConnect24.

If you want to see more great videos like this, patch your Nintendo Channel today and check out the Nintendo Channel on RiiConnect24 with either your Wii or the latest builds of Dolphin!

Note: RiiConnect24 and WiiLink are third party services much like Wiimmfi. You should make sure that you trust any third party service before connecting to it via any emulator. However, both RiiConnect and WiiLink are open source, and were tested by developers during the development/testing of WiiConnect24 changes.

5.0-17527 - Netplay: Redesign Wii Remote Data Exchange by AdmiralCurtiss¶

As we said in the intro, Wii Remote Netplay has been a frustrating, yet tantalizing, feature since its inception. The Wii has a ton of multiplayer games that either didn't support Wi-Fi, or had substandard Wi-Fi support leading to couch multiplayer being the superior choice. Dolphin has netplay that lets you take couch multiplayer online. Everyone wins, right? There's one problem: Wii Remotes.

Using Wii Remote Netplay is a test of frustration for all but the most hardened of users. A ton of pitfalls awaited anyone who dared try to use it.

Wii Remote Netplay did not support automatic port assignment, which was completely the opposite of GameCube Controller Netplay. This meant each player had to configure the actual Wii Remote slot's profile to match what slot they were assigned to on netplay. To see how automatic port assignment works in Netplay now, please check out the netplay guide.
Wii Remote Netplay would crash on close due a previously undetermined bug with Safe Shutdown on netplay. Some Wii games flush saves during "Safe Shutdown" so we couldn't just outright disable this feature on netplay.
Wii Netplay has to export saves at the end of a Netplay Session if a user wants to permanently save them. But, because Wii Remotes would usually cause Wii Netplay to crash during safe shutdown, this meant that saves would get lost in limbo. While it was technically possible to restore them, it required expert knowledge and manual reconstruction of the NAND.
If a Wii Remote disconnected during a netplay session, for any reason, Dolphin would crash. This is despite there being code designed to handle this exact situation. Unfortunately, this meant that games like Donkey Kong Country Returns and Dokapon Kingdom couldn't be played on netplay, as these games will disconnect various Wii Remotes during the menus.
The Real Wii Remote setting will never work on Netplay. This is less of a problem nowadays thanks to the innovation of connecting physical Wii Remotes as emulated controllers and the "Wii Remote" controller profile. Some problems solve themselves.

These limitations and a confusing UI for setting up Wii Remotes on netplay meant that only extremely well researched users could actually use it. In order to fix all of these problems, AdmiralCurtiss decided to rethink how Dolphin would communicate Wii Remotes over netplay.

Donkey Kong Country Returns struggled with netplay because it disconnected Wii Remotes.

If it wasn't obvious by the list of problems, Dolphin's netplay was not designed for the complexity of the Wii Remote. Still, it was implemented because we figured someone would want to use it, even if it was a pain in the ass to setup and use. Unfortunately, it was hard to recommend to anyone but the most desperate of players because of all the hoops you had to jump to get there.

The initial implementation from RachelBryk was an experimental solution to enable functionality. It was meant more for experimentation and testing than general users, but once they saw it could work, users obviously wanted to use it. It was hard to provide help for the feature because it was so temperamental that most developers couldn't tell what was wrong. It got to the point where Wii Remote Netplay was one of the few features outright removed for the Dolphin 5.0 release in order to prevent users from thinking it was a fully working stable feature.

Experimental Wii Remote Netplay was available throughout most of the 4.0 era.

However it was removed before 5.0, and restored after the release.

Dolphin's Netplay has evolved over the years. The advent of the desync checker revolutionized netplay, and allowed users to immediately know if something was wrong on boot. Other features, like the "Blank NAND" further stabilized Wii Netplay in general. Wii Netplay was on the rise, but one problem remained constant: The Wii Remote.

The problem with fixing this is that the Wii Remotes are so complicated to handle. They communicate over Bluetooth at a high polling rate of 200hz, have their own logic for attachments, come equipped with accelerometers and (optionally) a gyroscope, carry a speaker which can play 8-bit PCM audio, and even come with an infrared camera with a resolution of 128x96. While Dolphin doesn't enable it on netplay, Wii Remotes even have a small bit of EEPROM for storing Miis on them! Wii Remotes are weird. But worse of all, the Wii Remote's reporting mode can change at any time, and the sessions have to be perfectly synced in order to prevent a deadlock from the wrong inputs being received on one or more Wii instances.

Sometimes in order to make things work, you need to start fresh. In order to start the healing, AdmiralCurtiss did the most logical thing and immediately threw out most of the existing Wii Remote handling code used for Netplay. At this point, we knew the problems with Wii Remote Netplay and could now try again to write a solution that avoided these issues.

The big one is that when a Wii Remote talks to the Wii, it does this with input reports - small chunks of data sent over the Bluetooth connection that contain a partial Wii Remote state. These reports are what was sent over the network during Wii Remote Netplay. The problem comes that the game can configure at any time what kind of report it wants the Wii Remote to send. This means if there's any kind of problem on netplay on any of the clients and the reports don't match what the game is expecting, Dolphin would lock-up. In the best case, netplay would close but usually the entire emulator would crash.

Because of how sensitive this is, AdmiralCurtiss decided to take a different route. Instead of sending just what the game is requesting, all players will send all of the Wii Remote state across netplay and let each Dolphin instance translate those into an input report. This makes Wii Remote netplay more resilient to crashes over minor configuration problems and also opens up a ton of new features. Since we're no longer relying on each Dolphin instance to sort out the Wii Remote state, players on netplay can now do things like change attachments during netplay and it can handle events where the game might forcibly disconnect a Wii Remote.

AdmiralCurtiss also standardized Wii Remotes to use the same conventions as GameCube netplay. This means Dolphin's automatic port assignment now works the same across all controller types. Best of all, Dolphin no longer crashes when you attempt to end a Wii Remote Netplay session.

Wii Remotes have seen some renovations and should be just as easy to setup as GameCube Controllers for netplay.

That's not to say everything is perfect. AdmiralCurtiss mostly focused on getting things working with this rewrite, but there are still some missing features. "Golf Mode" and "Host Input Authority" should be able to work under the new implementation, but weren't done alongside the first wave of changes. As well, SD cards are not synced on netplay, so it's usually best to unplug them or make sure they are manually synced between players if SD cards are absolutely necessary.

With these changes, we're hoping that Wii Remote Netplay will finally be a feature that our general users can setup and enjoy.

5.0-17681 - Vulkan: Use VMA for memory allocations by K0bin¶

We're going to be talking a lot about Vulkan coming up as there were some renovations done throughout the backend. A consequence of these renovations is that Dolphin now uses Vulkan Memory Allocator (used by many open source projects to efficiently allocate memory, including other emulators) to handle memory management with Vulkan.

This is a definite improvement, but it didn't exactly fix anything. The problem was that other changes to the Vulkan backend left us with some instability problems and we thought that Vulkan Memory Allocator would fix the issue and most likely improve performance. It didn't fix the issue and didn't have an immediate impact on performance, but it still optimizes how we're handling memory in Vulkan. VMA is a definite improvement and we're happy to join the ranks of projects using the library.

5.0-17499 - Vulkan: Raise number of command buffers and 5.0-17620 - Vulkan: Allocate descriptor pools as needed by K0bin¶

Now we're going to get into why VMA was thought to be needed. Namely, Dolphin's usage of Vulkan was pretty primitive in some ways. The emulator was only using two command buffers and a single descriptor pool of 100,000 descriptor sets every frame. These choices weren't exactly efficient, but they weren't exactly causing problems either. Except on Android.

Our eternal battle with GPU drivers on Android has an ebb and flow. While we love to blame the drivers for their problems, there's always the otherside of things where Dolphin does something stupid. This time, we were the ones being grossly inefficient.

K0bin found out that Adreno GPUs were forced to stall when running Dolphin because they were waiting on an available command buffer, particularly in games that need readbacks (EFB/XFB2RAM titles.) By increasing the number of command buffers to eight, K0bin reduced GPU stalling and made it so the mobile GPUs could work more efficiently. This doesn't mean your maximum performance at 1x Internal Resolution will go up, but this might mean you'll be able to play at a higher internal resolution before you become GPU limited!

This is a major optimization and we wanted to show some fancy graphs showing how much better things were running. Unfortunately, Android said no. Even though we reduced GPU usage by up to 30%, due to performance governors on the phone clocking things down, we were unable to see a difference in framerate on our devices. While sometimes the CPU would clock up, the numbers varied so greatly even within the same build, that we no longer feel confident in giving performance numbers on Android.

"You need this? No, I don't think you need this."

The good news? This brings Vulkan's performance roughly in line with OpenGL on Android under Adreno devices. While we can't guarantee the drivers play nice in every game because performance testing has been a nightmare, we were able to confirm this fixes NES VC games being abnormally slow on Vulkan + Adreno.

Unfortunately, this optimization had some unintended effects that reverberated through the Vulkan backend, especially for our macOS users through MoltenVK. Players were reporting new and exciting crashes throughout tons of games, forcing K0bin into figuring out what was going wrong.

Thankfully, the issue became apparent relatively fast. The new code wasn't wrong but other parts of the backend relied on how things worked before. Previously, if Dolphin ran out of descriptors, it would submit a command buffer expecting that to get it a fresh descriptor pool. With the new changes, submitting a command buffer would no longer get a fresh pool, and Dolphin would find itself still out of descriptors, at which point it would skip the draw.

In order to prevent the crashes, graphical issues, and further reduce memory overhead, K0bin changed Dolphin to now allocate descriptor pools as needed. This technically could positively affect performance, but we weren't able to measure any difference in practice.

5.0-17357 - Optimize GetVertexSize and 5.0-17370 - Cache Vertex Sizes by K0bin¶

New hardware always brings new opportunities. But that new hardware doesn't need to be something that pushes the boundaries of performance. In fact, one of the most exciting new devices this year is made up of decent, but unremarkable hardware in an interesting form factor. Of course, we're talking about the Steam Deck. This is an exciting target for Dolphin because it's got a respectable CPU and real GPU drivers paired with a mobile gaming form factor. In theory, it should be great for Dolphin.

However, early days of testing has been a somewhat rocky experience. Using Dolphin's desktop GUI on the Steam Deck isn't fun and takes a lot longer than you would like. Setting up controls is frustrating and actually getting Dolphin to compile on the Steam Deck is a nightmare unless you're fairly well versed in "Linux-fu". Thankfully, there is an easily accessible flatpak version (not maintained by Dolphin Emulator Staff) that keeps up with our beta builds, but it has a few problems not present when you compile yourself.

Thankfully, the situation improves a lot once you get past the setup stage. Light-to-midweight games run very well, and if you need a bit more juice you can always lock the GPU at a higher clockrate in exchange for lower battery life. But the hardware was just missing full speed on some mainstream titles. One game in particular was Super Mario Galaxy, which hovered around 80 to 90% speed in several strenuous areas.

A slight optimization wouldn't be enough to make one of the Wii's premiere 3D platformers fullspeed on the Steam Deck, but it was close enough to at least give it a shot. Having observed the performance problems first hand, K0bin downclocked their desktop and decided to profile things there. While a 20% jump in performance was a lot to ask for, they figured they could look for some low-hanging fruit and at least bring it closer.

Things took a twist when they discovered that the function GetVertexSize was using a lot of CPU time on the GPU emulation thread. This function should only need to come up once per vertex format and isn't anything that you'd expect to see in a flame graph. Surely there was a reason, right? Well, they started optimizing it and immediately got positive results. In fact, just optimizing this alone was able to push performance up on a downclocked R9 5900 roughly 30%! That's a huge jump, and one that had to be seen to be believed.

Testing it on the Steam Deck didn't provide as huge of a jump everywhere, but it was just enough to push it to nearly full speed in most demanding areas. But then the question became how we missed such an obvious problem.

git blame revealed that this is a performance regression from just under 2 years ago during the fifoplayer quality of life updates. We didn't notice the performance regression because other optimizations were masking it, but an erroneous duplicate GetVertexSize was added which was causing it to be called for every single primitive. Suddenly something that should only take a little CPU time was taking a lot.

Finding this issue inspired K0bin to continue to optimize that part of the code. They discovered that we could also use the cached VertexSize instead of having use GetVertexSize again in some cases. This gave another jolt to performance.

The fix plus the optimization put together more than did the trick. We tested the Steam Deck after painfully compiling a build with the optimizations and played through a good bit of Super Mario Galaxy (and a little of Super Mario Galaxy 2) at full speed and 2x Internal Resolution without any noticeable slowdown. In fact, you can even throw on Hybrid Ubershaders and get a pretty smooth experience on par with a mid-range desktop!

So, at this point you're probably wondering if this optimization carries over into other games. After all, pretty much every game is going to be using primitives, right?

The answer is yes, but the numbers aren't usually this ridiculous. On high-end gaming PCs using Dolphin's default settings, the Super Mario Galaxy games saw an improvement of around 30% when running at 4x Internal Resolution. High polygon games that lack other bottlenecks will improve similarly, but games that have different performance profiles may not see as big of a benefit. If a game is really difficult to run with tons of different bottlenecks, they will see very little gain. Rogue Squadron 3 gains less than ~1.5% performance in most areas.

Most normal games will see an increase in performance ranging from around 5% to 10%, with some anomalies like Super Mario Galaxy seeing larger gains.

5.0-17542 - Update EFB Peek Cache on Draw Done and Tokens by K0bin¶

The other major bottleneck in the Super Mario Galaxy games comes from their use of EFB Peeks. In essence, an EFB Peek is when the GameCube/Wii CPU reads pixels of the Embedded FrameBuffer (EFB). By peeking into it the game can learn information about one or more pixels, such as their depth, color, etc.

Super Mario Galaxy 1 and 2 use EFB Peeks for two things, and only one of them is necessary for gameplay. The first thing is a depth check for pixels on screen. This is how the game is able to tell where your cursor is in relation to 3D space. It's used to tell where to shoot starbits and can be used to see if you're trying to grab objects like Pull Stars.

Pull Stars are essential to proceed throughout the game, much to the chagrin of many Android users.

The other use doesn't affect gameplay but can hurt performance just as much. This check is only active while a "sun" is on screen. Even when the sun is within the field of view of the camera, that doesn't mean it's actually visible. There might be a wall, planet, ground, or something else occluding (blocking) the view. That's where EFB Peeks come in - the game uses EFB peeks whenever a sun is in front of the camera to make sure it is actually visible! This is why many users complain of slowdown on weak devices only when a sun is on screen!

Galaxy uses EFB Peeks to look at the screen coordinates where the sun should be.

If the EFB Peek cannot "see" the sun, the game will not render the sunflare. In this demonstration we disabled EFB Peeks to force it to fail.

This technique is an easy and effectively free way to sample the screen for occlusion on the GameCube and Wii. Tons of games use this technique (or a variation on it) for rendering lens flares only when the source light is visible. For example, The Legend of Zelda: The Wind Waker does the same check but with inverted conditions - it isn't checking if the sun is visible but if it is blocked. However, not every developer got the memo on this simple lesson. See Rune Factory: Tides of Destiny.

If only they had used EFB Peeks.

While this technique is more-or-less free on the GameCube, it is an absolute pain to emulate. We've covered something similar in the previous Progress Report so this explanation will be a little familiar.

The GameCube and Wii use a unified memory model, where the CPU and GPU can read or edit eachother's memory at any point with no performance cost. However, Dolphin runs on split memory model systems where the CPU and GPU cannot access eachother's memory easily. To emulate the unified memory model, Dolphin duplicates the GC/Wii Main Memory on both the host's system memory and the host's GPU vram, and we sync any changes across both memory pools. Any time a sync is issued, we have to stop all work until the sync is complete, so the host hardware will just sit and wait while the data is moving through the system. At the speed computers operate, moving data from system RAM to GPU VRAM takes ages, so all that waiting causes a sizable performance hit.

Specifically with EFB Peeks, we have to stall the GPU and synchronize the memory pools so the CPU can read the rendered frame.

Fortunately, desktop GPU drivers have many optimizations to minimize the impact of stalls, and modern desktops are so powerful they can usually just eat the performance hit while keeping emulation far above full speed. The only time that EFB Peeks become a problem for Dolphin is in very extreme cases where they are combined with other shenanigans (EFB Pokes, Store EFB Copies to Texture and RAM, etc.) or weaker hardware with iffy drivers and stingy governors.

Enter Android.

Whether you're on Adreno, Mali, or PowerVR, a game using EFB Peeks, Pokes, or one that requires the use of Store EFB/XFB Copies to RAM usually spells doom for performance. In the mobile landscape, everything is optimized to save power. But mobile SoCs do not understand Dolphin's weird workload. If a game triggers a memory pool sync, we have to stall the GPU while data is moving around. Mobile power governors see us stalling and think we are done with work, and immediately drop the clocks back to idle. But a few microseconds later we're back to needing maximum power. Unfortunately, the SoC will take its time and reluctantly raise clocks back up. Super Mario Galaxy and Super Mario Galaxy 2 will be doing many of these checks every frame. Unless your phone is absurdly powerful or your performance governor is extra forgiving, it's very hard to maintain to maintain full speed with all of this going on. Many of our mobile players have been working around this by only enabling EFB Peeks in stages that absolutely need them.

There is no way to make stalls cheap, and power governors are mostly out of our control, so the challenge becomes bundling and reducing the number of required readbacks as much as possible. This optimization by K0bin helps us get a little more mileage out of our last GPU sync/stall. Instead of just invalidating the EFB Peek cache, on tokens and drawdone, we can queue an update to all previously used EFB tiles. If the game only does work on the CPU between the DrawDone or Token and the actual EFB read, the read is able to hit the prepopulated cache and no longer needs to stall the GPU for another readback. This reduces the number of readbacks in many situations.

With this change, EFB Peeks are significantly less costly. In our testing, a Snapdragon 865 was able to run many stages of Super Mario Galaxy at 60 FPS without disabling "Skip EFB Access to CPU", including ones with Pull Stars that would need the performance the most.

Is this a catch all to improve performance across all games? Unfortunately, not really. EFB Peeks are pretty much the best case scenario of readbacks, and this change further cements this. Other games like Super Mario Sunshine uses Peeks, Pokes, PerfQueries, Store EFB Copies to RAM, and more. Even though this game only runs at 30 FPS (unless you choose to use a 60 FPS mod), the fact it uses so many difficult to emulate features turns it into a performance nightmare on Android.

This optimization has been merged into the setting Defer EFB Cache Invalidation, which is enabled automatically for the Super Mario Galaxy games. Because these cached results could break things in other games, we haven't enabled this optimization everywhere. You can test this change out in other games by enabling it under Graphics Settings > Advanced > Defer EFB Cache Invalidation.

5.0-17762 - D3D12: Fix Numerous hangs by K0bin¶

D3D12 is usually considered Dolphin's most performant backend for integrated and low-end graphics cards on Windows. Unfortunately it's also gotten another reputation among people with stronger computers: the most unstable backend. In fact, there have been dozens of reports of crashing in games specifically when using D3D12, forcing users to switch to other backends.

Things went from bad to worse when unrelated optimizations in 5.0-17542 caused more games to start crashing in D3D12. So K0bin was enlisted to figure out why this optimization that improved all backends would only cause problems in D3D12.

After fixing up D3D12's validation layers, which hadn't been touched in a while, K0bin quickly found out there was a slight issue with BindFramebuffer in the D3D12 backend. It seemed very possible for it to rely on a pipeline configuration that hasn't been set. While we had seen a lot of reports of crashes in D3D12, we were never able to figure out an exact cause because of how particular it was to trigger it. You needed specific games, running under specific settings, using a specific GPU and sometimes even a specific driver version.

Ironically, by accidentally making the problem occur more often, K0bin made it much easier to track down and fix. All that was needed was a small change to prevent Dolphin from relying on unset pipeline configurations. This fixed both the new crashes on D3D12, and the previously unsolved crashes that had been plaguing it for years.

We're happy to report that D3D12's stability should finally be on par with the other backends now.

5.0-17403 - Add Dynamic Vertex Loaders for Ubershaders by tellowkrinkle¶

The last couple of changes have been about achieving maximum performance, but now we go into a different kind of performance. As mentioned in the last Progress Report, tellowkrinkle has been working toward smoothing things out with Ubershaders. Due to various issues across various drivers, Ubershaders haven't been able to completely remove stuttering, especially in the modern Graphics APIs.

The original Ubershaders were created back when D3D12 and Vulkan were the "next-gen" video backends and most of our users were on D3D11 and OpenGL. We were aware that the new APIs used "pipelines" but it wasn't 100% clear the effect they would have on Dolphin yet. For Ubershaders, it's been a problem, to say the least. We talked about these a bit in the last Progress Report where tellowkrinkle already had one change dedicated toward reducing pipeline counts.

For a quick rundown, the graphics pipeline is a fundamental building block for rendering on newer graphics APIs. It contain all of the data for a draw, taking vertices and textures all the way to the pixels in the render targets. However, since the pipeline contains all the settings for the draw, the display driver can optimize it before feeding it to the GPU. Some drivers then optimize those pipelines by combining the hardware vertex loader settings into the actual shader, which essentially makes our Ubershaders not so Uber anymore. So when the vertex loader on the GameCube changes settings, a whole new shader would need to be compiled with new vertex loader settings, usually resulting in a lengthy stutter.

We did run into this issue with Vulkan when Ubershaders were first implemented, but we were hopeful that API extensions or driver updates would eventually lessen or erase the issue. That hasn't happened.

tellowkrinkle's solution isn't to make pipeline generation faster, but to simplify our pipelines so there are fewer branches and thus fewer pipelines in total. tellowkrinkle was able to reduce our pipeline count so much that now nearly every pipeline is able to be precompiled at boot! And while these changes aren't able to remove the possibility of shader stuttering on every backend on every graphics card, it brings us much closer to that reality.

Ubershaders weren't fixing the problem on Metal before these changes.

In newer builds, Ubershaders work as advertised by simplifying things for pipelines.

The Vertex Loader Ubershader, along with some changes leading up to it make a huge difference in shader compilation stuttering on all hardware.

Metal: macOS users can rejoice, as there are now no known drivers that will suffer from shader generation issues when using Ubershaders.
D3D12: On NVIDIA and AMD graphics cards, using D3D12 should now provide the same stutter free experience as D3D11 has when using Ubershaders. Intel's drivers were not tested, but are likely greatly improved or completely stutter free.
Vulkan: This is the most complicated case. On macOS via MoltenVK, shader compilation stuttering is completely eliminated except on Apple Silicon, where there may still be rare pipeline compiles. On Windows and Linux, the situation is improved but NVIDIA still tends to have a few noticeable compiles here and there. Wider support of the VK_EXT_rasterization_order_attachment_access extension would help eliminate pipeline compiles across pretty much every driver. That includes mobile drivers too, such as Adreno and Mali!
D3D11: D3D11 does not have pipelines and doesn't benefit from this change. It also didn't suffer from the problems, so there's that.
OpenGL: While it does have proto-pipelines with display lists and command lists, this change only targeted the newer APIs. OpenGL worked fairly well on most drivers anyway, so there wasn't too much to gain.

Odds are, you probably won't see shader stuttering anymore even if you're on one of the configurations listed as not completely fixed. And if you do see shader stuttering, it'll be greatly reduced compared to before.

5.0-17691 - Add Emulation of Pointsize/Linewidth in Vertex Shaders by tellowkrinkle¶

This is a big one for macOS users, but it will have implications for everyone else sooner or later. The GameCube/Wii GPU has features called "Pointsize" and "Linewidth" which allows a developer to draw a point or line and give it an arbitrary size without having to use actual vertices or polygons. OpenGL developers may find that this feature sounds familiar, but that is to be expected as the GameCube and Wii's pointsize and linewidth were based on OpenGL's! However, the GameCube added enough special sauce that they cannot be accurately emulated with OpenGL's native pointsize and linewidth. Since newer APIs have nothing like this and neither does D3D11, all of the APIs our backends use do not support this feature natively.

Many games use these features, and without emulation of pointsize and linewidth, any lines will be 1 pixel wide and any points don't appear at all!

Without proper Pointsize and Linewidth emulation, most of Mega Man Network Transmission's effects are barely visible.

So, considering our host GPUs can't natively render this, we had to find a way to emulate it. Our solution has been the use of Geometry Shaders. Geometry Shaders are an optional shader stage that can take a primitive in as an input and can output zero or more primitives. For Dolphin's purposes, we could use the "Point" or "Line" request as the input and then, based on the other properties the game specifies for that point/line, draw triangles that will create an identical shape.

When Dolphin adopted Geometry Shaders, they were a new and promising feature in graphics tech. Unfortunately, they were quickly superseded by newer features because Geometry Shaders are slow, so games avoided them. This put Geometry Shaders in a precarious position that finally reached a breaking point with the Metal Graphics API by Apple - Metal does not support geometry shaders whatsoever. Even though Geometry Shaders work in macOS under OpenGL, but, it's not in Metal. For us, this meant we needed to find a new solution if we were going to emulate Pointsize and Linewidth on modern macOS machines.

Originally, skylersaleh (who did Dolphin's port to macOS M1 and now works on skyemu) started an experiment with using tried and true Vertex Shaders. While this could make wide-lines and thick-points, the original experiment failed because it wasn't able to get them to render correctly. pokechu22 picked it up but quickly found that this wasn't a simple fix.

Dolphin as it was couldn't give the Vertex Shaders all of the information it needed to determine the way to orient line caps. A way to work around this was to have Dynamic Vertex Loaders, which would be able to determine the information we need directly in the Vertex Shader. Funnily enough, while 5.0-17403 was designed to make Ubershaders more effective, those same Dynamic Vertex Loaders could be used to finally finish Pointsize/Linewidth with a Vertex Shader!

Support for Geometry Shaders, especially with Metal outright abandoning them, might be on the way out. So having this option is good now, but might be outright necessary later. Currently, we still use Geometry Shaders when they're available, but on GPUs without Geometry Shader support, Dolphin will now use the Vertex Shader implementation instead. Users can also try it out - it can be enabled in Graphics Settings -> Advanced with "Prefer VS for Point/Line Expansion".

With working effects, Network Transmission comes to life!

Because the Vertex Shader implementation is slightly faster, we will probably move over to it as the default implementation. This actually comes into play throughout the Metroid Prime Series, where the linewidth effects can effect overall performance. If your machine has a driver with incredibly slow Geometry Shader support, this may help things! However, on most modern GPUs, this is far down on the list of bottlenecks.

Note: Our D3D11 Backend does not have Vertex Shader Linewidth/Pointsize for now. It's not impossible to accomplish, but due to the inline constant system from D3D12 not existing, it would take a different implementation.

5.0-17836 - Debugging: Add Support for Conditional Breakpoints by smurf3tte and TryTwo¶

For people debugging, modding, TASing, or just in general messing around with a game's behavior, this is a major enhancement that will make your life easier. Dolphin has long had support for breakpoints, but the problem was that if it was a frequently used instruction, you'd have no way of telling it only to notify you if the condition you were looking for actually happened. Instead, debuggers would often rely on third party tools in order to debug more difficult issues.

Conditional Breakpoints make debugging hot functions much easier.

This change adds support for basic logical conditions, but TryTwo has already started work on callstack based conditions and support for conditional Memory Breakpoints as well.

5.0-17902 - Add GBA TAS Window by JosJuice¶

When Dolphin added support for the Integrated GBA there was some excitement about TASing titles that require GBAs. After all, Integrated GBAs worked with Dolphin's movie code as shown by Netplay Support!

Technically, Integrated GBAs could be controlled using TAS input when things were merged, but there was no built-in support. Instead, Bonta hooked up the existing GameCube Controller TAS input to the GameCube TAS Input window. However, as with any major, complex change, this detail was actually overlooked. When the TAS Input Handling was rewritten, this feature was accidentally removed and suddenly there was no way to control Integrated GBAs through TAS Input.

As the guilty party that accidentally removed support, JosJuice quickly jumped on the issue to rectify things as soon as they realized what had happened. But rather than just returning the old normal, JosJuice greatly improved the situation by making a special TAS Input window for Integrated GBAs with all of the controls now clearly labeled.

Will we see a Four Swords Adventures 4 player TAS someday? We sure hope so!

5.0-17907 - Improve FPS/VPS Counting and Revamp Appearance by Sam-Belliveau¶

Dolphin's FPS counter has always just been there. We don't even know for sure how long we've had it - we found it in r488 (1.0-488) from 9 Sept 2008, but it could be even older! It has changed a lot in that time of course. Originally it was an overlay built directly into each graphics plugin, before being moved to the Rasterfont system split between videocommon and the video backend, and finally moving to the shared Dear ImGui form we have today. However, despite being moved and rebuilt several times, how our FPS display calculates frames per second has never changed. Until today.

Progress Report newcomer Sam-Belliveau was distracted by how Dolphin's FPS display constantly flickered above and below 60FPS. It annoyed them so much that he decided he was going to do something about it... and fell down a rabbit hole. First of all, he added VPS (v-blanks per second) and emulation speed measures to the performance overlay, so that users in fullscreen and on Android can finally get this essential information.

The above is correct. In NTSC territories the GameCube and Wii operate at 59.94fps not 60, requiring us to do some shenanigans for correct emulation on modern displays. What you see in Dolphin's titlebar is rounded to whole frames.

And he added color to the performance overlay, providing a very glanceable indicator of Dolphin's performance! The colors are cyan (full speed), green, yellow, orange, then finally red.

Red is bad. You probably didn't need us to tell you that.

But most importantly, he changed how Dolphin's FPS display is averaged. Before we explain how he did it, here's a before and after of the FPS display with a title running at a perfect 60fps (59.94 technically).

With the old formula, the FPS counter was a little unstable, with a variance of about half a frame. Unfortunately, it varied above and below 60fps, causing the most significant digits to constantly change. It was difficult to keep track of performance with this display.

With the new formula, the FPS display no longer flickers the most significant digits and its variance is actually close to Dolphin's rendering!
_{Note: It isn't staying exactly 59.94 due to the shenanigans we have to do running 59.94 content on a 60hz display.}

Previously, the FPS display used an extremely simple formula: number of frames in the sample / microseconds of the sample / 1,000,000. That's it. This is an incredibly basic way to calculate frames per second, and it has worked for Dolphin for a very long time. It does the job. However, the downside of this method is that it is "sample and hold". Between samples Dolphin just shows the previous sample, completely unchanged, which feels unresponsive and could make stutters and other problems either invisible or overly emphasized. To minimize this Dolphin could use a very short sample cycle, but that has the consequence that each sample has little data to work with. If your sample size is only a few frames long, then even a spike lasting a single frame could significantly alter the results of the average, making the FPS display highly unstable. A longer sample time would resolve that, but then we're back to having it feel unresponsive and hiding stutters and other problems. So Dolphin developers of the past chose a sample duration of 0.25 seconds - this leaned a bit toward frenetic and unstable but kept the FPS display reasonably responsive. With a super simple formula like this, compromises are unavoidable.

The solution to this is to use an exponential moving average on top of a standard moving average - we'll call this a "Euler Average" for short. Basically, it averages the framerate over the last second (by default) using a standard moving average, then applies an exponential moving average on top to reduce jitter. The result of this math is that Dolphin can sample every frame so it is always up to date, it can smooth out sudden spikes and drops for a stable, legible indicator, and it can update the FPS indicator every frame so it is visually pleasing as well!

To show how this works in action, here is a graph showing the two methods against eachother. The data we're feeding into it is from a Dolphin test with an unlocked framerate, with frame to frame swings as high as 100FPS. It's a worst case scenario for an FPS display. How do the old and new FPS formulas handle this awful data?

Click for detail.

The purpose of an FPS display is to give a glanceable reference of a game's performance. But the FPS display with the original formula can't handle data that is this variable. It just goes all over the place; even if you stared at it you would have no idea how fast the game is performing! But the Euler average is able to display a proper average of the framerate even from this garbage data. Of course, no one should encounter frametime variance on this level in actual gameplay unless something has gone very very wrong, but even in this worst case scenario our frame rate display is now able to do its job thanks to the new formula!

A consequence of using the Euler Average is that there is a now ramp up. If a game goes from 0FPS to 60FPS in one frame, it will take the whole sample window (1 second by default) to resolve to 60. Averaging the current data with prior data prevents sudden spikes and drops from making the FPS display devolve into noise, so it has to catch up to extreme change. To account for this, this change also adds a control to allow the user to change the sample window duration. A longer window will give a smoother and more consistent indicator, and a shorter window will be more frenetic but will be closer to real time and show smaller drops.

This and other new controls necessitated a move for our performance display options. You'll now find them in Graphics > Advanced under "Performance Statistics". This is not necessarily their permanent home but it's a safe place for Sam-Belliveau to continue working on this feature.

With this, our performance statistics display is better than ever! But Sam-Belliveau is not done. Expect this feature to get even better in the coming months!

More Patches for dcache Reliant Games¶

Dolphin doesn't currently target emulating the CPU Data Cache (dcache) and once it does, odds are that enabling it will make emulation too slow. For now, we're relying on patching these games that accidentally rely on the GameCube/Wii's CPU dcache behaviors.

The past three months, we've seen two new patches from smurf3tte, who has done the hard work of reverse engineering these games, figuring out why they need dcache emulation, and patching their code to no longer need it! So if you're playing Dead to Rights (audio issues) or Ten Pin Alley 2 (crashing before gameplay) in the latest development builds, you have smurf3tte to thank!

Note that the patch for Ten Pin Alley 2 is only for the NTSC version of the game.

The Android GUI Refresh¶

There are far too many changes that have gone into this over the past quarter of the year. t895 has been extremely busy going through the Android GUI and modernizing it. From redesigning buttons, to making things fit your phone's theme/shape/size, and even some optimizations that will allow the menus to run more smoothly with fewer hitches.

Everything is at least a little nicer than before!

One of the biggest keys is that Dolphin now supports Google's "Material You" design system. By default, Dolphin uses its own color scheming under "Material 3", but if you want it to match your system-wide theming better, you can swap over to "Material You" and several other color based options in the theme menu.

In addition to the theming changes, t895 has greatly optimized the cover loading/caching mechanism to prevent the lockups on first load when swapping between GC/Wii/WiiWare tabs. This should make app usage much smoother overall. There are tons of minor fixes, especially for those with oddly shaped phones that should prevent things from going off screen or awkwardly resizing.

A bunch of the menus have also been redesigned to make things fit better and look nicer.

Some changes are subtle.

Others are radically better.

But basically every window has been given some needed attention.

While none of this directly affects emulation, it does make setting up the emulator easier and allows for greater customization. Those of you that want your phone and its apps to be personalized for you should have a lot of fun with these changes. For everyone else, these changes will make setting up and adjusting things from within the emulator much smoother.

Last Month's Contributors...¶

Special thanks to all of the contributors that incremented Dolphin from 5.0-17271 through to 5.0-17995!

Dolphin Progress Report: July and August 2022

2022-09-13T07:46:32+00:00

The Summer tends to consistently be one of the busiest times for Dolphin's development. While sometimes the question is what do we put into the Progress Report, during the summer months it's usually how much can we fit into the Progress Report? This summer's congestion was then compounded by us blog staff having a few things we've been planning coming into fruition. Still, the show must go on, and we're here... albeit a bit delayed.

As such, we've got a huge smattering of changes to go over and many smaller ones that we couldn't quite fit in. macOS users in general will be able to rejoice with the addition of a brand new Metal backend brought to us by veteran developer TellowKrinkle. They also brought their graphics expertise to improve things for everyone, greatly reducing the remaining causes of shader based delays/stuttering when using Ubershaders. If you're looking for an easier way to setup a wide variety of controllers, a new SDL2 controller backend has been added for all OSes, and even brings native motion control support without the use of a DSU server to non-Linux operating systems. We also have a wide variety of emulation fixes, more graphics mods added, and the long awaited SD card "folder" feature!

All of that and it's our job to write about it. We've got our work cut out for us.

Notable Changes¶

5.0-16965 - macOS: Add Metal Backend by TellowKrinkle and 5.0-17206 - MoltenVK: Update to v1.1.11 by OatmealDome¶

Early on in Metal's life, Stenzek experimented with adding a Metal Graphics Backend to Dolphin. Unfortunately, due to Dolphin's quirks and unfamiliarity with the Metal API, the effort stalled out. However, in the midst of that struggle an alternative arrived - MoltenVK. As a translation layer between Vulkan and Metal, MoltenVK allowed us to support Metal through our Vulkan graphics backend, with little effort on our end. This proved to be a very successful compromise, and it may very well have saved our macOS support.

But, in theory, a native Metal backend would be faster than MoltenVK. Enter TellowKrinkle the architect of PCSX2's macOS port and Metal Graphics Backend. Having conquered Metal on PCSX2, they turned their attention to Dolphin and decided to try their hand at a native Metal backend. The results were immediately apparent.

The above graph is not current, please keep reading.

Our macOS users were extremely excited by these improvements! In GPU heavy titles, such as the GPU focused Skyloft and Elyia tests, the difference was enormous! However, something felt off. Our native Metal backend was performing too much better. Based on our prior experience and general industry knowledge, MoltenVK is an excellent translation layer - a native Metal implementation should only be a little faster. But the new Metal backend was functioning correctly and we weren't going to argue with improved performance, so we cautiously continued forward. When we ran our new Metal graphics backend and MoltenVK through the tests above for this very Progress Report, it finally hit us. The MoltenVK results we were getting, as recorded in the graph above, were far lower than the previous times we've shown these tests. It varied substantially depending on the test (hence the difficulty isolating this), but in some scenarios MoltenVK was performing up to 45% worse than before! Something had gone wrong.

Comparing our native Metal results to our old MoltenVK results, Metal is still better, but by only a little bit.

Now with some solid reproducible cases, we went to work bisecting to isolate this nasty performance regression. We traced it to 5.0-15474 - a MoltenVK version update. This was a regression in MoltenVK itself.

Normally the story would end here. We are a tiny volunteer team, we cannot be expected to debug another project! However TellowKrinkle went above and beyond and, using their Metal knowledge, worked with our testers to isolate the regression in MoltenVK. The end of their bisecting was KhronosGroup/MoltenVK@4371ef4, a change that contained a number of optimizations for Vulkan Descriptor Pools.

In Vulkan, descriptor sets are used to tell the graphics driver what resources (textures, buffers, etc) to make available for shaders to use. However, a program cannot create descriptor sets. Instead, the program needs to create a descriptor pool with a specified maximum number of sets, and then the pool itself allocates the descriptor sets.

Most programs implement this with a "growth strategy" where they ask for a small pool of a few thousand sets, then enlarge the pool as required. Dolphin however takes the simple route, and just asks for a pool of 100,000 descriptor sets. Though inefficient, by asking for a pool far larger than anything it can ever possibly fill, Dolphin never has to worry about managing the pool.

Our Vulkan descriptor allocation code has been untouched since Stenzek's very first implementation six years ago. If anyone has the know-how and wants to make this better, by all means, have at it.

Once Dolphin allocates the tiny fraction of the pool's descriptor sets that it needs, it uses vkResetDescriptorPool (link) to give the used sets back to the pool for the next draw. Importantly, Vulkan resets only the used sets, leaving the rest of the 100,000 sets untouched - Dolphin's approach only makes sense because of this detail.

And that is exactly where MoltenVK's regression occurred. In the optimizations for Vulkan Descriptor Pools, MoltenVK accidentally made vkResetDescriptorPool reset ALL descriptor sets in a pool, regardless of what was actually used. Most programs wouldn't have any problem with this as they use as small of pools as possible, but Dolphin's 100k pool smashed into this issue. vkResetDescriptorSets was now taking up a significant amount of CPU time, causing many types of GPU heavy titles to become CPU limited within MoltenVK!

Once we had all of this figured out, TellowKrinkle forwarded our results to MoltenVK. There, the author of the original optimization that caused this regression, billhollings, swooped in. They improved the implementation so it only reset descriptor sets that were actually used, and made a PR within a couple days of our report. Once that was merged into MoltenVK, we quickly tested it to confirm it fixed our issue and OatmealDome made a pull request to update Dolphin to the latest version of MoltenVK. The regression was resolved!

We'll save the full graph for later and focus exclusively on the regression fix for the moment. How much faster is latest master (as of this writing) compared to the version we showed earlier?

While we are focusing on MoltenVK right now, Metal also got a little faster on Apple silicon thanks to an unrelated AArch64 JIT optimization that was merged between our sample versions. Our data is a little messy because developers just keep making Dolphin better, how dare they.

In MoltenVK, the performance regression fix (plus that JITARM optimization) lead to noticeable performance gains across the board. But for the the GPU heavy titles that were strongly affected by the regression, such as Metroid Prime 3, the performance improvement is enormous! It took Prime 3 from completely unplayable to playable with occasional slowdown. All of the performance that MoltenVK had in older builds was back!

This regression fix also improves MoltenVK's performance in Bounding Box, especially on Intel graphics. However this section is already ginormous so rather than posting yet another graph, just click here if you want to see the chart.

Now with that nasty regression sorted, we can finally return to Metal. How does our shiny new Metal backend compare to MoltenVK now that it's a fair fight?

The theory holds true - our own native Metal graphics backend is faster than translating our Vulkan backend to Metal via MoltenVK. Most notable here is Skyward Sword and Rogue Leader, where Metal has a considerable performance benefit of +23% and +30%. Metal even takes Hoth to a reliably full speed experience for the first time ever on an Apple laptop! That being said, now that it is no longer held back by a performance regression, MoltenVK puts up a hell of a fight.

After reading all of this you might be thinking, "now that someone has made a native Metal backend, you're going to remove MoltenVK right?" Absolutely not, MoltenVK is here to stay. The MoltenVK performance regression was a huge reminder for us on why we have many graphics backends in the first place.

During the regression, many users came to us and complained that it was slower than before. Some even correctly bisected the regression in Dolphin! However, due to the complexity of the issue, no one was able to clearly give us a reproducible case. Without anything to compare it against, we simply looked at MoltenVK's performance in whatever we wanted to try, found it fine, and moved on. However, once we had the Metal backend and compared it to MoltenVK, we immediately noticed the performance disparity was beyond our expectations and began searching for the problem. The Metal backend is why we noticed the performance regression in MoltenVK! Relying on only one graphics backend for macOS (OpenGL doesn't count anymore) let this regression slip under our noses.

Having other graphics backends to compare against is essential for the maintenance of our graphics backends, and this is especially important on macOS where we have so few. The new Metal graphics backend is our own code, so any issues or regressions with it are on us to solve. We will be relying on MoltenVK to be the benchmark that we compare our native Metal backend against going forward. And it should perform that role excellently, as it is bringing our well tested Vulkan backend to macOS through a very well supported translation layer from a team that has earned our trust.

So while our new native Metal backend is faster, MoltenVK is here to stay. Together, they will help us deliver the most consistently reliable and performant experience that we can give to our macOS users.

Note: Due to changed (much improved) methodology, the Fountain of Dreams and New Pork tests are not directly comparable to prior results. All other tests maintain the same methodology.

5.0-16930 - Reduce Pipeline Compilation Stutter through Forcing FBFetch in Ubershaders by TellowKrinkle¶

Ubershaders was a revolutionary moment in GameCube/Wii emulation. It presented a hope, a solution against the problem that TEV changes were instant while generating/compiling new shaders on modern GPUs was not. Under certain circumstances, Ubershaders can completely remove all Shader Compilation Stuttering... but for some users, their limitations meant that they couldn't get a smooth experience.

On top of being demanding, newer graphics APIs have thrown a curveball at Ubershaders. Namely, they have pipelines to optimize rendering, and these pipelines will analyze what is being rendered and only use what is necessary to simplify shaders and increase performance. Because different GPUs and drivers have hardware and software support for different things, the pipeline compilation stuttering can vary depending on the driver. D3D11, through a mixture of not having pipelines + good driver support, was the only backend that completely had Shader Stuttering removed on certain graphics cards... until now.

TellowKrinkle showed up with the Metal backend and a deep dive in to how Dolphin was generating shaders. They identified some of the weaknesses in what Dolphin was doing and identified them during the development of the the Metal Backend and started coming up with solutions.

One such problem is that Dolphin actually had too many configurations to precompile every pipeline configuration. But, there was a way to mend that. By sacrificing performance and simplifying the Ubershaders to only use a single method for blending, we could actually precompile every pipeline configuration with some other changes down the road. To achieve this, FrameBuffer Fetch is now used for almost all blend unit configurations in the Ubershaders for GPUs that support this feature. Considering that Apple GPUs and some mobile GPUs support FBFetch, many of our users should be able to see a major difference.

This reduces the extra shader compilation stuttering that was happening on Apple and some mobile chipsets and further sets us up to reduce stuttering across all GPUs. TellowKrinkle has more changes on the way that should completely eliminate* Shader Compilation Stuttering on many GPUs that currently have issues in Vulkan and D3D12 when using Exclusive or Hybrid Ubershaders. Stay tuned.

5.0-16861 - ControllerInterface - Add Support for Native Motion/Rumble with SDL2 and Re-Enable SDL on Windows Builds by shuffle2¶

Back in July 2015, Dolphin waved goodbye to its SDL input backend. Back then, there wasn't much point for Dolphin to even be using it. It didn't really serve our needs on Windows or macOS, and on Linux it was essentially just an evdev wrapper that we could (and eventually did) implement ourselves.

Unfortunately for Dolphin, the vastness of SDL has caused a number of problems over the years, and has slowly been removed bit by bit. For example, in 4.0-1628 the SDL backend was removed from Dolphin on Windows due to numerous crash reports related to webcams. SDL was reading the webcam as a controller with thousands of buttons, crashing the emulator.
Dolphin Progress Report: July 2015

However, over the last seven years, a lot of resources have been pumped into SDL and it's greatly improved from when we waved goodbye. In 2018 it added a feature that was very interesting for us - Motion Inputs. Dolphin didn't yet have the emulated MotionPlus infrastructure, but we've kept our eye on SDL knowing that it might provide an easy way to get Gyro and Accelerometer while also being a stable cross-platform API that we could rely on much like Cubeb has become for audio.

In 2022, we've finally taken the plunge and re-added support for SDL, relying on the new and improved versions of the controller API.

On Linux and macOS, the situation is similar. This is especially important for macOS, where Motion Controls are a lot more annoying to setup. In fact, Wii Remotes can't easily be connected to any macOS version from Monterey onward due to an unknown bug with Apple's Bluetooth stack that seems to be rather low priority to fix. Some users have found success using external Bluetooth adapters or using a DolphinBar.

5.0-16891 - SD Card Folder Syncing Support by AdmiralCurtiss and stblr¶

This is one of the longest awaited features that has been requested many times over the years. You can now set a SD Card Sync Folder that allows you to place files in that folder and let Dolphin automatically create an appropriately sized SD Card. This setup was inspired by how melonDS handles SD cards and was originally submitted by stblr in March.

Previously, handling SD cards in Dolphin was rather annoying, especially on Windows and Android. On Linux/macOS, it was a bit easier. There, you could mount the sd.raw file that Dolphin uses to simulate the SD card and edit files on it just like you would a real SD card. On Windows, this could only be accomplished by installing a third party program and is generally a bit buggy when trying to unmount virtual drives. On Android, you couldn't edit the sd.raw at all without access to another Operating System!

The new system isn't perfect, but it does simplify things quite a bit. Dolphin still uses the sd.raw file during emulation, but now you can choose a folder that Dolphin can use to build the sd.raw file. No more mounting, no more third party programs, just simply configure your sd card folder how you want it and let Dolphin do the work. Dolphin can also export the current sd.raw into this folder, if you've already been using other methods.

As a potentially added bonus, there is an option to automatically sync this folder at emulation start and end. This will keep your folder up to date if you're using it a lot, but we don't recommend using it on larger SD cards, as this process can take a long time on slower disks and cause a large delay in starting Wii emulation.

Due to the SD card code being rewritten, a few of the defaults have changed as well. Logically, it made no sense that the old SD card default path was inside of the Wii NAND and this gave us a good excuse to finally fix it. While this update won't override existing paths, all new users will have SD card paths moved into the "Load" folder along with other things like texture packs. In new builds, the default sd.raw name has also been changed to WiiSD.raw.

For those of you on Android, there is some good news and bad news. The good news is that this feature has been ported over by JosJuice in 5.0-16970. It works the same as in desktop builds with one exception, which is the bad news. Due to Scoped Storage, we cannot let you customize the SD folder location and accessing Dolphin's app data locations may be annoying. On most Android devices, the easiest way to do this would be by connecting it to a desktop and manually accessing the displayed directories for your device.

While not ideal, SD Card editing for Android users is now simpler than it was before.

5.0-16901 - Flush command buffers after multiple EFB copies by TellowKrinkle¶

While working on graphics, TellowKrinkle spotted a flaw with how Deferred EFB Copies were working in Dolphin.

As a reminder on what this is, the GameCube and Wii use a unified memory model, where the CPU and GPU can edit eachother's memory at any point with no performance cost. However, Dolphin runs on split memory model systems where the CPU and GPU cannot access eachother's memory easily. To emulate the unified memory model, Dolphin duplicates the GC/Wii Main Memory on both the host's system memory and the host's GPU vram, and we sync any changes across both memory pools. This syncing is very costly, and it is why games that require Store EFB Copies to Texture and RAM are so demanding. Deferred EFB Copies is as an optimization to this process. Rather than syncing every single time the game changes something in memory, Deferred EFB Copies delays EFB Copies to the host system memory so it can batch many EFB Copies to RAM together for a sizable performance boost.

Unfortunately, an oversight in the implementation limited the performance boost this option could give.

When using Deferred EFB Copies, there was a system set up to not flush command buffers if multiple EFB copies were issued in succession, but it only ever checked whether it needed to flush when an EFB copy was issued. TellowKrinkle noticed that if a game is using a lot of EFB Copies in quick succession, Dolphin doesn't check to see if they need to be flushed during this burst of EFB copies. Not flushing for each EFB copy and then flushing at the end would normally be faster, but Dolphin was waiting far too long after the burst of EFB copies to actually start checking if things needed to be flushed, causing a sizeable drop in performance when the flush and GPU <-> CPU synchronization finally happened.

This is a rather particular scenario that shouldn't be that common, but one of the games that do hit this issue is rather demanding, making this a big optimization: Metroid Prime 3.

5.0-16926 - Accurately Handle the Copy Filter and Gamma for EFB and XFB copies by Pokechu22¶

In a finale to the crazy EA Sports Active pink tinting issues, Pokechu22 has made the necessary changes to fix the remaining imperfections with color handling. While it's not as dramatic as the original issue, some of the colors of various objects were still wrong in Dolphin due to differences in rounding and some weird overflow behaviors that were left unemulated.

With this added, EA Sports Active now renders perfectly in Dolphin this plus Manual Texture Sampling. Quite a difference from just a year ago.

5.0-16838 - Add HLE Broadband Device by schthack and many additional fixes by sepalani¶

The GameCube Broadband Adapter (BBA) is another of those "What Ifs" of potential that hit the GameCube. Much like GBA connectivity there was a lot of potential for great things with the GameCube BBA, but very few games truly took advantage of it. In fact, there are only six total games that can use the Broadband Adapter for gameplay.

Phantasy Star Online I and II (and I and II+)
Phantasy Star Online III: Card Revolution
Mario Kart: Double Dash!!
1080° Snowboarding Avalanche
Kirby Air Ride
Homeland (JP Exclusive)

Not all of these were created equal, however. Only the two Phantasy Star Online games and Homeland supported true online play. All the others only supported local play via LAN (local area network). Much like GBA connectivity, the feature saw limited use simply because of the expenses and setup required. For an eight kart game of Mario Kart: Double Dash!! with everyone getting their own T.V. you'd need:

Eight GameCubes
Eight T.V.s
Eight Controllers (16 if you want two players per kart!)
Eight Copies of Mario Kart: Double Dash!!
Eight BBAs
Networking cables and ethernet switches capable of handling this mess

Unlike Mario Kart DS, where people could just pull out their own DS out of their pocket and be in the game in minutes, setting up for GameCube LAN games was a huge endeavor. For games like Kirby Air Ride it was hard to justify the cost and setup when the split-screen option afforded identical features with the only downside being less screen real-estate and your opponents being able to see your screen.

Emulation didn't really make things easier or better. If you were willing to go through the daunting setup of creating a TAP adapter on your computer, it was possible to link emulators together. But due to Windows doing Windows things, this was mostly limited to running all of the instances on the same computer. This mostly defeats the point of BBA entirely! On Linux it was a lot easier, but it was still a lot more trouble than it was worth to get working.

This is where schthack comes in. For those that have been in the GameCube community for a long time, that name may seem familiar because of schtserv, schthack's Phantasy Star Online I and II replacement server that's been keeping the game's online service alive for many, many years.

While Dolphin technically could connect to schtserv, it was a less than ideal setup due to how difficult it was to setup on Windows and how fragile it was. While the XLink Kai BBA option avoided the need for a TAP adapter entirely, it required its own service through XLink Kai and is primarily used for tunneling LAN games through the internet, like Project Warp Pipe once did during the early days of the GameCube.

Dolphin's BBA emulation was mostly low level (LLE) and functioned very similar to how it worked on console. However, because of how exactly it behaved, it did not work on Windows without a TAP adapter, and didn't work on Android at all. On Unix based operating systems, you'd still have to go through setup with OpenVPN and virtual interfaces, making it quite a process regardless of your choice. In order to make things easier, Dolphin would have to translate what the BBA was doing to something that would immediately work on the host device's network. What we needed was an high level (HLE) solution, and schthack wanted to make it happen.

Getting it working was one thing, but actually cleaning up Dolphin's ancient BBA code was another. In fact, Dolphin's LLE BBA implementation originated from documentation from Whinecube, a rival GameCube emulator that ceased development back in 2006. The documentation (and implementation based off of it) were rock solid enough that it's remained almost untouched since it was implemented. Unfortunately for schthack, that also meant that some of the code needed to be modernized for modern Dolphin. Thankfully, sepalani, another network engineer, was available to help harden the networking code. The initial results were astounding.

A GameCube, a Wii via Nintendont, and Dolphin all connected through BBA!

That isn't to say things were perfect - getting all of the Dolphin instances to detect each other can be a bit annoying, especially on Windows. Cause Windows things. Thankfully, sepalani has continued to improve the HLE Broadband Adapter with a myriad of fixes. While sometimes there are occasionally still detection issues, especially when dealing with real hardware, usually any combination of Dolphin, GameCubes, and Wiis (running BBA emulation through Nintendont) can be connected together with enough dedication.

As a note, there are some limitations with one of the games that has nothing to do with the networking code. 1080° Avalanche is not compatible when playing against physical hardware. There is some kind of miscalculation in the physics that causes Dolphin instances to desync, ruining the session. While this bug has not been fixed as of this beta, there was originally a second bug involving AArch64 devices, causing them to desync with x86-64 devices! JosJuice quickly quelled that bug, meaning that theoretically even Android users could join in on the BBA fun... if they had BBA...

5.0-16950 and 5.0-16967 - Android: Add XLinkKai Broadband Adapter and HLE Broadband Adapter Options to GUI by codedwrench and JosJuice¶

If you didn't catch it, Dolphin on Android now has access to Gamecube Broadband Adapters! Thanks to work by codedwrench to add the XLink Kai BBA option to port everything over to the Android GUI, users now can easily access the settings. JosJuice took that framework and ported that over to support the HLE Broadband device.

This means that GameCube LAN play is now in the palm of your hands. A group of friends (with exceedingly powerful phones/tablets) can now just make sure they're on the same network, select a BBA option, and instantly be able to play any of the LAN supported games against eachother.

This is where the photo of our friends meeting together for an Android BBA session would be, if, well, you know.

Sure, it's limited to just Mario Kart: Double Dash!! 1080 Snowboarding: Avalanche, and Kirby Air Ride, but that's fun in and of itself. If you can't gather everyone together but live nearby, setting up XLink Kai might be able to get you playing anyway. Note that these games have a fairly low latency tolerance, so we do recommend being on the same network if possible.

If you're looking to get your fix on for Phantasy Star Online I and II, the Android HLE BBA works the same way as the desktop HLE BBA.

5.0-16991 - DSP-HLE - Implement Support for Libaesnd Microcode by Pokechu22¶

If you use a lot of homebrew in Dolphin, you're probably someone who commonly swaps over to LLE audio. This is because a lot of Homebrew use special homebrew DSP microcodes called libasnd and libaesnd. Dolphin's DSP-HLE had no way to handle these microcodes!

This popup means you aren't getting audio unless you swap to DSP-LLE.

Feeling a bit of deja vu? Same here. This is the same change as last Report except this time it's tackling libaesnd instead of libasnd along with a few more edge cases that cropped up over the years.

This is the Duke Nukem game you've been waiting forever on, right?

With this, most major homebrew should be supported in DSP-HLE. There may be exceptions, and some homebrew may opt to create their own microcodes. In those edge-cases, DSP-LLE will always be there to cover the holes.

5.0-17132 - Implement Support for NFS files by JosJuice¶

For preservationists and those users who have bought Wii titles from the Wii U eshop, this is a rather important update. JosJuice has added direct support for the NFS file format that Wii games are distributed in on the Wii U eshop. Given that the Wii U eshop is going to end the ability to purchase new titles, your days are numbered on how long you can purchase these digital copies. For a full list of games available via the Wii U eshop, please check out this link.

While this list is fairly limited, given the price spikes of physical copies, this may be the cheapest way to get some of your favorite Wii games until the shop goes down.

As for the NFS format? There really isn't much interesting about it. It's a lossy format that removes garbage data. Adding support for it was not very difficult, and was mainly done for users wanting to test/use Wii U eshop dumps more easily.

Last Month's Contributors...¶

Special thanks to all of the contributors that incremented Dolphin from 5.0-16795 through to 5.0-17269!

Dolphin Progress Report: May and June 2022

2022-07-07T11:41:26+00:00

It's been a very hectic two months. Dolphin's development builds officially dropped support for Windows 7, Windows 8, and Windows 8.1 in 5.0-16393 when the Windows buildbots were updated to use Qt6. If you read the last Progress Report, you'd know that Windows 7 was already on shaky terms due to rampant breakages, but it was Qt6 that finally ended the legacy operating systems. We wrote an entire article about this, so be sure to read that here if you haven't already.

But with loss, some new has also come. We now have a new builder for Windows on ARM! Dolphin has supported Windows on ARM for a couple of years now, but we haven't provided builds due to a lack of prospective users and a lack of space on the buildbot server. But times have changed - the buildbot has seen some upgrades with a new, bigger harddisk and shuffle2 has renovated parts of the infrastructure to make supporting Windows ARM64 builds easier. With those two hurdles out of the way, we've now configured our buildbot to provide Windows ARM64 builds on our Downloads page. We're not exactly sure how much use these builds will get, but we're hopeful for the future of the platform.

But by this point, you're probably as sick of hearing about the gives and takes of supporting various operating systems as we are of writing about them, so let's get to some emulation goodness. We've got some highly technical changes, including a new "Graphics Mod" system that allows modders and users to create graphical mods. If you're into the edge of emulation, we've also seen support for the annoying Datel Loader used for Action Replay discs and a few very odd unlicensed devices without needing an original GameCube BIOS or swapping to DSP-LLE. This is somewhat significant for reasons we'll get into later, because using real Action Replay discs does make a difference!

For those who love creative homebrew, we've also added support for the homebrew libasnd microcode to HLE audio, meaning that you no longer need to switch to LLE audio for many homebrew titles. We go into the details of all of this and more on this Dolphin Progress Report!

Notable Changes¶

5.0-16763 - Add 'Graphics Mod' Infrastructure by iwubcode¶

Dolphin's current suite to modify the graphics of games is quite limited. All that we have are post processing shaders with no access to depth or any other fancy features. While things like Texture Packs give some freedom, a lot of players have turned to forks and third party programs in order to make larger graphical overhauls. This situation is due to the fact that post-processing has a fundamental limitation - it's done after the frame is rendered. This approach seriously hinders the goal of modifying the game's visuals. For example, if the game crushes its depth during the rendering process, all post-processing sees is a 2D frame. How are we supposed to apply post-processing effects with depth to this? That exact scenario is sadly extremely common on the GameCube and Wii, and why Dolphin's post-processing excludes depth - it was so unreliable that we decided it be better to not have it.

While most users are probably waiting for our Post Processing system to be rewritten, iwubcode has sneakily been working on a different approach, one that addresses that fundamental limitation in post-processing. The first piece of the puzzle has arrived in the form of a feature called Graphics Mods!

Graphics Mods gives users a way to hook into the game's rendering pipeline and directly modify game assets during the rendering process. It exists as something inbetween post-processing and game modding - it is specific like game modding, but like post-processing it doesn't require the daunting task of learning PowerPC assembly to order to create a game patch. Right now, the feature is in its infancy, but it's already shown a ton of promise in allowing quality of life mods to many games.

These are composed of two parts: an "action" and a "target" group. The action contains what the mod will do with the target, such as a "skip" to prevent the target from rendering, and can be generic. The target is specific, extremely specific, as it defines the precise texture, texture format or EFB Copy format we wish to modify. The target group can have a single target or many targets depending on what the modder wants to do.

This may all sound complicated, but in actual application it is extremely simple. To give an example of what Graphics Mods can do, lets look at Super Mario Galaxy 2 on Dolphin without enabling any Graphics Mods.

Super Mario Galaxy's bloom effects look fine at native resolution.

At higher resolutions, the bloom becomes ✧･ﾟ: * sparkly * :･ﾟ✧

But with the power of "Native Bloom" and "No Bloom" Graphics Mods, we can transform how the game looks by directly changing how the game renders!

By scaling the bloom back down, the 'Native Bloom' Graphics Mod restores the game to a more authentic look at higher resolutions.

If you prefer to use third party bloom or just don't want bloom at all, the 'No Bloom' Graphics Mod completely removes the game's built-in bloom effect.

The Graphics Mods feature installs hooks into Dolphin's graphics pipeline. This can have a slight cost to performance, so Graphics Mods must be enabled to be used.

For the feature's debut, the following titles have Graphics Mods:

Arc Rise Fantasia
Battalion Wars 2
Donkey Kong Country Returns
Fragile Dreams - Farewell Ruins of the Moon
The House of the Dead: Overkill
The Last Story
Link's Crossbow Training
Little King's Story
Mario Kart Wii
Monster Hunter Tri
Nights: Journey Into Dreams
Okami
Super Mario Galaxy 2
Mario Strikers: Charged
The Conduit
The Legend of Zelda: Twilight Princess - Wii version only currently
The Legend of Zelda: Skyward Sword
Wii Play
Xenoblade Chronicles

These mods mostly consist of Bloom definitions, with a few games having definitions for removing GUI elements. However, Graphics Mods aren't limited to just generic operations like that, they have a set of actions that can be defined to create a multitude of effects, and users are encouraged to create their own Graphics Mods through the actions available.

Skip: Allows the modder to skip rendering this target group.
Scale: Allows the user to scale/stretch a target group.
Move: Allows a user to move a particular target group.

However, we cannot stress enough that the system is still very early in this initial release and there is a chance that some textures and effects may be reused for multiple things. An example of this is Depth of Field and Bloom sometimes using the same efb copy format, meaning that changing one without changing the other may prove difficult in certain games.

Graphics Mods for supported titles will be in the Game Properties page under the "Graphics Mod" tab.

If you're interested in creating your own Graphics Mods, we'll be maintaining a Graphics Mod guide on the Dolphin Wiki that should stay up to date as the feature evolves.

Future Plans

iwubcode has many grand plans to renovate Dolphin's ability to enhance graphics. From post-processing to Graphics Mods, they've got a lot up the pipeline. But if anything was going to get merged, that meant breaking down their projects into smaller pieces. This is just a taste of what Graphics Mods can do, and we can promise that there is more coming in the future. This is a massive undertaking being powered by a single person, so for now things are very barebones on purpose. It was a necessary evil to scale things back so that the system itself could be reviewed and merged.

One issue is Android. While there is nothing stopping Graphics Mods from working on Android, at this point it has not been implemented into the Android GUI. The Android GUI is a bit of a pain to develop for, and not every developer has an interest in dealing with the JNI parts of Dolphin. In fact, no one wants to do it, it's just that some end up having to do it.

As this feature sees more use, we hope to include more Graphics Mods across many titles in Dolphin. If any other creators want to submit their Graphics Mods to be available in the emulator, they can be submitted as Pull Requests.

5.0-16448 - Fix Some Dual Core + Full Screen + Panic Alert Deadlocks by JosJuice¶

Modern consoles have many cores and do tons of thread management. That's something we're thankful we don't have to worry about emulating, as the GameCube and Wii are from a bygone era of single core processors and games that run directly on bare metal.

But if the GameCube and Wii are Single Core devices, what does Dolphin's Dual Core mode actually do? Most users seem to think that it splits CPU emulation onto multiple threads, and ask why we can't just split it even further to use even more cores. But that's not what it does.

Dual Core is actually moving GPU related CPU tasks onto a separate core. The CPU has to do a lot of work figuring out what to render, handling the Vertex Loader, mipmaps, and other things. This "GPU thread" basically does all the legwork to figure out the GPU commands for what your GPU will then have to render. Because the GPU thread and the CPU thread are almost all of the major work that Dolphin does on a typical configuration, splitting them up can theoretically give up to 100% faster performance depending on the game.

This was essential in Dolphin's early days. Back then, both Dolphin's CPU JIT and the CPUs we'd be running it on were significantly slower than today. Twelve years ago, hundreds of games were too demanding to run fullspeed on the fastest computers in the world. It was a community effort in those days to buy the latest processors and overclock the hell out of them to see what games were now fullspeed on the bleeding edge. In the face of this incredible struggle, developers were willing to cut a few corners in order to make things faster. Dual Core's design is a result of that.

Dual Core relies on the fact that the CPU and GPU threads can do some of their work in parallel without having to interact. If everything goes well, they both run at full speed and don't drift too far apart. Then, when an action that requires the CPU/GPU to communicate is detected, they can sync up without any major issues. The more that things can run in parallel, the more efficient that Dual Core is, so it syncs as little as possible in order to get the massive performance gains that it gives.

However, in recent years Dual Core has drawn more and more ire for causing random bugs and crashes across a lot of popular games. But it wasn't always this problematic. Something changed along the way that has exasperated the core problem of Dual Core...

What exactly happened?

After Dolphin 4.0, something flipped that no one in the early days of Dolphin's development could have predicted. With the advent of TEV Fixes New and a huge slate of massive JIT optimizations, we actually made it so that the GPU thread was now the bottleneck most of the time!

This turned Dual Core into a much more unstable beast, as a sudden spike that causes the GPU thread to fall too far behind can cause bad data to be executed (unknown opcodes), visual errors, shaky geometry, spiky polygons, and more!

A handful of games were the opposite and actually struggled with the GPU thread overrunning the CPU thread, and those have benefitted.

Since Dual Core has become more unstable, there have been a lot of efforts to fix it, but we've ran into a rather difficult conundrum. If we fix the core problem - the fact we allow the GPU and CPU threads to run apart - we lose the performance gains of Dual Core. Fake-completion, a method used for netplay to make Dual Core more deterministic, only works in around half of the library and is roughly 20% slower. It's great for netplay in the games it supports, but not really viable as a general option. SyncGPU, a setting that forces the CPU and GPU thread to synchronize every so many cycles, often ends up slower than Single Core due to thread synchronization overhead and still has some of the same issues as Dual Core.

We've come to the conclusion that fixing Dual Core within the existing design just isn't on the table. If you can't run the game on Single Core, and the game relies on tighter CPU/GPU synchronization, you just have to deal with the occasional unknown opcodes, weird graphical oddities, and the occasional crash.

This pull request doesn't fix any of that, but it does fix something that was making it even worse. A bug in Dolphin's GUI system on desktops was causing popups from the GPU thread to lockup Dolphin if the game was in exclusive fullscreen. Because Dual Core's behaviors can cause various assertions from the GPU thread, this meant that previously non-fatal popups would essentially deadlock the emulator. The only advice we could give users was to disable panic handlers while in full-screen because Dual Core is occasionally going to mess up.

Thankfully, the panic handler issue has finally been stopped. JosJuice introduced a small tweak to the way popups from the GPU thread are handled in order to make sure they do not deadlock when in Full Screen. It's a rather messy solution, but Dual Core itself is messy problem.

This should fix the annoying "Unknown" blank popups that have been stopping people's games when running in Full Screen. If these popups were trying to tell you that a fatal error has happened, then the game might still crash. But if it's just a harmless Unknown Opcode, you might be able to continue.

5.0-16443 - Implement PI FIFO Reset by pokechu22¶

Speaking of annoying unknown opcode popups, pokechu22 investigated a case where Dolphin could erroneously execute bad data after a game called the command for a FIFO RESET.

In normal gameplay, you aren't going to see this command very often. In fact, the most common place we've seen this issue reported is from The Legend of Zelda: Ocarina of Time (VC). This is because randomizer players would abuse soft resets to test particular item checks and use save/quit into reset to quickly travel to specific areas. Randomly during these resets, the data past the FIFO RESET would contain invalid data, which triggered the unknown opcodes.

pokechu22 investigated a similar case found in a demo disc that used FIFO RESET between games and menus and found that any data leftover past a FIFO RESET was thrown out. As such, we now throw out any commands immediately following a FIFO RESET before things are reinitialized.

5.0-16722 and 5.0-16737 - Fix HLE audio and HLE boot of Datel Titles by pokechu22¶

Let's be honest here. In the past, booting Datel titles in Dolphin was a pain in the ass. It required both DSP-LLE and an original GameCube BIOS. Otherwise, they would simply hang and/or lock up Dolphin. And when that happens, your settings would likely get reset when Dolphin crashed and then you'd have to figure out what you forgot to change and the cycle continues.

You may wonder: "Why would I want to boot a Datel title in an emulator? All Datel did was make a bunch of unlicensed products, right?" While their stuff may not have been of the highest budget and quality, they did make some rather interesting and useful products. The Advance Game Port allowed you to play Game Boy Advance games on the GameCube through a GBA Emulator which loaded real cartridges through a Memory Card expansion device. But, Datel is more commonly known on the GameCube for their slew of Action Replay releases, Freeloader discs, and their weird Max Drive gigantic memory cards.

This brings us to a rather weird point. The Gecko Code loader is free open source software, which allows Dolphin to directly use the same Gecko Code Loader that is used on console. Thanks to that, our Gecko code support is nearly 1:1 with console. However, Datel's Action Replay loader is closed source and protected by copyright, and we cannot include it. So Dolphin uses a reversed engineered cheat code loader for Action Replay codes. While Datel's codes should be able to produce near identical results in Dolphin, it's very obvious that our Action Replay cheat loader is fairly inaccurate in some respects. For example, the "Hold R to Mega Jump" Action Replay code in The Legend of Zelda: The Wind Waker only works when using a real Action Replay disc to initialize the code.

We were going to do a comparison, but the code just does nothing with Dolphin's Action Replay loader. So just imagine Link not jumping here.

In an effort to make these unlicensed titles more accessible, pokechu22 dug through them to figure out why they didn't work with Dolphin's emulated BS2 (AKA - Skip Main Menu) or with HLE audio. The answers for each were rather interesting.

For the HLE audio issue, the problem was caused by a typo in Datel's code that ended up not mattering on console or DSP-LLE, but completely broke our HLE implementation. Namely, they were supposed to write 0x800 to the DSP control register, which would have started the initialization process. Instead they wrote 0x80, which does absolutely nothing. How exactly did this work on DSP-LLE and real hardware? Well, it didn't, but other data arrived at just the right time just as Datel's initialization code exited. We're not 100% sure why this works, and for once we don't have an overly complicated summary from pokechu22 to rely on yet. All we know is that by improving the timings on DSP-HLE, pokechu22 was able to get it working in the same manner that it was on DSP-LLE and console.

Emulated BS2 is our internal name for what users see as "GameCube - Skip Main Menu" in the GUI. If you don't hear that jingle and see that cube before booting a GameCube game, then you're using Dolphin's Emulated BS2. Its job is to make sure that all of the registers and memory are setup correctly as if the Main Menu had run, so that games work the same regardless of if you have the Main Menu dumped from a console or not. Emulated BS2 works so well for most games, that users almost never have to rely on a real Main Menu for compatibility reasons in retail titles.

The reason why Emulated BS2 didn't work with Datel's Loader stemmed from the fact that Datel did way less initialization than actual games. Datel's titles heavily relied on the Main Menu to setup almost everything. pokechu22 had to go through various registers and even dive into parts of the graphics code and give them proper default values in order to have the games boot correctly without needing a GameCube Main Menu.

The result of all of this work is that Datel's titles will now boot properly without needing special settings in the latest development builds. However, there are still a lot of problems when using these titles, especially in Action Replay devices that check memory cards. Some Action Replay titles will hang if you have a memory card plugged in on boot. Most Datel titles will throw unknown opcodes as well, and in one rare case in the third Advance Game Port release, enabling MMU will cause the game to crash.

We highly recommend not using GCI Folders with any Datel products that can write to the memory card, especially Advance Game Port's third release, which will actively break things with how it writes Savestates to the memory card. As with any kind of sketchy game (like True Crime: New York City) or homebrew that can do unexpected things, please use these titles with caution.

5.0-16730 - Add HLE version of libasnd by pokechu22¶

If you use a lot of homebrew in Dolphin, you're probably someone who commonly swaps over to LLE audio. This is because a lot of Homebrew use special homebrew DSP microcodes called libasnd and libaesnd. Dolphin's DSP-HLE had no way to handle these microcodes!

This popup means you aren't getting audio unless you swap to DSP-LLE.

This is because DSP-HLE doesn't actually emulate the DSP hardware, instead it identifies what DSP microcode is running (based on a hash) and directly emulates that microcode without bothering to actually emulate the hardware itself. This is many times faster, to the point where DSP emulation is never a performance bottleneck when using DSP-HLE. Yet in modern builds of Dolphin, DSP-HLE and DSP-LLE have near parity in supported microcodes. Users no longer have to choose between the accurate but demanding DSP-LLE or old HLE audio that was rife with bugs and only supported a handful of titles well.

Because the GameCube and Wii's retail library is now set, we can be certain that Dolphin's DSP-HLE completely handles those cases with relative accuracy. However, Homebrew (and one demo we found earlier this year!) are the last bastions of unsupported microcodes under DSP-HLE.

And that's the main reason why Dolphin's DSP-HLE hasn't worked for a lot of homebrew. A lot of homebrew uses the libasnd and libaesnd microcodes, which were under active development during most of Dolphin's development life. Writing support for something that could change at any moment seemed silly, but at this point development on the homebrew microcodes seem to have mostly stabilized. The last changes occurred in 2020, and they were minor changes at that.

As part of making homebrew in Dolphin more accessible, it seemed natural to finally add support for the libasnd and libaesnd microcodes that they use. And because they're a part of libogc and open source, adding support for them was far easier than it was figuring out all the crazy behaviors present in various AX and Zelda microcodes! In fact, pokechu22 implemented the libasnd microcode used in most homebrew on the side while working on other audio things.

Play tons of homebrew without needing LLE audio! This is Newo Escape, a flight homebrew game that previously played no audio on DSP-HLE.

Some homebrew that use the slightly more complicated libaesnd still require LLE audio as of this Progress Report, but work on changing that is already underway.

Dev Diary - Solving the Mystery of Monster House¶

Monster House is a game that has been problematic in Dolphin for a very long time. It's right in that zone where it's not popular enough to see a lot of attention, but not awful enough to draw a lot of morbid curiosity. It's a servicable game that falls apart in the final act.

There have been reports that Monster House is a cursed game, and is simply unbeatable in Dolphin. Invalid read errors would chase away prospective users looking to sneak into the depths of this seemingly haunted labyrinth. Every time we've taken a glance at this title, it has looked like nothing else but a normal game with no noticeable issues. But again and again on the issue tracker and wiki, another soul would be lost to these mysterious crashes.

After many years of avoiding the eyesore, it was time to send someone in for real. Someone to get to the bottom of Monster House and find out the truth.

Our unwilling volunteer this time around was JMC47. He was a skeptic that there would be anything special with this particular game and rolled his eyes at the request. We sent him in anyway and armed him with a squirt gun, some savestates, and a cheatcode to refill health. He should have been completely safe with those tools. Should have. Unfortunately, we lost contact soon after he entered the house. All that we could find were these log files of his exploits.

Testers Log - Day 1

I've seen Monster House reported a couple of times over the years and bought the game probably over half a decade ago. I've tried it a few times but upon seeing nothing interesting, I'd always put it on the back burner. This game isn't aggressively bad or maliciously coded, it just seems like a pretty mediocre movie tie-in. Compared to something with crazy issues like True Crime: New York City, it just seemed like it wasn't worth my time. Yet, supposedly this game still isn't playable. We'll see about that.

The game starts out rather suddenly, with the main cast getting thrown into the Monster House with little to no setup. This is apparently a movie tie-in game, so apparently telling the story properly is just optional. At the center of the game are three kids. I will dub them Annoying Child, Sarcastic Girl, and Scared Kid. The gimmick of the game is that these three kids are exploring the Monster House armed with different weapons and they are trying to destroy it in order to... I don't know honestly. They just seem to want to destroy it. But is it evil? Having played through the first chapter of the game, I'm not entirely sure.

These kids will be my company during my foray into the Monster House.

Testers Log - Day 2

This game is starting to get on my nerves. Maybe it's because the developers were inexperienced, but I'm constantly ending up going the wrong way in a mostly linear game. The reason for this is rather silly.

When you unlock a door in other games, say a 3D Legend of Zelda game, the developers tend to show you the door you unlocked. The developers of this game have seen this and know that, but it seems like they didn't understand why it works. They show me that I unlocked a door in a close up, but then zip back to my character facing whatever direction I was facing when the cutscene started. Compare this to [Wind Waker], which will keep your camera angled toward the door that you unlocked when you regain control. This is a reoccuring problem in Monster House, especially in hallways where you might unlock a vent that is all the way back near where you came.

I unlocked a door, but it sure isn't this one.

Does this make it a terrible game? No. The game seems solid enough overall, and I haven't seen any signs of really bad programming that would cause a crash. Maybe all of the users before me were just using bad dumps or cheats that don't work.

Testers Log - Day 3

I felt a chill run down my spine. I was crawling through a vent when I heard the horrible ding of invalid reads. I thought the Monster House had swallowed me alive.

I held frantically mashed enter to try and break free, fearing my journey was over. In the end, I survived. The last invalid read error was squashed and the game loaded the next area. I let out a sigh of relief, as I had made a fatal error in my complacency.

Logging wasn't enabled this entire time - meaning that if this had been a game crash, I would have lost everything. Thankfully, because the game didn't crash, I was able to save and enable logging and other debugging features. The Monster House should have stopped me while it had the chance. Now it's war.

Testers Log - Day 4

The game put up a rather spirited fight, but i have emerged victorious.

It tried the same trick on me again with the invalid reads and this time crashed afterwards thinking it would fell me. Fortunately, the damage done was minimal as I had been saving regularly since the initial scare. During this attack, however, the game revealed its weakpoint! In the logs I caught "Stale icache" messages right alongside the invalid reads. This game is just icache sensitive!

This fireplace would have felled a normal tester, but not me.

If I had been playing this game years ago, perhaps I wouldn't have known what to do. Thankfully, by this point we have weapons to fight off such a problem thanks to pokechu22 and the infamous Scooby Doo! incident.

Oddly enough, those also dealt with mysteries, haunted houses, and monsters... Oh well. It looks like my job is done here. All I need to do is beat the game and write up a report.

Testers Log - Day 5

Despite disabling the icache, I'm still getting invalid read errors every now and then. The game hasn't crashed on me, but this shouldn't be happening. Either the game needs accurate icache emulation or the game has programming bugs that cause invalid reads on console that get skipped by their error handler. In order to verify this myself, I decided to enable MMU emulation.

If the game crashes now, I'll be able to follow a stack trace and figure out exactly where in the game code the problem is happening. From there, if the game is relying on icache behaviors to the point of needing accurate emulation of it, we can just patch the game instead.

After dealing with all of that annoying emulator stuff, the game rewarded me with a rather competently made boss fight. Things are starting to look up after all!

Testers Log - Day 6

Apparently the developers couldn't design harder enemies and have just decided to make the game harder by throwing a 30+ enemies into every room. What the hell is their problem? There are so many enemies in these rooms that you can't actually move your character half of the time until you clear them out.

And please, can we stop with all the quicktime events?! These QTEs were annoying in the first half of the game, but there they only cost a tiny amount of health as long as you mashed the failure minigame. Now they cause instant death and reset you to the beginning of the section!

Better hope you weren't doing something or hitting other buttons when this sudden QTE showed up.

This last section I'm in has been a real doozy. Multiple rooms packed with tons of enemies and areas that lock you in until you clear all the enemies, followed by a boss fight, followed by not one but two instant death QTEs?! Come on. That's more than enough, especially considering that the boss had an instant KO move too, even if it was easy enough to dodge.

At least I'm almost done with this maze. Whenever the story switches characters, the game gives me a checkpoint. I just need to find my way out, and every direction just looks the same. Oh, and there are a bunch of extra dead-ends with nothing but collectable bonuses. And if you dare grab the collectable you spawn more enemies. Thanks! That's just wonderful.

AND ANOTHER INSTANT DEATH QUICKTIME EVENT SPACED JUST FAR ENOUGH OUT THAT I LET MY GUARD DOWN SENDS ME BACK TO BEFORE THE BOSS?! You know what, I'm just going to spam savestates.

Testers Log - Day 7

Now the #@&$ing cutscenes have #@&$ing quicktime events in them that if you fail you die, or worse, have to fight the boss again. You can't even rest during the cutscenes. At least I'm almost- What.

This game checks to make sure the memory card you're using matches the memory card the save was created on, and I apparently loaded a savestate from before my last in-game save, so now it thinks the memory card doesn't match. At least it doesn't refuse to save - oh great, the game #@&$ing crashed after saving because it's poorly coded. Now I need to make sure this isn't a Dolphin bug.

And, why exactly are the cutscenes where you get caught to switch characters exactly the same as the QTEs that you can't fail or else you game over? Where is the consistency. And, you know what would be a great idea? Putting a room with a thousand #@&$ing enemies and then have a QTE trigger in the same area is just stupid. And guess what, if you manage to get hit as a QTE loads, the #@&$ button prompt won't show up so you're just dead. GREAT. And the button prompts are randomized, so you can't even use the dodge button or something consistent like that.

It's a horrible conundrum. Killing all the enemies takes forever, so I just want to rush through the rooms. But if I don't kill the enemies, I risk glitching out their precious QTE that instantly kills me if I mess up. This section of the game is literal garbage, and honestly sours everything else.

I was willing to forgive the fact that the annoying #@&$ing kid needed a #@&$ing ladder hook in order to grab a ladder that was clearly at arm's height. I was willing to forgive the fact the game's enemy design had as much variety as a modern sitcom. Hell, I was willing forgive the fact that this "movie tie-in" hadn't actually told me anything about the characters or story!

How come the #@&$ing house can seemingly capture these kids at will and kill them but doesn't. The same exact cutscene where the vent comes down and grabs you during a QTE to kill you is used multiple times to force character swaps, but the kid ends up fine in another section anyway! Why? How come they're fine when that happens but not during the QTE?!

This is literally the the final stretch of the game. I just need to push through and finish it so I can mark the game as playable on the Wiki and forget this ever happened.

Testers Log - Day 8

@#&$ing this stupid #@&$ing house in this stupid #@&$ing game. You know, the game has truly made me appreciate that last section of enemy mobs and QTEs. You want to know why? Because at least there was gameplay. This is the second to last chapter of the game, and do you want to know what it is composed of? #@&$ing QTEs! THAT'S IT! THERE'S NO MORE GAMEPLAY!

Okay, so get this. The house is chasing me, and I have a three button quicktime event where every so often I have to hit a button to avoid rubble with one of the three characters. Mess up too many times, and you restart the section. The timings aren't all that tight, but considering how long the section actually lasts, it's rather annoying.

This goes on forever and ever and ever...

This is just wonderful.

Testers Log - Day 9

This log has been removed due to excessive profanity.

Thankfully the game has mercy if you fail the cutcene QTEs and only make your repeat part of the last section instead of the whole thing. Thanks.

Testers Log - Day 10

The #@&$ing chase cutscene is still #@&$ing going. I can't believe it. And on this section you can't make any mistakes because the house has caught up.

Please just let it end.

Testers Log - Day 11

After several minutes of playing the worst version of Simon says I've ever seen, the final boss fight has finally commenced. And considering the quality of the last chapter, it is fitting the final boss is barely gameplay. Rather than using the third person shooter gameplay that the game has established up until this point, we get an incredibly janky vehicle boss fight where we take a crane, approach the house, mash attack, back away... rinse and repeat.

There's no actual variety to the fight. The house has one attack that can be mirrored left or right - an extremely slow swipe followed by a reverse swipe. You just backup to avoid it, and then after the attack get close and mash the attack button to deal a tiny pixel of damage to its health bar. But, don't you dare make a mistake, as if the house so much as grazes your crane, it takes off a huge chunk of your health bar. Just don't be greedy and the fight isn't that bad. You can't really get into a rhythm though because there's yet another randomly occurring #@&$ing QTE during the boss. It's just a simple joystick spin, but unless you use the palm of your hand to spin it extremely fast, you're guaranteed to lose some of your precious life every time. If the QTE comes up too many times, you can lose half of your health. It's worth swapping your hand grip to make sure that doesn't happen, because this fight takes way too long to lose to chip damage.

You even get random QTEs during this limited mobility boss fight which is barely more gameplay than a quick time event.

The boss's health bar is almost depleted... please... just end... YES! IT'S OVER!

The house is no more! I am victorious.

After all of that, it's hard to judge Monster House because of how hard it relies on quick time events toward the end of the game. The core gameplay isn't bad, and while the developer was inexperienced, they did a decent enough job at varying up the characters, enemies, and their first boss fight was well designed.

It's just that the latter half of the game became such a QTE fest that it was hard to play. And the parts after you get out of the house are almost entirely QTEs! But now we're in the ending cutscene and it's all over-

This #@!&ing prompt happens well over 30 seconds after the boss fight is over and serves no purpose but to cause you pain.

What you want me to hit buttons during the end cutscene! NO! #@&$ NO NO #@&$! WHO THE #@&$ PUTS A QUICKTIME EVENT AFTER YOU DEPLETE THE FINAL BOSSES HEALTH BAR WHAT THE #@&$ IS YOUR PROBLEM WHY-

Unfortunately, the log cuts off there. The random Savestate/Memory Card Crash never happened a second time, so we were unable to confirm if that was a bug in Dolphin or the game, but we can confirm that the game is now playable from start to finish... if you dare.

Last Month's Contributors...¶

Special thanks to all of the contributors that incremented Dolphin from 5.0-16383 through to 5.0-16793!

Leaving a Legend: Saying Goodbye to Windows 7

2022-06-09T03:27:47+00:00

With none of our active developers using Windows 7 as their primary OS, the userbase dwindling, and Windows 7 starting to meaningfully fall behind newer versions of Windows, it's going to become more and more likely that features are accidentally broken in Windows 7. Eventually, the differences between Windows 7 and newer versions of Windows may increase to the point where we drop support for the aged OS. We don't plan on purposefully breaking support, but, its days are numbered.
Dolphin Progress Report: June and July 2019

Windows 7 had a hell of a run. After the wide rejection of Windows Vista, Windows 7 set the bar for all Windows versions to come. It continued the technical advancements from Vista while righting most of its wrongs, all wrapped up in a friendly, reliable package. This combination was a tremendous success, and users loved Windows 7 so much that it had a support lifespan of over 10 years!

Dolphin has been proud to support Windows 7 for its entire life, and then some. We've supported Windows 7 for 13 years, making it our longest supported single operating system version ever. However, all good things must come to an end. While Windows 7 was able to survive the release of Windows 8 and 8.1, Windows 10 finally provided another popular option, and users have moved on. With Microsoft ending support for Windows 7 a few years ago and more and more software abandoning it, supporting Windows 7 has become a liability for us.

After several months of breaking/restoring Windows 7 support, we've decided to drop support for Windows 7... and Windows 8 and 8.1. We did not take this decision lightly, but after evaluating the situation, we knew what had to be done in order to make sure we can keep working on Dolphin without having to make compromises.

Trials of Supporting Windows 7 in 2022¶

One of the main reasons that supporting Windows 7 has become such a burden is that Microsoft very strongly wanted people to use Windows 10. Once Windows 10 released most new features simply never came to Windows 7. Over the past couple of years, we ran into differences with Direct3D11 support which affected LogicOps Emulation, BSOD issues when using USB Passthrough, among others.

Running into a minor issue here and there wasn't going to cause us to drop support, however. But within the last couple of months, time has caught up to Windows 7. In our previous Dolphin Progress Report, we detailed the back and forth of trying to keep Windows 7 running. We broke it and then fixed it and then broke it again, and had to fix that too.

This was made all the more difficult by the fact that Dolphin's developers have long moved on. Not only are we no longer using Windows 7 regularly, we don't even have any Windows 7 systems readily available for us to test with! This meant that Windows 7 was totally untested by the Dolphin team, so Windows 7 support could break at any time and we'd only know when a user reported issues to us.

This put developers in a rough spot. If we did merge something and it broke Windows 7, that meant we had to add more branches to the code and complicate features, or potentially use a different method altogether to implement said feature. And if an issue was reported months later, which was common due to dwindling user numbers on Windows 7, that meant that it usually fell on another developer to pick up the pieces and fix things. It was okay when it came to one or two minor issues every year, but when it was happening multiple times a month, something had to change.

Few Windows 7 Users to Support¶

When it comes time to make difficult maintenance decisions, one of the things we have to do is a cost versus benefit analysis. In this case, Windows 7 was costing an increasing amount of developer time to maintain. But, if a lot of Dolphin's users were still on Windows 7, then perhaps this would be worth the trouble, at least for now.

So how many Windows 7 users did we actually have? We turned to our optional usage statistics to find out.

Mouse over or tap on a graph for details.

Why and When We Drop Support¶

A shockingly small number of Dolphin's users were on Windows 7, and none of our developers used Windows 7, yet we were still fixing Windows 7 support well into 2022. How did it last so long? The answer is that Dolphin is an open source project! If someone breaks support for an older operating system when merging a new feature, anyone can come behind them and do the work on their own to refactor the code to support the new feature while still maintaining support for the old OS. As long as the new code meets current standards and doesn't over complicate things too much, support is resumed.

However, there is a limit to the sustainability of this process. As a project, we rely heavily on a number of outside libraries and APIs. For example, we use the Microsoft Visual Studio to compile our Windows builds, Qt for our desktop graphical user interface, Cubeb audio library for sound, multiple graphics and input APIs, on and on. These are our dependencies, and if they drop support for an older operating system, the labor involved to refactor code on our own becomes astronomical. At that point, we're not refactoring a single change, we're refactoring someone else's entire project. This is so challenging that even large corporations avoid doing this. For our little volunteer team, it's just too much. So while we do what we can to support older operating systems, when our dependancies move on, it is time for us to move on too.

We were honestly expecting our Windows 7 support to be killed by Visual Studio moving on first, much like it did for Windows XP. But no, something else came up.

Qt6 released without support for Windows 7, and surprisingly also without 8 and 8.1 support. As mentioned earlier, Dolphin uses the Qt GUI framework for our primary desktop GUI. While we have some support through dear imgui and our NO-GUI mode, Dolphin heavily relies on Qt, and Qt6 provided some fixes and functionality that would iron out a few GUI problems that users had reported and allow for new features. As soon as Qt6 was announced to not have support for versions of Windows before Windows 10, their days were numbered. We did however delay our move to Qt6 for quite a while (Qt6 first released in December of 2020), but we wanted the fixes that Qt6 brought and wanted to use its new features. So when one of our developers made a pull request to update Dolphin to Qt6, we weighed out all of the reasons above, and came to a decision.

The End¶

With the merging of Qt6 support on the Windows buildbot in 5.0-16393, Dolphin has dropped Windows 7, Windows 8, and Windows 8.1. Our minimum spec for Windows is now Windows 10. The currently released beta build is the last beta that will have support for Windows 7 and Windows 8.x. Users on these operating systems should turn off Auto-Update, as newer builds will no longer work on their operating system.

And so we say goodbye to a titan in the history of Operating Systems. As Qt6 is rolled out, our requirements will be bumped up accordingly for all of the different operating systems, except Android which uses a different GUI system altogether.

Dolphin Progress Report: February, March, and April 2022

2022-05-17T06:39:12+00:00

After a long wait, the Progress Report is back! This time it wasn't so much from a lack of content, but from a lack of content creators. The past three months had illnesses hit one of our writers and the other had a very challenging move. Even with these major hurdles jumped, we're not even close to 100% yet. It's been a battle to get caught up with all of the big changes to Dolphin the past couple of months and because of that this report is a tad late.

Needless to say, there's only one way to start catching up, and that's to get to digging through the past three months of Notable Changes. Enjoy!

Notable Changes¶

5.0-16380 - Change default NUS Shop URL to Dolphin's fake NUS by OatmealDome¶

On the 16th of March the Wii Nintendo Update Servers (NUS) abruptly went offline. Without them, Wiis can no longer download previously purchased titles, or download critical files needed for setting up your Wii system. Nintendo refuses to say this is anything more than a temporary maintenance blip, but after two months we're starting to believe that this is a permanent change. To our knowledge, the life-support from the Wii Shop has been pulled and the Nintendo Wii is now an offline console.

While it may not seem like much, NUS was an important tool to casual users, the modding scene, and even Dolphin users. Easy access to official System Files (IOSes) and default channels allowed users to easily setup a clean Wii System that is fully up-to-date without needing a game with a late release date. If you made a mistake on a modded Wii, you could easily access NUS to get clean copies of IOS files to unbrick your system. On Dolphin, it made it so users could get a fully up-to-date Wii System Menu setup, complete with channels, with just a few clicks. For preservation of the Wii experience, NUS made things simple.

More importantly, Wii games require various IOS files in order to run. We've had our run-ins with differences between older IOS behaviors and newer IOS behaviors while wrangling with USB Microphone support. There are lots of games that either won't run, or won't run correctly if they're missing IOSes. The good news is that almost every Wii disc title comes with the necessary IOS files to run that game along with a full Wii System Menu and all the default channels. Whenever you insert a disc into a real Wii, it'll prompt you to update if there is a missing System File. Most Dolphin users won't notice much of a change, as Dolphin has a hack for when a game is launched from the gamelist to ignore missing IOS files. For anything more complicated, IOS files are also required in Dolphin.

This may seem like a minor issue, but since the servers have gone down, there's been a huge uptick in issue reports from Dolphin users, along with an increase in bugs relating to incorrectly configured Wii Systems. A lot of users would simply pull something like that the Mii Channel and the Wii System Menu off of a Wii or a Disc, and think that installing that was enough. But, without the IOSes required to run the Mii Channel, you'll either be greeted with a blackscreen, the system menu rebooting, or a notice that the title could not be launched. Issues like these have been running rampant, and we no longer had an immediate solution that would clean up their issues.

Here's the kicker; Nintendo is still hosting all of these core system files for the Wii, they're still available to download... from the Wii U Content Delivery Network (CDN)! It still has all of the Wii's System Files for some reason. As far as we know, the Wii U's Virtual Wii used the Wii NUS. This isn't exactly unusual for Nintendo, as the 3DS CDN also has the Wii System Files!

Because of this duplication, this gives us an option to extend the life of the "Perform Online System Update" functionality in Dolphin. We now have a Dolphin Update Server. OatmealDome created a static page and delroth configured the server to act as an intermediary Update Server so that Dolphin can use the Wii U CDN for System Updates. Because the same files are on the Wii U CDN, all of this shuffling should amount to no noticeable change from the previous behavior for our users. Perform Online System Update works just how it did before.

Inevitably, the Wii U and 3DS CDNs will eventually go down, but this should buy us time to develop a more permanent solution for when that happens.

5.0-16005 - Remove MMU Default in Disney Trio of Destruction™ by JMC47¶

During the previous Progress Report the blog writers, JMC47 and MayImilae, were discussing MMU (Memory Management Unit) titles. And this exchange took place.

MayImilae: do any wii games use mmu?
JMC47: yes
MayImilae: which ones?
JMC47: Disney Infinity, Cars 2, Toy Story 3
MayImilae: oh right, the anti emulation nonsense
JMC47: no!
JMC47: actually one of the devs reached out to us
JMC47: and explained that the MMU stuff was not anti-emulation
JMC47: the dcache stuff was
JMC47: but not the MMU usage

Sonicadvance1, MayImilae's partner, happened to see this conversation by peeking at her laptop. He simply pointed at the screen and said, "That's not MMU." and walked away. These three Disney titles we lovingly call the Disney Trio of Destruction™ had MMU enabled on by default, as without full MMU emulation they emitted a backpatch error then crashed. However, Sonicadvance1 is a former Dolphin developer who made Dolphin's ARM JIT - he knows what he is talking about. It was worth checking. So May immediately passed this on this comment, and JMC gave the three titles a quick test. They ran perfectly fine without full MMU emulation. Huh. Well there's only one thing to do when games are mysteriously fixed like this - bisect!

Through bisecting, we learned that 5.0-15699 is what now allows the Disney Trio of Destruction™ to work without full MMU emulation. This change was briefly mentioned in the previous Progress Report but was not explained, so we'll go over it now.

One of the biggest speedups in Dolphin is "fastmem". Emulating memory mapping is a very involved task, as the GameCube and Wii have very different memory mapping than the the hardware Dolphin runs on, and checking the mapping of every memory access beforehand is quite expensive. So Dolphin handles this by... just mapping the memory on the host system directly, differences be damned. Whenever the mappings are shared, as it can be for simple mappings, the host CPU will handle it and we get a massive speedup (fastmem). However, whenever it doesn't match, the host CPU faults. Then Dolphin's fastmem exception handler will backpatch that access to use "slowmem" where Dolphin will manually translate the memory address. Due to the brute force nature of fastmem, it fails a lot, a lot lot, but it's always worth it to try for fastmem on pretty much any memory access - a fastmem loadstore takes as little as 2 instructions, where as the same access in slowmem can take up to 1000 instructions! However, fastmem can only work because we catch exceptions and backpatch them through slowmem.

We just had to use this image again.

Even with exceptions, there is an exception. Quantized Paired Single Loadstore instructions, due to various quirks involving said quantization, cannot be backpatched. If one of these were to trigger an exception through fastmem, everything would explode. When fastmem was implemented in our x86-64 JIT long ago, the Dolphin's developers of the time were aware of this. They provided a solution, a "safe" path which uses a "test and branch" approach. Any instruction set to use this safe path will be tested before reaching fastmem, and if the test determines that it would fail in fastmem, it will be routed directly to slowmem without triggering an exception.

However, our predecessors only added test and branch to Quantized Paired Single Stores. For some reason, they left Quantized Paired Single Loads out of the safe route. We honestly don't know why. It is our assumption that they never encountered Quantized Paired Loads triggering exceptions after testing hundreds of games, so even though it was dangerous, they decided that the very minor performance hit of the test and branch method was not necessary.

Unfortunately, it appears that they never considered that Dolphin could force Quantized Paired Loads down the path of destruction.

While fixing the graphical issue in Rygar, we noticed that it now required full MMU emulation when it didn't need it before. Josjuice looked into it, and traced this regression to 5.0-14829. That change made Dolphin able to emulate the GameCube and Wii's broken masking for uncached unaligned writes, which was required for a powerful Majora's Mask speedrunning trick. But to accomplish that, we had to make uncached memory accesses always trigger a fastmem exception and go through slowmem.

Rygar just so happens to do a Quantized Paired Load from an uncached memory region. This forced a fastmem exception on a Quantized Paired Load and...

Full MMU emulation happened to work around this. Under full MMU emulation, all quantized memory access instructions use test and branch. Thanks to that, the test caught the Quantized Paired Load and routed it directly to slowmem, bypassing the exception and crash.

Fortunately the solution was very simple. In 5.0-15699, Josjuice made Quantized Paired Singles Loads safe with test and branch. Now, even without full MMU emulation, we always test Quantized Paired Loads and prevent them from triggering the exception that leads to catastrophy.

And now we return to the Disney Trio of Destruction™. In their case, well we don't know exactly, but we believe they are using a Quantized Paired Single Load to load from MMIO (Memory-Mapped Input and Output). MMIO cannot go through fastmem, so that case will always trigger a fastmem exception. And since it was a Quantized Paired Single Load... boom. But thanks to 5.0-15699, this no longer occurred, and we no longer needed to use full MMU emulation to work around it. Once we discovered this, we were able to safely remove the MMU default from the Disney Trio of Destruction™.

Now that Toy Story 3, Cars 2, and Disney Infinity can run without the extremely performance-intensive full MMU option, what kind of performance improvement will this give us?

Absolutely none - these games are bottlenecked by something else. Oh well!

5.0-16009 - MemArena: Use memory placeholders for fastmem on Windows to ensure nothing allocates within the fastmem space by AdmiralCurtiss¶

This change added a placeholder for our fastmem address region on Windows, making sure that nothing else can allocate memory within our fastmem address region once we've claimed it. This resolves an issue where very large texture packs could crash Dolphin.

It also broke our Windows 7 support.

5.0-16035 - MemArena: Restore Windows 7 support by AdmiralCurtiss¶

The above change works by using the Windows function UnmapViewOfFileEx. In the words of Microsoft, this function "Unmaps a mapped view of a file from the calling process's address space." This allows Dolphin to preserve fastmem against very large texture packs in a fairly elegant way. However, UnmapViewOfFileEx has a minimum supported version of Windows 8. On Windows 7, Dolphin calls for the nonexisting function and Windows, recognizing that it isn't there, panics and crashes Dolphin.

AdmiralCurtiss fixed this with 5.0-16035. With this, Dolphin itself now checks whether UnmapViewOfFileEx is present on the Windows system, and will not use it if it fails to detect it. Of course this means that Windows 7 users may still encounter crashes when using very large texture packs, but that's better than Dolphin not working at all.

5.0-16214 - InputCommon: Add Windows.Gaming.Input to ControllerInterface by Billiard¶

Long ago, there was DirectInput (DInput). This was Microsoft's original input API for game controllers on Windows, going all the way back to Windows 95. It was/is fairly messy by today's standards, requiring manual mapping of each button individually, but it was/is extremely flexible, able to handle any and all types of game control devices. However, once Microsoft created the Xbox 360, they wanted a way to easily connect a 360 controller to a PC without mapping or other hassle. So Microsoft created a new input API, XInput. While it is much less configurable than DInput, its simplicity allowed game developers to ship mappings for it within the game itself, so user mapping was no longer required.

Microsoft knew that they would want to add features to their controllers with new consoles, so they added a way to expand Xinput’s functionality with XInputGetCapabilities (link). This Windows function allowed a controller to report if it had differing functionality than a 360 controller, potentially allowing for future expandability or even “weird” functionality like touchpads or gyros featured on other controllers. However, it turned out that the majority of programs took a bit of a shortcut and ignored non-essential parts of the XInput spec. If a controller used XInputGetCapabilities, it was very unlikely to encounter software that even noticed. This laziness dripped down toward manufacturers, and many controllers began to improperly implement the XInput API because the games they used to test weren’t enforcing it correctly. If one of these flawed controllers was used in a software that actually supported the full, proper XInput spec, the software could crash. Ask us how we know.

When Microsoft created new Xbox controllers, they wanted to support the controller’s new functionality on Windows. Now with a reason to resolve the XInputGetCapabilities nightmare, Microsoft’s devised a solution - make a new input API. Naturally.

The creatively named “Windows.Gaming.Input” (WGI) is the newest input API for Windows. This ambitious new API seeks to combine the best of both DInput and XInput into a single API, with a new input-centric approach that theoretically will give it the flexibility for many different types of input devices while maintaining easy setup and use. However, those new features haven't been implemented yet, and as it stands today it is basically just XInput plus One/Series controller features. And it's still missing esssential features that aren't on their Xbox controllers, like accelerometers and gyros, so currently WGI is just yet another Microsoft input API for Microsoft input devices.

Regardless, Dolphin's need to emulate Wii Remotes and several odd controllers for the GameCube and Wii makes having robust input API support a higher priority for us than most other programs, so supporting Windows.Gaming.Input was a natural choice. Many benefits are immediate, as it supports up to eight simultaneous controllers (up from four with XInput), support for the Xbox One/Series rumble triggers, and has better battery reporting. Basically everything we were hoping XInputGetCapabilities would be. However, if the input-centric WGI future comes to pass, users may be able to use it for all kinds of different input devices. We shall see.

It also broke our Windows 7 support.

5.0-16236 - Core/WGInput: Dynamically load winrt function addresses by AdmiralCurtiss¶

AdmiralCurtiss came to rescue Windows 7 once again. Much like the previous Windows 7 fix, this change made Dolphin use IsApiSetImplemented (link) to check for Windows.Gaming.Input support before trying to use it. With that, Dolphin's Windows 7 support was saved.

...briefly. But that's a story for the next Dolphin Progress Report.

5.0-16174 - Fix OpenGL Label Identifiers for ANGLE by iwubcode¶

This may not sound very interesting, but this was a quick fix necessary to fix Dolphin running under an OpenGLES wrapper called ANGLE. Why exactly?

The story actually started a few months ago, when it was announced that the Exynos 2200 chipset to be used in some models of the Samsung Galaxy S22 would contain AMD's RDNA2 graphics hardware and drivers. This left us very interested. RDNA2 is great hardware, and while AMD's drivers may not be best in class, they are leagues above the horrors we've seen on Android. We were very hopeful!

Now the hardware is out and users have been able to test it. Vulkan performance on the Exynos 2200 is a step above what we've seen on any other phone. It's able to reach full speed in demanding games like Super Mario Galaxy at up to 2x Internal Resolution without having to disable critical features like EFB Access to CPU. This is notable because GPU readbacks have long been a major bottleneck on mobile devices.

But when we saw OpenGLES on the device, we were taken aback. It's disappointing to say the least. More disappointing than normal AMD OpenGL drivers on Windows. Even more disappointing than Mali drivers. That's because there are no OpenGLES drivers provided for this device. Instead, it uses a wrapper called ANGLE to translate OpenGLES to Vulkan.

This is how graphics software engineers responded to this news.

ANGLE was designed to translate WebGL to other graphics APIs. It was not designed for games, and it is not battle-hardened the way a graphics driver would be. Naturally, there were some growing pains.

For us, when the phones first launched Dolphin's OpenGLES backend wasn't even able to run on them due to a minor mistake in Dolphin's OpenGL Label Identifiers. This was a known whoops that iwubcode found during work on another feature a while ago, but it was so inconsequential that it wasn't a priority to split-off and upstream right away. When given an incorrect Label Identifier, the driver should just return an error saying it is incorrect then continue on. It's harmless. But ANGLE has no validation for this function, so rather than say that the Label is wrong and continue, it hits an unreachable and explodes. While it may have been a Dolphin mistake that caused this, crashing for such a minor mistake in a harmless debugging feature is absolutely an ANGLE issue.

Once we identified that this was the source of the problem, iwubcode picked out the Label Identifier fix and we merged it. We never should have needed to fix it, but here we are. With that, the OpenGLES backend now works on the Exynos 2200.

However, because OpenGLES is being translated to Vulkan by ANGLE for this device, performance seems significantly worse than native Vulkan in every recorded instance. If you have an Exynos 2200 device, please do not use the OpenGLES backend on it.

5.0-16301 - VideoCommon: Handle emboss texgen with only a single normal by Pokechu22¶

The Rogue Squadron series is a marvel of game engine programming. There seems to be no end to Factor 5's tricks, as we've talked about over and over and over again. But surely, after all these fixes over the years, we should have everything pretty down pat by now. There's no way there would be a major effect that has never worked in Dolphin before, right? RIIIIGHT?

These sand and snow effects looked alright in Dolphin.

Until you launched the games on console again and saw what they are supposed to look like.

This is an emboss effect Rogue Squadron 2 and 3 are applying to the sand and snow to give them more dimensionality and texture. Specifically, this is a GameCube implementation of DirectX6-era bump mapping. It's an impressive effect for the time, as the lighting on the ridges will shift and match the sun's angle even as the suns dynamically move through the sky. Bump mapping like this wouldn't become common until the next console generation, and here it is in a GameCube launch title from 2001!

However, there was a reason this effect didn't take off until years later. The DirectX9 and newer forms of bump mapping are painless - developers can use them with very little setup and they are very, very cheap to run. Devs don't even need to think about it. But with this older type of bump mapping, developers had to build the effect themselves. And it was not cheap. For something that just adds a bit of visual flare, most GameCube and Wii developers decided it was not worth it and passed it by.

But not Factor 5. This is Factor 5 we're talking about, of course they used it.

To explain how this all works, here is a bump mapping effect that already worked in Dolphin before this change. This X-Wing will be our example.

Click/Tap and hold to disable the X-Wing's bump mapping.

To build the effect, Factor 5 first needs to have a color map which contains the color of the object itself, then a height map, aka "bump map", which represents the height of the surface as a greyscale image. Cleverly, Factor 5 wasn't going to need the Alpha channel of the X-wing texture, so they used the Alpha as the height map.

This is the color map for an X-Wing in Rogue Squadron II.

And here's the height map, converted to traditional greyscale. Factor 5 is using bump mapping to add depth to the panels on the X-Wing.

But this is the actual texture. The "cut out" areas are the Alpha channel which the game is using as its height map.

The process begins with the game writing the light direction into the Tangent and Bi-normal vectors (registers) with each vertex. As opposed to the Normal vector which tracks movement out from a surface, the Tangent and Bi-normal vectors track movement parallel to the surface. If Normal is Z, Tangent and Bi-normal are X and Y, effectively.

From there, the game reads the texture twice, the first time with the base texture coordinates then again with an offset using the light direction values written into the Tangent and Bi-normal vectors earlier. Then it combines this with the height map to apply the bump mapping to the texture, brightening or darkening the texture based on the height differences. This process burns two TEV stages (out of sixteen), so this is not a cheap effect, but that is how you do bump mapping on the GameCube!

Due to how the effect is built we were not able to dump the final embossed texture. This is a photoshop creation that shows more or less how it would look when applied to the color map.

While this effect is fairly primitive by modern standards, literally just painting the texture, the magic of this effect is that it is tied to the light direction. Thanks to this, the effect does a fantastic job of giving convincing depth to the surface, even in motion!

Here is the bump mapping in motion, with most other effects and textures removed for clarity. Pay attention to the lines here. After the light moves over it, it flips! It uses the light direction!
_{Click the video for the high resolution version.}

When added to all of the rest of the ahead-of-their-time effects like self-shadowing and reflections, these games look like nothing else.

This thumbnail does not do this video justice. Please click it for full res.

Now, all that we've covered so far already worked in Dolphin. So why didn't the sand and snow effect appear correctly? Well, the sand and snow are using effectively the same effect, but on these two surfaces the game doesn't supply the Tangent and Bi-normal vectors for the effect. Without them, Dolphin can't know what the offset is, and the effect cannot be rendered. Yet we know this works on console. It was as though Factor 5 used literal magic!

This has annoyed Dolphin developers for years. Factor 5 was clearly getting the offset from something, but try as we might, we couldn't find it. Sonicadvance1 years ago made a guess that it was using default values, and it even passed a hardware test, but further analysis proved this to be incorrect. Pokechu22 more recently tried to hardcode some values that looked correct for RS2, but they ended up being very wrong for RS3. No matter what we threw at it, we just couldn't figure it out.

In the end, we didn't - we were told how it was done by Factor 5 themselves when we discovered a 2002 article written by a Factor 5 employee.

A trick that is worth mentioning is how to avoid sending the same bi-normals and tangents for emboss mapping repeatedly to the transform unit (XF) of the graphics processor. It turns out that if these vectors are not present in the vertex format, XF will provide the previously transformed bi-normal and tangent, which reside in internal registers. Thus, if a dummy triangle is drawn with the bi-normal and tangent immediately before the landscape is drawn, then there is no need to send the same vectors over again for the rest of the height-map triangles. This means that only one vertex format is needed for the entire landscape, and it saves memory, transfer bandwidth and most importantly transform performance.

Basically, the sand and snow are the exact same effect as the bump mapping effects that were already working elsewhere in the Rogue Squadron games. However, the sand and snow have a performance optimization where the Tangent/Bi-normal vectors are written at the start of the terrain's construction, and all the subsequent steps (including the bump mapping) reuse the stale data in the vectors.

After discovering this, we weren't really all that surprised. We had considered this as one of the many possibilities. However, it was very difficult for us to test due to how Dolphin JITs the vertex loader - it was not designed to preserve the vectors and it would not be easy to make it do so. Due to the difficulty, we never tried it. But once we knew for sure that this is what they did, Pokechu22 did some hardware testing and confirmed it, then stepped in to make the vertex loader able to preserve stale data in the vectors.

And with that, the sand and snow bump mapping effect works in Dolphin!

At long last, Dolphin now properly supports this effect!

Now before we move on, we wanted to share one final thing. While working on this, Pokechu22 wanted to confirm that the bump mapping on the sand and snow reacted to the light direction, so they set up a time lapse on console by spinning around in circles and taking captures at regular intervals while the suns set. It ended up not being very useful as the stage runs out of time before the light moves enough to confirm it for sure, but it looked awesome. So Pokechu22 rerecorded a nicer version in Dolphin for us to share in this Report.

There will be no hyper compressed thumbnail video for this one. Click the image above to see the timelapse! Humming a certain Star Wars theme is optional.

5.0-16337 - macOS: Work Around EarlyZ Bug on Apple Silicon by OatmealDome¶

Apple silicon has proven to have an impressive capability at running Dolphin and has charmed the Dolphin developers. But there have been a few bumps here and there. One problem was that a lot of games were having a lot of darkness and strange flickering during some special effects. This ranges from platformers like Super Mario Sunshine to top-down shooters like Ikaruga.

Ikaruga was barely recognizable on Apple silicon.

The issue was tracked down by OatmealDome and they found that there was a nasty bug in the Apple driver when using discard while Early Z testing was enabled. Their solution was to simply emulate discard using a framebuffer fetch. This let Dolphin do things correctly while avoiding the broken codepath on the driver. This could result in a slight performance decrease on Apple Silicon, but so far we haven't recorded any noticeable differences.

Now that's more like it.

5.0-16348 - Rework scissor handling by Pokechu22¶

This is the second scissor change made to Dolphin in recent years, after the Mario Galaxy roar was discovered to use a negative scissor offset. Dolphin developers assumed that meant that the scissor offset could be negative and that was the end of the story. After all, if something else was wrong, wouldn't there be more examples of games having issues?

Well, there was one, we just didn't know it yet. This is the curious case of Major Minor's Majestic March, a game that barely rendered anything in Dolphin and for the past half decade, no one had much of an idea of why.

What's all this? It's just white.

Wait this is gameplay.

As we've already spoiled thanks to Pokechu22 being the change author, we now know way too much about how Major Minor's Majestic March works and the behaviors it relies on. Let's get technical. And please take notes, as there will be a test at the end.

The viewport, the scissor, and the scissor offset are all used to change where things end up on screen. Modern graphics APIs have both a viewport and a scissor, but don't have a direct equivalent to the scissor offset. Let's break down how each of these things work together.

The Viewport is used to scale vertices into screen coordinates. It uses floating-point numbers, so it doesn't necessarily need to be aligned to a pixel grid, though in practice it is most of the time. This is mostly used to set the size of the rendering canvas.

The Scissor is used to indicate which pixels get rasterized - pixels that are within the scissor region are drawn to and pixels that are not in that region are ignored. It usually is set to cover the whole screen with values that match the viewport, but can be set to a smaller value to create picture-in-picture style effects. There are 12 bits of space per coordinate, capable of representing a value from 0 to 4095, but testing found that the 12th bit is ignored, allowing only values from 0 to 2047. In Dolphin, it remains aligned to 1x IR pixel boundaries at higher internal resolutions in order to prevent issues.

Scissor Offset is used to shift pixels after they've been rasterized but before they're written into the Embedded Frame Buffer (EFB). It operates on Pixel Quads, much like our good friend bounding box, and it has 10 bits of space each for the x and y offsets, which could hypothetically represent a value from 0 to 1023 pixels directly, but instead is multiplied by 2 (to operate on pixel quads). Only 9 bits would be needed to represent a value from 0 to 1022, so the previous change assumed the 10th bit indicated negative numbers. This value is multiplied by 2, so to represent a value from 0-1022 only 9 bits are used, leaving the 10th bit unused. The EFB is 640 by 528 at most, and the largest size a texture can be is 1024 by 1024, so wrapping at 1024 isn't that strange.

All of this so far makes sense, but what follows doesn't. It turns out that much more space is provided than that, which can result in a triangle drawing over itself in a large enough viewport. We don't know of any games that do this, but it's apparently possible with fringe configurations. If you care about all of the hardware testing and strange behaviors, Pokechu22 documented the details of their hardware tests in copious detail.

In the case of Major Minor's Majestic March they add a 1024 scissor offset to most of their graphics, which resulted in it rendering off screen in Dolphin. If you were paying attention in the lecture above, you'd already know that an offset of 1024 doesn't actually do anything in practice because it wraps! By reworking Scissor Handling to be more correct, Pokechu22 fixed this issue to make the game finally playable in Dolphin.

Marching is a lot easier when you can see.

The fix for Dolphin's Hardware Backends is a bit simplified and doesn't handle certain cases, like a game using an offset to have the same thing render multiple times. This does mean there are some minor cases of graphics disappearing early during certain transitions in Major Minor's Majestic March and can be observed on the left side of the screen in the demonstration above. Note that this is seen because Major Minor's Majestic March, on top of the aforementioned initial offset, also uses scissor offset to scroll the screen for transitions! If you want to see these scrolls and the duplicated graphics shown correctly, you'll need to use Dolphin's software renderer.

As an added bonus, these changes also fix a minor issue in Mario Golf: Toadstool Tour in which a picture-in-picture effect used for the Hazard placard would render slightly bigger than it should. This was rarely noticed because the issue was seemingly random, and the viewport itself wasn't affected.

Sometimes the hazard screen would show up with a bit of garbage on the the right side.

This is how it would normally display

With some hackery, here's what Dolphin thought the game was trying to do.

Now that's widescreen.

5.0-16260 - Round Viewport Coordinates when using Vertex Rounding by Pokechu22¶

This is tangentially related to all of the viewport and scissor shenanigans we detailed above, but instead this is a hack to help games render correctly at higher resolutions. In this case, we're targeting Wii Sports Resort. At higher resolutions, an annoying blue line would appear in the Archery Minigame.

The cyan line here gets increasingly worse at high resolutions.

The issue is that the game is trying to reset depth on part of the screen by drawing a rectangle over it, and then clearing the color of the region using an EFB copy. Unfortunately, the coordinates stop matching up at higher resolutions because the game has the x coordinate of the viewport centered at 478.266. These decimals don't result in any problems with the low resolution of the console, but at higher resolutions this strange inaccuracy becomes increasingly noticeable.

Pokechu22 stumbled upon this and decided that it should be possible to fix similar to other high IR bugs by rounding viewport coordinates at higher resolutions. They tried it out and...

No more line!

It turns out that rounding the coordinates off so that they match up again does work, and the solution was presented. Because this is such an edge-case of an edge-case, it was decided not to make Viewport Rounding a new option, but instead it was rolled into the already existing Vertex Rounding which is used for similar looking issues.

If there are any games that need Vertex Rounding that break because of this change, the two options will be split apart, but from our testing this appears to be fairly unlikely.

Porpoise on Deck¶

Between Progress Reports we saw the arrival of the long awaited Steam Deck, a portable x86-based gaming PC/console hybrid from Valve. And you know we have one! So how does the Steam Deck handle some very challenging Dolphin workloads?

These are absolutely torturous scenes that we are putting the Steam Deck through, and it's handling them very well. These results easily beat high end Coffee Lake ultrabooks from just a few years ago! We are confident that the majority of titles can run at fullspeed on the Steam Deck.

However, we have noticed that there is a lot of confusion about optimizing Dolphin on the Steam Deck. Here are a few things to keep in mind.

Building Dolphin with our Building Dolphin for Linux guide does not work on the Deck due to its immutable root directory. Fortunately, in desktop mode the deck has an app store called "Discover" which distributes flatpaks from flathub, and it has Dolphin's latest "Beta" build ready for installation. This is our recommended way to install Dolphin onto the Steam Deck. We're working on a better solution, but for now this is the best method available. If you need any help with this process feel free to ask on our forums.

To preserve its battery as much as possible, the Steam Deck lowers the clockspeed of the CPU or GPU any chance it can. However, we're a bit unusual, and the Deck may guess incorrectly and take megahertz away from the CPU that we so desperately need. This is particularly present in readback heavy titles that use EFB Access or Store EFB to Texture and Ram. So when optimizing Dolphin on the Deck, be sure to use MangoHud to keep an eye on the CPU clockspeed. If you are below fullspeed and see MangoHud showing a CPU clock in the 2000-2500mhz range, you should make some adjustments - in our testing adjusting Dolphin's Internal Resolution and the Steam Deck's GPU Clocks help most. What you want to see is CPU clocks in the 3000-3400mhz range; then you know all of the Deck's CPU power is available to you.

The Steam Deck doesn't just support Vulkan, it supports OpenGL too. And sometimes, OpenGL can actually be faster than Vulkan! In the Skyward Sword test above, Vulkan tried desperately but couldn't quite reach fullspeed, while OpenGL ran right past it to around 38fps. So when running games on the Deck, be sure to give OpenGL a try.

And that's all for now. We have a lot more tips on the Steam Deck. In fact we even had a setup guide partially completed! However SteamOS is changing so fast that half of it was invalid within a month, so we decided to just cover the important tips. If you need help configuring Dolphin on your Steam Deck, please ask us on our forums.

Last Month's Contributors...¶

Special thanks to all of the contributors that incremented Dolphin from 5.0-15995 through to 5.0-16380!

Dolphin Progress Report: November and December 2021, January 2022

2022-02-08T12:04:47+00:00

This year, we've hit an important milestone that's been in the works for nearly a decade. In late 2012, Sonicadvance1 began work on Dolphin's ARM JIT. Back then, there weren't any devices that had even a sliver of hope of running Dolphin close to full speed, but that wasn't really the goal. All he wanted to do was see if it could be done; it sounded like a fun, challenging project. However, as time passed the idea turned into more than just a passing curiosity. Users were more than happy to donate to cover the hardware cost of staying on the bleeding edge of a rapidly evolving ecosystem, allowing ARM development to flourish. By 2015, Sonicadvance1 astounded developers and the community alike with footage of Mario Kart: Double Dash!!'s time trial mode running close to full speed.

We've come a long way.

On that note, we're happy to announce that Dolphin's AArch64 JIT has finally reached feature parity with Dolphin's x86-64 JIT. This means that every PowerPC instruction that the x86-64 JIT supports along with every major JIT feature are now supported in the AArch64 JIT! And this is a great time for ARM in general, with each generation of processor pushing the boundaries and companies like Apple adopting the architecture for larger and higher power devices like their M1 Mac line. For those on mobile phones and tablets, Adreno powered devices provide decent enough graphics drivers to get a reasonable experience at this point. And with a critical bottleneck getting fixed just days ago, performance on Adreno GPUs has skyrocketed. You won't have to scroll far for that news, we promise.

But that's only the tip of the iceberg; we've had three months worth of changes pile up and some other important infrastructure news. We've improved the user experience on macOS significantly and restored support for older devices. In fact, enough has happened that we'll be detailing the status of Dolphin's macOS support near the end of the report.

And... we haven't even talked about any emulation fixes yet. The past three months have had tons of changes that would have normally been the highlight of a Progress Report. The three month gap between reports was not because of a lack of changes. Want to take Riivolution games on netplay? You can. Hate the EA VP6 bugs? Make them a thing of the past with a new option. Wish your favorite LogicOp game worked on GLES or MoltenVK? Odds are, it does now! The list goes on, but outlining everything would take way too long, so let's just dive in. Please enjoy the November, December, and January Progress Report!

Notable Changes¶

5.0-15952 - Disable Primitive Restart on Adreno by The Dolphin Android Users¶

As stated in the title of this change, credit for this discovery can't go to any single developer or tester. This change happened because of the greater Android community that spends way too much time trying to get the very most out of their mobile devices. Over the past four years, Dolphin has gotten a lot of optimizations, fixes, and tons of quality of life features. Yet, despite everything a lot of users would swear by old forks and some have taken up the mantle of trying to retrofit them with modern features. Why go through all of that effort? Performance!

Unfortunately, these forks are often just personal endeavors with messy histories, sometimes incoherent changelogs, and some of them don't provide the source code at all (which is illegal, don't do that). Some users swear by these forks, and we could never know why because there isn't a good way to see how they are different. Yet one thing was for sure: numbers didn't lie, and users said that these old forks allowed their GPUs to run at much higher resolutions than the latest builds, even if it meant losing out on game compatibility and some CPU optimizations. No matter what we did, we couldn't bridge the gap, at least on the Snapdragon line of devices.

And now we know why.

Near the end of January, Gamer64ytb reported that the difference had finally been found. One of the changes in the old fork was removing an optimization called "Primitive Restart." In fact, the original creator of that fork, weihouya, tried to upstream this change to master, but their inexperience with contributing to Open Source projects, and a language barrier, left us with a rather messy change that had no reported benefits, it was simply because they didn't like the additional complexity Primitive Restart created. Testing of the time didn't reveal any conclusive benefits, yet it caused issues with Vulkan on Android, so Dolphin's developers declined to merge the change. However weihouya pushed it into their fork anyway and fixed Vulkan separately. And that is what set this all into motion.

Primitive restart functionality allows you to tell OpenGL that a particular index value means, not to source a vertex at that index, but to begin a new Primitive of the same type with the next vertex

On the surface, Primitive Restart should be a safe performance benefit. It allows Dolphin to reduce draw calls by merging primitives together. In fact, some GameCube/Wii games natively use Primitive Restart! Unfortunately, Primitive Restart being faster requires the GPU driver to handle things efficiently, and in the case of Adreno that simply was not happening. In fact, it had such a huge overhead, that it became the single biggest bottleneck while using the driver. And profiling the Adreno driver isn't all that simple, so we didn't have a very good way to even see that this was a problem. It was only after Gamer64ytb reached out to us about this discovery that we were able to go through and analyze things for ourselves.

The chart paints a very clear picture. This is one of the biggest across-the-board performance boosts we've seen in a very long time. This affects all supported Adreno devices, and should speed up Dolphin in any GPU limited situation. On mobile, this is most games, especially beyond 1x internal resolution. According to users and our personal tests, sometimes you'll see games that were lagging at 2x Internal Resolution now able to run at 4x Internal Resolution full speed! If you have an Adreno device and haven't tried Dolphin in a while, now's your chance. You might be pretty happy with the increased performance, along with all of the other changes that have brought compatibility roughly in line with that of desktop versions of Dolphin.

Unfortunately, disabling Primitive Restart is not a magic bullet for literally everything. Low-end Adreno devices with extremely weak CPUs aren't going to see a huge benefit. If you're not able to run a game at native resolution, odds are this won't help you. As well, Mali and Mediatek gain no benefit from disabling Primitive Restart. And on the Desktop side of things, as expected using Primitive Restart is slightly faster on NVIDIA devices and was already disabled on some AMD drivers and backends. This change and the performance implications only affect Adreno/Snapdragon devices. It's just that Adreno/Snapdragon devices also make up some of the best mobile devices that you can run Dolphin on currently.

5.0-15538 - MMU Support for AArch64 JIT by JosJuice¶

Dolphin's AArch64 JIT has been highly capable the last few years, but as we've repeatedly noted, there were a few features missing here and there that caused it to be slower in certain titles. The biggest of those was the lack of MMU support.

The MMU is a part of the GameCube's CPU. _{Credit: Wikimedia user ZyMOS / CC by-SA 4.0}

On the GameCube and Wii, rather than directly accessing available RAM, games interface with virtual memory which is then translated to physical memory by the Memory Management Unit (MMU). The MMU is programmable and gives games a wide array of options for manipulating virtual memory. Fortunately, to our benefit, most games didn't bother to take advantage of that feature and just used the default memory mappings of the MMU. As such, for the vast majority of games Dolphin can just directly translate the virtual memory to host memory, which is simple and speedy. However, a few impressive games did decide to go beyond the default mappings and write their own custom exception handlers to allow themselves to move things around in memory wherever they wanted. Star Wars: The Clone Wars even changed the Block Address Translations mid-game! Any game that takes advantage of the MMU requires Dolphin to slow down and pay attention so it can emulate all of these behaviors, creating a significant bottleneck on CPU emulation. While it will never be cheap, Dolphin's x86-64 JIT does everything it can to make this as fast as possible.

The AArch64 JIT completely lacked MMU support, forcing all of these instructions to be run through the interpreter instead. This meant that one of our most intensive emulation tasks was being run through our compatibility-focused interpreter, on power limited hardware! For games like Rogue Squadron 2, Rogue Squadron 3, and Spider-Man 2 to ever approach fullspeed on AArch64 devices, MMU supported needed to be implemented in the AArch64 JIT. This change essentially proves that, with huge performance gains across all MMU titles. Now that dream of running some of these games full speed on your favorite ARM devices isn't so far-fetched.

Note that this is an M1 Max, the most powerful AArch64 device on the market, and even it can't run Rogue Squadron 3 at full speed. This is because MMU titles are still much more demanding in general, and that particular game does everything that's hard to emulate. Still, all MMU games perform better and normal MMU titles may even be able to run full speed on high-end AArch64 devices.

5.0-15524 - AArch64 Support for Codegen Space Reuse by JosJuice¶

If your raw performance is fine, the next thing most users want is for things to run as smoothly as possible. And that's where Codegen Space Reuse comes in. By marking spaces of invalidated code as reuseable, Dolphin can minimize costly JIT cache flushes and keep your game running smoothly, even when it's generating dynamic code. This feature has been present in Dolphin's x86-64 JIT for over a year, but now JosJuice has ported the feature over to the AArch64 JIT.

Overall, this is a targeted optimization that only targets certain games. Probably the most popular game that used to suffer from this issue was Metroid Prime and the other games on that engine. Nintendo 64 Virtual Console games have their very own JIT, so they generate tons of code and would hitch constantly before as the cache would get flushed once or twice every five minutes, but now will only require cache flushes every thirty minutes or so on average. And of course, we can't forget the memory management nightmare that is True Crime: New York City which used to do... this...

People did not follow our advice when we said not to play the GameCube version of this game. We're looking at you, Vinny.

These issues are entirely resolved in most cases, and greatly reduced in the most extreme cases with Codegen Space Reuse. In most of the library, you should never see a JIT Cache Flush under normal play.

As a small aside, shortly after this feature was merged, users reported severe performance issues in a few select games, including Harry Potter and the Prisoner of Azkaban and F1 2002. This was due to some minor JIT implementation differences between the x86-64 JIT and the AArch64 JIT, and were quickly rectified by modifying the AArch64 JIT cache to take into account some differences in how certain instructions are handled.

5.0-15484 - Also Use Copy Filter for EFB Copies by Pokechu22¶

The EA Sports Active games were EA's response to the Wii Fitness game craze. Despite having other franchises on the Wii such as Madden NFL, FIFA, Need For Speed and many, many others... according to Wikipedia, EA Sports Active is EA's top selling Wii game. Seriously. It was so popular that they made four EA Sports Active titles, including one that leveraged their NFL license.

Despite seeming like nothing more than simple exercise games, users trying to run the original EA Sports Active in Dolphin would find that things weren't exactly looking like they remembered.

Believe it or not, this is a bug. We know it's hard to tell, but trust us.

This bug was reported in 2013, but was accidentally swept under the rug because EA Sports Active: More Workouts, EA Sports Active 2, and EA Sports Active: NFL Training Camp didn't suffer from this issue and their naming scheme was less than clear. Because of that, it was mistakenly marked as a duplicate of the more typical "VP6" video bug when there was actually a unique issue present only in the original game!

To what has seemingly become Pokechu22's specialty, they decided to investigate this bug in almost too much detail. If you care about exactly what was going on, what the developers were likely thinking, and exactly how the game renders, check out Pokechu22's writeup. For now, we'll just go into the basics.

This game uses the GameCube and Wii hardware feature "Copy Filter". While copying a rendered frame from the Embedded Frame Buffer (EFB) to main memory, the hardware can for free do some very basic effects to each line of the image. This can be used to blur the image slightly, such as the "Deflicker" filters in the Super Smash Bros. series, or to brighten/darken the image, as used in fade-out transitions in Rogue Squadron 2 or gamma adjustments in Metroid Prime. This is a non-programmable hardware feature, so after we implemented it a few years ago, we were confident that we had seen the last of Copy Filter related issues. However, we made a bit of an assumption that would come to bite us later.

With EA Sports Active, Pokechu22 discovered yet another clever use of the Copy Filter - Color Filtering! Thanks to their research, we can actually get a look at what the game looks like before and after the Copy Filter... filtering.

The base colors look a little washed out.

After filtering, the game does look a little bit nicer.

So how was EA Sports Active actually accomplishing this and what exactly were they doing? The game was making two different EFB copies for each frame. The first copy is configured to take the red and green channels of the image, and then the second copy takes the blue channel and uses the Copy Filter to take 1/16th the value of the current line. By separating the values out like this, the game is able to do some custom color/alpha blending to create more contrasty scenes with crisper colors.

When implementing the Copy Filter, we noticed that every known use of the Copy Filter was being done exclusively to XFB Copies, a special type of EFB Copy where the frame is moved to a specific region of Main Memory designated for scanout. So we assumed that copy filter effects could only be used for XFB Copies, and excluded standard EFB Copies from the Copy Filter entirely. EA Sports Active proved us wrong. By merely allowing EFB Copies to go through the Copy Filter, a trivial change, Pokechu22 corrected the issue and now EA Sports Active's custom color shenanigans all work as intended.

The game with the bug has a certain eye-searing charm.

And fixed. ...Well that's a lot more boring.

Surprisingly enough, after submitting the fix we found out that EA Sports Active isn't the only game that uses Color Filtering like this! The Last Airbender, based on the hit movie that Avatar fans love to bring up, used similar color filtering system, just with a much less interesting color palette.

If you look closely, you can see those same splotchy artifacts in the gray that you could see in EA Active.

With it fixed, the gray background is... well still grey but you can see things now. It's very serious.

As with any major change to emulation, adding this did cause a few minor issues here and there. Thankfully, the regressions were found and sorted out 5.0-15518. And then a few more were discovered and addressed in 5.0-15950. And one of our debug features was also broken and finally addressed in 5.0-15961.

Unfortunately there appears to still be a few quibbles to sort out. While working on this Progress Report, we noticed something was a little off about one of the characters and confirmed it does not occur on console.

On console after filtering, this character is still wearing a pretty normal light blue top.

But Dolphin renders it as white with pink and blue shadows. Thankfully, a fix is already in the works.

If you want to see more details on this issue, please read Pokechu22's writeup on this bug. It goes into a depth that we could never manage in a Progress Report!

5.0-15515 - Support for Manually Handling Texture Wrapping and Sampling by Pokechu22¶

Fixing the discoloration of EA Sports Active was a win, but unfortunately there was still another problem that affected it and over one hundred other games. The breadth of games was huge, from EA's own sports titles, to the James Bond series, various Harry Potter games, several Need for Speed games, the eternal Just Dance series, and even strange outliers like Target: Terror. Odds are if you had a sizeable library of games, you probably had at least one that was affected by this bug... if you had certain hardware.

If you were on a GPU that suffered from the bug, James Bond cutscenes would be a little hard to watch.

Other GPUs had no issues whatsoever.

Target: Terror's backdrops and sprites are all FMVs.

You can see the familiar buggy lines if you look closely, since this was taken from a NVIDIA machine.

There are probably some readers scratching their head right now. It's very possible you've played many of the games we've mentioned and never noticed any kind of defect like this. That's because this primarily affected NVIDIA GPUs. There are exceptions, but if you haven't been using a NVIDIA GPU, odds are you haven't seen these issues. AMD graphics card users were almost entirely unaffected, and so were most phone and tablet users since Adreno and Mali are did not exhibit this bug.

That's because this is entirely due to texture sampling quirks. Texture sampling is the act of reading texture data (its color data, texture coordinates, etc) as well as texture filtering. As this is a feature that is going to be used, in scientific terminology, a bajillion times per frame, it needs to be extremely fast, so even the latest GPUs use fixed function hardware to accelerate this task. However, not all GPUs sample textures in the same way, but usually the differences from this are so small that they are limited to subpixel quirks.

The afflicted videos are comprised of many tiny and large textures that are combined together to build each frame of the video; a video that doesn't match the resolution the game is using. This already creates MANY opportunities for interpolation differences to crop up, but these video codecs takes things even further. The videos actually have color data from one texture produce an offset to the texture coordinates that are used when reading a second texture. This leads to cascading rounding errors, where even the tiniest differences can explode into view. We understand why they are doing this, but it makes these videos extremely fragile and they require extreme precision to reproduce accurately. In fact, if you look at the Bink Video changelog from this era, you can see them struggling with this on real consoles.

Why are some graphics cards unaffected? While we're not 100% sure, we can at least give some conjecture to why AMD based cards aren't affected. The GameCube and Wii have ArtX graphics processors inside of them, a company that was absorbed by and became ATi and then was later purchased by AMD. It appears as though texture sampling behaviors haven't changed since the days of the GameCube, so these issues don't appear on their modern hardware. This also extends to our Adreno users, as their hardware traces their roots right back to ArtX as well.

Score one for Adreno!

Unfortunately for Nvidia users, they had no such luck. They would see the visual issues in VP5, VP6, and Bink videos that used these techniques. Worse yet, the issue actually can extend to cases outside of FMVs, such as the text boxes in Mario Party 7 or the video gameplay elements in Target: Terror which uses multiple Bink Videos for animated sprites to emulate the look of a classic arcade shooter!

For all this time, Nvidia users have simply had to deal with these issues. Since this is tied to low level GPU hardware differences, how are we supposed fix this for them? Well, we just had to stop relying on the offending bit of the GPU's hardware and do texture sampling ourselves!

Note: The Open Source "RADV" drivers for AMD graphics cards do show the sampling bugs. While Texture Sampling is handled by low-level GPU hardware, it's entirely possible for the GPU driver to affect how that low-level hardware functions. Oddly enough, the RADV driver's defects in these situations look slightly different than the defects on every other graphics card, with the vertical lines looking more like they are made up of dots.

Sorting Through Sampling¶

For the most part, Dolphin didn't do anything all that strange when sampling a texture. Outside of the shader, Dolphin would tell its graphics backend what to do while sampling the texture, such as linear sampling, mip mapping, wrap horizontally, wrap vertically, etc, all based on the situation. Regardless of orders sent, the shader then calls upon the fixed-function GPU hardware to sample that texture with the selected settings. Given that this wouldn't work for every GPU in every situation, a new solution had to be devised. What Pokechu22 decided to do was to create a way to manually sample the texture instead of relying on the graphics card's texture sampling unit. While it was a fair bit more work and we were concerned about performance, Dolphin itself could read and filter the texture manually in order to ensure results were consistent and correct to precisely what we needed. From there, the shader can look at the texture configuration and find out about other nearby coordinates, mipmap levels, and more with greater accuracy.

Inexact texture sampling could cause ugly lines, even at 1x internal resolution sometimes.

Manual texture sampling eliminates the issue entirely.

The experiment was a huge success right away, but there was a ton of work that had to be done to support literally everything that Dolphin could do. It took literal months to work through everything, but the greater level of control meant that Dolphin could also start emulating some of the stranger behaviors of texture handling of the GameCube and Wii. Most of those cases do not usually occur in retail games, but sometimes happen in mods and homebrew tested in Dolphin. One example of this was when a developer of the Star Fox Adventures: Amethyst Edition reported that textures that worked fine in Dolphin were broken on console. However, with Manual Texture sampling, we have the ability to make these textures behave accurately without forcing people to use the software renderer. If you use Manual Texture Sampling at 1x Native Internal Resolution with Load Custom Textures disabled, you can now catch problems with irregular textures that would have rendered fine otherwise.

Dolphin's standard handling of textures happily accepted these malformed textures and rendered it normally. This is incorrect emulation.

However, the secret title only for console and now Manual Texture Sampling was StarFox StarFox in the issue report.

For those that want the most accurate picture possible, Pokechu22 has also added support for diagonal level of detail, which allows for more accurate selection of the correct texture mipmap if the game chooses to use it. This results in very minor differences that are only evident if you're directly comparing side by side with an identical screenshot from console. All of these cool features and fixes comes with no known regressions at this time, making it a rather safe option to try if you're interested in seeing if an annoying graphical issue is related to texture sampling! Just note that the enhancement "Anisotropic Filtering" is currently not implemented in Manual Texture Sampling, so that feature does nothing when Manual Texture Sampling is enabled.

Performance Perils¶

We've talked about having higher accuracy, better picture quality, and less reliance on GPU quirks without any visual regressions. But we haven't talked too much about performance. Since we are bypassing dedicated hardware meant to make texture sampling as fast as possible, a performance hit was inevitable. However, the story is actually rather complicated - how Manual Texture Sampling behaves depends on your GPU's architecture and raw computing power, as well as the resolution you wish to play at. At lower resolutions, i.e. 1-2x Native Internal Resolution, there isn't much of a bottleneck at all. In fact, some games actually run faster on certain hardware. However this will change at a certain resolution, usually around 3-4x Native depending on your GPU, and it becomes a noticeable performance bottleneck.

Tip: You can hide or reveal items by clicking/tapping them in the legend.

If you have an absolute powerhouse GPU, odds are the performance impact won't affect you until you're at a resolution beyond reasonable. Those of us on more modest hardware are hit a bit harder. And those on older GPU architectures that are more sensitive to this, such as Pascal, are hit even harder. Considering that this only impacts certain hardware and can have a sizeable performance impact depending on your resolution and GPU architecture, we've mostly left this option disabled for now. In a few low impact games that heavily rely on FMVs (e.g. Just Dance) we have decided to enable it by default, as they aren't GPU limited in general and see almost no benefit from higher resolution. If every graphics card were affected, the decision of when to enable this would be a lot easier, but that's just not the case.

Eventually, we may need to come up with a conditional default, depending on the user's hardware, much like a driver details bug, but this time handled per-game. For now, if you have an afflicted card, "Manual Texture Sampling" resides in the "Advanced" area of the Graphics Settings Menu. If you enable Manual Texture Sampling, Dolphin will then Manually Sample Textures along with enabling all of those other accuracy bonuses. Our current plans are to find games that have heavy glitches with "Fast Texture Sampling" to the point that they are unplayable, and slowly enable Manual Texture Sampling on a case by case basis. Unfortunately, this does mean that some users with Graphics Cards/Drivers that did not have the error may have the setting enabled despite not really needing it. We'll continue to try to make smart decisions when to enable this feature, especially as we get more data on what games it effects and how it performs on all the vast variety of machines that our users play Dolphin on.

5.0-15520 and 5.0-15604 - Riivolution Fixes, Additions, and Netplay Support by AdmiralCurtiss¶

When Dolphin added High Level Emulation (HLE) for launching and configuring Riivolution mods, users quickly embraced the feature and we saw a huge influx of both appreciation and support requests. The initial implementation was fairly good, but there was no way we could test every mod and find every edge-case. Over the past three months, AdmiralCurtiss has been busy fixing Riivolution mods that didn't run on Dolphin and adding a few much requested features. Most of these bugs were very silly, and had to with things like "case sensitivity" of filenames and paths, duplicate files in the mod, and were mostly centralized to haphazardly constructed mods.

Wii Sports Resort: Storm Island relies on very peculiar Riivolution behaviors.

On the side of new features, AdmiralCurtiss has brought some big hitters to the table. First of all, you can now create Game list Entries for Riivolution mods, letting you boot preconfigured mods directly from your game list!

Creating game list entries for mods can be done from the Riivolution Menu and then those can be launched directly from the game list!

This may not seem like a huge deal at first, but this was one of the major requirements for booting Riivolution mods on Netplay! Once a Riivolution configuration is in your game list, you can use it for netplay. As long as all players in the netplay session have the Riivolution mod configured correctly, it'll work like any other game on netplay.

Note: Wii Remote Netplay is still experimental, and only works with Emulated Wii Remotes. Even then, some actions, such as Wii Remotes disconnecting, may not behave properly on netplay and improperly configured netplay sessions may hang on boot. Riivolution Mods for GameCube games and Wii games that support GameCube controllers are much easier to setup and synchronize properly.

Note 2: If you are planning on using Wii Netplay, please use revision 5.0-15559 or newer for reasons that we'll get to... right now!

5.0-15549 and 5.0-15559 - Netplay Shutdown and Wii Save Fixes by AdmiralCurtiss¶

After all of these years, Wii Netplay is still in a rather experimental state. There are a lot of challenges surrounding it, such as the Wii's internal memory, system files, and of course, those pesky Wii Remotes. Dolphin's netplay infrastructure was designed before the idea of taking Wii games onto netplay was even considered a possibility, so a lot of Dolphin's Wii netplay are tacked on top of an aging foundation. Syncing memory cards is one thing, but how do you synchronize a NAND that can be 500 MB and can contain copyrighted data? Well, that's actually the crux of a lot of bugs on Wii Netplay - synchronizing the NAND.

In order to avoid both legal and bandwidth issues, Dolphin sets up a "Blank" NAND for netplay, and then imports the necessary savefiles for the games the users want to play on netplay. This keeps the footprint small and avoids all the legal issues. When Netplay is over, these files are then exported back to the original NAND if the user has turned on "write saves"... which is actually where a nasty problem cropped up, one that could actually affect your actual NAND's save.

Due to an unfortunate race condition, mixed with Wii Remotes' propensity to want to crash Netplay in general, it was possible for the original save to be lost during the export process due to a race condition. While cleaning up part of the codebase for Riivolution games to function on netplay, AdmiralCurtiss noticed a bunch of these problems and found himself unable to figure out how the code was actually supposed to work. This may sound outrageous, but it's a fairly common occurence when you dive into the older parts of a project that has had this long of a lifespan. The only option at that point was to rewrite and fix up the code to at least make it work again. As it was, it seemed like Dolphin's Netplay was making assumptions that were no longer true due to changes in other parts of the codebase.

The save loss bug is fixed to the best of our knowledge in the latest builds, meaning it should be safe to take your saves on netplay again. Your original save from your real NAND should never get lost again. However, if Dolphin crashes during netplay, the updates to save files done during netplay will not exported to the main NAND. Do not panic if this happens! Your save data from the netplay session can still be retrieved in a Wii.backup folder contained in Dolphin's user files and manually converted. Do note that starting Dolphin and booting up another game will clear these files.

5.0-15579 - Delay Single Core GPU Interrupts by phire¶

Most of the time, Single Core is Dolphin's accuracy option that helps with most random crashes and hangs. But in a few rare games, Dual Core is actually the more stable option. One of those games is Bomberman Jetters, and the reason why is pretty interesting.

One thing to note is that the GameCube and Wii are single core consoles, so there's only a limited amount of things we can try to parallelize from the main workload. However, early Dolphin developers realized that the GPU-related CPU work, such as sending graphics data and the like, was reasonably safe to split into a second host CPU core. After all, the CPU side of things doesn't interact with the GPU-related CPU work all that often. This meant they could run in parallel on separate host CPU cores for a time and only sync up at important moments (such as specific interrupts) in order to greatly improve performance. While today we know of Dual Core as the source of many random crashes, when it was initially implemented Dual Core mode wasn't as problematic as it is nowadays; usually the GPU thread was more than fast enough to keep up and users were always limited by the CPU thread. Ever since TEV_Fixes_New Dolphin's performance profile has flipped, with the CPU thread now actually being faster where as the GPU thread has a lot more to do thanks to improved emulation.

This creates a scenario where the CPU thread may run too far ahead of the GPU thread, and if the GPU thread is too far behind when an interrupt happens, you may run into synchronization issues. There's not much we can do about this problem - the reason why Dual Core is fast is because the threads run without much syncing. If we add more syncing to fix the crashes, performance would drop. Besides, at this point Single Core has been optimized pretty well and on a lot of computers works well enough without any of the risks. It's a properly deterministic option for when a game is problematic on Dual Core.

Bomberman Jetters is one of the games where Dual Core's lack of synchronization is actually a good thing. This game expects GPU FIFO processing to take time. In Dual Core, this happens out of pure happenstance because the CPU thread and the GPU thread only meet up once in a while. Single Core executes everything exactly in order on a single thread with no delays whatsoever. Worse yet, the execution time would be backdated to when the FIFO command was first sent, meaning that zero time had passed since the game issued the command!

Rather than trying to emulate the whole pipeline correctly, phire came up with a little bit of a hotfix that makes FIFO execution a bit closer to correct on Single Core. With this change, FIFO execution is fed through an interrupt scheduler that can delay and make sure interrupts happen at the right time. Here, we just force a minimum wait time so that those interrupts that were happening instantly now happen a tiny bit into the future from when they were issued. It doesn't exactly address the core issue, but it's good enough to get the game booting. Unfortunately, this game is still prone to random hangs even with the initial hang fixed. But the good news is that there is a work-around now - lowering the emulated CPU clock by a small amount significantly (perhaps completely) reduces the likelihood of the game hanging.

It's fitting that this game would be a ticking time bomb in Dolphin...

This also affects some Datel Products and Resident Evil 3 when running in Single Core, preventing game breaking hangs from happening. This is important because these Datel Products were actually broken on Dual Core too, so having them working at all is rather nice. Resident Evil 3 is kind of in-between. It works on Dual Core, but depending on your device, there's a very small chance of hanging if things go wrong in just the right way. In our limited testing, we were unable to cause any hangs at all in Resident Evil 3, but some transitions appear to take an abnormally long time, including the initial first door where the game was hanging previously. If this issue is similar to Bomberman Jetters, it's likely that slightly reducing the Emulated CPU Clock would smooth out any remaining issues if there are any.

5.0-15586 - Don't Clear RTC Flags on BS2 Reset by Pokechu22¶

Some users and developers love using the Wii Menu (commonly referred to as the System Menu). It's a lot of fun to go through some of the channels and see various animated game banners that aren't shown from the typical Dolphin GUI. However, if you boot a game and then return to the Wii Menu, the game you were playing wouldn't be present in the Disc Channel. This is because Dolphin was clearing RTC (Real Time Clock) flags on reset, so the emulated console didn't know that it should update the Wii Menu's cache and refresh the inserted disc, leading to stale data being used. Pokechu22 made a quick correction to this behavior, so that the correct disc appears in the disc channel after reset.

Now you don't have to force change disc after every reset to get the correct games to show up.

5.0-15676 - Fix LogicOps in OpenGLES (Android) and MoltenVK (macOS) by OatmealDome¶

This is a workaround for missing LogicOps support in Metal (MoltenVK) and the many mobile drivers (Adreno, Mali, etc.) that do not support the OpenGLES and Vulkan extension. However, this time around, we're not trading one broken game for another; OatmealDome has taken advantage of an improving situation on Android alongside a small hack to MoltenVK to get correct output in LogicOps titles on the afflicted devices.

While OatmealDome is best known for working on Apple features, including a fork of Dolphin designed to run on iOS devices, they've also taken over the burden of helping maintain Dolphin's macOS builds. They've submitted fixes for MoltenVK, helped update the buildbot, and have generally improved the macOS user experience. In this case, they wanted to fix LogicOps features on MoltenVK, but then stumbled into the fact that OpenGLES environments (Android on Non-NVIDIA) suffer from the same problem. A while back, Stenzek added LogicOps approximation through blending to fix Mario Kart Wii on Windows 7 D3D11 and OpenGLES devices.

Unfortunately, restoring some remedial emulation broke things in other situations, and left some games like Kirby Air Ride looking a little dark.

The game is still quite playable, if you're used to blindfolded runs.

Why exactly is this happening in Kirby Air Ride? To answer that, we need to talk about LogicOps and how they work on the GameCube/Wii. LogicOps (Logical Operations) are a more complex version of Blending operations, allowing a game to perform a wide variety of binary commands in the blending stage. The GameCube and Wii support this natively (based on the OpenGL implementation). In the hardware, they are bitwise operations that use the output color from TEV and/or the current color of the framebuffer and use them in various ways. The result of the operation is then written to the framebuffer and used.

Kirby Air Ride uses the alpha value on the framebuffer to determine where to draw shadows on the screen. At the start of the frame, the game sets the alpha of the rectangle 255. However, it also uselessly uses the SET logic op, which sets the output color to the current TEV color. This is fine if the system supports one of Dolphin's proper LogicOp paths. However, this goes completely wrong under Dolphin's LogicOps approximation with blending path. In this case, Dolphin sets the source and destination factors for the color, but does not set factors for the alpha. This causes the alpha to be set to zero for the entire frame. Even when the game attempts to modify the value to mark where shadows should be drawn, it remains at zero.

If we simply disable LogicOps, everything is bathed in shadow.

If LogicOps are emulated properly, all of the non-shadowed portions are brightened.

If you feed in black rather than the alpha value, instead of lightening the scene, it instead gets shrowded in darkness. Emulating LogicOps with blending is already a last resort, so to improve the situation, OatmealDome had to go another route. With macOS and MoltenVK, Metal does not support LogicOps, so OatmealDome modified our MoltenVK implementation slightly to enable SPIRV-Cross to convert Vulkan's subpass inputs into a framebuffer fetch. This allows Apple Silicon GPUs to support LogicOps, but unfortunately all other macOS GPUs still will not work as they do not support this function. For OpenGLES, there is an extension to support LogicOps, but of course no mobile drivers bother to support it. Instead, we rely on GL_EXT_shader_framebuffer_fetch or GL_ARM_shader_framebuffer_fetch, which can give us the colors of the framebuffer and then we can handle the LogicOps logic in the shader itself. This is slightly slower than native support, but much better than using blending approximation.

And then OatmealDome said, let there be light!

Note: The modifications to MoltenVK will not be upstreamed. This is because the behavior we're utilizing is specific to what Dolphin needs. It works for our purposes, but chances are that other programs probably wouldn't want this. Eventually MoltenVK should mature to the point that this hack won't be necessary, but for now this helps make the game's playable on Apple Silicon.

5.0-15680 - TextureConverterShaderGen: Set alpha to 1 on intensity formats if EFB lacks alpha by Pokechu22¶

Sometimes an obscure game can lead you to some rather interesting effects. Rygar: The Battle of Argus was a cash-in port of an already six year old PS2 game, Rygar: The Legendary Adventure which was a follow up to Rygar (Arcade), which is playable on the Wii Virtual Console Arcade. Based on the reviews people gave to Rygar: The Battle of Argus, that might actually be the better Rygar game on Wii.

And that's just about all the information we could find on this game. However, any game, no matter how good or bad, can become notable to emulation developers. All it has to do is have one thing that confuses everyone. For Rygar: The Battle of Argus, that ended up being what made it fun for us. An issue report mentioned that some screens would be washed out in Dolphin, which eventually was tracked down to its bloom effect. Initial experimentation with the effect and how it worked led us to wonder if the effect even worked on console. But, that was easily tested and it turned out that it was yet another weird edge-case.

This dark and moody game is looking very washed out.

The game is supposed to have a much darker tone.

Pokechu22 took interest and you can probably guess what happened next if you've been reading these reports. A hunch was quickly surmised that this problem might be related to other visual glitches throughout the game. After testing things in the latest development versions, Pokechu22 found that the bug was present in most scenes throughout the game with varying degrees of aggressiveness.

Rather than just trying to see what was wrong in Dolphin, they instead did a deep dive into exactly how the game was rendering the effect. Once the effect was understood, the answer to what was going wrong would be simple. It turns out the game's bloom actually uses a clever trick to work around a hardware limitation - that the GameCube and Wii can only work with a single framebuffer. If a developer wishes to make other computations using the GPU, such as creating a texture for dynamic shadows, then they will need to draw on top of what's already been drawn on the screen. This is similar to the difficulties and problems Heavy Iron Studios ran into when rendering the shadows in Spongebob Squarepants: The Battle for Bikini Bottom.

Long story short, because the game was having to render over what it had already rendered, it created an EFB Copy without an alpha channel. Because of that, the alpha channel would return 1, or totally opaque. While that's normally correct, Rygar was making an EFB copy from a texture using an intensity format. While normal textures as EFB copies would usually be 1, when using an intensity format, Dolphin was setting it to zero! This completely changes how things are rendered in Rygar: The Battle of Argus, and is the key to their rather interesting dynamic bloom technique.

Rygar: The Battle of Argus still has some nice set pieces throughout it.

As custom after running into a unique issue, Pokechu22 started looking through fifologs and issue reports to see if there were any other bugs that were potentially related. Oddly enough, they stumbled into a much more widely known game: Pokemon Battle Revolution! For the past couple of years, it had been suffering with a regression that caused the screen to shift whenever a special effect that used the EFB was on screen.

This regression frustrated users, as the black border (right and bottom) would appear during most special effects.

Unfortunately, we had no real leads as to what was wrong, but we didn't end up needing any. Fixing Rygar: The Battle of Argus also fixed Pokemon Battle Revolution. However, because no one knew why Pokemon was fixed, the job wasn't completely done. It turns out, what was happening here was actually two separate bugs, and one of them actually happens on console! The screenshifting a huge amount was a Dolphin bug, but many of the special effects were also broken on console to a degree. That's because the game accidentally crops the bottommost and rightmost row of pixels, and then because of texture clamping, those rows get used for anything that would use content off of the screen.

Pokechu22 found their bug and created a game patch, which caused a bunch of special effects to render like they were intended for the first time.

This is how the game was broken in Dolphin before.

Here's what it looks like with the issue fixed, essentially matching the output on console.

And here is how the effect was originally intended to look, with the game bug patched.

And with that, our dive into these two games was complete. . . . Except it wasn't. Shortly after investigating Rygar: The Battle of Argus, it was noted that the game no longer worked in the latest development builds, crashing with a backpatch error unless full MMU was enabled. This regression was fixed in 5.0-15699 to return the game to normal.

5.0-15928 - Add Online Wii System Update Functionality to Dolphin on Android by Simonx22 and OatmealDome¶

Another major feature lands in the Android GUI. If you're looking to see some of the Wii's more advanced features or run homebrew, having a full assortment of System Files is necessary. On Android, getting those System Files could be a bit tricky, as actually updating the emulated Wii wasn't as simple as on Desktop versions of Dolphin. Simonx22 and OatmealDome teamed up to rectify this issue, with Simonx22 handling the Android side of things and OatmealDome helping with the C++ part of the implementation.

Performing an Online Wii System Update goes through the same steps as a real Wii would to update.

...Do remember that this does use the internet, though! Watch your mobile data usage!

Once you've run a Wii System Update, you'll be able to access the Wii Menu and be able to boot channels, games, and even things like the Open Homebrew Channel!

A "Fresh" Wii NAND running on Android.

For most users, this won't be too important, but it does allow for easy access to the Wii Menu and will allow booting discs and channels from it without the need for a PC for downloading or copying files.

Mario Party 5 players have been complaining to us for many years about a very peculiar bug. "Why does Dolphin crash when I use a Wiggler Orb"?

Technically, Dolphin wasn't crashing, but notifying the user of an unknown opcode. While this did interrupt play, all the user had to do was proceed through the message boxes and the game would keep going as if nothing happened. Over the years we found this to be a harmless occurrence and no cause for concern, but we didn't want to remove the message. After all, it was correct and pointed to a likely bug in Dolphin's GPU emulation.

Console doesn't hang or crash here, so surely this is a Dolphin issue, right?

However we couldn't really investigate the scene further, as Dolphin's Fifoplayer was unable to record scenes with unknown opcodes. At least it wasn't... until very recently. We've said this name a lot, but once again Pokechu22, has found time between investigating all of these issues to renovate our Fifoplayer with fixes and new features. One such consequence of their fixes is that the Fifoplayer can now record scenes with unknown opcodes. What mysteries would be awaiting us with the Wiggler Capsule after it had evaded our gaze for all of these years? For this, we'll let Pokechu22's own writeup explain.

Basically, the Wiggler capsule's animation draws a bunch of rings. Each ring has 128 vertices in it, with positions moving around a circle and texture coordinates going up by .03125 (1/32) for each horizontal step. The position, color, and texture coordinate data for each vertex is indexed into several arrays, with the first set of 4 vertices using indices 0, 1, 3, and 2. However, after all 128 vertices are written, the game writes data for 4 more vertices, again using indices 0, 1, 3, and 2. But since the game said it would only draw 128 vertices, not 132, those 4 vertices are instead interpreted as graphics commands. Opcode 0 is a NOP, and my brief hardware testing indicates that opcodes 1-7 are also treated as NOPs, so on real hardware these are ignored, but Dolphin didn't like that extra data. ...

By isolating an individual ring from the effect, we can see something isn't quite right.

If we modify the FIFO data to say that there are 132 vertices, then the first part of the ring is drawn twice, which indicates that vertices 129-132 normally go unused.

If we force render the extra vertices, one section of the ring gets brighter. This means that these vertices really aren't rendered.

This confirmed a rather exciting event! For the first time in many, many years, this is a case of an "Unknown Opcode" popup actually caused by an Unknown Opcode in a retail, licensed game. Most of the time these popups are disregarded as Dual Core misbehaving or strange GPU timing issues. There's a reason the message written by developers well over a decade ago seemingly disregard that the popup could be caused by an actual unknown opcode.

Unlikely, but here we are.

How exactly did this slip by the game's developers? Well, our best guess is this effect was programmed rather haphazardly and developers didn't realize how broken it was. The effect is broken in multiple ways, one of which is visual in the form of a texture defect. While normally this would be very, very difficult to see on console, Pokechu22 devised a way to use the HW Fifoplayer (a Fifoplayer that runs on an actual console) along with some fancy stitching of XFB copies to create high resolution screenshots on console. This isn't perfect but it does give us a chance to get a very high quality look at how this effect renders on console and confirms that Dolphin is emulating it right.

With some advanced techniques and a lot of stitching, we can see that everything renders the same on console. It's a game bug!

With this game's issues fully understood and Opcodes 0x1 -> 0x7 confirmed to be Nops (No Operation), the Unknown Opcode popups have been disabled for these Opcodes. This means that in the latest development builds, you no longer have to worry about the Wiggler Capsule causing any interruptions to your gameplay experience. As this is a strange behavior, Dolphin will continue to log Unknown Opcodes 0x1 -> 0x7 behind the scenes as it can give us a clue toward other bad behaviors and potential visual issues.

5.0-15936 - Android: Alternative Infrared Pointer Control by lynxnb¶

lynxnb returns with another Android centric change, this time an alternative control scheme for Touchscreen Pointer. Currently in Dolphin, you control the IR pointer by touching the screen, and then the cursor moves to the approximate point your finger tapped. This isn't very exact due to how different games are calibrated differently, and how large fingers are relative to the targets on screen. This change adds a second mode, where instead of the Infrared Pointer following your finger's position, it instead follows your finger's movements - like a touchpad. This is especially useful in shooters where you're going to do a lot of turning.

5.0-15974 - Android - Add support to import/export User Files by JosJuice¶

The Scoped Storage situation on Android has turned out to be a confusing, frustrating place for both users and developers alike. Depending on your phone, manufacturer, and the version of Android that you're on, your experience with Scoped Storage and its problems are going to vary. Some manufacturers seem to lock down app specific directories entirely, even preventing users from copying files in from a desktop computer. This means that users can't copy in saves, setup Riivolution mods, or backup their data in a meaningful way whatsoever. Given that this was a rather dire situation, JosJuice decided to rush in an option that will at least give users something they can use to import and export their user settings.

Under "Config/User Data" you now have the option to import and export User Data.

Do note that we're not going to implement our own file manager just to handle user settings. Currently, Dolphin can import .zip files that contain the user directory. A "Dolphin.ini" must be present in the "Config" folder for it to be considered valid user data. Do note that importing User Data will overwrite and delete all existing User Data. When exporting your User Data, it will be exported into the same kind of zip file that Dolphin expects for importing, so you can use that as a guide to see how the zip file should be laid out. Currently, support is a bit spotty, so making as "basic" of a compressed zip file as possible is for the best. We'll continue to explore other avenues for managing User Data now that we know this is going to be a problem from here on out.

5.0-15862 - Panic Alert Improvements by pokechu22¶

This is an overhaul that was quite overdue. Essentially, Dolphin's Panic Alert system had a few minor bugs. Namely, sometimes they wouldn't display all of the information we intended and translations weren't working, meaning even though some of the Panic Alerts were translated, the translations would never get shown regardless of the user's language. In between solving all of those crazy graphics bugs, pokechu22 found time to fix them up a bit.

This Panic Alert says the bare minimum, but it could be better.

And now in the latest builds, that better has finally come.

Port Settings to new Configuration System by AdmiralCurtiss¶

We haven't talked about the new configuration system in quite a while. To be honest, it's actually not that new anymore, now is it? This summer, it'll actually be five years old, the Layered Configuration System (Layered Config) is a more powerful configuration system that allows layers of overrides while also keeping multiple settings in mind. To harken back to a simpler time, Layered Config is an overlay configuration system with multiple layers - like an onion - and each layer lays over the one beneath it. Even though Dolphin only acts on the final result of all of the layers, each layer exists at all times in the config system, allowing Dolphin to know what settings layer is affecting what and why. This allowed users to make changes on the fly, without actually overriding the defaults as soon as they opened the menus. Unfortunately, once the important settings were ported over, progress of moving things over to Layered Config stalled and we have two active configuration systems for the past five years. The classic, fast, but limited SConfig, and the newer, more robust, but sometimes difficult to optimize Layered Config.

The fact that Dolphin has two very different Configuration Systems has led to a bit of technical debt, and has limited Dolphin's ability to move forward in some ways. Want a "Return to Default Settings" button? Well, that's not easy to do because there are two active configuration systems. Want to add a certain setting to your Game Config? SConfig settings aren't guaranteed to work in GameINIs! Want to change a setting while playing Dolphin on Android? Well, if that setting is handled by SConfig, odds are you'll have to stop emulation first. The list goes on, but simply moving everything over was a rather big task.

In recent months, AdmiralCurtiss has taken the mantle to finally remove all of the remaining reliances on SConfig and simplify Dolphin's configuration system in general. The end goal of all of this will be new, easier ways to manage Dolphin's settings so that you don't need to be an expert to get the most out of your Dolphin experience. But right now, we're still porting over a few stragglers in preparation for bigger things. Stay tuned.

Redump Has Made the Wii Database Public!¶

While this isn't directly a Dolphin change, it's a change that affects disc verification. Dolphin's disc verifier can now verify good dumps of Wii games by making use of the redump.org Wii database. In builds with the disc verification feature, notice that Dolphin can now tell you when you're using a good dump of a Wii game. This actually extends backwards to builds before the database was public, as the functionality had been prepped for this eventual release.

You can finally be sure if you're using a good dump for Wii games.

macOS Gets Some Love¶

macOS has been in an odd position with Dolphin the past few years. We've had to deal with Apple deprecating their already neglected OpenGL support, ignoring Vulkan to set up their own graphics API, and Bluetooth changes to macOS 12 Monterey that took connecting Real Wii Remotes from occasionally possible on a good day to no chance in hell. Add in their strict security measures, and it's been very difficult to give users on macOS a good experience when using Dolphin. While there are still some problems, OatmealDome, along with a few others, have taken up the mantle of maintaining and renovating macOS support in Dolphin. These past three months saw two significant steps forward for the OS.

Maybe someone should have checked that¶

Under macOS, our official minimum supported version is macOS 10.13 High Sierra. We do have a High Sierra system on hand for verification, however, after the recent move to the new Universal Builds, we never actually got around to trying those builds on the High Sierra machine. Intel machines were tested, of course, but never ones running older versions of macOS. Since Universal Binaries go all the way back to macOS 10.4.4 Tiger, we weren't worried about it.

Six months after the Universal Builds were introduced and two months after the Intel-only mac builder was turned off, we recieved an issue report of macOS failing to launch on a macOS 10.14 Mojave system. Well, there was only one way for us to respond. After digging through a shelf and wiping off some dust, the High Sierra system was retrieved and finally got to see the new Universal Builds. They didn't work. With great irritation our eyes immediately glared toward Qt, after all it was what forced us to a minimum of High Sierra in the first place, but Qt wasn't to blame. TellowKrinkle found that the Universal builder was set up with a new SDL version that had a minimum support of macOS 11, a year-old version of macOS. That's not acceptable at all! Fortunately, once this issue was discovered it was pretty simple to resolve, and now the latest builds of Dolphin run on High Sierra once again.

A 2012 MacBook Pro running 2022 Dolphin!
_{Almost ten years old now, this venerable laptop has spent its entire life serving Dolphin, from programming work initially to over five years writing Dolphin blogs, to now helping maintain the bounds of macOS support. It was even the sole macOS testing device for years. This MacBook has probably helped Dolphin more than any other single machine, and hopefully it will continue to do so for many more years to come.}

Notorious Notarizing¶

Our macOS builds have been signed for years and years, so Gatekeeper's slowly tightening jaws didn't matter to us. That was until macOS 10.14.5 turned on the notarization requirement. Signing your application was no longer enough, now macOS developers were expected to also send a copy of their builds to Apple to have Apple themselves scan it for malware and verify the signing key. We were not very enthusiastic about these strict new requirements. It clashed with our buildbot systems of the time and it would have been non-trivial to implement, so the maintainer chose to not to. Unfortunately for our users, that meant that Gatekeeper now treated our builds as if they weren't even signed.

So for the past two years, users could not simply double click to open new Dolphin builds. Gatekeeper would complain saying that it could not be sure that it was safe and refuse to let Dolphin load. To bypass this, users had to ctrl-click Dolphin and click Open, then click Open in the resulting prompt. Then Dolphin would open... or the prompt would disappear and require the user to double click on Dolphin manually. If anyone knows why it did that sometimes please let us know, that quirk made explaining this process to new users an absolute nightmare.

Every macOS Dolphin user has seen this screen A LOT.

Regardless of the problems of the past, OatmealDome sorted out most of the pain with notarization and the new Universal buildbot was painlessly updated to include it. Now the latest builds will run on macOS without all of those annoying popups and workarounds. Just double click Dolphin and it works, how novel!

Last Month's Contributors...¶

Special thanks to all of the contributors that incremented Dolphin from 5.0-15448 through to 5.0-15993!

Dolphin Progress Report: September and October 2021

2021-11-13T07:36:31+00:00

It's the beginning of the month and time for another Dolphin Progress Report! ...That line doesn't exactly work when it's midway through the month, huh? This Progress Report ended up being a very technically challenging report to write with several huge rabbit holes that go through the history of Dolphin and the games themselves. The first rabbit hole showcases TMEM, the GameCube and Wii's texture cache. Dolphin's approach to emulating this bit of the hardware has been to effectively ignore it exists. Trying to even begin to rectify the problems with this approach and explain the reasoning behind why it sort of wasn't emulated go very, very deep. This Progress Report also contains collaboration with the PCSX2 development team as they helped us understand some of the behaviors of Floating Point Math on the PlayStation 2. The fact that the PlayStation 2's floating point behaviors mattered to us for this Progress Report should tell you the kinds of things we were up against when writing up the changes.

If that wasn't enough, Dolphin also welcomed support for a wealth of mods through support for Riivolution. An easy to use GUI for launching Riivolution mods was added both to desktop Dolphin builds and Android. Speaking of Android, users may have noticed we pushed out an early beta last month. This beta was mostly to showcase and let users on the Play Store try out the newly finished Cheat GUI! We'll finally showcase that after a lengthy delay between when that extra beta was pushed and this Progress Report. While it's not related to Dolphin directly, Apple released the new M1 Max and we got our hands on one to see how it stacks up against the M1 with some rather interesting performance numbers at the end of the report.

With that out of the way, there's no point in delaying things any further. Please enjoy these rather lengthy Notable Changes!

Notable Changes¶

5.0-15178 - Android: Update GUI for Cheat Management and Creation by JosJuice¶

Dolphin has the ability to hook in various types of cheat codes and patches, so even though the Android version lacked the GUI for it, it has always had the ability to use cheat codes. For the past couple of years, enterprising Android users have gone through the trouble of setting up cheat codes by hand through text editors or using the Desktop version to create the settings files they wanted. Some forks of Dolphin even hooked a conventional text editor into the program to try and make editing cheats easier! But all of these stopgaps weren't actual solutions, they were working around the problem. Someone had to get down and dirty and make serious additions to the Android GUI if we were to ever have a permanent solution.

JosJuice has been dealing with Android issues for quite some time, and has become more familiar with the JNI (Java Native Interface) that powers the Android GUI. Much like how DolphinQt calls into Dolphin to handle things like enabling/disabling cheats and editing GUIs, JosJuice completely replicated Dolphin's Cheat interface without duplicating the core code within Android. This means all of the same features that you already enjoy on desktop related to enabling, disabling, and adding cheats are all there, and work exactly the same!

The cheats menu finally arrives in Android.

5.0-15438 - Android: Comply with Scoped Storage Requirements by JosJuice¶

The fated day has finally come. Nearly a year ago we expressed our frustrations with the upcoming Scoped Storage requirement in Android. Since then... not much has changed about our concerns, but JosJuice has done their best in order to make sure the experience of Dolphin on Android doesn't change much. The main difference is that Dolphin is now locked to using an app-specific directory for a majority of its user files on Android 11 and up.

Unlike some other emulators, Dolphin does not have the option to simply ask for permission to use other directories. For managing things like the Wii NAND and GameCube GCI folders, Dolphin is reliant on accessing tons of files in quick order. If access to those files is too slow, the user may see noticeable lag, or in dualcore games could even crash. When using directories other than the app-specific one, performance on accessing files is terrible, so much so that it would impact emulation in a negative manner. This doesn't apply to your games however, as when using most game formats in Dolphin, you're only accessing a single file. The main culprit in Scoped Storage performance issues is dealing with many smaller files.

Using the app-specific directory may not seem like a big deal, but there are some tricky things to keep in mind. First of all, you will have an incredibly difficult time trying to copy files into the app-specific directory with the default file manager on Android 11 and up. This is problematic as things like the Wii NAND and Texture Packs need to be in the app-specific directory. The good news is, if you have a PC, you can connect your phone and navigate to the new directory (Android/data/org.dolphinemu.dolphinemu/files/) the same as the old one on most devices. Some users have reported difficulties editing these folders on certain devices, but we've been unable to verify the reports to this point. While this may be a bit frustrating, our biggest fear with Scoped Storage was that, by default, uninstalling Dolphin would delete user files including save data. Thankfully, there is a work-around to that problem provided by Android called fragile userdata. Essentially, we mark the files in Dolphin's app-specific directory as fragile, so if you uninstall Dolphin to downgrade, bisect, or do something else where you would want to reinstall it later, Android will ask you if you want to keep the App's data files. This only works when uninstalling from Android itself; if you uninstall from the Play Store you will lose all of your data.

If you want to protect your savefiles and other user data when uninstalling Dolphin, make sure to *not* delete your user data!

There is one other exception we should note. Scoped Storage does not apply to you if you upgrade from an older version of Dolphin without ever uninstalling it. So if you download 5.0-15260, for example, and then just continually upgrade without ever uninstalling, then Scoped Storage won't come into effect for you until Google closes this loophole. Though going through that trouble shouldn't really be necessary as all of the known issues have already been quelled. Unless you specifically need things like custom directories for tons of Wii NANDs that cannot be within the app-specific data directory for some reason, you shouldn't see much of a difference if any with the latest builds.

For more information on if Scoped Storage affects you, please check Dolphin's Wiki.

5.0-15249 - Add broken dual source blending bug to MoltenVK on Intel GPUs by OatmealDome¶

MoltenVK was introduced to Dolphin 3 years ago, and it has since become the defacto backend for macOS users wanting to play games in Dolphin. However, it hasn't exactly been smooth sailing. In many games, such as Super Mario Galaxy, Sonic Colors, and the Paper Mario games, have considerable geometry flickering when MoltenVK is used on some Macs.

This got old pretty fast.

We assumed it was a MoltenVK bug and ignored it, thinking that it would be fixed eventually in a MoltenVK update. After the issue remained for three years, macOS and iOS veteran OatmealDome decided to look into this longstanding issue and sus out the source. It turns out it MoltenVK wasn't the issue at all, but Intel's macOS graphics drivers. On newer Macs with Intel Graphics, if ocol1 is present in the fragment shader and dual source blending is enabled, entire primitives will not be written to the depth buffer if any fragment is discarded. There's our flickering. Fortunately (or unfortunately), we have already experienced dual source blending issues on other drivers, so we already have a fallback path set up that only allows dual source blending when absolutely necessary. OatmealDome added Intel Graphics on macOS to the list and now the flickering is gone.

Now Mac owners with newer Intel Graphics finally can play games without flickering!

5.0-15294 - Extend Minimal TMEM Cache Implementation by phire¶

In the early years of Dolphin's life, developers were very limited in what they could do to emulate the GameCube and Wii. These consoles are quite different from PCs, and most of the tricks that today's computers can use to work around these differences simply didn't exist back then. So developers did whatever they had to, and usually that meant hacks, but sometimes that even meant not emulating something if that happened to work. Now that proper emulation is possible, for the past eight years Dolphin has been unraveling those knots, replacing hacks with better solutions as they come up. However, a lot of these old tricks still remain, especially in cases where they aren't a major source of issues and/or where the work required to replace them would be very high. And one of those such places is emulating the GameCube and Wii's texture cache - TMEM.

_SOURCE

Texture Memory (TMEM) is a 1MiB piece of super fast SRAM that lives within the consoles' GPU. Not large enough to hold a frame but much faster than going to Main Memory (10.4 GiB/s for TMEM vs 2.6 GiB/s to Main Memory), TMEM by default operates as a hardware-managed texture cache that is completely transparent to the game. In this hardware mode, TMEM sits inbetween Main Memory and the GPU and caches every 32 byte texture chunk it can, so if the GPU asks for a texture that happens to be in TMEM, TMEM will provide it instead of Main Memory and the GPU gets it much faster. There are limitations to this of course. While TMEM is HUGE for a texture cache of the period (the PS2's texture cache is 8KiB, for reference), it can still only hold so much, so texture chunks are constantly flowing in and out of the cache every frame. Also, the game can edit textures in Main Memory at any time and TMEM will never know. As such, TMEM is expecting games to explicitly order a TMEM invalidation in this event.

Dolphin ignored all of that. In fact, it ignored that the consoles even have a texture cache. Instead, Dolphin kind of replaced the TMEM's hardware mode with Dolphin's Texture Cache.

A Dolphin developer after hearing "Dolphin's Texture Cache".

Textures straight from the GameCube or Wii will not work on modern GPUs; Dolphin needs to convert them. This takes time and processing power, so Dolphin stores converted textures in a cache on the host GPU for a long time to make the most of this work. However, this cache would balloon to enormous scale if it isn't constantly pruned as even the tiniest variation is stored as a separate texture in the cache, so Dolphin has a horrifying cacophony of heuristics to guess what textures a game will or won't use every frame. It's terrifying, and no sane Dolphin developer will even go near it.

In Dolphin, it is Dolphin's Texture Cache, not TMEM, that is sitting inbetween the GPU and Main Memory. As such, Dolphin's Texture Cache should be respecting TMEM's behaviors to be accurate. It wasn't. Instead, every draw call Dolphin simply hashed all textures in Main Memory, and if the hash didn't match, Dolphin would invalidate the cached copy. That's it. This is what Dolphin does for every texture already, so Dolphin is more or less ignoring that the consoles have their own texture cache at all. Yet for the majority of Dolphin's catalog, this is fine. As TMEM's hardware-mode texture cache is transparent to the game anyway, Dolphin could just take the texture caching job and implement it in a way that worked best for Dolphin, and everything just worked. Mostly.

Four years ago phire discovered one of the limitations of this strategy. Spyro: A Hero's Tail has a highly complex SDR bloom effect which uses 16 EFB copies to build, where it reads the screen then blurs and brightens multiple copies of what it read before stacking them all on top of eachother for scanout to the screen. As it is manipulating textures in Main Memory, the game dutifully invalidates TMEM along the way - except for one step.

In one of the stages of the process, A Hero's Tail orders the GPU to scale a texture from Main Memory up to twice the size. While performing this operation the GPU reads the texture in Main Memory, and TMEM automatically caches it. Then the game EFB copies the 2x version over the original copy in Main Memory while explicitly NOT invalidating the cached version in TMEM. The game then reads from the 1x original in TMEM to generate another texture which it writes elsewhere in Main Memory, then invalidates TMEM. This is a bit of an abuse of the GameCube hardware to help build a complex effect. Dolphin, however, couldn't do this. Dolphin's "emulation" of hardware-mode TMEM and Dolphin's Texture Cache for converted textures in Main Memory are one and the same; it ignored that the consoles have a seperate cache that may have different contents than Main Memory. If something was changed in Main Memory, the version in Dolphin's Texture Cache was automatically changed too. So in Dolphin, when Spyro overwrote the texture in Main Memory with the 2x version, Dolphin did just that, but there was no other cache that still contained the 1x version. When the game tried to read the 1x size version from TMEM, Dolphin's Texture Cache gave it the 2x version instead, breaking the bloom effect.

Store EFB Copies to Texture Only resulted in bloom haphazardly dragging across the screen.

Store EFB Copies to Texture and RAM resulted in bloom nonsensically flickering anywhere it felt like it.

phire, as later cleaned up by mimimi, dealt with this by adding a backdoor that allows Dolphin to bypass the hash check if a heuristic determines it is safe to do so. With this, some changes to cached textures are allowed to occur without invalidating the cached copy as long as the texture was the same size, the same address, and no explicitly requested TMEM invalidation took place. Since Spyro: A Hero's Tail's bloom fell within that criteria, Dolphin now keeps both the 1x version of the texture and the 2x version of the texture in Dolphin's Texture Cache, allowing the bloom effect to be built correctly.

Bloom now works in EFB Copies to Texture+RAM, and works with EFB Copies to Texture Only as long as you aren't underwater. That's a different bug.

This isn't proper hardware-mode TMEM emulation, not even by a longshot. Dolphin's wildly different texture caching approach is still there - the patch essentially added a dirty heuristic to “do the right thing” in an edge case. But this was still an important step toward accurate emulation, as it broke Dolphin’s longstanding assumption that textures were always fetched directly from Main Memory and introduced basic awareness of TMEM.

However, there is a reason why no one wants to touch Dolphin's Texture Cache. After this change, a slow trickle of regressions started to flow.

Uh oh.

The common thread through most of these games is FMVs. Their videos would become stuck, only playing audio. While the games themselves didn't freeze, this regression made it frustrating to play certain games or impossible in the case of NHL Slapshot.

Imagine a bunch of music and sound effects playing behind this for a few minutes.

So what are these FMV games doing differently from other games with FMVs? Normally, games will store many frames in a buffer in Main Memory, streaming a frame at a time as it goes through the buffer. Once it reaches the end of the buffer, it loops around to the beginning where new frames are waiting. That method of FMV streaming still worked fine after the heuristic was added. But the games above (minus NHL Slapshot) share a common FMV library that, in a curious choice, has a buffer in Main Memory of one frame. To the GameCube and Wii's GPU it appears that the same texture is being reused over and over again, because technically it is; the texture is just being updated outside of the GPU's awareness. However, it is hardware-mode TMEM's job to cache textures that are used repeatedly, and it does indeed cache this texture. If TMEM delivered that cached frame, the FMV would become stuck just like Dolphin did after adding the heuristic. However, each frame is too large to fit into TMEM. Once TMEM is full, it just keeps caching, replacing the first parts of the texture with new parts. After the draw call is complete and the GPU asks for the frame again, TMEM notices that it doesn't contain the first parts of the texture, so TMEM lets the GPU get it from Main Memory instead. The FMV library doesn't even need to worry about explicitly invalidating TMEM, as the size limitation naturally invalidates it and prevents the cached frames from appearing on screen.

Dolphin's Texture Cache, however, didn't care at all about hardware-mode TMEM or the fact that it has limited space. It cached the entire texture, and when the GPU called for it again, Dolphin's Texture Cache provided it. And over and over it goes, displaying the first frame of the FMV over and over again until the FMV is done. Before the addition of the heuristic, Dolphin was so simple it managed to escape this trap. The hash check caught the changing contents of the texture in Main Memory and coincidentally followed the pattern the game expected by invalidating the cache texture after the frame was changed. But the heuristic determined (correctly) that the same texture was being reused and bypassed that hash check, allowing it to be cached and breaking the FMVs.

To fix this, Dolphin was going to need to start caring about what fits into TMEM. phire returned to do just that, with an expanded version of their original work that make's Dolphin's hardware-mode TMEM emulation able to keep track of the contents of TMEM and whether or not an incoming texture is too large for it. This allows Dolphin's TMEM hash bypassing heuristic to be much better at estimating whether or not an invalidation is necessary, and brings Dolphin a little bit closer to actual hardware-mode TMEM emulation.

Now we can see the FMVs in their full motion-captured glory once again.

The odd one out for this whole case is NHL Slapshot. It's bug is not related to FMVs at all, instead, it has columns of static graphics during gameplay. We're not completely sure what's going on with this one. We know it is also not respecting the TMEM invalidation rules, and that it is continuously reusing a texture like the FMVs did, presumably for some sort of post-processing effect. But it was fixed before we got the chance to look into it in detail.

This is not playable.

Now the players are much more visible.

Of course, this is still yet another patch for our not-emulation of TMEM. Rather than actually emulating TMEM so quirks in its behaviors just occur naturally, we're manually accounting for those quirks and stepping in to force it to work. This approach is fixing games, but it is a very unsatisfying solution that is definitely not ideal. It is phire's intention to eventually remake this whole system and genuinely emulate TMEM. It won't be easy, but it is possible with modern APIs. phire promises it will be done within this century, so we wait with bated breath.

5.0-15330 - Raise Program Exceptions On Floating Point Exceptions by JosJuice¶

True Crime: New York City has shown up on the Dolphin Progress Report a couple of times now. It's been laughed at for being an incredibly buggy, broken game, that was a stress test for Dolphin's memory management due to how much it swapped data and code between MEM1 and ARAM. But there was another intriguing thing about the game: the game would instantly crash in Dolphin when standing on any kind of dynamic object and no one knew why. This was the primary reason why people within the project knew the game existed, and over the course of seven years, developers spent hundreds of hours debugging the issue. Just glancing at it, we thought it was a typical bad game, but the more we were able to play it the more we realized just how wrong we were.

From the outside, the issue plaguing Dolphin seemed to be simple enough. The game ran fine, but any time your character contacted a physics object, the game would freak out and send you out of bounds. Because of a separate JIT bug, Dolphin would then crash. This isn't especially surprising to see in an emulator, as improperly emulating a CPU instruction can result in the wrong values being passed and eventually result in strange clipping issues or other problems that compound into the catastrophic failure you see here. For the longest time, we thought there was a bug somewhere in Dolphin's CPU emulation but we didn't have many leads. Thankfully, the game actually has a (semi) functional debug menu that let us examine the actual positional coordinates of the player during the crash!

Pause, go to the map screen. Hit right, then Hold L and R as it transitions and then tap left to access the debug menu.
_{Click to play. Click here for fullsize.}

Unknown issues to developers are like a lamp is to mosquitos. The fact that no one knew what was going wrong just made it all the more enticing to fix! booto literally followed a bad NaN (Not a Number) value backwards through tons of functions before eventually finding an operation on an INF (Infinite) that came from a divide by zero, but even then it didn't seem like Dolphin was doing anything wrong. As far as everyone could tell, Dolphin was behaving correctly. By the time 2020 rolled around, developers started to realize this was anything but an ordinary game. Rather, it had a special quality about it. At first developers lashed out against it, calling it garbage game that was poorly coded. And why wouldn't they? The game is super buggy and barely functional on console. In fact, the game will crash if you try to debug it with a USB Gecko, meaning that we couldn't even test to see what was happening in memory on console. All seemed lost... when something amazing happened.

smurf3tte, after having felled several other difficult problem games, decided that True Crime: New York City was worth a look. From there, they realized a rather sickening truth: The fact that the physics engine was dividing by zero wasn't a bug in Dolphin. It was all part of the game's plan. On Dolphin, these DIV0s would result in INFs, which then would become NaNs when used in other math operations that would result in the crashes. Until this point, we thought the way to fix the NaNs would be to stop the DIV0s, but smurf3tte realized that the game itself was using a custom Floating Point Exception handler to catch DIV0 exceptions and stop the INFs/NaNs from happening. Throughout the entire GameCube/Wii library, no one had run into anything like this so there was some skepticism that this was really happening, but the evidence was pretty strong.

Rather than investing a ton of time modifying Dolphin to support a custom Floating Point Exception handler without even knowing if the hypothesis was correct, smurf3tte instead hacked up the JIT to replicate what the Floating Point Exception Handler in True Crime: New York City would have done. Paydirt. This hacked up build unlocked Pandora's Box and could finally emulate True Crime: New York City. It wasn't a "real" solution, but for the first time we could examine the game and how it worked. Now the mystery became why. Why in the world was the game doing this? To do that, we had to dive into the game's history and collaborate with emulator devs from across the land.

The GameCube version of True Crime: New York City is something else sometimes...

The latter half of the sixth gen of consoles was the era of the "Grand Theft Auto Clone". After the success of Grand Theft Auto III, everyone wanted to get a piece of the action. True Crime: Streets of LA was a surprise hit and one of the more well-liked GTA clones of the era. It was successful enough to spawn a sequel, which leads us to True Crime: New York City. With a bigger budget and a taste of success, they set out to make an absolutely massive game with a huge scope. It's easy to point and laugh at it now, but looking back it was clear that the developers were trying to make a special product, even if the final game didn't turn out well. Something as simple as driving down the streets is rather impressive as you can use a real map of New York City instead of the in-game map and actually get around!

You can navigate the game reasonably well using directions from GPS providers.

This is the same spot in-game on Google Maps.

For a sixth generation open world game, the map is absolutely huge and densely packed with detail. The world isn't static either; as you clean up New York City, both the exteriors and interiors of buildings will change depending on what you do. If you're a bad cop ignoring crimes and just chasing your own goals, buildings get vandalized, windows are shattered, and stores across the city close down. On the other hand, being a good cop makes the place look nicer. Plants are watered, interiors clean up, and there are even nicer cars on the streets. This even spills into gameplay, as cleaner parts of the city have stores stay open later, which gives you more time to buy health items, weapons, and other upgrades during critical missions.

The story itself also had a lot of potential, with a lot of big name voice actors, branching missions where you can fail them and have to find a new lead, and tons of side activities that you'd expect in an open world game, including dynamically generated crimes. When we first started looking into True Crime: New York City, we thought it was just a case of incompetent developers making a bad game, but everything we saw while playing it made us realize that this wasn't the case. The people behind this game obviously cared about the product and put a ton of thought into the mechanics to really make the world breathe. Unfortunately, development constraints like budget and time cut out massive parts of the game, limited testing, and rushed the game out the door in an obviously unfinished state. And this is just referring to the original PS2 version. The ports weren't quite as lucky.

It... took me 15 years to realize True Crime: New York City has broken engine sounds on PC. Compare this to Xbox gameplay, where engine revs actually do change 😖https://www.youtube.com/watch?v=Gd5atcKpGBY&t=65s
— Silent (@__silent_) August 29, 2021

The PC version is... special. Framerate is inconsistent, sounds are broken/missing, and playing the game on a modern computer is an exercise in futility. The Xbox version looks competent on the surface, but the developers accidentally pushed the wrong build of the game into production according to what we know. The build they pushed has extra AI pathing issues, physics issues, and a mid-boss where the throw mechanic is broken, instead requiring frame perfect inputs or else you'll be softlocked. But none of these other versions can prepare you for the atrocity that is the GameCube version of the game. After playing the game for a few weeks, we've found so many issues with it that Dolphin's Wiki Entry on the game contains a list of bugs for users not to report because they are confirmed to happen on console. While the other three versions of the game look relatively close at a glance, the GameCube version is missing tons of effects and textures and looks like a plastic toy in comparison.

Dolphin can only do so much for the GameCube version. It's lacks many of the game's special effects, has much worse shading, and the texture resolution is abysmal.

On PCSX2, emulating this game currently requires the software renderer, which means it only renders at native resolution. However, the superior texture quality and shading are immediately evident.

While both the Xbox and GameCube version were ported by Exakt Entertainment, it appears that the GameCube version got far less effort overall. Lighting and shading has been simplified resulting in a flatter looking world, especially during daytime scenes. A lot of other effects are missing completely, such as water physics in flooded basements. Perhaps because the GameCube used mini-DVDs, even texture quality has seen a massive downgrade, with some textures removed and everything being blurrier overall. They even broke the Main Menu, which is just a black screen with text on the GameCube version while the other versions have the Main Menu running on top of the backdrop of the city.

If all of these downgrades meant the GameCube version ran better, maybe it would be forgivable, right? If so, they were really struggling as the game runs a silky smooth 12 to 20 FPS while driving around the city on console. If you have a powerful PC and turn up the emulated CPU clock rate to ~170%, you can get a stable 30 FPS when emulating it. This is the one saving grace of running the game in Dolphin, as it makes driving around the city much more pleasant than it could ever be on console. Even then, the port still sucks and we haven't even gotten to the actually problematic part of the port: the physics engine!

As we said above, the physics engine is flooded with NaNs when playing the game on Dolphin. The reason why is because the PlayStation 2 supports extended floats. Rather than doing things how most other processors, such as PowerPC, x86-64, AArch64, etc. handle things, the PS2 decided that it would be faster to throw away all of that pesky error checking and special casing when handling floating point math. With the help of developers that work on the PlayStation 2 emulator, PCSX2, we started to learn about just how devious that console was when it came to Floating Point Math.

GameCube: 
1/0 = INF
sqrt (-4) = NaN 
INF - 1000 = INF  
INF/INF OR INF - INF = NaN

PlayStation 2: 
1/0 = Greatest Positive Float Number (0x7ffffffff) 
sqrt (-4) = sqrt(abs(-4)) = 2
7fffffff - 1000 = 7fffefff
7fffffff/7fffefff = 1

Essentially, the PlayStation 2 doesn't really have INF or NaN. One of the reasons that our friends working on PCSX2 have so much trouble emulating Floating Point Math on modern computers is because it's just not possible to emulate it quickly and correctly at the same time. We asked for a quote regarding their thoughts on Floating Point Math on the PS2, unfortunately due to the mostly worksafe nature of the Dolphin Progress Report, we didn't see it fit to broadcast such harsh language and we do not approve of insulting one's mother, even if it is the mother of a mathematical concept.

The important part to note about this is that True Crime: New York City divides by zero a lot. As in, every single time you step on a dynamic object, these divide by zeroes flood the physics engine to the point where we had to assume there was something wrong with Dolphin's emulation of a CPU instruction. We never actually considered that the game engine was doing all of this on purpose... yet, we now know that is indeed the case. It is likely Exakt Entertainment didn't have the time nor budget to rewrite and fix up the physics engine to get rid of the INFs. So their solution was to let the game divide by zero, raise an exception to be handled by their custom floating point exception handler, and change the INF to zero. This left us in the awkward position of needing to implement support for Floating Point Exception Handling, something that the developers who designed Dolphin's JIT never expected to need.

Where is the person I'm supposed to arrest?

Oh.

With us finally able to understand what was going wrong, the hard part of solving the problem was over. Now all developers had to do was add support for custom floating point exception handlers. The easiest way to do this was to add support to Dolphin's CPU interpreter, and then modify the JIT instructions so that they fallback to the interpreter when FPE handlers are enabled. And that's exactly what we did. The only downside is that there is a performance penalty to using the interpreter for these instructions, but it ended up not being a big deal.

By default, Floating Point Exception Handling is disabled. It was important that we don't let this change impact performance across the library just to support one really weird game. Then there are two settings for enabled Floating Point Exception Handling, with one of which being used for two games in their INI settings. The first is to enable Floating Point Exception Handling for DIV0 (Divide By Zero) exceptions. This allows Dolphin to emulate True Crime: New York City and another game ported by Exakt Entertainment, Call of Duty: Finest Hour, both of which rely on catching DIV0 exceptions to prevent game issues. However, that isn't correct emulation, so there is a second option that allows you to enable Full Floating Point Exception Support. This option is incredibly slow but allows Dolphin to accurately emulate console behavior when dealing with Floating Point Exceptions, even when the game is using a custom handler. This more or less exists for people working on homebrew or if we run into any unknown problems in the future that maybe would need full accuracy in this department.

Note, the original hack by Smurf3tte didn't have much of a performance penalty, but it also wasn't a real solution. Adding a bunch of code to the JIT to support just True Crime: New York City, not even Call of Duty: Finest Hour, just isn't reasonable. Even with the interpreter solution we chose, both games run full speed on modern computers, and the DIV0 fallbacks don't cost very much performance.

There's a cut second island in the game. It's still there and somewhat functional, but the bridges to it have no collision. Except for one. Clip through an invisible wall and take a very long walk and you can reach the cut island. Note that most areas of the island count as out of bounds and will kick you back to the mainland, so be careful where you walk!

Warning¶

The following is a bit of an odd request, but we at the Dolphin team highly recommend that casual users do not play True Crime: New York City in Dolphin or on GameCube/Wii at all. Period. The GameCube version has tons of serious problems, including reports that it could outright corrupt your memory card and cause you to lose all of your savedata. While we never saw anything that corrupted our memory card, we did have one instance where True Crime: New York City just stopped saving until we restarted the game and all of our previous savefiles were missing. Thankfully, with the power of hexediting we were able to fix the savefiles, but any game that has a bug like that should be considered risky to play. We did play through the game on console as well, but unfortunately we were unable to trigger any of the memory card issues there, so we cannot confirm the type of memory card corruption that happened on console that players reported back when the game released.

Even ignoring that risk, this is the type of game where it's common for enemies that you need to kill to just spawn out of bounds where you can't reach them unless you know how to get out of bounds yourself. Sometimes, you can't even use glitches to fix your situation as loading zones might just stop working. And there are the typical problems of random crashes, physics issues with both driving and walking around the city, and you're better off just not unlocking the special driving techniques. Hell, even the controls are broken on the GameCube version as they mapped the horn to the same button as change song and there's no way to remap your buttons! The controls suck on GameCube overall because they ran out of buttons for other things so you have to do a lot of two button combos for actions that just use one button on the other systems. It's a game that fights you the whole way.

(Mostly) muted glitch showcase showing off some of the oddities of this game.

Is it possible to beat True Crime: New York City in Dolphin? Yes. One brave developer 100%ed the game in Dolphin, unlocked both endings, and beat the bonus mission. At some point it was less about completionism and more about proving it was even possible given some of the issues in the game, including the fact that one segment of the city will usually crash on the GameCube version. If you have fond memories of this game, you're probably remembering the superior PS2 version, which is buggy in some pretty funny ways while still being playable. Again, if you want to play this game, the PS2 version of the game is cheaper to buy, compatible with PCSX2 and is a much better game in almost every way. There's no reason to go out of your way to play the GameCube version...

Unless.

If you're looking to experience one of the most bizarre, buggy, and nonsensically broken GameCube releases, True Crime: New York City is the closest thing we have to a Sonic 06 level of trainwreck. Throughout testing, every time we played it we discovered new oddities, crashes, and just plain weird behaviors. The sad thing is that the game isn't all that bad when it is working, it's obvious that the developers were trying to build something so much better than what they made. If you have a powerful enough PC to run the game at a healthy emulated CPU overclock, the game can be fun at times. Just remember, we warned you of the risks.

Do not do this.

5.0-15407 - HLE Riivolution Patch Support by AdmiralCurtiss¶

The Riivolution patching infrastructure is one of the most popular ways to create large scale game mods for the Wii. By taking advantage of complex IOS patches provided by the Riivolution homebrew launcher, mod developers can redirect disc reads to the SD card, making it easy to develop and distribute mods. For users, it was also simple as there was no extra patching process, and the fact that you could play the mods using genuine game discs made it feel safer for purists.

This format is essentially the standard for a lot of different mods, and Dolphin users have been asking about support for years. Unfortunately, the situation was rather murky. There were methods to convert Riivolution mods to a pre-patched ISO, but this was rather tricky and most mods didn't provide instructions nor did they want users to use the mod that way. Supporting it accurately isn't really an option: supporting cIOS mods requires Low Level Emulation of the Starlet Coprocessor, and Dolphin isn't even close to that. This would also bring a rather hefty performance penalty to users trying to run these mods.

AdmiralCurtiss noticed that there was another option. Riivolution's mod format isn't all that complicated, and could be recreated without the need for cIOSes rather easily. Instead of trying to emulate it, he decided to go the same direction as Dolphin's IOS emulation and directly reimplement the functionality in Dolphin. Thus, he began work on supporting Riivolution mods and making playing them in Dolphin as simple as it is on console.

Riivolution Support in Dolphin¶

Dolphin's Riivolution support uses the same Riivolution mods you download for console and works similarly overall, just with a splash of HLE to implement some cIOS functionality. All users need to do is extract the Riivolution mod to the correct directory (On Windows by default - Documents\Dolphin Emulator\Load\Riivolution) just like you would on a Wii. Because this is handled through High Level Emulation, there's no need to mess with Dolphin's virtual SD card or anything like that, putting it in the folder is good enough. Then, simply right click the game in the gamelist and click Start with Riivolution Patches. Enable the one you want and launch and you're ready to go. Eventually, we plan to add support for being able to boot Riivolution mods directly from the gamelist and on netplay once a few more issues are ironed out.

Monster Hunter Tri has Riivolution mods to re-enable Online Play via various backup server options...

And you can add new quests to the game for added difficulty and rewards!

AdmiralCurtiss also implemented a lot of niceties to make sure that playing Riivolution games is robust and simple. Pretty much any game mod should work, and savegame redirects are supported if you want to have different saves between Riivolution mods and the base game. Not everything works however. Advanced features such as RiiFS and the such are not currently implemented in Dolphin. As well, Dolphin's disc read timings are currently disabled when playing Riivolution mods. This is because Dolphin is not currently able to differentiate which files are located on the virtual SD card and which files are on the disc. A game might expect to be able to jump between a lot of different files on the SD card quickly, but if Dolphin were to apply disc seek timings to the reads, it would cause a huge slowdown and maybe even break the game.

To this point, it may seem like the choice of HLE only comes with downsides outside of performance and ease of implementation. However, there's one rather interesting benefit as well. On console, because Riivolution relies on IOS patching, it can only be used in Wii mode on Wii games. Dolphin's Riivolution support does not have this limitation. It is possible to create Riivolution mods for GameCube games in the same manner as Wii games and run them directly in Dolphin. You don't need to worry about complicated patching instructions that users will stumble over or potentially running amiss of copyright holders by trying to distribute pre-patched files. Combined with features like CPU Clockrate Override and Extended MEM1, there are a lot of possibilities for powerful GameCube mods using an infrastructure that modders are have been using for years. We've already seen some modders embrace this feature with Shadow the Hedgehog 2p working directly in GC Riivolution in Dolphin.

Shadow the Hedgehog has a very dedicated fan community and a myriad of game mods.

As one final note, Riivolution patches are not supported on WiiWare titles, as they do not use disc reads.

Riivolution Support and Android¶

A lot of times, new features sometimes lag behind in the Android version because of GUI issues. Thankfully, Android users won't have to wait for Riivolution support. JosJuice jumped on porting over the Riivolution launching/loading interface so that you can run your favorite Riivolution mods on your preferred mobile device.

A GUI for configuring and activating Riivolution Mods was also added to Android.

Launching Newer Super Mario Bros. Wii has never been easier.

Macsimum¶

A new machine has entered the Dolphin family - a 14in MacBook Pro with an M1 Max. Naturally, we promptly ran it through the same benchmarks we put the M1 MacBook Air through in our prior tests. How did it fare?

Some of you may view the above and be surprised. Sure it's better but the M1 Max is not trouncing the original M1 - it's only a notch above. That's simply because of Dolphin's workload. The M1 Pro and M1 Max have more multithreaded CPU power thanks to many more performance cores, but those are the exact same performance cores that are in the M1, running at the exact same clockspeed. As an application that depends on single thread CPU performance, the CPU power available to Dolphin is basically the same for both SoCs and the performance is similar. The improvements we're seeing here are from removing every bottleneck that constrained the M1, thanks to the M1 Max's cache, memory bandwidth, and significant GPU improvements.

What isn't shown on that chart is the absolutely monsterous GPU the M1 Max delivers. Native res for the display (5x native for the 14in) is trivial, and many games can run fullspeed at 8k (12x native) in our tests. The original M1 choked on 4x native, hence picking 3x for the original testing.

This is a 17x native (10880x8160) screenshot. It was recorded while running at fullspeed on a laptop.
_{Click HERE for the full 10880x8160 image. It may crash your browser.}

Now that we have direct access to M1 hardware, we took the opportunity to revisit our framepacing tests that previously revealed framepacing issues on Macs with Intel graphics, and confirmed that it is not an issue on M1. Macs with Intel graphics STILL suffer from this problem. For you are not familiar with frame timing and frame pacing, we briefly explained it previously.

Both Macs are able to handle this test at faster than full speed, but on Intel there is constant stutter. The M1 Max performs excellently, with only one drop in ~12,000 frames.
_{Click/tap the image for detail.}

Expect to see more of this MacBook Pro in tests going forward.

Last Month's Contributors...¶

Special thanks to all of the contributors that incremented Dolphin from 5.0-15107 through to 5.0-15445!

dolphin-emu.org - Last entries

Dolphin Progress Report: Release 2407 and 2409

Google Play Update Delay¶

Visual Studio Twenty-Twenty-Woes¶

Notable Changes¶

5.0-21462 - Windows: Remove rounded corners on emulation render window by Filoppi¶

Balloon Tooltip Quality of Life Updates - 5.0-21123, 5.0-21635, and 2407-130 by Dentomologist¶

2407-103 - Cached Interpreter 2.0 by mitaclaw¶

2407-165 - macOS: Embed the Updater into DolphinQt's app bundle by OatmealDome¶

Zelda HLE Pikmin Fixes - 2407-177 and 2407-225 by flacs¶

2407-228 - VideoCommon: Force Display List Alignment by flacs¶

2407-236 - Android: Fix and enable input device sensor input by JosJuice¶

Last Month's Contributors...¶

The First Month of Dolphin RetroAchievements¶

General Statistics¶

Top Ten Games with the Most Players¶

Top Ten Most Mastered Games¶

Top Ten Most Beaten Games¶

Unlocked: RetroAchievements Come to Dolphin

RetroAchievements Dolphin Launch Announcement!¶

Activating RetroAchievements¶

Achievement Lifestyle¶

Finding the Right Challenge¶

Old School Mentality¶

A Cooperative Experience¶

Multi-Sets¶

Achievement Unlocked - Marrying Two Massive Projects¶

Wait! What about Wii?¶

Congratulations - You've Mastered This Article¶

Dolphin Releases Announcement

Announcement¶

A New Look!¶

But why not 6.0?¶

Credits¶

Dolphin Progress Report Tenth Anniversary Special: February, March, and April 2024

Surprise!¶

Notable Changes¶

5.0-21264 - Core: Fix IPL device m_cursor overflow by JosJuice¶

5.0-21145 - Improve window presentation at native resolution by Filoppi¶

5.0-21162 - BranchWatchDialog: A Total Replacement for CodeDiffDialog by mitaclaw¶

5.0-21164 - Corrected Custom Aspect Ratio by Filoppi¶

5.0-21194 - Implement IR passthrough for Emulated Wii Remotes by AdmiralCurtiss¶

Features¶

Game Specific¶

Limitations¶

HDR Enhancements: 5.0-19931 - Add AutoHDR post process shader by Filoppi and 5.0-21232 - Add HDR to Metal + Perceptual HDR by samb¶

HDR Block¶

5.0-21253 - Implement Modem Adapter by fuzziqersoftware¶

5.0-21345 - JitCache: Software Profiling Restoration by mitaclaw¶

Last Month's Contributors...¶

Social Media Update¶

Why Dolphin Isn’t Coming to the iOS App Store¶

Dolphin Progress Report: November and December 2023, January 2024

Notable Changes¶

5.0-20353 - DSPHLE: Support 2023 libaesnd uCode by Pokechu22¶

5.0-20880 - Zelda-HLE: Fix Reverb Volume Factor by flacs¶

5.0-20517 - Implement Send Mail by Sketch¶

5.0-20589 - Rewrite LazyMemoryRegion by AdmiralCurtiss¶

5.0-20745 - Disable Arbitrary Mipmap Detection by Default by iwubcode¶

5.0-20785 - Support Custom Aspect Ratios by Filoppi¶

5.0-20849 - VideoCommon: Apply "Force 24-bit Color" to EFB Copies by flacs¶

5.0-20923 - Steam Deck: Pad out feature report to 64 bytes by endrift and ArcaneNibble¶

5.0-20941 - SDL: Add GameController API, cleanup by SuperSamus¶

5.0-20961 - Only initialize Bounding Box if supported by GPU/driver by AdmiralCurtiss¶

Notice for Nvidia Users¶

Last Month's Contributors...¶

Dolphin Progress Report: August, September, and October 2023

Notable Changes¶

5.0-19886 - Add Custom Dark Style for Windows by AdmiralCurtiss¶

5.0-19939 - Implement Output Resampling (Upscaling/Downscaling) by Filoppi and samb¶

What is Output Resampling?¶

What are the resample options?¶

When is Output Resampling Better than Existing Solutions?¶

EFB Copy Brute Forcing¶

Upsampling to a Close Resolution¶

Downsampling on Platforms where SSAA is Unviable¶

5.0-20193 - Expose Resolutions Multipliers Up to 12x (~8k) by Filoppi¶

5.0-20199 - Use LZ4 for SaveState Compression/Decompression by Malleo¶

5.0-19415 and 5.0-20126 - Improve JIT Block Lookup Performance by krnlyng¶

5.0-20201 - Increase FarCode/NearCode Cache Sizes by dreamsyntax¶