As seems to be happening annually, due to a short summer lull, we decided to combine the June and July Progress Reports. As you may have noticed, we're a few days into August at this point and things ended up running a bit late. That's actually a consequence of how we do these Progress Reports - we sometimes will go through big changes, test them, and get developer input on how they work in order to better explain them. In late July, a mixture of late changes, unexpected behaviors, and an extremely subtle game bug forced us to delay things while we sorted everything out. In this case, the end result didn't actually affect Dolphin, but does make for a better read as everything finally came full circle.

While we apologize for things being late, we do have a rather wide variety of changes that hit over the last two months to make this Progress Report extremely well-rounded. Whether you're looking for GUI updates, Android, fixes to ancient bugs, and even one feature inspired by a developer who saw Dolphin being used during Summer Game's Done Quick!

Notable Changes¶

5.0-10558 - Allow Gecko/Action Replay Code Reordering by Spycrab¶

On the surface, displaying a list of Action Replay or Gecko codes may seem like a no-brainer. That's what we thought, too, but we quickly learned from a prior attempt at cleaning up the menu made things much more frustrating to some of the users that relied most on these features! It got to the point where one of them opened a pull request to revert the automatic ordering.

Once we thought about it, their complaint made perfect sense. Dolphin was listing the codes just as they appeared in the user's INI file. A lot of users would just stack important codes to the top of the list, and thus be able to find them at the top of the list in Dolphin. The prior reordering change automatically listed codes in alphabetical order, meaning that users with lots of codes could no longer stash their favorites at the top. More frustratingly, reverting it then annoyed users who did want the alphabetical ordering for searching through downloaded codes!

Dolphin is a general purpose GameCube and Wii emulator, and it has to cater to a very wide variety of users. We wanted to make the cheat listings easier to use for both casual users and our power users. Spycrab finally took up the task and added two new features to Dolphin's Action Replay and Gecko Code pages. First of all, if you preferred alphabetical ordering, you can now right click the list and have Dolphin do that. If you're a power user that doesn't want alphabetical ordering, you aren't forced to use it this time around.

As a bit of an added bonus for our power users, you no longer have to trudge around into the INI files to use custom reordering either. Simply drag and drop cheats right in the window to move them up and down. This should make getting codes in the exact order that you want much easier. You can even combine these features by sorting alphabetically first and then dragging your favorites to the top of the list!

This time around, we're hoping that we didn't inadvertently make things harder on our users, and we hope to continue improving the user experience moving forward.

5.0-10578 - Fix Cropping Aspect Ratios... Again by techjar¶

One of the dirty secrets of the GameCube/Wii is that they don't output perfect 4:3 or 16:9 in most games. In Dolphin, we favor showing everything the game renders without distortion while placing small black bars as padding where appropriate. For users who dislike these black bars, the Crop option will fill the screen without distorting the image, though a small amount of the game's rendered area will be off screen. It's not much different than treating the edges like the garbage area on a television.

If this feels like deja vu, that's because we've broken cropping a couple of times in recent history. This time around, a rewrite inadvertently made it so Dolphin was stretching the screen instead of chopping off part of the garbage area. Thankfully, techjar caught on and quickly fixed the minor code issue to restore its behavior back to normal.

This is Mario Galaxy cropped correctly. Click/Tap and hold to see the distorted version before the fix.

While the distortion may seem rather slight, it is a visual flaw and users have caught onto it every time we've broken the crop feature. To some, stretched output is worse than most other visual issues! As such, we're more than happy to have crop working once again... for now.

5.0-10625 - TextureCache: Support Reinterpreting Formats for VRAM Textures by Stenzek¶

Misinterpreting a bug can be among the most dangerous and damaging mistakes that can be made when debugging an issue. Sometimes, such as in the case of The Simpsons Game, because it behaved so close to some other issues, it ended up lumped in with them. The graphical bugs plaguing the game were considered to be unfixable without changes to Dolphin that would make emulation significantly slower. This demotivated developers from looking into it further and what was known was documented in an issue report.

Spider-Man Shattered Dimensions had no such reputation, so when iwubcode turned up in chat asking about severe graphical issues throughout the tutorial, it warranted some investigation. One of the bigger differences to debugging it now versus 8 years ago is that Dolphin has much better overall emulation and a lot more options for debugging. Long time readers of the Progress Report may know that we have a powerful third mode for EFB copies, called Disable EFB Copies to VRAM. This is the slower option and completely disables high resolution output because it forces all EFB copies to be the emulated RAM version. While most users probably wouldn't want to use this feature, it can sometimes be useful as a sanity check for Dolphin's other EFB copy emulation paths. Just as it caught rendering issues with Metroid Prime 3's bloom months ago, it again ended up key in debugging.

Neither path is actually correct in these image, but the fact that Disable EFB Copies to VRAM showed such drastic differences led developers to believe that the game's issue stemmed from how Dolphin was handling EFB copies. Stenzek spent a few hours looking at fifologs and investigating the situation slowly making his way through how the game rendered. He found not one, but two bugs. Fittingly, one was in the Store EFB Copies to Texture path, and the other was in the Store EFB Copies to RAM path.

The main problem that users were running into stemmed from the fact that Spider-Man Shattered Dimensions was creating a texture in one format and then sampling it as another to create a post processing effect. Because the CPU wasn't modifying this texture, this would always take the Store EFB Copies to Texture path... unless you used Disable EFB Copies to VRAM, as we did during debugging.

The bug on the Store EFB Copies to RAM path was a simple mixup of color channels. Namely, Dolphin was interpreting CC8 textures as RG8 textures as Red Green when they were actually Green Red. Same for GB8 textures, which were being encoded as Green Blue when they were actually Blue Green. The other flaw was actually a bit more complicated, as Stenzek had to implement sampling textures in different format so long as they had the same number of bits per texel. The original texture was encoded with 8 bits for R, G, B, and A. Spiderman was actually changing it to 4 bits of red/intensity and 4 bits of alpha, where as Dolphin was just treating it as 8 bits of red. Stenzek added additional functionality to the Store EFB Copies to Texture path in order to not incorrectly truncate textures.

Once Stenzek submitted the change, Dolphin's FIFOCI infrastructure automatically ran his changes against tons of fifologs captured from a variety of games that have had problematic rendering in the past. As you've probably guessed, we have a fifolog from The Simpsons Game as one of the unsolved issues being tested against every change. When checking through the results, Stenzek found a rather pleasant surprise awaiting him.

As anti-climatic as it may sound, one of the most infamous graphical bugs among developers was fixed without anyone even realizing it. Everyone had more or less come to the conclusion that The Simpsons Game required texture coordinate rounding accuracy beyond what was possible to do in a hardware renderer - at least while maintaining any performance. Thankfully, we were wrong and the game is now playable in the latest development builds and the 8 year old issue report can be put to rest.

5.0-10707 - Save EFB/XFB Copies to Savestate by Stenzek¶

During Summer Games Done Quick, they demonstrated a glitch in Majora's Mask (VC) using Dolphin Emulator. During this presentation, the presenter noted that when they loaded their savestate, for some reason there was one purple frame before things started rendering correctly again. While the issue was rather minor, it caught the eye of Dolphin developers.

All of this happens because Dolphin's savestates didn't contain the EFB nor the texture cache, which contains EFB copies. That means that some visual data could be missing, especially if the savestate was done midway through the frame. It could result in anything from a purple screen to missing objects. Some objects, like Mii faces, were stored in the texture cache for a long time, meaning that loading a savestate would often cause them to disappear or be missing features. If you were using Store EFB Copies to Texture, there wouldn't be a backup copy of the texture in emulated RAM. In order to fix this, Stenzek has added an option to save both the EFB and texture cache to savestates. This also means that TASers can load a savestate while paused and, instead of getting a blank screen, see the last frame that was rendered in the savestate. As a tradeoff for all of this, savestates will be slightly larger. In a game like Mario Kart Wii savestates range from 24 - 28MB with the feature off, and 32 - 34MB with the feature on at 3x internal resolution. As more textures are cached, this number may rise higher depending on the game.

As an added note, there are some games (particularly N64 VC) that cause Dolphin's texture cache serious headaches. In order to prevent gigantic savestates, we've disabled this feature in Super Smash Bros. (VC) and Mario Tennis (VC). If a game you're playing is misbehaving or you do not wish to use this feature, it can be disabled in the Graphics Setting's hacks tab.

5.0-10758 - Approximate logic op with blending if unsupported by Stenzek¶

It's not very often that something changes because of the work that goes into preparing a Progress Report. Tight at the cusp of publishing this report, we had an epiphany that changed everything, and made us a little late. But we certainly got a story for our troubles!

First, a bit of history to establish what's happening. Two years ago, we were thrilled that LogicOps support finally came to D3D11 via the 11.1 update. LogicOps 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), and while most games don't use them, for those that do having proper API support of the feature is important for Dolphin to emulate those titles. OpenGL, Vulkan, and even D3D12 all support LogicOps, so the only outlier was D3D11. But thanks to the D3D11.1 update, every API we used finally properly supported LogicOps. This meant the ugly hack, which was extra ugly due to old VideoCommon, could finally be removed.

Unfortunately, Microsoft decided to bring D3D11.1 to Windows 7 SP1 without LogicOps. While this did make the decision a bit harder, Windows 7 is not home to many of our users and has seen official support from Microsoft cease already. That isn't to say that Windows 7 was useless for Dolphin, but the specific combination of Windows 7 SP1 and D3D11, any game effects that require LogicOps will break.

And that's been the situation for the past couple of years. Of course, Dolphin is an open source project and anyone can contribute. This month, CookiePLMonster decided to see if they could improve the situation for Windows 7 users. After all, if anyone using D3D11 on Windows 7 ran a game that used LogicOps, any LogicOps effects would just hard fail without any indication whatsoever. While they weren't sure if they could fix the issues, they decided they could at least make it clear why things were failing with a dedicated system to alert users with a popup whenever they tried to switch to D3D11 in an environment that didn't fully support LogicOps (Windows 7). They also went the extra mile and disabled the LogicOps blend state in Dolphin whenever the detection determined LogicOps was not supported. This changed the behavior in a few games, and seemed like a nice improvement for Windows 7.

As we do here on the Dolphin Blog, we wrote about the changes. We outlined LogicOps support, talked about the popup, and how disabling the LogicOps blend state weirdly fixed the black box issue in Mario Kart Wii. While we did this, Stenzek decided to investigate what the game was doing because he didn't think the change should affect things like that. As we were wrapping up the Progress Report, he discovered that the Mario Kart Wii "fix" was actually causing null render target, which essentially causing it to skip drawing the blackbox. When Stenzek fixed that bug the box returned. While there's a ton more complications on why these changes affected the game this way, it's irrelevant to LogicOps emulation. If you are interested in our best guess as to why this occurred, let us know and we'll post it onto twitter. We aren't going to cover it here because as you are about to read, that is now all irrelevant.

As we were discussing LogicOps with Stenzek in IRC, the topic came to current support among different devices, and upon checking vendor support, Stenzek discovered something really bad. Pretty much our entire Android userbase are still dealing with these same issues. Whoops.

This was well known when the LogicOps hacks were removed, after all, OpenGL ES doesn't have LogicOps support whatsoever. But with Vulkan having support for LogicOps, we assumed it was only a matter of time before drivers caught up and we were left with an easier to maintain codebase. Except Adreno and Mali have, for whatever reason, decided not to support LogicOps in Vulkan. Since these GPUs are used by the two main vendors of phone SoCs (ARM and Qualcomm), effectively no phones available have LogicOps support. Cue facepalming.

Realizing that this is unlikely to change anytime soon, Stenzek reluctantly started working on a new LogicOps hack. Thanks to the VideoCommon Unification, this new hack could be redone with a much smaller footprint. It's still a very dirty, inaccurate hack, but at least it's less intrusive than before. For the time being, Mali, Adreno, and Windows 7 D3D11 users all have emulated LogicOps features with far fewer graphical bugs. And just to be clear, yes the LogicOps hack fixes the Mario Kart Wii black box bug.

The return of the LogicOps hack does supplant CookiePLMonster's changes, but, they were present during the conversation, and were more than fine with it. After all, their goal was to improve the situation for our Windows 7 D3D users, and the revival of the LogicOps hack is an even greater improvement than they had hoped! That said... We don't want to get Windows 7 users hopes up. 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.

As we come to the end of our LogicOps tale, there is one last bit within this story. As we were testing the new LogicOps hack, we discovered that LogicOps Invert, used by F-Zero GX seemed to be broken. The game uses LogicOps in one location, stage 2 of story mode, specifically for boulders that roll down a hill into a canyon. The problem was that these shadows seemed to be malfunctioning from any kind of distance. We didn't want to put up the Progress Report talking about LogicOps with one of the more prominent uses of LogicOps broken, so we went into investigation mode. Upon trying to bisect it, users found that what builds worked and what builds were broken made little to no sense. After two days, a lucky guess finally uncovered that the culprit was not Dolphin, but F-Zero GX. It turns out the developers didn't quite test the game well enough, as if you flip on the game's native widescreen setting, the shadows act very wonky.

And so we delayed the Progress Report a little bit longer because we were unaware of a game bug. Oops.

Dev Diary - Fixing the Most Curious Wii Game¶

Originally, there was just going to be a Progress Report entry talking about a one line fix for 全国デコトラ祭り (Zenkoku Dekotora Matsuri Dekotora National Festival). Unfortunately, talking about the fix and the bug doesn't really do the situation justice. This is one of the rare cases where we were glad something was broken in emulation that brought this game to our attention. Dekotora National Festival is quite possibly one of the weirdest Wii games we've seen... and also one of the most graphically ambitious games on the console.

The year is 2007. The Wii had already established itself as a surprise hit with hundreds of titles and a long backorder if you wanted to get one. With developers racing to get their games on console, Jaleco Entertainment and the developer Suzak noticed there was a huge hole in the Wii's library. There wasn't a single racing game about decorating semi-trucks and racing them around Japan's city streets. After cornering the market on the PS2 with Shin Bakusou Dekotora Densetsu, they decided to develop a sequel taking advantage of the Wii's superior horsepower.

With a small time developer and a rather unknown publisher, it may seem like this game was assuredly shovelware, but you'd be wrong. Dead wrong. Dekotora National Festival may not be the perfect game, but after looking into the game for a few hours, we can wholeheartedly say that Suzak put their heart into this game.

Dekotora National Festival is a strange game that plays more like Amplitude than Eurotruck Simulator. With quick inputs on the dpad, you dance between cars and race your opponent. At the same time, picking your route can be the difference between success and failure, and going the wrong way can put you kilometers off course. By braving traffic and avoiding red lights, you can earn money for winning races and turn your standard semi-truck into a beautiful dekotora!

And that's where we can really tell that Suzak was really pushing the Wii. This game, even on console, will frequently drop into the mid teens for framerate, especially when you have a truck decked out with lights and other fancy upgrades. It was even worse in Dolphin, as users trying to play this game reported that the game was more or less unplayable. Almost none of the city actually rendered!

Stenzek was kindly asked repeatedly over the course of months to look into it and eventually gave in. He loaded Dolphin through a program called Renderdoc. Renderdoc is an incredibly powerful tool that can let you record frames of rendering and see how they are constructed call by call. By using Renderdoc, we can not only see how the game is rendering, but why it is rendering something in a particular way. The goal was to see what was failing and causing the city to end up completely unrendered.

Unfortunately, that would be delayed as Stenzek was immediately distracted by some of the visual effects that Suzak managed pull off on the Wii. Dekotora has a lot going on in game. It features high polygon models, custom textures you can draw for your trucks in an editor, and even dynamic resolution scaling in a Wii game during replays for increased performance! But the crown jewel at the center of the game was its dynamically generated reflections as you drive around the city.

How is Dekotora National Festival able to pull off these brilliant reflections? Pure. Brute. Force. It renders each side of the truck separately and saves each side to EFB copies as it goes. Then it wraps all those images around a sphere, then renders that as another EFB copy which it uses as a reflection map. Yep, it is generating sphere maps live during play. And of course, the Wii doesn't have any understanding of or support for sphere maps, so the game is using the Wii's texgen unit to perform all of the texture coordinate transformation involved in using a sphere map entirely on its own somehow. On fixed function hardware. This is amazing, and we still don't entirely understand how it's even able to do this!

We've seen lots of EFB copy effects in games before, but usually its simpler techniques like taking the rendered output, flipping it over, and using it as a reflection. Wave Race: Blue Storm's water is a classic example of this. But this technique is something far beyond the typical reflections used in pretty much any other Wii game, and it does it during main gameplay! No wonder the game chugs even on real hardware!

Though it certainly isn't efficient or wise, all of this madness results in some really nice, fairly high resolution reflections that can even reflect off-screen geometry in real time. That is something that no other Wii title does, and even most modern titles can't do without raytracing. Of course it's utterly insane, so they had to cheat quite a bit. It's only updating the reflection every other other frame, the resolution of the reflections is reduced, and the reflections are rendered without any other vehicles present. Still, hats off to you Suzak, you brute forced your way into our hearts.

After his infatuation with the reflections wore off, Stenzek continued digging into the game to figure out why the city itself wasn't rendering. Eventually, he stumbled upon yet another depth issue in Dolphin. With its rather long draw distance, Suzak employed some more rendering trickery in order to reduce zfighting. They started out by doing a depth prepass on the city itself before rendering the background. They would then copy that out, clear it, and render the foreground. Then, that would be copied out and cleared again and everything would be re-rendered together as EFB copies.

Dolphin was mucking up the values very slightly during all of the conversions, and since the game uses equal for its depth test, this slight error caused nothing in the foreground city to render at all.

Unfortunately, it has taken us quite a while to actually solve this issue. The game itself is still quite expensive and importing it was a bit of a chore. The issue for it was reported over 3 years ago but we hope the user who reported it is still waiting. This is a game that deserved to be played, and given how much effort was put into it, we couldn't help but try it out ourselves. And despite the high expectations set by digging at the internals, the game doesn't disappoint. Enjoy.

As an added note, in order to get Dekotora National Festival working in Vulkan, we've merged support for reversed depth range in viewport. This allows Dolphin's Vulkan backend to get the same level of depth accuracy as OpenGL, but it isn't quite as supported among vendors quite yet.

Last Month's Contributors...¶

Special thanks to all of the contributors that incremented Dolphin from 5.0-10413 through to 5.0-10758!