fix some wording

Signed-off-by: crueter <crueter@eden-emu.dev>

docs/README.md

@@ -7,4 +7,4 @@ This contains documentation created by developers. This contains build instructi
 - **[Dependencies](Deps.md)**
 - **[CPM - CMake Package Manager](CPMUtil.md)**
 - **[Platform-Specific Caveats](Caveats.md)**
-- **[User Directory Handling](User.md)**
+- **[User Handbook](User.md)**

docs/SIGNUP.md

@@ -27,6 +27,7 @@ The following are not valid reasons to sign up:
   * To download and use Eden, see our [Releases page](https://github.com/eden-emulator/Releases/releases)!
 - I want to see the source code.
   * To see Eden's source code, go [here](https://git.eden-emu.dev/eden-emu/eden).
+
 ## Other Information
 
 Requests that appear suspicious, automated, OR blank will generally be automatically filtered. In cases of suspicion, or any of the invalid reasons listed above, you may receive an email back asking for clarification.

docs/User.md

@@ -1,11 +1,10 @@
-# User configuration
+# User Handbook
 
-## Configuration directories
+The "FAQ".
 
-Eden will store configuration in the following directories:
+This handbook is primarily aimed at the end-user - baking useful knowledge for enhancing their emulation experience.
 
-- **Windows**: `%AppData%\Roaming`.
-- **Android**: Data is stored internally.
-- **Linux, macOS, FreeBSD, Solaris, OpenBSD**: `$XDG_DATA_HOME`, `$XDG_CACHE_HOME`, `$XDG_CONFIG_HOME`.
-
-If a `user` directory is present in the current working directory, that will override all global configuration directories and the emulator will use that instead.
+- **[The Basics](user/Basics.md)**
+- **[Audio](user/Audio.md)**
+- **[Graphics](user/Graphics.md)**
+- **[Platforms and Architectures](user/Architectures.md)**

docs/user/Architectures.md

@@ -0,0 +1,128 @@
+# User Handbook - Architectures and Platforms
+
+Notes and caveats for different architectures and platforms.
+
+# Architectures
+
+Eden is primarily designed to run on amd64 (x86_64--Intel/AMD 64-bit) and aarch64 (arm64--ARM 64-bit) CPUs. Each architecture tends to have their own quirks and fun stuff; this page serves as a reference for these quirks.
+
+## amd64
+
+AMD64 is the most tested and supported architecture for desktop targets. Android is entirely unsupported.
+
+### Caveats
+
+AMD64 systems are almost always limited by the CPU. For example, a Zen 5/RX 6600 system will often hit max CPU usage before the GPU ever reaches 70% usage, with minimal exceptions (that tend to pop up only at >200fps). JIT is slow!
+
+Computers on Linux will almost always run Eden strictly better than an equivalent machine on Windows. This is largely due to the way the Linux kernel handles memory management (and the lack of Microsoft spyware).
+
+Intel Macs are believed to be supported, but no CI is provided for them. Performance will likely be awful on all but the highest-end iMacs and Pro-level Macs, and the MoltenVK requirement generally means Vulkan compatibility will suffer.
+
+## aarch64
+
+ARM64/aarch64 is the only supported architecture for Android, with limited experimental support available on Linux, Windows, and macOS.
+
+### Caveats
+
+NCE (Native Code Execution) is currently only available on Android and (experimentally) Linux. Support for macOS is in the works, but Windows is extremely unlikely to ever happen (if you want it--submit patches!). Generally, if NCE is available, you should pretty much always use it due to the massive performance hit JIT has.
+
+When NCE is enabled, do note that the GPU will almost always be the limiting factor. This is especially the case for Android, as well as desktops that lack dedicated GPUs; Adreno, Mali, PowerVR, etc. GPUs are generally significantly weaker relative to their respective CPUs.
+
+Windows/arm64 is *very* experimental and is unlikely to work at all. Support and testing is in the works.
+
+## riscv64
+
+RISC-V/riscv64 is sparsely tested, but preliminary tests from developers have reported at least partial support on Milk-V's Fedora/riscv64 Linux distribution. Performance, Vulkan support, compatibility, and build system caveats are largely unknown for the time being.
+
+### Caveats
+
+Windows/riscv64 doesn't exist, and may never (until corporate greed no longer consumes Microsoft).
+
+Android/riscv64 is interesting. While support for it may be added if and when RISC-V phones/handhelds ever go mainstream, arm64 devices will always be preferred due to NCE.
+
+Only Fedora/riscv64 has been tested, but in theory, every riscv64 distribution that has *at least* the standard build tools, Qt, FFmpeg, and SDL2 should work.
+
+## Other
+
+Other architectures, such as SPARC, MIPS, PowerPC, Loong, and all 32-bit architectures are completely unsupported, as there is no JIT backend or emitter thereof. If you want support for it--submit patches!
+
+IA-64 (Itanium) support is completely unknown. Existing amd64 packages will not run on IA-64 (assuming you can even find a supported Windows/Linux distribution)
+
+# Platforms
+
+The vast majority of Eden's testing is done on Windows, Linux, and Android. However, first-class support is also provided for:
+
+- FreeBSD
+- OpenBSD
+- OpenIndiana (Solaris)
+- macOS
+
+## Linux
+
+While all modern Linux distributions are supported (Fedora >40, Ubuntu >24.04, Debian >12, Arch, Gentoo, etc.), the vast majority of testing and development for Linux is on Arch and Gentoo. Most major build systems changes are tested on Gentoo first and foremost, so if builds fail on any modern distribution no matter what you do, it's likely a bug and should be reported.
+
+Intel and Nvidia GPU support is limited. AMD (RADV) drivers receive first-class testing and are known to provide the most stable Eden experience possible.
+
+## Windows
+
+Windows 10 and 11 are supported. Support for Windows 8.x is unknown, and Windows 7 support is unlikely to ever be added.
+
+In order to run Eden, you will probably need to install the [Visual C++ Redistributable](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170).
+
+Neither AMD nor Nvidia drivers work nearly as well as Linux's RADV drivers. Compatibility is still largely the same, but performance and some hard-to-run games may suffer compared to Linux.
+
+## Android
+
+A cooler is always recommended. Phone SoCs tend to get very hot, especially those manufactured with the Samsung process or those lacking in power.
+
+Adreno 6xx and 7xx GPUs with Turnip drivers will always have the best compatibility. "Stock" (system) drivers will have better performance on Adreno, but compatibility will suffer. Better support for stock drivers (including Adreno 8xx) is in the works.
+
+Android 16 is always recommended, as it brought major improvements to Vulkan requirements and compatibility, *plus* significant performance gains. Some users reported an over 50% performance gain on some Pixel phones after updating.
+
+Mali, PowerVR, Xclipse, and other GPU vendors generally lack in performance and compatibility. Notably:
+- No PowerVR GPUs *except* the DXT-48-1536 are known to work with Eden at all.
+- No Xclipse GPUs *except* the very latest (e.g. Xclipse 950) are known to work with Eden at all.
+- Mali has especially bad performance, though the Mali-G715 (Tensor G4) and Immortalis-G925 are known to generally run surprisingly well, especially on Android 16.
+- The status of all other GPU vendors is unknown. As long as they support Vulkan, they theoretically can run Eden.
+- Note that these GPUs generally don't play well with driver injection. If you choose to inject custom drivers via a rooted system (Panfrost, RADV, etc), you may see good results.
+
+Qualcomm Snapdragon SoCs are generally the most well supported.
+- Google Tensor chips have pretty terrible performance, but even the G1 has been proven to be able to run some games well on the Pixel 6 Pro.
+  * The Tensor G4 is the best-supported at the time. How the G5 currently fares is unknown, but on paper, it should do about as well as a Snapdragon 8 Gen 2 with stock drivers.
+- Samsung Exynos chips made before 2022 are not supported.
+- MediaTek Dimensity chips are extremely weak and most before mid-2023 don't work at all.
+  * This means that most budget phones won't work, as they tend to use old MediaTek SoCs.
+  * Generally, if your phone doesn't cost *at least* as much as a Switch itself, it will not *emulate* the Switch very well.
+- Snapdragon 865 and other old-ish SoCs may benefit from the Legacy build. These will reduce performance but *should* drastically improve compatibility.
+- If you're not sure how powerful your SoC is, check [NanoReview](https://nanoreview.net/en/soc-compare) - e.g. [Tensor G5](https://archive.is/ylC4Z).
+  * A good base to compare to is the Snapdragon 865--e.g. [Tensor vs SD865](https://archive.is/M1P58)
+  * Some benchmarks may be misleading due to thermal throttling OR RAM requirements.
+    - For example, a Pixel 6a (Tensor G1) performs about 1/3 as well as an 865 due to its lack of RAM and poor thermals.
+  * Remember--always use a cooler if you can, and you MUST have *at least* 8GB of RAM!
+- If you're not sure what SoC you have, check [GSMArena](https://www.gsmarena.com) - e.g. [Pixel 9 Pro](https://archive.ph/91VhA)
+
+Custom ROMs are recommdended, *as long as* you know what you're doing.
+- For most devices, [LineageOS](https://lineageos.org/) is preferred.
+- [CalyxOS](https://calyxos.org/) is available as well.
+- For Google Pixel devices ONLY... and [soon another OEM](https://archive.ph/cPpMd)... [GrapheneOS](https://grapheneos.org/) is highly recommended.
+  * As of October 5, 2025, the Pixel 10 line is unsupported, however, [it will be](https://archive.is/viAUl) in the very near future!
+  * Keep checking the [FAQ page](https://grapheneos.org/faq#supported-devices) for news.
+- Custom ROMs will likely be exclusively recommended in the future due to Google's upcoming [draconian](https://archive.is/hGIjZ), [anti-privacy, anti-user](https://archive.is/mc1CJ) verification requirements.
+
+Eden is currently unavailable on F-Droid or the Play Store. Check back occasionally.
+
+## macOS
+
+macOS is relatively stable, with only the occasional crash and bug. Compatibility may suffer due to the MoltenVK layer, however. Do note that building the GUI version with Qt versions higher than 6.7.3 will cause mysterious bugs, Vulkan errors, and crashes, alongside the cool feature of freezing the entire system UI randomly; we recommend you build with 6.7.3 (via aqtinstall) or earlier as the CI does.
+
+## *BSD, Solaris
+
+BSD and Solaris distributions tend to lag behind Linux in terms of Vulkan and other library compatibility. For example, OpenIndiana (Solaris) does not properly package Qt, meaning the recommended method of usage is to use `eden-cli` only for now. Solaris also generally works better with OpenGL.
+
+AMD GPU support on these platforms is limited or nonexistent.
+
+## VMs
+
+Eden "can" run in a VM, but only with the software renderer, *unless* you create a hardware-accelerated KVM with GPU passthrough. If you *really* want to do this and don't have a spare GPU lying around, RX 570 and 580 GPUs are extremely cheap on the black market and are powerful enough to run most commercial games at 60fps.
+
+Some users and developers have had success using a pure OpenGL-accelerated KVM on Linux with a Windows VM, but this is ridiculously tedious to set up. You're probably better off dual-booting.

docs/user/Audio.md

@@ -0,0 +1,3 @@
+# User Handbook - Audio
+
+`PULSE_SERVER=none` forces cubeb to use ALSA.

docs/user/Basics.md

@@ -0,0 +1,57 @@
+# User Handbook - The Basics
+
+## Introduction
+
+Eden is a very complicated piece of software, and as such there are many knobs and toggles that can be configured. Most of these are invisible to normal users, however power users may be able to leverage them to their advantage.
+
+This handbook primarily describes such knobs and toggles. Normal configuration options are described within the emulator itself and will not be covered in detail.
+
+## Requirements
+
+The emulator is very demanding on hardware, and as such requires a decent mid-range computer/cellphone.
+
+See [the requirements page](https://archive.is/sv83h) for recommended and minimum specs.
+
+The CPU must support FMA for an optimal gameplay experience. The GPU needs to support OpenGL 4.6 ([compatibility list](https://opengl.gpuinfo.org/)), or Vulkan 1.1 ([compatibility list](https://vulkan.gpuinfo.org/)).
+
+If your GPU doesn't support or is just behind by a minor version, see Mesa environment variables below (*nix only).
+
+## User configuration
+
+### Configuration directories
+
+Eden will store configuration files in the following directories:
+
+- **Windows**: `%AppData%\Roaming`.
+- **Android**: Data is stored internally.
+- **Linux, macOS, FreeBSD, Solaris, OpenBSD**: `$XDG_DATA_HOME`, `$XDG_CACHE_HOME`, `$XDG_CONFIG_HOME`.
+
+If a `user` directory is present in the current working directory, that will override all global configuration directories and the emulator will use that instead.
+
+### Environment variables
+
+Throughout the handbook, environment variables are mentioned. These are often either global (system wide) or local (set in a script, bound only to the current session). It's heavily recommended to use them in a local context only, as this allows you to rollback changes easily (if for example, there are regressions setting them).
+
+The recommended way is to create a `.bat` file alongside the emulator `.exe`; contents of which could resemble something like:
+
+```bat
+set "__GL_THREADED_OPTIMIZATIONS=1"
+set "SOME_OTHER_VAR=1"
+eden.exe
+```
+
+Android doesn't have a convenient way to set environment variables.
+
+For other platforms, the recommended method is using a shell script:
+
+```sh
+export __GL_THREADED_OPTIMIZATIONS=1
+export SOME_OTHER_VAR=1
+./eden
+```
+
+Then just running `chmod +x script.sh && source script.sh`.
+
+## Compatibility list
+
+Eden doesn't mantain a compatibility list. However, [EmuReady](https://www.emuready.com/) has a more fine-grained compatibility information for multiple emulators/forks as well.

docs/user/Graphics.md

@@ -0,0 +1,62 @@
+# User Handbook - Graphics
+
+## Visual Enhancements
+
+### Anti-aliasing
+
+Enhancements aimed at removing jagged lines/sharp edges and/or masking artifacts.
+
+- **No AA**: Default, provides no anti-aliasing.
+- **FXAA**: Fast Anti-Aliasing, an implementation as described on [this blog post](https://web.archive.org/web/20110831051323/http://timothylottes.blogspot.com/2011/03/nvidia-fxaa.html). Generally fast but with some innocuos artifacts.
+- **SMAA**: Subpixel Morphological Anti-Aliasing, an implementation as described on [this article](https://web.archive.org/web/20250000000000*/https://www.iryoku.com/smaa/).
+
+### Filters
+
+Various graphical filters exist - each of them aimed at a specific target/image quality preset.
+
+- **Nearest**: Provides no filtering - useful for debugging.
+  - **Pros**: Fast, works in any hardware.
+  - **Cons**: Less image quality.
+- **Bilinear**: Provides the hardware default filtering of the Tegra X1.
+  - **Pros**: Fast with acceptable image quality.
+- **Bicubic**: Provides a bicubic interpolation using a Catmull-Rom (or hardware-accelerated) implementation.
+  - **Pros**: Better image quality with more rounded edges.
+- **Zero-Tangent, B-Spline, Mitchell**: Provides bicubic interpolation using the respective matrix weights. They're normally not hardware accelerated unless the device supports the `VK_QCOM_filter_cubic_weights` extension. The matrix weights are those matching [the specification itself](https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#VkSamplerCubicWeightsCreateInfoQCOM).
+  - **Pros/Cons**: Each of them is a variation of the Bicubic interpolation model with different weights, they offer different methods to fix some artifacts present in Catmull-Rom.
+- **Spline-1**: Bicubic interpolation (similar to Mitchell) but with a faster texel fetch method. Generally less blurry than bicubic.
+  - **Pros**: Faster than bicubic even without hardware accelerated bicubic.
+- **Gaussian**: Whole-area blur, an applied gaussian blur is done to the entire frame.
+  - **Pros**: Less edge artifacts.
+  - **Cons**: Slow and sometimes blurry.
+- **Lanczos**: An implementation using `a = 3` (49 texel fetches). Provides sharper edges but blurrier artifacts.
+  - **Pros**: Less edge artifacts and less blurry than gaussian.
+  - **Cons**: Slow.
+- **ScaleForce**: Experimental texture upscale method, see [ScaleFish](https://github.com/BreadFish64/ScaleFish).
+  - **Pros**: Relatively fast.
+- **FSR**: Uses AMD FidelityFX Super Resolution to enhance image quality.
+  - **Pros**: Great for upscaling, and offers sharper visual quality.
+  - **Cons**: Somewhat slow, and may be offputtingly sharp.
+- **Area**: Area interpolation (high kernel count).
+  - **Pros**: Best for downscaling (internal resolution > display resolution).
+  - **Cons**: Costly and slow.
+- **MMPX**: Nearest-neighbour filter aimed at providing higher pixel-art quality.
+  - **Pros**: Offers decent pixel-art upscaling.
+  - **Cons**: Only works for pixel-art.
+
+### External
+
+While stock shaders offer a basic subset of options for most users, programs such as [ReShade](https://github.com/crosire/reshade) offer a more flexible experience. In addition to that users can also seek out modifications (mods) for enhancing visual experience (60 FPS mods, HDR, etc).
+
+## Driver specifics
+
+### Mesa environment variable hacks
+
+The software requires a certain version of Vulkan and a certain version of OpenGL to work - otherwise it will refuse to load, this can be easily bypassed by setting an environment variable: `MESA_GL_VERSION_OVERRIDE=4.6 MESA_GLSL_VERSION_OVERRIDE=460` (OpenGL) and `MESA_VK_VERSION_OVERRIDE=1.3` (Vulkan), for more information see [Environment variables for Mesa](https://web.archive.org/web/20250000000000*/https://docs.mesa3d.org/envvars.html).
+
+### NVIDIA OpenGL environment variables
+
+Unstable multithreaded optimisations are offered by the stock proprietary NVIDIA driver on X11 platforms. Setting `__GL_THREADED_OPTIMIZATIONS` to `1` would enable such optimisations. This mainly benefits the OpenGL backend. For more information see [Environment Variables for X11 NVIDIA](https://web.archive.org/web/20250115162518/https://download.nvidia.com/XFree86/Linux-x86_64/435.17/README/openglenvvariables.html).
+
+### swrast/LLVMpipe crashes under high load
+
+The OpenGL backend would invoke behaviour that would result in swarst/LLVMpipe writing an invalid SSA IR (on old versions of Mesa), and then proceeding to crash. The solution is using a script found in [tools/llvmpipe-run.sh](../../tools/llvmpipe-run.sh).