feature update: Vulkan announcement (#190)

* vulkan announcement

* review comments

site/assets/js/download.js

@@ -49,7 +49,7 @@ function getRelease(v, count = 5) {
 
           let env_icon = "/images/icons/file.png";
           if (is_windows) env_icon = "/images/icons/windows.png";
-          else if (asset.name.includes("osx"))
+          else if (asset.name.includes("macos"))
             env_icon = "/images/icons/apple.png";
           else if (asset.name.includes("linux"))
             env_icon = "/images/icons/linux.png";

site/content/download.md

@@ -27,9 +27,9 @@ The Citra updater provides a easy interface to install, update and manage Citra.
     Unknown platform - Citra is <b>only supported</b> on 64-bit versions of Windows, macOS, Linux, and Android 8 (Oreo) or above.
     If you are running one of these, choose one of the options below.
 </div>
-<a href="https://github.com/citra-emu/citra-web/releases/download/1.0/citra-setup-windows.exe" class="btn btn-lg btn-primary dl-updater-button" id="dl-windows-x64">Download for Windows x64</a>
+<a href="https://github.com/citra-emu/citra-web/releases/download/2.0/citra-setup-windows.exe" class="btn btn-lg btn-primary dl-updater-button" id="dl-windows-x64">Download for Windows x64</a>
-<a href="https://github.com/citra-emu/citra-web/releases/download/1.0/citra-setup-mac.dmg" class="btn btn-lg btn-primary dl-updater-button" id="dl-mac-x64">Download for Mac x64</a>
+<a href="https://github.com/citra-emu/citra-web/releases/download/2.0/citra-setup-mac.dmg" class="btn btn-lg btn-primary dl-updater-button" id="dl-mac-x64">Download for macOS Universal</a>
-<a href="https://flathub.org/apps/details/org.citra_emu.citra" class="btn btn-lg btn-primary dl-updater-button" id="dl-linux-x64">Download for Linux x64</a>
+<a href="https://github.com/citra-emu/citra-web/releases/download/2.0/citra-setup-linux" class="btn btn-lg btn-primary dl-updater-button" id="dl-linux-x64">Download for Linux x64</a>
 <a href='https://play.google.com/store/apps/details?id=org.citra.citra_emu' class="dl-updater-button" id="dl-android-x64"><img style="width:275px" alt='Get it on Google Play' src='https://play.google.com/intl/en_us/badges/static/images/badges/en_badge_web_generic.png'/></a>
 
 <br />
@@ -100,9 +100,9 @@ Hi! We see that you have JavaScript disabled. Unfortunately, this means that we
 prepare a updater for you, nor are we able to show you the latest archives of Citra either. Here are a few
 links to get you started however:<br />
 <br />
-<a href="https://github.com/citra-emu/citra-web/releases/download/1.0/citra-setup-windows.exe">Windows x64 Installer</a><br />
+<a href="https://github.com/citra-emu/citra-web/releases/download/2.0/citra-setup-windows.exe">Windows x64 Installer</a><br />
-<a href="https://github.com/citra-emu/citra-web/releases/download/1.0/citra-setup-mac.dmg">Mac x64 Installer</a><br />
+<a href="https://github.com/citra-emu/citra-web/releases/download/2.0/citra-setup-mac.dmg">macOS Universal Installer</a><br />
-<a href="https://flathub.org/apps/details/org.citra_emu.citra">Download for Linux x64</a><br /> 
+<a href="https://github.com/citra-emu/citra-web/releases/download/2.0/citra-setup-linux">Download for Linux x64</a><br /> 
 <a href="https://play.google.com/store/apps/details?id=org.citra.citra_emu">Download for Android</a><br />
 <a href="https://github.com/citra-emu/citra-nightly/releases">Nightly Builds</a><br />
 <a href="https://github.com/citra-emu/citra-canary/releases">Canary Builds</a> <br />

site/content/entry/citra-vulkan-announcement/index.md

@@ -0,0 +1,114 @@
++++
+date = "2023-09-15T22:00:00+01:00"
+title = "The Vulkan-o erupts - Citra Vulkan is here!"
+tags = [ "feature-update" ]
+author = "autumnburra"
+coauthor = "sleepingsnake"
+forum = 897225
++++
+
+Hey there, Citra fans! (We haven't used that one for a while, have we?)
+
+You've all wanted it and we've heard your cries and pleas. Vulkan has arrived and is here to stay, available now in the latest Citra release!
+
+# Why Vulkan?
+
+Since the dawn of time — well, since Citra's creation — many, *many* users have requested we add support for the [Vulkan Graphics API](https://en.wikipedia.org/wiki/Vulkan.); providing better performance in many cases and better support on devices, especially Android. There's a lot to love, but oh boy, was it ever a challenge!
+
+{{< sidebyside "image" ""
+    "sm3dlogl.png=OpenGL on Intel Core i3-1005G1. FPS: 75 Speed: 125%"
+    "sm3dlvk.png=Vulkan on Intel Core i3-1005G1.FPS: 115 Speed: 193%" >}}
+
+Vulkan support is also becoming a standard feature across many emulators, such as [Dolphin](https://dolphin-emu.org/), [Ryujinx](https://ryujinx.org/), [RPCS3](https://rpcs3.net/), [yuzu](https://yuzu-emu.org/), and many others. 
+As we've mentioned before, Citra is heading into the modern age. OpenGL is considered an ageing graphics API, with buggy and slow drivers, and performance bottlenecks. A modern graphics API like Vulkan is perfect for our vision of the New™️ Citra.
+
+If you haven't read it already, we have posted a detailed teaser about Vulkan in Citra in our [2020 Q2 ~ 2023 Q1 Progress Report](https://citra-emu.org/entry/citra-progress-report-2023-q1/#surprise-announcement). 
+We thoroughly recommend you give that a read, as it's a really good recap of the development of Vulkan at the time of writing.
+
+# Where to get Vulkan
+
+If you'd rather jump straight into the action, Citra with the Vulkan renderer can be found in the latest Nightly release, either as a [standalone build](https://github.com/citra-emu/citra-nightly/releases) or from our [installer](https://citra-emu.org/download/).
+
+# What to expect
+
+As with anything to do with emulation, nothing is ever perfect. Things are always evolving and changing, and this is no different.
+
+## Android
+
+Attention Android users! We have not forgotten about you! We are still here, making your gaming experience on mobile even better!
+
+A very large number of Citra users currently use a phone with a Mali GPU. This isn't something specific to Citra users, the majority of phones currently on the market have them! Especially with Samsung phones, if you live anywhere in the world apart from the United States or China, there's a high chance you'll get one with a Mali GPU.
+
+Sadly, these GPUs tend to have rather poor OpenGL ES drivers, so Citra's performance on them generally left a lot to be desired and bordered on unplayable for most 3DS titles. Performance improved significantly for these devices after some of the initial [rasterizer cache refactor](https://github.com/citra-emu/citra/pull/6375) work on our graphics backend was done, making many less demanding titles capable of reaching 100% emulation speed. However, many titles were still running short of full speed. 
+
+Now, these concerns can be laid to rest! Mali's vastly better Vulkan drivers allow for better, and smoother, gameplay when using Citra's Vulkan backend. You can now easily go beyond 100% emulation speed on most, if not all, games. And with the addition of asynchronous shader compilation, in-game stutter due to shaders building is greatly reduced, leaving you with a more seamless gameplay experience.
+
+{{< mp4 src="glesvk.mp4" title="Just look at the difference!" >}}
+
+If we could rewind to the terrible OpenGL ES drivers on Mali GPUs we mentioned before for a moment; another caveat of these drivers is the amount of bugs in them. This would cause graphical glitches in games, from characters being the wrong colors, to entire landscapes being rendered incorrectly.
+Of course, this would affect the gameplay just as much as poor performance would. Who wants to play a game if it doesn't even look right?
+Thankfully, this is another area of concern that has been fixed by the Citra Vulkan backend on Android.
+
+Bringing us back to the first ever game Citra launched, The Legend of Zelda: Ocarina of Time 3D is one such game that has graphical glitches caused by the Mali OpenGL ES drivers fixed with Vulkan:
+
+{{< mp4 src="oot3d.mp4" title="We've been waiting for you, Hero of Time." >}}
+
+## macOS
+
+Great news for macOS (Apple Silicon and Intel) users! Citra once again fully supports macOS devices! 
+
+"Well, what does that have to do with Vulkan?" one might ask...
+
+The answer is a bit complicated. 
+Citra used to require only OpenGL 3.3 in order to run, which macOS still technically supports. However, after many revisions of our graphics backend, that requirement was upped to at least OpenGL 4.3. Unlike all other major operating systems, Apple decided to deprecate OpenGL support. This means that macOS does not support anything beyond OpenGL 4.1, which doesn't meet Citra's new requirements. As such, Citra could no longer run on macOS.
+
+"Does macOS support Vulkan then?" another might ask...
+
+Sadly, the answer to that is a "no". Apple, in their infinite wisdom, decided to create a proprietary graphics API called "Metal", and wants all apps to use that instead. However, that would require us to create a graphics backend that is only relevant for macOS, and no other platform. Given Citra's cross-platform nature, that wouldn't be ideal. There is a solution though: [MoltenVK](https://github.com/KhronosGroup/MoltenVK). This is a translation layer that translates Vulkan calls into Metal calls. Through this translation, Citra can run on macOS once again!
+
+To use Vulkan, go to `Citra > Preferences > Graphics > Advanced tab` and set the Graphics API option to `Vulkan`. Additionally, the long-standing white/grey-screen bug, that required you to resize your Citra window in order to see anything being rendered, has been fixed with this API!
+
+## AMD
+
+There is another group of users that will benefit greatly from Vulkan. Namely, Windows users with older AMD GPUs.
+
+A while back, AMD massively improved their notoriously bad OpenGL drivers. This improvement saw those AMD GPU users, who were struggling to hit 100% emulation speed before, suddenly achieving up to 10 times that emulation speed. Whilst this was incredible news for AMD users, there was a caveat to this: only GCN 4.0 GPUs and newer received these improved drivers. For anyone using an older AMD GPU architecture, they are still stuck on the old, and really bad, OpenGL drivers.
+
+Luckily for them, the Vulkan drivers on those GPUs are still pretty good! As such, they'll no longer have to deal with sub-par performance, and can even compete with the new kids in performance!
+
+# What NOT to expect
+
+Keep in mind that Vulkan is a very new, and very big, addition to Citra. There are bound to be many bugs and glitches that slipped through the cracks. However, we've tried to make sure that what renders properly in OpenGL, renders properly in Vulkan. If you find a title where that isn't the case, please do let us know! With your testing and reports, we'll keep working to improve our Vulkan backend!
+
+Some quick notes:
+
+- Do not expect Vulkan to fix old emulation bugs that are not related to graphics or rendering.
+
+- Do not expect Vulkan to render games correctly that our OpenGL backend does not render correctly. Aside from OpenGL or Vulkan driver bugs, switching between the APIs shouldn't show any visual difference. If that _is_ the case for you, please report this to us!
+
+- Do not expect Vulkan to be an improvement over OpenGL in every aspect, on every device. Whilst Vulkan provides better performance than OpenGL in most cases, that is not always the case.
+
+- As of writing, Vulkan does not have full feature parity with our OpenGL backend. We will list some of the missing features below.
+
+- Whilst Vulkan currently has a disk pipeline cache, as well as runtime shader caching, an actual Disk Shader Cache for it is not yet implemented. As such, you may still experience some shader stutter at the start of each session until that is properly implemented.
+
+- Recording your gameplay using Video Dumping is not yet implemented.
+
+- Texture Filtering and Post-Processing Shaders are not yet implemented.
+
+As always, if you need support with anything, head to our [Discord server](https://discord.gg/FAXfZV9) or our [community forums](https://community.citra-emu.org/).
+
+# Requirements
+
+As with our OpenGL backend, we have minimum hardware requirements for running Vulkan. 
+
+Any device that supports Vulkan 1.1 or above will work with our Vulkan backend. Be it macOS, AMD, or Android. As long as your device supports this, you’re good to go!
+However, there is an exception for Adreno 5xx devices on Android, as these GPUs do not work with our Vulkan implementation at this time. We'll be working to fix this with future updates, so keep your eyes peeled!
+
+# What's next?
+
+As mentioned, our Vulkan backend does not yet have full feature parity with our OpenGL backend. Once that parity is achieved, we plan on giving you a much more technical article about the entire Vulkan backend, sure to satisfy the curious among you.
+
+We hope this release excites you about the future of Citra as much as it excites us.
+Our greatest gratitude goes out to the countless developers involved in bringing Vulkan to Citra, but especially to [GPUCode](https://github.com/GPUCode). Without him, none of this would ever have been possible.
+We also express thanks to [Steveice10](https://github.com/Steveice10), who helped on the macOS side of things for the Vulkan release, and to [BreadFish64](https://github.com/BreadFish64) for his expertise with Vulkan from his previous attempt to bring Vulkan to Citra.

site/content/help/_index.md

@@ -2,6 +2,6 @@
 title = "Help"
 +++
 
-User documentation on how to use Citra and frequently asked questions can be found here. Information for developers can be found on the [developer wiki](https://citra-emu.org/wiki/faq/).
+User documentation on how to use Citra and frequently asked questions can be found here. Information for developers can be found on the [wiki](https://citra-emu.org/wiki/faq/).
 
 If you would like more information on a subject, or you're having trouble, support is offered in our [Discord server](https://citra-emu.org/discord/).

site/content/help/feature/custom-textures/index.md

@@ -3,18 +3,54 @@ title = "Custom Textures"
 description = "Custom texture features for displaying custom graphics packs."
 +++
 
-Citra has the ability to dump game textures and load custom texture packs. Currently, only **`.PNG`** files are supported, but it is expected that more formats will come in the future.
+Citra has the ability to dump game textures and load custom texture packs. Game textures will be dumped as **`.png`** files. Texture packs may contain either **`.png`**, **`.dds`** or **`.ktx`** files. Supported compression formats include **`BCn`** and the various **`ASTC`** block variations.
 
 ## Instructions for dumping textures
 
 * Open `Emulation > Configure...` in Citra's menu and go to `Graphics > Enhancements`.
 * Enable **`Dump textures`** and click **`OK`**.
-* Now open a game of your choice, and start playing. As you keep playing, the textures used by the game will be dumped as **`.PNG`** files.
+* Now open a game of your choice, and start playing. As you keep playing, the textures used by the game will be dumped as **`.png`** files.
   - Right-click on your game in the games list and select **`Open Texture Dump Location`** to open the dump folder.
+  - The dump folder will contain a template **`pack.json`** file, that is used for configuration options. This file **must** be copied in the load folder.
 
 ## Instructions for replacing textures
 
 * Right-click on your game in the games list and select **`Open Custom Texture Location`** to open the folder where custom textures will be loaded from.
-* Place your custom texture **`.PNG`** files in the folder.
+* Place your custom texture **`.png`** files in the folder.
 * In `Emulation > Configure... > Graphics > Enhancements`, enable **`Use Custom Textures`** and click **`OK`**.
   - Additionally, if you want your custom textures to be pre-loaded to RAM, enable **`Preload Custom Textures`** as well. This will help improve the performance but will also increase memory usage.
+
+## Texture dumping
+
+Citra will dump textures when they are used by the game and uploaded from the guest VRAM to the host memory. Dumped textures may only have power-of-two dimensions in order to avoid dumping host framebuffers.
+
+The texture dumper will write a template **`pack.json`** file in the dump directory, which should be copied in the `load` folder when testing the texture pack. By default, textures will be dumped using the new hashing method. If a texture pack exists in the load folder, the dumper will use the same hashing method as that pack. Regardless of the hashing method, packs should still load correctly on any recent build of Citra. For any concerns regarding pack compatibility, possible breakages or feature requests please contact us either on [GitHub](https://github.com/citra-emu/citra/issues/) or on our [Discord server](https://citra-emu.org/discord/), as this is still a very new feature.
+
+The filename of dumped textures is comprised of various information about the guest texture. For example, the filename **"tex1_256x256_543624189C94B105_12_mip0.png"** includes the guest texture dimensions **256x256**, the texture hash **543624189C94B105**, the guest pixel format **12** and the mipmap level of the texture **mip0**
+
+## Pack configuration
+
+The custom textures rework introduced a new json configuration file for texture packs, which is used to distinguish between old and new packs. It contains information about the pack such as name, author, as well as other configuration options like the used hash format, automatic mipmap generation and control for texture flipping. The latter two options are **unsupported** when compressed texture formats are used.
+
+The new hashing option is recommended for new texture packs and is enabled by default. Advantages include faster hashing, as it requires less input data compared to the old hash and better compatibility between graphics APIs. In order to maintain compatibility with existing packs, loading the older hashing format is still fully supported. Usage of the old hash occurs either when the pack.json file does not exist in the texture pack load folder, or the **`use_new_hash`** option is disabled.
+
+The configuration file also allows for hash mappings, which means textures can have arbitrary filenames that don't strictly adhere to the dumper naming guidelines. For example:
+
+```
+"textures" : {
+  "114BFC385ED72F15" : "logo.png"
+  "22B8C43233F640AE" : "sky.png"
+}
+```
+
+## Normal maps
+
+The new custom texture system supports custom normal maps. This feature allows creators to add additional details to objects that would not be possible with only diffuse maps.
+
+Normal maps have the same filename as their diffuse counterpart, with an added **`.norm`** prefix before the file extension. For example the normal map for dumped texture **texture.png** will be named **texture.norm.png**. This applies for all supported file types and for hash mappings.
+
+There are limitations to when custom normal maps may be used. Most notably, the scene must enable fragment lighting. In the absence of lighting normal maps will **not** function and show the following error in the log:
+
+```
+[  24.086113] Render.OpenGL <Warning> video_core\renderer_opengl\gl_rasterizer.cpp:OpenGL::RasterizerOpenGL::BindMaterial:598: Custom normal map used but scene has no light enabled
+```

site/themes/citra-bs-theme/layouts/_default/baseof.html

@@ -79,7 +79,7 @@
                     <h1>Documentation</h1>
                     <a href="/help/">Help Documents</a>
                     <a href="/game/">Compatibility</a>
-                    <a href="/wiki/home/">Dev Wiki</a>
+                    <a href="/wiki/home/">Wiki</a>
                     <a href="/wiki/faq/">FAQ</a>
                 </div>
 

site/themes/citra-bs-theme/layouts/partials/menu.html

@@ -18,7 +18,7 @@
                 <li class="index-3"><a href="/help/" title="Help">Help</a></li>
                 <li class="index-4"><a href="/wiki/faq/" title="Frequently Asked Questions">FAQ</a></li>
                 <li class="index-5"><a href="/game/" title="Game Compatibility">Compatibility</a></li>
-                <li class="index-6"><a href="/wiki/home/" title="Wiki Homepage">Dev Wiki</a></li>
+                <li class="index-6"><a href="/wiki/home/" title="Wiki Homepage">Wiki</a></li>
 
                 <li class="index-7 dropdown">
                     <a href="#" class="dropdown-toggle" data-toggle="dropdown"
@@ -27,9 +27,9 @@
                     </a>
 
                     <ul class="dropdown-menu">
-                        <li class="index-1 first"><a href="/rules/" title="">Rules</a></li>
+                        <li class="index-1 first"><a href="/rules/" title="Community Rules">Rules</a></li>
                         <li class="index-2"><a href="https://community.citra-emu.org/" title="Forums">Community Forums</a></li>
-                        <li class="index-3 last"><a href="/discord/" title="Discord Channel">Discord Chat</a></li>
+                        <li class="index-3 last"><a href="/discord/" title="Discord Server">Discord Chat</a></li>
                     </ul>
                 </li>
 
@@ -42,7 +42,7 @@
                     <ul class="dropdown-menu">
                         <li class="index-1 first"><a href="/screenshots/" title="Screenshots">Screenshots</a></li>
                         <li class="index-2 last"><a href="https://www.youtube.com/channel/UC_dcdgzuapBtAY4ol3x-90Q"
-                                                    title="Youtube Channel">Videos</a></li>
+                                                    title="YouTube Channel">Videos</a></li>
                     </ul>
                 </li>
 

site/themes/citra-bs-theme/layouts/wiki/single.html

@@ -1,17 +1,4 @@
 {{ define "main" }}
-  <div class="alert alert-warning">
-    <div class="row">
-      <div class="col-md-2">
-        <strong>Read First!</strong>
-      </div>
-      <div class="col-md-10">
-        <p>The below wiki article is based on user submitted content.<br>
-        Please verify <strong>all</strong> hyperlinks and terminal commands below!</p>
-        See a mistake? Want to contribute? <a href="https://github.com/citra-emu/citra/wiki/{{ .File.BaseFileName }}/_edit/">Edit this article on Github</a>
-      </div>
-    </div>
-  </div>
-
 	<h1>{{ .Title }}</h1>
 	{{ .Content }}
 {{ end }}